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

[Paul B. <pb...@ma...>]

Mark,

Thats very smart I like it.

Regards
Paul

> -----Original Message-----
> From: Mark Rotteveel [mailto:ma...@la...]
> 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
Fir...@li...
https://lists.sourceforge.net/lists/listinfo/firebird-docs