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
