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


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

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!


Check out the vibrant tech community on one of the world's most
engaging tech sites,!
Firebird-docs mailing list

Reply via email to