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
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Firebird-docs mailing list
Firebird-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/firebird-docs
