Solutions to Common Problems

Timo Abele Pascal Euhus Ralf D. Müller Jérémie Bresson Ralf D. Müller faltfe Aaron Collier Bennykillua stehlih Dr. Stefan Pfeiffer Alexander Schwartz funkr Lars Francke jakubjab

9 minutes to read

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

References

Q: How can I reference source code from my documentation?

Answer

As long, as you stay within your documents folder (default src/docs), you can simply reference other files with a relative include::filename.adoc[]-statement.
If you need to reference files outside of the documents folder, you need to reference them with an absolute path.

include::/opt/build/repofilename.adoc[]

The /opt/build/repo will point to the folder where your dtcw file resides. In order make this also work in your editor preview, specify a line like the following in your documents:

ifndef::projectRootDir[:projectRootDir: ../../../]

Images

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

Answer

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?

Answer

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 (happens 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

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 metadata 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 @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

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

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 for ':generateDeck' saying 'No such file or directory' when cloning reveal.js.

./dtcw generateDeck
dtcw - docToolchain wrapper V0.38
docToolchain Vlatest
docToolchain as CLI available
docker available
home folder exists
cloning reveal.js
./dtcw: line 133: cd: $HOME/.doctoolchain/docToolchain-latest/resources: No such file or directory
Answer

You’re using dtcw v0.38 or an older version. This is because with the release of docToolchain 3.x, the ':generateDeck' tasks no longer rely on helper scripts. To resolve this issue, simply upgrade dtcw to the latest version. The good news is that dtcw is backwards compatible with docToolchain, meaning you can use the latest version of dtcw while still referring to older versions of docToolchain. To switch to other version of docToolchain refer to the installation docs.

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

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

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

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

Q: I get the error saying Could not initialize class java.awt.GraphicsEnvironment$LocaleGE

Answer

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 with 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 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 your configuration is to run xeyes in WSL.

Make sure that your WSL is up-to-date by running wsl --update. This is not part of your regular Windows update!

Q: I get a Failed to create parent directory /project/.gradle error

> Gradle could not start your build.
> Could not create service of type CrossBuildFileHashCache using BuildSessionServices.createCrossBuildFileHashCache().
   > Failed to create parent directory '/project/.gradle' when creating directory '/project/.gradle/6.7.1/fileHashes'
Answer

This issue can occur in CI environments (such as Bamboo) that have restricted permissions in the working folder where files or directories created outside the container might not be accessible inside the container. Before starting the container, give the working directory maximum permissions for allowing access to the user inside the Docker container.

chmod -R o+rwx ${bamboo.working.directory}
./dtcw generateSite

Another solution could be that you work on the same project with WSL and Powershell. In such an environment, the WSL environment creates temporary files which can not be modified via powershell.

In such a case, just delete the .gradle folder.

Q: I get an error stating that Gradle dependencies cannot be downloaded because a proxy is restricting internet access

Answer

Remember that dtcw is a wrapper around Gradle. So instead of calling this:

./dtcw generateSite

You could call this instead (remember to replace the values used in our example):

./dtcw generateSite -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=3128 "-http.nonProxyHosts=*.nonproxyrepos.com|localhost"

(IP, port, etc. just an example)

For more information about Gradle proxy configuration, read this article.