Skip to main content

Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Eclipse Projects » Eclipse Titan » Titan documents migrated to asciidoc
Titan documents migrated to asciidoc [message #1794476] Fri, 31 August 2018 07:05 Go to next message
Elemer Lelik is currently offline Elemer LelikFriend
Messages: 1120
Registered: January 2015
Senior Member
Dear all,

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

• The TopLevel.adoc contains the list of all included files (chapters)

For HTML output, links to the rest of the chapters are listed:

 == Contents

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

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

Prerequisites: Ruby (1.9.3 or higher; 2.2.x recommended) and a few Ruby Gems installed (
•	$ 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
Re: Titan documents migrated to asciidoc [message #1795278 is a reply to message #1794476] Wed, 19 September 2018 18:11 Go to previous message
Harald Welte is currently offline Harald WelteFriend
Messages: 128
Registered: July 2017
Location: Berlin, Germany
Senior Member


For those who are wondering about why: The big advantage for any project maintaining their documentation this way is that you get readable/usable git commit log information. So like changes to source code, you can now see in the unified diff who has changed what, together with a (hopefully) meaningful commit log message.
Previous Topic:Limitation on TTCN support.
Next Topic:Timer not started in the context.
Goto Forum:

Current Time: Wed Jun 23 16:09:38 GMT 2021

Powered by FUDForum. Page generated in 0.02494 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software

Back to the top