Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2011-10-19 09:41:59

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.

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.

Best regards
Matias