[Firebird-docs] Experimenting with asciidoc / asciidoctor

[Mark R. <ma...@la...>]

I'm trying to modernize the build of the documentation by converting it 
to gradle (which should allow us to do away with manual setup and 
downloading of things, and may fix issues with more recent Java 
versions), but I got side-tracked into experimenting with asciidoc / 
asciidoctor (see https://asciidoctor.org/).

I was wondering how people think about migrating from docbook to 
asciidoc. Asciidoc is an "almost plain text" format that is used a lot 
these days for documentation (as an example, Hibernate and Spring 
switched from docbook to asciidoc), as its markup is a lot simpler and 
allows for editing with basic tools and is even - relatively - readable 
without having rendered it to HTML or PDF. It has been based on docbook 
(as originally asciidoc was converted to docbook before actually rendering).

Pros of asciidoc:
- Simpler, could lower bar of entry for contributions
- More readable
- Wider support in tools

Cons:
- Some of the more semantic features of docbook are not supported by 
asciidoc (but we don't really use those AFAIK).
- Tools for asciidoc are simpler (compared to - for example - XMLMind; 
might be a pro)

Conversion could be done document by document (Spring did that), that 
will probably complicate the setup, but would allow for spreading out 
the conversion.

I have converted two documents from docbook to asciidoc using 
https://github.com/asciidoctor/docbookrx, and fixed a number of obvious 
issues with features not supported by the converter. I haven't checked 
the documents fully, so it is possible some other things 'disappeared' 
or render incorrectly in this conversion. I have also enabled table of 
content rendering, otherwise all the defaults have been used (including 
default styles).

The two HTML renderings can be found on 
https://mrotteveel.github.io/firebird-documentation/

Sources are on 
https://github.com/mrotteveel/firebird-documentation/tree/asciidoc-conversion-experiment

Specifically (linking to raw, because otherwise GitHub renders asciidoc 
files):

https://raw.githubusercontent.com/mrotteveel/firebird-documentation/asciidoc-conversion-experiment/src/docs/firebirddocs/fbutil_isql.adoc

and

https://raw.githubusercontent.com/mrotteveel/firebird-documentation/asciidoc-conversion-experiment/src/docs/firebirddocs/wireprotocol.adoc

(switch extension to .xml to view the docbook sources)

Example of how GitHub renders it from the repository: 
https://github.com/mrotteveel/firebird-documentation/blob/asciidoc-conversion-experiment/src/docs/firebirddocs/fbutil_isql.adoc
-- 
Mark Rotteveel