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: 807
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: 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
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: 48
Registered: July 2017
Location: Berlin, Germany
Member

Congratulations!

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.
Goto Forum:
  


Current Time: Tue Sep 25 02:01:12 GMT 2018

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

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

Back to the top