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-19 11:50:09

On 10/19/2011 5:41 PM, Matias Capeletto wrote:
> On Wed, Oct 19, 2011 at 1:10 AM, Joel de Guzman <djowel_at_[hidden]> wrote:
>> Well, let's see the numbers. Matias, do you have the number of
>> Quickbook+Doxygen docs available? If there's a high number of
>> Dox+Qbk, then I have to conclude that Quickbook now is too tied
>> to DocBook/Doxygen to be practically decoupled from its backend.
> 
> I updated the documents format page with a survey of what is being
> used in the reference section of each doc (again, this was a manual
> inspection but the numbers should be close enough).
> 
> Reference section format
> 
>   Total              98
> 
>   HTML             31
>   Quickbook      25
>   Doxygen         23
>   Boostbook      13
>   rst                   6
> 
> A typical example of a Quickbook+Doxygen doc is Boost.Xpressive
> http://www.boost.org/doc/libs/1_47_0/doc/html/xpressive.html
> 
> The link between the Quickbook docs and the Doxgygen generated ones
> are through Boostbook. In Quickbook, there will be definition like
> this one that will be reused in the tutorial sections:
> 
>   [def _basic_regex_           [^[classref
> boost::xpressive::basic_regex basic_regex<>]]]
> 
> Apart from this, it seems that the Doxygen generated docs are just
> generally pasted at the end of the Quickbook docs.
> 
>> What's the implication of this? Well, we'll be forever tied to the
>> nasty DocBook tool chain.
> 
> LaTeX is a standard output for Doxygen. I think it is possible that he
> same kind of interaction that Boosters are using between
> Quickbook-Doxygen-BoostBook can be achieved under
> Quickbook-Doxygen-LaTeX. But  I am not very used to this toolchain.

That's a good point! Worth investigating.

> There is a big variety in Quickbook based references, a standard qbk
> templates library seems to be necessary if we want to sell Quickbook
> as a tool for C++ references. This template library may also help to
> interact with Doxygen anchors, by automatically give you the tools to
> make the definition links as Eric is doing manually for
> Boost.Xpressive.

Yes. You reminded us that the template system and that people have
written extensions using templates, can in fact help us to move
forward.

Thanks for the survey!

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