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-17 07:55:09

Hello,

On Mon, Oct 17, 2011 at 7:35 AM, Joel de Guzman
<joel_at_[hidden]> wrote:
> 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.

I think this is a great idea, generating LaTeX documents from
Quickbook will enable a healthier documentation ecosystem. LaTeX is in
better shape compared to Docbook, specially in the tools available and
the generating chain. Having a very popular and hackable back-end will
also help a lot to finally achieve a common look and feel in all our
documentation, as people will have the option to directly use LaTeX if
they prefer that. It is not very friendly to write and maintain a
Docbook document by hand.

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

LaTeX has great tools for dealing with math content, and I do not
think that the templates doesn't let you switch to another backend. If
you needed this features anyway, encapsulating them with templates was
a good very wise move.

> Thoughts? Please, I don't need another "just use XXX or YYY
> instead of Quickbook" answer. As its original author, I too
> love Quickbook.

:)

+1 to anything that improves the health of the Quickbook environment.
For me, it is the simplest documenting language I have seen so far.
The signal-to-noise ratio is just impressive. The complex tool-chain
is one of the things that is holding it back.

For what is worth, here is a survey of where we are standing now with
the documentation formats used by boost libraries. As Boost 1.48,
there are 94 libraries and the formats used are:

  Total : 94
  Quickbook : 40
  Boostbook : 13
  HTML : 34
  Rst : 6
  Doxygen : 1

Most of the libs documented in HTML are relatively small, and a lot of
the author of the ones written with BoostBook had expressed in favour
of migrating to QuickBook a few years ago.

The complete list can be founded here:
https://svn.boost.org/trac/boost/wiki/BoostDocsFormats

Best Regards
Matias