Hello,
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?
Regards,
Alexey Kovyazin
IBSurgeon
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
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
------------------------------------------------------------------------------
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
