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

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

On 16-6-2018 15:42, Paul Vinkenoog wrote:
>> 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
> 
> I'm skeptical about that. People can write in plaintext if they want
> and let the doc team take care of the rest. I can't remember if this
> has brought us even one contribution. Maybe.

I didn't even know that (but then again, I didn't actively search for 
that). Is that mentioned on the site somewhere?

> That said, I have nothing against a simpler syntax.
> 
>> - More readable
> 
> Absolutely.
> 
>> - Wider support in tools
> 
> Than what? DocBook? And in how much would this benefit us? I mean,
> you only need one good set of tools that render the docs the way you
> like them.

I actually mean support in (free) editors, eg there is AsciidocFX, 
plugins for IDEs and editors, including preview support

> (Please notice that these questions are not meant rhetorically; I
> really want to know. Anything that makes our life simpler while still
> producing quality output I'd welcome!)
> 
>> Cons:
>> - Some of the more semantic features of docbook are not supported by
>> asciidoc (but we don't really use those AFAIK).
> 
> One thing I wonder is if AsciiDoc supports automatic index building,
> as DocBook and our tool chain do. This is extremely helpful. See e.g.
> our Quick Start Guides and the Firebird Null Guide.

You can mark index terms in the document just like in docbook, see 
https://asciidoctor.org/docs/user-manual/#user-index and for the PDF 
this can build an index for you (if you declare an index section), this 
hasn't been done for html output (yet).

Then again, I hardly ever use an index in non-print. I usually just 
search (which is harder with multi-page docs like Firebird's HTML docs 
though).

There are also tools like Antora, but that is for building integrated 
documentation sites, including an online search (eg see 
https://docs.antora.org/antora/1.0/). Antora uses asciidoc, but requires 
a specific structure/organization of files to be able to generate the 
documentation site as linked). Could be interesting for the Firebird 
project, but I'm not sure if that is worth doing.

>> - Tools for asciidoc are simpler (compared to - for example - XMLMind;
>> might be a pro)
> 
> Yes, although the good thing about XMLMind is that it doesn't allow you
> to produce invalid XML, whereas if you screw up your AsciiDoc I don't
> know what the effect on the output will be and if you'll notice your
> error in a very big document.

With the preview support in most editors that is actually less of a 
problem, and in my experience (both with the Jaybird manual and at 
work), render errors due to markup problems are usually pretty localized 
(unless you forgot to close a table).

>> The two HTML renderings can be found on
>> https://mrotteveel.github.io/firebird-documentation/
> 
> Overall, it looks good; certainly not worse than our current HTML.
> There are some things I don't like, but that's a matter of editing
> the stylesheets.
> 
> I don't like the PDF. It looks too much like HTML copied into a book.
> (I don't know if this is a good argument - probably not - but it just
> doesn't "look right" to me. A well-rendered PDF can and should be much
> more pleasant to read.)

Compared to the existing Firebird PDFs, I think the biggest difference 
is a slightly smaller margin, a different font, no page header with the 
current section title, and no page break on a new section.

That is - I think - a matter of tweaking the theme, and otherwise there 
is always the option - at build time - to transform asciidoc to docbook 
(version 5 or 4.5) and use another rendering pipeline (asciidoc can be 
considered a subset of docbook, except not XML).

In any case, think it over.

For now I'll try and rewrite the existing ant build to gradle.

Mark
-- 
Mark Rotteveel