<commit_before>:jbake-rightColumnHtml: <a href="single-page.html"><i class="fa fa-file fa-fw"></i> View single page</a>
:filename: 010_manual/50_Frequently_asked_Questions.adoc
ifndef::imagesdir[:imagesdir: ../images]

= Solutions to Common Problems

include::../_feedback.adoc[]

This section tries to answer the most common and frequently asked questions about how to work with docToolchain.
It will also contain questions relevant to the tools used to build docToolchain, but the main focus is docToolchain itself.

If you are stuck, make sure that you also check other sources like https://stackoverflow.com/questions/tagged/asciidoctor[Stack Overflow].

There is also a great FAQ for all your arc42 questions: https://faq.arc42.org/home/

If you have a question or problem for which you can't find a solution, you can

* for this repo, add your question and create a pull request
* raise the issue through the https://github.com/docToolchain/docToolchain/issues[GitHub issue tracker]
* ask your question on https://stackoverflow.com/questions/tagged/doctoolchain?sort=active&pageSize=50[Stack Overflow]
* discuss the problem on https://t.co/lnqrUc1YMM[Slack]

== Images

* https://asciidoctor.org/docs/user-manual/#images[Asciidoctor User Manual on images]
* https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#images[Asciidoctor Quick Reference on images]
* https://asciidoctor.org/docs/asciidoc-writers-guide/#images[AsciiDoctor Writer Guide on images]

=== Q: Why are images not shown in the preview of my editor?

A: this is most likely because your editor doesn't know where they are stored.
If you follow the default settings, you probably store your images in a subfolder `images`.
The build script knows about it, because the attribute `imagesdir` has been set to `./images`, but your editor doesn't care about the build script - it only checks the currently opened AsciiDoc file.

The solution is to add a line to each file which checks if the `imagesdir` is set and if not, sets it to a valid value:

`ifndef::imagesdir[:imagesdir: ../images]`

=== Q: Which image format should I use?

A:
AsciiDoc and AsciiDoctor support several formats like GIF, PNG, JPG and SVG.
However, if you want to use most features, some formats are better to use than others:

GIF:: is not supported by the PDF renderer.
Use JPG or PNG instead.

JPG:: is great for photos but not for diagrams (you might get compression artifacts).
So, if you want to use photos from your flipcharts - JPG might work for you.

SVG:: great for high resolution diagrams, but not good supported by DOCX as output format.
OpenOffice Writer might display the image a bit stretched, MS Word didn't display it at all in some experiments.
PDF output might display a warning that newer SVG versions are not supported (happends especially with diagrams.net images).

PNG:: this is the preferred format for images used with docToolchain.
All output formats support it and if diagrams are rendered with a resolution high enough to display all details, it will also be scaled well with all output formats.

=== Q: Why are my images rotated in the output?

A:
This most likely happens when you've taken photos with a mobile device and include them in you docs.
A mobile device does not rotate the image itself, it only stores the orientation of the device in the meta data of the photo.
Your operating system will show you the image as expected, but the rendered AsciiDoc will not.
This can be „fixed“ with Imagemagick, by using `convert -auto-orient` or `mogrify -auto-orient` (thanx to https://twitter.com/RalfDMueller/status/920888868345384960[@rotnroll666] for this tip).
You can also try to just open the image in your favourite editor and re-save it.

== exportVisio

=== Q: I get an error message saying that a library is not registered when I try to run the `exportVisio`-task.

----
Ausnahme beim Festlegen von "Visible": "Das COM-Objekt des Typs "Microsoft.Office.Interop.Visio.ApplicationClass" kann nicht in den Schnittstellentyp
"Microsoft.Office.Interop.Visio.IVApplication" umgewandelt werden. Dieser Vorgang konnte nicht durchgeführt werden, da der QueryInterface-Aufruf an die
COM-Komponente für die Schnittstelle mit der IID "{000D0700-0000-0000-C000-000000000046}" aufgrund des folgenden Fehlers nicht durchgeführt werden konnte:
Bibliothek nicht registriert. (Ausnahme von HRESULT: 0x8002801D (TYPE_E_LIBNOTREGISTERED))."
In ...\scripts\VisioPageToPngConverter.ps1:48 Zeichen:1
+ $VisioApp.Visible = $false
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], SetValueInvocationException
    + FullyQualifiedErrorId : ExceptionWhenSetting
----

A:
When Visio is installed, it registers itself as a com library.
It seems that this registration can break.
You can fix this by visiting the windows system settings -> install or uninstall a program, select `visio`, select `change` and then `repair`.

== Sparx Enterprise Architect

=== Q: Sparx Enterprise Architect is a Windows tool, isn't it?

Yes, it is, but it is written to support CrossOver in order to run on Linux based systems.
Wine, the open source branch of CrossOver, seems to work as well.

Take a look at this page to see how to install it on a linux based system: https://www.sparxsystems.com/support/faq/ea_on_linux.html

I (Ralf) once gave it a try and even managed to get remote control over EA via VBS and COM up and running (which is the pre-requisite for docToolchain).

== Known error Messages

=== Q: I get the error saying 'Failed to create MD5 hash for file content'.

----
* What went wrong:
Failed to capture snapshot of input files for task ':generateHTML' property 'sourceDir' during up-to-date check.
> Failed to create MD5 hash for file content.`
----

There are two known reasons for this error.

1. One of the .adoc files is opened in an editor, so that windows can't get the lock for that file.
-> Close all .adoc files.

2. You use the Bash script `doctoolchain` on a windows system.
-> Use `doctoolchain.bat` instead.
It works even in a Bash Shell.

=== Q: I get the error saying 'Unsupported major.minor version 52.0'

This is a sign that you use an outdated version of Java.
Please upgrade to Java 8 at least and 14 max.
The docToolchain-wrapper (dtcw) in v2.0 will check the java version for you so that you will not see this error message in the future.

=== Q: I get an error message saying 'Error occurred during initialization of VM'

```
Starting a Gradle Daemon, 1 incompatible Daemon could not be reused, use --status for details

FAILURE: Build failed with an exception.

* What went wrong:
Unable to start the daemon process.
…
Error occurred during initialization of VM
Could not reserve enough space for 2097152KB object heap
```

Somehow docToolchain can't allocate the memory which is configured out of the box.
Try to free up some memory or comment out the line `org.gradle.jvmargs=-Xmx2048m` in `gradle.properties`

[[wsl]]
=== Q: I get the error saying `Could not initialize class java.awt.GraphicsEnvironment$LocaleGE`

This seems to be a problem with WSL on Windows.
Some sources mention to run Java in headless mode, but in this case, it doesn't solve the problem.
The root cause seems to be plantUML trying to get some font information.

Only real solution seems to be to shutdown WSL from a powershell window wiht `wsl --shutdown` and retry.

WARNING: this will kill all your WSL terminals without warning.

Another solution seems to be to install a fresh version of your java runtime (I thought it is immutable, but it really helps).

Best Solution is to switch to powershell.

Another solution is to avoid PlantUML and generate Diagrams through a https://kroki.io[kroki.io] server.

Another variant of this is `Can't connect to X11 window server using '192.168.189.153:0' as the value of the DISPLAY variable.`.
In this case, it might help to install an X-Server (x410 for example) and configure the `DISPLAY` variable correctly.
An easy way to test you configuration is to run `xeyes` in WSL.

NOTE:: Please make sure that you wsl is up-to-date bei executing `wsl --update` - this is not part of your regular windows update!
<commit_msg>:memo: Use collapsible sections for FAQ<commit_after>:jbake-rightColumnHtml: <a href="single-page.html"><i class="fa fa-file fa-fw"></i> View single page</a>
:filename: 010_manual/50_Frequently_asked_Questions.adoc
ifndef::imagesdir[:imagesdir: ../images]

= Solutions to Common Problems

include::../_feedback.adoc[]

This section tries to answer the most common and frequently asked questions about how to work with docToolchain.
It will also contain questions relevant to the tools used to build docToolchain, but the main focus is docToolchain itself.

If you are stuck, make sure that you also check other sources like https://stackoverflow.com/questions/tagged/asciidoctor[Stack Overflow].

There is also a great FAQ for all your arc42 questions: https://faq.arc42.org/home/

If you have a question or problem for which you can't find a solution, you can

* for this repo, add your question and create a pull request
* raise the issue through the https://github.com/docToolchain/docToolchain/issues[GitHub issue tracker]
* ask your question on https://stackoverflow.com/questions/tagged/doctoolchain?sort=active&pageSize=50[Stack Overflow]
* discuss the problem on https://t.co/lnqrUc1YMM[Slack]

== Images

* https://asciidoctor.org/docs/user-manual/#images[Asciidoctor User Manual on images]
* https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#images[Asciidoctor Quick Reference on images]
* https://asciidoctor.org/docs/asciidoc-writers-guide/#images[AsciiDoctor Writer Guide on images]

=== Q: Why are images not shown in the preview of my editor?

.Answer
[%collapsible]
====
Ahis is most likely because your editor doesn't know where they are stored.
If you follow the default settings, you probably store your images in a subfolder `images`.
The build script knows about it, because the attribute `imagesdir` has been set to `./images`, but your editor doesn't care about the build script - it only checks the currently opened AsciiDoc file.

The solution is to add a line to each file which checks if the `imagesdir` is set and if not, sets it to a valid value:

`ifndef::imagesdir[:imagesdir: ../images]`
====

=== Q: Which image format should I use?

.Answer
[%collapsible]
====
AsciiDoc and AsciiDoctor support several formats like GIF, PNG, JPG and SVG.
However, if you want to use most features, some formats are better to use than others:

GIF:: is not supported by the PDF renderer.
Use JPG or PNG instead.

JPG:: is great for photos but not for diagrams (you might get compression artifacts).
So, if you want to use photos from your flipcharts - JPG might work for you.

SVG:: great for high resolution diagrams, but not good supported by DOCX as output format.
OpenOffice Writer might display the image a bit stretched, MS Word didn't display it at all in some experiments.
PDF output might display a warning that newer SVG versions are not supported (happends especially with diagrams.net images).

PNG:: this is the preferred format for images used with docToolchain.
All output formats support it and if diagrams are rendered with a resolution high enough to display all details, it will also be scaled well with all output formats.
====

=== Q: Why are my images rotated in the output?

.Answer
[%collapsible]
====
This most likely happens when you've taken photos with a mobile device and include them in you docs.
A mobile device does not rotate the image itself, it only stores the orientation of the device in the meta data of the photo.
Your operating system will show you the image as expected, but the rendered AsciiDoc will not.
This can be „fixed“ with Imagemagick, by using `convert -auto-orient` or `mogrify -auto-orient` (thanx to https://twitter.com/RalfDMueller/status/920888868345384960[@rotnroll666] for this tip).
You can also try to just open the image in your favourite editor and re-save it.

== exportVisio
====

=== Q: I get an error message saying that a library is not registered when I try to run the `exportVisio`-task.

----
Ausnahme beim Festlegen von "Visible": "Das COM-Objekt des Typs "Microsoft.Office.Interop.Visio.ApplicationClass" kann nicht in den Schnittstellentyp
"Microsoft.Office.Interop.Visio.IVApplication" umgewandelt werden. Dieser Vorgang konnte nicht durchgeführt werden, da der QueryInterface-Aufruf an die
COM-Komponente für die Schnittstelle mit der IID "{000D0700-0000-0000-C000-000000000046}" aufgrund des folgenden Fehlers nicht durchgeführt werden konnte:
Bibliothek nicht registriert. (Ausnahme von HRESULT: 0x8002801D (TYPE_E_LIBNOTREGISTERED))."
In ...\scripts\VisioPageToPngConverter.ps1:48 Zeichen:1
+ $VisioApp.Visible = $false
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], SetValueInvocationException
    + FullyQualifiedErrorId : ExceptionWhenSetting
----

.Answer
[%collapsible]
====
When Visio is installed, it registers itself as a com library.
It seems that this registration can break.
You can fix this by visiting the windows system settings -> install or uninstall a program, select `visio`, select `change` and then `repair`.
====

== Sparx Enterprise Architect

=== Q: Sparx Enterprise Architect is a Windows tool, isn't it?

.Answer
[%collapsible]
====
Yes, it is, but it is written to support CrossOver in order to run on Linux based systems.
Wine, the open source branch of CrossOver, seems to work as well.

Take a look at this page to see how to install it on a linux based system: https://www.sparxsystems.com/support/faq/ea_on_linux.html

I (Ralf) once gave it a try and even managed to get remote control over EA via VBS and COM up and running (which is the pre-requisite for docToolchain).
====

== Known error Messages

=== Q: I get the error saying 'Failed to create MD5 hash for file content'.

----
* What went wrong:
Failed to capture snapshot of input files for task ':generateHTML' property 'sourceDir' during up-to-date check.
> Failed to create MD5 hash for file content.`
----

.Answer
[%collapsible]
====
There are two known reasons for this error.

1. One of the .adoc files is opened in an editor, so that windows can't get the lock for that file.
-> Close all .adoc files.

2. You use the Bash script `doctoolchain` on a windows system.
-> Use `doctoolchain.bat` instead.
It works even in a Bash Shell.
====

=== Q: I get the error saying 'Unsupported major.minor version 52.0'

.Answer
[%collapsible]
====
This is a sign that you use an outdated version of Java.
Please upgrade to Java 8 at least and 14 max.
The docToolchain-wrapper (dtcw) in v2.0 will check the java version for you so that you will not see this error message in the future.
====

=== Q: I get an error message saying 'Error occurred during initialization of VM'

```
Starting a Gradle Daemon, 1 incompatible Daemon could not be reused, use --status for details

FAILURE: Build failed with an exception.

* What went wrong:
Unable to start the daemon process.
…
Error occurred during initialization of VM
Could not reserve enough space for 2097152KB object heap
```

.Answer
[%collapsible]
====
Somehow docToolchain can't allocate the memory which is configured out of the box.
Try to free up some memory or comment out the line `org.gradle.jvmargs=-Xmx2048m` in `gradle.properties`
====

[[wsl]]
=== Q: I get the error saying `Could not initialize class java.awt.GraphicsEnvironment$LocaleGE`

.Answer
[%collapsible]
====
This seems to be a problem with WSL on Windows.
Some sources mention to run Java in headless mode, but in this case, it doesn't solve the problem.
The root cause seems to be plantUML trying to get some font information.

Only real solution seems to be to shutdown WSL from a powershell window wiht `wsl --shutdown` and retry.

WARNING: this will kill all your WSL terminals without warning.

Another solution seems to be to install a fresh version of your java runtime (I thought it is immutable, but it really helps).

Best Solution is to switch to powershell.

Another solution is to avoid PlantUML and generate Diagrams through a https://kroki.io[kroki.io] server.

Another variant of this is `Can't connect to X11 window server using '192.168.189.153:0' as the value of the DISPLAY variable.`.
In this case, it might help to install an X-Server (x410 for example) and configure the `DISPLAY` variable correctly.
An easy way to test you configuration is to run `xeyes` in WSL.

NOTE:: Please make sure that you wsl is up-to-date bei executing `wsl --update` - this is not part of your regular windows update!
====
{'fraction_non_alphanumeric': 0.07667347674558346, 'fraction_numerical': 0.014060809998798222, 'mean_word_length': 4.407082521117609, 'pattern_counts': {'":': 2, '<': 11, '<?xml version=': 0, '>': 19, 'https://': 22, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 2, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '823257', 'n_tokens_mistral': 4899, 'n_tokens_neox': 4608, 'n_words': 2361}