during the second half of August we have started to migrate our documentation, so far published in Word doc/docx or Adobe pdf formats,
Titan core and Eclipse plug-ins documents have been already pushed to github, together with asciidocs for over 70 associated products.
The rest will be finalized in the coming weeks.
Please find below a short set of instructions for asciidoc documents.
1. As asciidoc files are simple text files, any text editor can be used; however we recommend Atom, which is also being used internally in github and includes git/github integration.
The below packages will make it easier to work with asciidoc:
• language-asciidoc (for syntax highlighting)
2. Document structure
For syntax quick reference, see: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
• Smaller documents (<100 pages) are deposited in a single file, larger documents (>100 pages) consist of multiple files.
• In case of multiple files, a TopLevel.adoc is used as an index page.
• Document heading and metadata:
The documents have a YAML frontmatter containing metadata for GitHub:
Author: Jen┼æ Balask├│
Version: 6/198 17-CRL 113 200/6, Rev. PE1
and also a header of asciidoc metadata attributes for PDF:
= API Technical Reference for TITAN TTCN-3 Test Executor
:author: Jen┼æ Balask├│
:revnumber: 6/198 17-CRL 113 200/6, Rev. PE1
• The TopLevel.adoc contains the list of all included files (chapters)
For HTML output, links to the rest of the chapters are listed:
* link:2-test_ports.adoc[Test Ports]
* link:3-logger_plug-ins.adoc[Logger Plug-ins]
* link:4-encoding_and_decoding.adoc[Encoding and Decoding]
* link:5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc[Mapping TTCNΓÇô3 Data Types to C++ Constructs]
* link:6-tips_&_troubleshooting.adoc[Tips & Troubleshooting]
For non-HTML output (PDF); the asciidoc include mechanism is used. The output will contain the content of all the other chapters.
3. Converting to PDF
For this we have used asciidoctor-pdf (see https://asciidoctor.org/docs/asciidoctor-pdf/)
Prerequisites: Ruby (1.9.3 or higher; 2.2.x recommended) and a few Ruby Gems installed (https://asciidoctor.org/docs/asciidoctor-pdf/#prerequisites)
• $ gem install --pre asciidoctor-pdf
• $ gem install coderay pygments.rb (optional, for syntax highlighting, if needed)
To start conversion, enter this command:
• $ asciidoctor-pdf --attribute skip-front-matter <filename>.adoc
(if the document consists of multiple files, convert only TopLevel.adoc, it will include the rest of the files as well)
To set the name of the generated file, use:
• $ asciidoctor-pdf --attribute skip-front-matter <filename>.adoc o <outputfilename>.pdf
4. Tips and tricks
• In some cases, PNG images are not included and an error message says wrong interlace method.
o Solution: deinterlace with ImageMagick
$ convert -interlace none interlaced.png uninterlaced.png