Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

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

As a more complete example, you can also take a look at the 
jaybird-manual at https://github.com/FirebirdSQL/jaybird-manual

Its build automatically published to 
https://firebirdsql.github.io/jaybird-manual/jaybird_manual.html

Mark

On 14-6-2018 16: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 
> 


-- 
Mark Rotteveel