I like the result - html docs looks really cool.
Also, I think it is more suitable for the translation.

Do you have PDF version to take a look at?

Alexey Kovyazin

On 14.06.2018 17:04, Mark Rotteveel wrote:
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

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




(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

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

Reply via email to