1. Approach
Asciidoc or Asciidoctor is a proven system to write documentation, especially if part of sources should be included.
You can find also a nice explanation in https://www.dirkkoller.de/asciidoc
or also in https://www.baeldung.com/asciidoctor
Sources of Asciidoc (a .adoc file) can be edited with any plain text editor as well as for example in Eclipse (https://eclipse.org)
For translation I use
https://repo1.maven.org/maven2/org/asciidoctor/asciidoctorj/
in aproper version.
For a 'copy deployment' you can simple load a file such as
https://repo1.maven.org/maven2/org/asciidoctor/asciidoctorj/2.5.7/asciidoctorj-2.5.7-bin.zip
as zip file and unpack it manually in your own programs folder such as C:\Programs\Asciidoc,
also for linux, maybe in a local directory. Look an the batch or shell script contained there.
Because it is based on Java you can simple use it without operation system’s effort, only Java should be available.
You can translate it to html (first choice) but also to pdf (second choice) and some more.
2. Enhancement in srcjava_vishiaBase: Pre processing
Asciidoctor is a beautiful tool. But as in most of tools, not all is available as need.
2.1. Principle, invocation
set CP="-cp ../../../tools/vishiaBase.jar" set MAIN="org.vishia.tools.PrepareAsciidoc" set WD="-wd:D:/path/to/asciidoc" set IN="-in:dir/src.adoc" set OUT="-o:dir.gen/" set LI=-rlink:3:https://vishia.org -rlink:2:https://vishia.org/Fpga -rlink:1:https://vishia.org/Fpga/html -rlink:0:https://vishia.org/Fpga/html/Vhdl" java %CP% %MAIN% %WD%%IN% %OUT% %LI% -lmax:87
It is a java class inside the vishiaBase.jar available in some versionen after 2013-03-19
in the archive https://vishia.org/Java/deploy/.
It is also possible to write the call as
set CP="../../../tools/vishiaBase.jar" java -cp %CP% org.vishia.tools.PrepareAsciidoc --@%0:prep ::prep ## ::-wd:D:/vishia/Fpga/wrk_vishiaJ2Vhdl/src/vishiaJ2Vhdl/asciidoc/ ##working dir ::-in:Vhdl/Java2Vhdl_UserManual.adoc ## input file ::-o:Vhdl.gen/ ## output directory (file same as input) ::-lmax:87 ## max line length in pre blocks ::-rlink:3:https://vishia.org ## substituation of links ::-rlink:2:https://vishia.org/Fpga ::-rlink:1:https://vishia.org/Fpga/html ::-rlink:0:https://vishia.org/Fpga/html/Vhdl
This uses the feature to get the arguments from a file, here from the batch file itself
given with --@%0 after the label :prep
Then all arguments are written after a comment character sequence in the batch file also used for the label. Comments are also possible. it is better readable and changeable.
The arguments are explained with the features.
2.2. including sources.adoc
Including asciidoc sources is supported by asciidoc itself using
Note: because the pass capability does not work proper,
I have written jnclude instead include to outwit the Asciidoc itself for this article.
jnclude::path/to/file.adoc[]
with some options, see https://docs.asciidoctor.org/asciidoc/latest/directives/include/.
Because the PrepareAsciidoc should handle also all included files,
it does the include by itself and expands the included content in the output.
So the include::... lines are replaced by the included content, which is also prepared.
But if the inclusion capability is very important and interesting, it is enhanced with the possibility of chapter labels:
== chapter title jnclude::included.adoc[leveloffset=+1, chapter=chpLabelX..chpLabelY]
This syntax can be used to include all chapters from the given first label till inclusively the given last label in the document. For this example also an own chapter is planned, and the chapters in the document, which are also on level 2, are shifted in level as in the Asciidoctors original `pass[inlude::…] syntax.
If you want to include only one chapter you should only give its label.
jnclude::included.adoc[chapter=chpLabel]
But also maybe with the leveloffset=+1 designation if necessary.
2.3. shorten output in pre blocks
For html translation Asciidoctor produces an output form as you see in the following example:
This is any source code with a very long line because the developer writes too much in one line. //also some comments are following.
Usually, writing in long lines in sources is sensitive, because more non interesting things can be placed on end of this lines, for example all arguments for function calls. The advantage is, you need lesser lines, and an operation is able to overview on one screen side. A screen with 1920 pixel can be enhanced to more as 200 characters depending on the mechanical screen size and the used fonts.
But for documentation usual a width in html of about 80 characters is familiar and enough, if you want to see further content, you can shift the slider to the right.
But for pdf output such a slider window does not exists. The same is, if you want to convert your text in a word & co format. Thre are two solutions:
-
a) line break for the right content, continue in a new line in your output
-
b) Shorten, cut the right content, it is never visible in pdf.
The version a) is usual bad, because it disturbes the view to the essential. The essential may be the structure of a code snippet, blocks etc. The broken lines are very disturbing.
The variant b) can be seen as any time proper, because_
-
If you want to show important content in sources, you should write it left side oriented also for editing the sources.
-
Right side content should not so important to explain, only completes the code for proper compilation and functionality.
-
You can always write more as one line instead one long line in your code, except for command line scripts.
-
For command line scripts you should thing about shorten the line using variables, anyway else.
-
If you want to see the code exactly, you should visit the sources itself. Shown sources in documentation can anytime be seen as illustration for explaination, not as exact template. If it should be used as template, you can shorten it by the sources.
Hence the PrepareAsciidoc shortens all lines given as pre-text to the given length with the lmax=… argument.
If the line is longer than lmax, it is shorten to lmax-3 and thre points as ellipse are written on end
to document, it is shorten. Then you get a proper view also in pdf.
You can use the PrepareAsciidoc for html with a big value for 'lmax=9999' to prevent shorten,
use lmax=87 proper for pdf conversion.
To do it proper also for included sources, the PrepareAsciidoc includes the sources by itself
using the same syntax is for Asciidoctor to get the sources, search the tags, reads the lines and shorten it.
2.5. complete chapter nr
You can use a chapter link in asciidoc writing <<#label>>.
Then the chapter title is used as link. That is informell and proper.
But the chapter number should be also written there.
Compare to such tools as the known LaTeX or proper pdf documentations, the chapter number is presented.
I have not found a proper possibility for Asciidoctor which supports it.
Hence PrepareAsciidoc gathers first all chapter designations (==…== on line begin)
and builds an index with the label before ([#label]) and the built chapter number by its own count.
Then all chapter numbers are pad before the chapter link.
This is done unconditionally, because it is always proper.
2.6. replace relative with absolute link
It is a good idea for html content to have relative links:
link:../../parallelDir/xyz.html#Label[xyz chapter Label]
If the html is generated to a proper location, the relative link is proper and the html files can be visited without problems on a local hard disk also without internet connection. Working without internet connection maybe sometimes an important option, for example if you read documentation on notebook traveling in a train or outside living rooms.
But for a pdf this is not suitable, because the pdf is usually copied independent without regarding relative relations to other files. Hence it should have absolute links to the internet in a readable format, which allows also search the proper files locally or anyway other.
The PrepareAsciidoc allows to replace some link:../… designations replace with given absolute links.
The absolute links are given by command line options, for example:
-rlink:3:https://vishia.org -rlink:2:https://vishia.org/Fpga -rlink:1:https://vishia.org/Fpga/html -rlink:0:https://vishia.org/Fpga/html/Vhdl
The number after -rlink: is the number of ../. rlink:0: means replacing a link in the current directory.
Note, intrinsicly -rlink:https://vishia.org/Fpga/html/Vhdl is sufficient, because all other can be formally derived.
TODO change in next version.