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
------------------------------------------------------------------------------
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
