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

[Alexey K. <ak...@ib...>]

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