<commit_before>:jbake-rightColumnHtml: <a href="single-page.html"><i class="fa fa-file fa-fw"></i> View single page</a>
//tag::install[]

:filename: 010_manual/20_install.adoc
:icons: font

= Installing docToolchain

include::../_feedback.adoc[]

== Getting the Wrapper

The way docToolchain is installed has changed since the v2.x release. It now uses a simple wrapper script which takes care of everything.

This wrapper helps by:

- Ensuring that everyone using your repository uses the same docToolchain version.
- Keeping all docToolchain technology out of your repository.
- Wrapping your commands and directing them to your local installation.
- Checking your docToolchain installation (if not installed, the wrapper will do it for you via direct download or Docker).

This guide explains how to set up docToolchain in the following environments:

- A Linux/WSL2 with bash
- Windows with PowerShell
- Windows with cmd.exe

Please select the appropriate setup and follow these instructions to install docToolchain step by step.

.Linux / WSL2 with bash
[role='primary']
--

[source, bash]
----
cd <your project>
curl -Lo dtcw doctoolchain.github.io/dtcw
chmod +x dtcw
----

if you don't have `curl` installed, you can also use `wget`:

[source, bash]
----
cd <your project>
wget doctoolchain.github.io/dtcw
chmod +x dtcw
----

--

.Windows with Powershell
[role='secondary']
--
[source, powershell]
----
cd <your project>
Invoke-WebRequest doctoolchain.github.io/dtcw.ps1 -Outfile dtcw.ps1
----
--

.Windows with cmd.exe
[role='secondary']
--
[source, cmd]
----
cd <your project>
curl -Lo dtcw.bat doctoolchain.github.io/dtcw.bat
----

NOTE: `dtcw.bat` wraps the `dtcw.ps1` script and executes it in powershell. This might be easier to use if you haven't yet configured your powershell as a developer.

--

NOTE: In order to support development for your project on both, Linux and Windows, it makes sense to download all three scripts to your project.

NOTE: if you use cmd.exe, follow the PowerShell instructions but replace `.ps1` with `.bat`.

IMPORTANT: `dtcw` uses bash as shell and thus tries to find java from within bash. Chances are that when you use `dtcw` from another shell like zsh, you shell knows about the right java version but your bash doesn't. In that case, please switch to bash and make sure that the right java version is known. Afterwards, you can switch back to your shell.



== Running your First Command

To get started with docToolchain, run `tasks` as the first command:

.Linux / WSL2 with bash
[role='primary']
--
[source, bash]
----
./dtcw tasks --group=doctoolchain
----
--

.Windows with Powershell
[role='secondary']
--
[source, powershell]
----
./dtcw.ps1 tasks --group=doctoolchain
----

NOTE: if using cmd.exe replace `.ps1` with `.bat` for all subsequent commands.

--

This command shows all docToolchain tasks and verifies that docToolchain is installed by doing the following:

* Checking for a configuration file (and create one if none exist). Prefers a local installation. 

* Making use of Docker (if available) where there is no local installation.

NOTE: If this is your first time installing docToolchain, the images download might take a while.

* if docker is not available, it will download and install docToolchain to your home folder
** it will then run a gradle build through the gradle wrapper. If this is your first time, it will download and install gradle.
** the gradle build will also fetch some dependencies. This will also take a while if run for the first time..
** build-script dependencies are fetched from a repository referenced by the property `mavenRepository`. By default the value `https://plugins.gradle.org/m2/` is used. When a repository requiring credentials is used the properties `mavenUsername` and `mavenPassword` can be set as well.

[source, sh]
.Example command passing a custom maven repository with credentials from the command line
----
./gradlew generateHTML -PmavenRepository=your_maven_repo -PmavenUsername=your_username -PmavenPassword=<PASSWORD> --info
----

You'll notice the installation is an incremental process and will take a while because of all the additional dependencies needed.
After the first few commands, you'll have all the required dependencies installed and things will run faster.

//end::install[]

== Existing Documents

If your project already has documents in AsciiDoc format, you'll need to tell docToolchain where to find them.

To do so, take a look at the created `docToolchainConfig.groovy` and update it.

== 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.

Run the command below to tell docToolchain to download the template of your choice:

.Linux / WSL2 with bash
[.primary]
--
[source,bash]
----
./dtcw downloadTemplate
----
--

.Windows
[.secondary]
--
[source,powershell]
----
./dtcw.ps1 downloadTemplate
----
--

== Building and Creating Templates.

By now, the docToolchain wrapper `dtcw` should be in your project folder along with the arc42 template.

Now Let's render it to HTML and PDF. To do so, run the commands below:

.Linux / WSL2 with bash
[.primary]
--
[source,bash]
----
./dtcw generateHTML
./dtcw generatePDF
----
--

.Windows
[.secondary]
--
[source,powershell]
----
./dtcw.ps1 generateHTML
./dtcw.ps1 generatePDF
----
--

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 `build`:

[source]
----
build
|-- html5
|   |-- arc42
|   |   `-- arc42.html
|   `-- images
|       |-- 05_building_blocks-EN.png
|       |-- 08-Crosscutting-Concepts-Structure-EN.png
|       `-- arc42-logo.png
`-- pdf
    |-- arc42
    |   `-- arc42.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've just rendered the standard arc42 template as HTML and PDF!

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

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

<commit_msg>added documentation<commit_after>:jbake-rightColumnHtml: <a href="single-page.html"><i class="fa fa-file fa-fw"></i> View single page</a>
//tag::install[]

:filename: 010_manual/20_install.adoc
:icons: font

= Installing docToolchain

include::../_feedback.adoc[]

== Getting the Wrapper

The way docToolchain is installed has changed since the v2.x release. It now uses a simple wrapper script which takes care of everything.

This wrapper helps by:

- Ensuring that everyone using your repository uses the same docToolchain version.
- Keeping all docToolchain technology out of your repository.
- Wrapping your commands and directing them to your local installation.
- Checking your docToolchain installation (if not installed, the wrapper will do it for you via direct download or Docker).

This guide explains how to set up docToolchain in the following environments:

- A Linux/WSL2 with bash
- Windows with PowerShell
- Windows with cmd.exe

Please select the appropriate setup and follow these instructions to install docToolchain step by step.

.Linux / WSL2 with bash
[role='primary']
--

[source, bash]
----
cd <your project>
curl -Lo dtcw doctoolchain.github.io/dtcw
chmod +x dtcw
----

if you don't have `curl` installed, you can also use `wget`:

[source, bash]
----
cd <your project>
wget doctoolchain.github.io/dtcw
chmod +x dtcw
----

--

.Windows with Powershell
[role='secondary']
--
[source, powershell]
----
cd <your project>
Invoke-WebRequest doctoolchain.github.io/dtcw.ps1 -Outfile dtcw.ps1
----
--

.Windows with cmd.exe
[role='secondary']
--
[source, cmd]
----
cd <your project>
curl -Lo dtcw.bat doctoolchain.github.io/dtcw.bat
----

NOTE: `dtcw.bat` wraps the `dtcw.ps1` script and executes it in powershell. This might be easier to use if you haven't yet configured your powershell as a developer.

--

NOTE: In order to support development for your project on both, Linux and Windows, it makes sense to download all three scripts to your project.

NOTE: if you use cmd.exe, follow the PowerShell instructions but replace `.ps1` with `.bat`.

IMPORTANT: `dtcw` uses bash as shell and thus tries to find java from within bash. Chances are that when you use `dtcw` from another shell like zsh, you shell knows about the right java version but your bash doesn't. In that case, please switch to bash and make sure that the right java version is known. Afterwards, you can switch back to your shell.

== Configure the Wrapper

There is no need to configure the wrapper itself if you have just downloaded it.
But from time to time you should check github to see if there are https://github.com/docToolchain/docToolchain/releases[new releases] you want to use.

In this case, open dtcw in your favourite editor and look for the `VERSION`-line at the start of the file:

[source, bash]
----
# find official release versions on github:
# https://github.com/docToolchain/docToolchain/releases
# set VERSION to "latest" to get the unreleased latest version
VERSION=2.0.5
----

Update it to match the latest release and and everything will be updated with the next run.

NOTE: this will not update the wrapper (dtcw) itself.
If you think you should update the wrapper, please re-install it.

There are some situation where you want to test a not-yet-released feature.
In such a case, you can set the `VERSION` to `latest` and `dtcw` will `clone` or `pull` the current default branch of the project.

This only works with a local copy, not with a docker install. 

You can also use `latestdev` as version.
In this case, `dtcw` will try to clone the repository with the ssh-git protocoll.
This way, you can easily point it to your fork and develop new features for docToolchain.
You will find the fork in `$HOME/.doctoolchain/docToolchain-latest`.

NOTE: `latest` and `latestdev` currently only work with the bash version of the wrapper.

== Running your First Command

To get started with docToolchain, run `tasks` as the first command:

.Linux / WSL2 with bash
[role='primary']
--
[source, bash]
----
./dtcw tasks --group=doctoolchain
----
--

.Windows with Powershell
[role='secondary']
--
[source, powershell]
----
./dtcw.ps1 tasks --group=doctoolchain
----

NOTE: if using cmd.exe replace `.ps1` with `.bat` for all subsequent commands.

--

This command shows all docToolchain tasks and verifies that docToolchain is installed by doing the following:

* Checking for a configuration file (and create one if none exist). Prefers a local installation. 

* Making use of Docker (if available) where there is no local installation.

NOTE: If this is your first time installing docToolchain, the images download might take a while.

* if docker is not available, it will download and install docToolchain to your home folder
** it will then run a gradle build through the gradle wrapper. If this is your first time, it will download and install gradle.
** the gradle build will also fetch some dependencies. This will also take a while if run for the first time..
** build-script dependencies are fetched from a repository referenced by the property `mavenRepository`. By default the value `https://plugins.gradle.org/m2/` is used. When a repository requiring credentials is used the properties `mavenUsername` and `mavenPassword` can be set as well.

[source, sh]
.Example command passing a custom maven repository with credentials from the command line
----
./gradlew generateHTML -PmavenRepository=your_maven_repo -PmavenUsername=your_username -PmavenPassword=<PASSWORD> --info
----

You'll notice the installation is an incremental process and will take a while because of all the additional dependencies needed.
After the first few commands, you'll have all the required dependencies installed and things will run faster.

//end::install[]

== Existing Documents

If your project already has documents in AsciiDoc format, you'll need to tell docToolchain where to find them.

To do so, take a look at the created `docToolchainConfig.groovy` and update it.

== 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.

Run the command below to tell docToolchain to download the template of your choice:

.Linux / WSL2 with bash
[.primary]
--
[source,bash]
----
./dtcw downloadTemplate
----
--

.Windows
[.secondary]
--
[source,powershell]
----
./dtcw.ps1 downloadTemplate
----
--

== Building and Creating Templates.

By now, the docToolchain wrapper `dtcw` should be in your project folder along with the arc42 template.

Now Let's render it to HTML and PDF. To do so, run the commands below:

.Linux / WSL2 with bash
[.primary]
--
[source,bash]
----
./dtcw generateHTML
./dtcw generatePDF
----
--

.Windows
[.secondary]
--
[source,powershell]
----
./dtcw.ps1 generateHTML
./dtcw.ps1 generatePDF
----
--

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 `build`:

[source]
----
build
|-- html5
|   |-- arc42
|   |   `-- arc42.html
|   `-- images
|       |-- 05_building_blocks-EN.png
|       |-- 08-Crosscutting-Concepts-Structure-EN.png
|       `-- arc42-logo.png
`-- pdf
    |-- arc42
    |   `-- arc42.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've just rendered the standard arc42 template as HTML and PDF!

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

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.09459364206668076, 'fraction_numerical': 0.007683090152956933, 'mean_word_length': 3.6763348714568225, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 17, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4536197', 'n_tokens_mistral': 4297, 'n_tokens_neox': 4062, 'n_words': 1844}