during the second half of August we have started to migrate our documentation, so far published in Word doc/docx or Adobe pdf formats,
to asciidoc.
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.
Asciidoc howto
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:
• asciidoc-preview
• language-asciidoc (for syntax highlighting)
• autocomplete-asciidoc
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
Date: 2018-06-18
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
:revdate: 2018-06-18
:title-logo-image: images/titan_logo.png
:toc:
• The TopLevel.adoc contains the list of all included files (chapters)
For HTML output, links to the rest of the chapters are listed:
== Contents
ifdef::env-github,backend-html5[]
* link:1-introduction.adoc[Introduction]
* 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]
* link:7-references.adoc[References]
* link:8-abbreviations.adoc[Abbreviations]
endif::[]
For non-HTML output (PDF); the asciidoc include mechanism is used. The output will contain the content of all the other chapters.
ifndef::env-github,backend-html5[]
include::1-introduction.adoc[]
include::2-test_ports.adoc[]
include::3-logger_plug-ins.adoc[]
include::4-encoding_and_decoding.adoc[]
include::5-mapping_ttcn3_data_types_to_c++_constructs.adoc[]
include::6-tips_&_troubleshooting.adoc[]
include::7-references.adoc[]
include::8-abbreviations.adoc[]
endif::[]
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
Best regards
Elemer
]]>