Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Joel de Guzman (joel_at_[hidden])
Date: 2011-10-17 23:37:09

On 10/18/2011 4:31 AM, Daniel James wrote:
> On 17 October 2011 06:35, Joel de Guzman <joel_at_[hidden]> wrote:
>>
>> To be honest, I've been quite disappointed with DocBook and its
>> ugly hack (tool chain) at generating PDF files.
> 
> O'Reilly use docbook for all of their books, although they might use
> commercial software for generating the final book. I'm not sure. But
> it is possible to get decent results from docbook. I've never spent
> much time looking at pdf generation.

O'Reilly uses a slightly modified version of the DocBook
language to author their content, then they feed this XML
into custom scripts that integrate with Adobe FrameMaker
to layout their books.

The current state is a very fragile conglomeration of stuff
that barely work. "From the quality point of view the other
products are way behind LaTeX" says this comment on:

  http://stackoverflow.com/questions/796201/latex-vs-docbook

and I agree! And in that "LaTeX vs DocBook" discussion, the
best point *for* DocBook is the document structure and the
nice separation of content and presentation. It turns out that
QuickBook, being designed after DocBook, is in a nice position
to have the best of both.

>> Anyway, I guess if it still goes through the complex XSLT tool
>> chain, I'll still have my doubts. Another way is to decouple
>> the back-end of quickbook to allow it to directly generate
>> HTML, or LaTeX in addition to Docbook. Quickbook started out
>> generating HTML anyway and it should be reasonably doable to
>> refactor the code, decoupling the output generation. The only
>> problem I see is that some folks (e.g. John M), have written
>> Quickbook templates that leverage more advanced features of
>> DocBook. Those DocBook targetted templates obviously won't work
>> with a different back-end. Me, I avoided writing such templates
>> and going directly to DocBook because I didn't want to lose the
>> possibility to have Quickbook retarget another back-end.
> 
> It's certainly doable, the spirit 2 fork of quickbook had a half
> written html generator (it didn't do chunking and missed a few
> features). The feedback wasn't particularly positive which is part of
> the reason that it's the only feature I haven't ported back yet. The
> implementation of the current quickbook is quite different though, the
> spirit 2 version was very static, while the current version uses a
> more dynamic data structure (along similar lines to utree), so it
> isn't just a case of copying the implementation over. Generating latex
> would be a bit trickier.

I like the idea of having an IR (ala utree) to represent the
structure. It's a very positive move, IMO.

> There is another problem, much of the current documentation based on
> doxygen + quickbook make use of tags like 'funcref' and 'classref' to
> link into the doxygen documentation, a replacement would need
> something to support that. I haven't really thought about doing that
> in quickbook, could possibly add some sort of anchor for language
> reference types, would need to build in some sort of namespace
> resolution, and maybe a way to identify the language type (could just
> use the source mode?). I'm not sure if it'd be a good idea.

This is the ugly bit that I utterly dislike :-(. IMO it's a
turn in the wrong direction. I don't see any reason why these
can't be user defined templates instead of intrinsics. In fact
we should convert as much markups as we can into Qbk template
libraries. Less is more! My real goal a long time ago was to
simplify Quickbook and the first step towards that was to move
a big chunk of the feature set in a qbk "standard" template
library.

The doxygen features you mention could very well be separated in
a doxygen qbk template library. It should be *optional*. Non-
Dox users, like me and Rene, should not be forced to have
Dox features down our throat.

Regards,
-- 
Joel de Guzman
http://www.boostpro.com
http://boost-spirit.com