<commit_before>:filename: manual/02_install.adoc

= How to install docToolchain

include::feedback.adoc[]

== Get the tool

To start with docToolchain you need to get a copy of the current docToolchain repository.
The easiest way is to clone the repository without history and remove the `.git` folder:

.Linux with git clone
[source,bash]
----
git clone --recursive https://github.com/docToolchain/docToolchain.git <docToolchain home>
cd <docToolchain home>
rm -rf .git
rm -rf resources/asciidoctor-reveal.js/.git
rm -rf resources/reveal.js/.git
----

`--recursive` option is required because the repository contains 2 submodules - `resources/asciidoctor-reveal.js` and `resources/reveal.js`.

Another way is to download the zipped git repository and rename it:

.Linux with download as zip
[source,bash]
----
wget https://github.com/docToolchain/docToolchain/archive/master.zip
unzip master.zip

# fetching dependencies

cd docToolchain-master/resources

rm -d reveal.js
wget https://github.com/hakimel/reveal.js/archive/tags/3.3.0.zip -O reveal.js.zip
unzip reveal.js.zip
mv reveal.js-tags-3.3.0 reveal.js

rm -d asciidoctor-reveal.js
wget https://github.com/asciidoctor/asciidoctor-reveal.js/archive/9667f5c.zip -O asciidoctor-reveal.js.zip
unzip asciidoctor-reveal.js.zip
mv asciidoctor-reveal.js-9667f5c5d926b3be48361d6d6413d3896954894c asciidoctor-reveal.js

mv docToolchain-master <docToolchain home>
----

If you work (like me) on a Windows environment, just download and unzip the https://github.com/docToolchain/docToolchain/archive/master.zip[repository] as well as its dependencies:
https://github.com/hakimel/reveal.js/archive/tags/3.3.0.zip[reveal.js] and https://github.com/asciidoctor/asciidoctor-reveal.js/archive/9667f5c.zip[asciidoctor-reveal.js].

After unzipping, put the dependencies in `resources` folder, so that the structure is the same as on https://github.com/docToolchain/docToolchain/tree/master/resources[GitHub].

//[source]
//----
//(New-Object Net.WebClient).DownloadFile('https://github.com/docToolchain/docToolchain/archive/master.zip','master.zip')
//----

You can add <docToolchain home>/bin to your PATH or you can run doctoolchain with full path if you prefer.

== Initialize directory for documents

The next step after getting docToolchain is to initialize a directory where your documents live.
In docToolchain this directory is named "newDocDir" during initialization, or just "docDir" later on.

=== Existing documents

If you already have some existing documents in AsciiDoc format in your project, you need to put the configuration file there to inform docToolchain what and how to process.
You can do that manually by copying the contents of template_config directory.
You can also do that by running `initExisting` task.

.Linux initExisting example
[source,bash]
----
cd <docToolchain home>
./gradlew -b init.gradle initExisting -PnewDocDir=<your directory>
----

You need to open Config.groovy file and configure names of your files properly.
You may also change the PDF schema file to your taste.

IMPORTANT: docToolchain by default uses `src/docs` as the directory of your documentation.
If you use a different directory you need to go to <docToolchain home> and set the `inputPath` property in `gradle.properties` to `your/path`.

=== arc42 from scratch

If you don't have existing documents yet, or if you need a fresh start, you can get the https://arc42.org[arc42] template in AsciiDoc format.
You can do that by manually downloading from https://arc42.org/download.
You can also do that by running the
`initArc42<language>` task.
Currently supported languages are:

- DE - German
- EN - English
- ES - Spanish
- RU - Russian

.Linux initArc42EN example
[source,bash]
----
cd <docToolchain home>
./gradlew -b init.gradle initArc42EN -PnewDocDir=<newDocDir>
----

The Config.groovy file is then preconfigured to use the downloaded template.

TIP: Blog-Post: https://rdmueller.github.io/arc42/[Let's add Content!]

== Build

This should already be enough to start a first build.

By now, docToolchain should be installed as command line tool and the path to its `bin` folder should be on your path.
If you now switch to your freshly initialized <newDocDir>, you should be able to execute the following commands:

.Linux
[source,bash]
----
doctoolchain <docDir> generateHTML
doctoolchain <docDir> generatePDF
----

.Windows
[source]
----
doctoolchain.bat <docDir> generateHTML
doctoolchain.bat <docDir> generatePDF
----

<docDir> may be relative, e.g. ".", or absolute.

As a result, you will see the progress of your build together with some warnings which you can just ignore for the moment.

The first build generated some files within the `<docDir>/build`:

[source]
----
build
|-- html5
|   |-- arc42-template.html
|   `-- images
|       |-- 05_building_blocks-EN.png
|       |-- 08-Crosscutting-Concepts-Structure-EN.png
|       `-- arc42-logo.png
`-- pdf
    |-- arc42-template.pdf
    `-- images
        |-- 05_building_blocks-EN.png
        |-- 08-Crosscutting-Concepts-Structure-EN.png
        `-- arc42-logo.png
----

*Congratulations!* If you see the same folder structure, you just managed to render the standard arc42 template as html and pdf!

If you didn't get the right output, please raise an issue on https://github.com/docToolchain/docToolchain/issues[github]

TIP: Blog-Posts: https://rdmueller.github.io/enterprise-edition/[Behind the great Firewall], https://rdmueller.github.io/enterprise-edition2/[Enterprise AsciiDoctor]

== Publish to Confluence

In addition to `Config.groovy` there is also a `scripts/ConfluenceConfig.groovy` file.
If you are not using Confluence you can remove it.
If you use Confluence, then you need to open this file and adapt it to your environment.
You can also create multiple copies of that file.
For example you can have `ConfluenceConfig.groovy` for publishing official pages, and `MyConfluenceConfig.groovy` with a different Confluence space for reviews.

For example:

[source,bash]
----
doctoolchain <docDir> publishToConfluence
----<commit_msg>removed last section because of #492<commit_after>:filename: manual/02_install.adoc

= How to install docToolchain

include::feedback.adoc[]

== Get the tool

To start with docToolchain you need to get a copy of the current docToolchain repository.
The easiest way is to clone the repository without history and remove the `.git` folder:

.Linux with git clone
[source,bash]
----
git clone --recursive https://github.com/docToolchain/docToolchain.git <docToolchain home>
cd <docToolchain home>
rm -rf .git
rm -rf resources/asciidoctor-reveal.js/.git
rm -rf resources/reveal.js/.git
----

`--recursive` option is required because the repository contains 2 submodules - `resources/asciidoctor-reveal.js` and `resources/reveal.js`.

Another way is to download the zipped git repository and rename it:

.Linux with download as zip
[source,bash]
----
wget https://github.com/docToolchain/docToolchain/archive/master.zip
unzip master.zip

# fetching dependencies

cd docToolchain-master/resources

rm -d reveal.js
wget https://github.com/hakimel/reveal.js/archive/tags/3.3.0.zip -O reveal.js.zip
unzip reveal.js.zip
mv reveal.js-tags-3.3.0 reveal.js

rm -d asciidoctor-reveal.js
wget https://github.com/asciidoctor/asciidoctor-reveal.js/archive/9667f5c.zip -O asciidoctor-reveal.js.zip
unzip asciidoctor-reveal.js.zip
mv asciidoctor-reveal.js-9667f5c5d926b3be48361d6d6413d3896954894c asciidoctor-reveal.js

mv docToolchain-master <docToolchain home>
----

If you work (like me) on a Windows environment, just download and unzip the https://github.com/docToolchain/docToolchain/archive/master.zip[repository] as well as its dependencies:
https://github.com/hakimel/reveal.js/archive/tags/3.3.0.zip[reveal.js] and https://github.com/asciidoctor/asciidoctor-reveal.js/archive/9667f5c.zip[asciidoctor-reveal.js].

After unzipping, put the dependencies in `resources` folder, so that the structure is the same as on https://github.com/docToolchain/docToolchain/tree/master/resources[GitHub].

//[source]
//----
//(New-Object Net.WebClient).DownloadFile('https://github.com/docToolchain/docToolchain/archive/master.zip','master.zip')
//----

You can add <docToolchain home>/bin to your PATH or you can run doctoolchain with full path if you prefer.

== Initialize directory for documents

The next step after getting docToolchain is to initialize a directory where your documents live.
In docToolchain this directory is named "newDocDir" during initialization, or just "docDir" later on.

=== Existing documents

If you already have some existing documents in AsciiDoc format in your project, you need to put the configuration file there to inform docToolchain what and how to process.
You can do that manually by copying the contents of template_config directory.
You can also do that by running `initExisting` task.

.Linux initExisting example
[source,bash]
----
cd <docToolchain home>
./gradlew -b init.gradle initExisting -PnewDocDir=<your directory>
----

You need to open Config.groovy file and configure names of your files properly.
You may also change the PDF schema file to your taste.

IMPORTANT: docToolchain by default uses `src/docs` as the directory of your documentation.
If you use a different directory you need to go to <docToolchain home> and set the `inputPath` property in `gradle.properties` to `your/path`.

=== arc42 from scratch

If you don't have existing documents yet, or if you need a fresh start, you can get the https://arc42.org[arc42] template in AsciiDoc format.
You can do that by manually downloading from https://arc42.org/download.
You can also do that by running the
`initArc42<language>` task.
Currently supported languages are:

- DE - German
- EN - English
- ES - Spanish
- RU - Russian

.Linux initArc42EN example
[source,bash]
----
cd <docToolchain home>
./gradlew -b init.gradle initArc42EN -PnewDocDir=<newDocDir>
----

The Config.groovy file is then preconfigured to use the downloaded template.

TIP: Blog-Post: https://rdmueller.github.io/arc42/[Let's add Content!]

== Build

This should already be enough to start a first build.

By now, docToolchain should be installed as command line tool and the path to its `bin` folder should be on your path.
If you now switch to your freshly initialized <newDocDir>, you should be able to execute the following commands:

.Linux
[source,bash]
----
doctoolchain <docDir> generateHTML
doctoolchain <docDir> generatePDF
----

.Windows
[source]
----
doctoolchain.bat <docDir> generateHTML
doctoolchain.bat <docDir> generatePDF
----

<docDir> may be relative, e.g. ".", or absolute.

As a result, you will see the progress of your build together with some warnings which you can just ignore for the moment.

The first build generated some files within the `<docDir>/build`:

[source]
----
build
|-- html5
|   |-- arc42-template.html
|   `-- images
|       |-- 05_building_blocks-EN.png
|       |-- 08-Crosscutting-Concepts-Structure-EN.png
|       `-- arc42-logo.png
`-- pdf
    |-- arc42-template.pdf
    `-- images
        |-- 05_building_blocks-EN.png
        |-- 08-Crosscutting-Concepts-Structure-EN.png
        `-- arc42-logo.png
----

*Congratulations!* If you see the same folder structure, you just managed to render the standard arc42 template as html and pdf!

If you didn't get the right output, please raise an issue on https://github.com/docToolchain/docToolchain/issues[github]

TIP: Blog-Posts: https://rdmueller.github.io/enterprise-edition/[Behind the great Firewall], https://rdmueller.github.io/enterprise-edition2/[Enterprise AsciiDoctor]

{'fraction_non_alphanumeric': 0.10081062435322526, 'fraction_numerical': 0.015436357364608485, 'mean_word_length': 4.0290546400693845, 'pattern_counts': {'":': 0, '<': 38, '<?xml version=': 0, '>': 38, 'https://': 30, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 14, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4869202', 'n_tokens_mistral': 3725, 'n_tokens_neox': 3523, 'n_words': 1271}