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),
That would be a very good thing.
> 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.
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.
(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.
> - 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.
> 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.)
Anyway, I'm very interested!
Cheers,
Paul
--
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
