Mark, Thats very smart I like it.
Regards Paul > -----Original Message----- > From: Mark Rotteveel [mailto:m...@lawinegevaar.nl] > Sent: 14 June 2018 16:05 > To: Chatter regarding Firebird documentation > Subject: [Firebird-docs] Experimenting with asciidoc / asciidoctor > > > 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/f butil_isql.adoc and https://raw.githubusercontent.com/mrotteveel/firebird-documentation/asciidoc-conversion-experiment/src/docs/firebirddocs/wireprotoco l.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 ------------------------------------------------------------------------------ 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
