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-18 23:46:43

On 10/18/2011 5:35 PM, Paul A. Bristow wrote:

> But surely documenting the classes, member functions and functions API is *part* of the task we are
> discussing?

My post might have come at the wrong time. No, I did not intend to
discuss specifics like classes, member functions and functions API,
Doxygen interoperability, or anything of "function". My target was
simply limited to:

1) Aesthetics: "The beauty of LATEX" and the maturity/power of
   LaTeX vs. DocBook.
2) The unmanageably *broken* DocBook toolchain and the need
   to decouple the Qbk backend as a way forward.

> So I really, really do want to see *a* way of helping authors to provide that information.  The
> Doxygen C++ code comments  /pre /post /param /tparam /returns provide it :  "source coupled
> documentation" as Rene Rivera dubs it.
> 
> I'm adamant that this requires a tool that 'understands' C++  (Gcc/Clang?) : that's all that many
> libraries are using Doxygen for.  
> 
> Some libraries do this using html or Quickbook tables, but that doesn't provide any link to the
> actual code, so the two can get out of step easily, and you can't warn about items that you haven't
> documented.  And it's even more hard and tedious work than writing comments in the code, so I would
> fault many of these libraries as being thin and/or incomplete on detail, if good on tutorial and
> examples. 
> 
> If you can accept the need for this, then it *is* part of the answer to your question.

Agreed. And these specifics can best be given a solution with a more
powerful and easily extensible Quickbook backend and toolchain. The
current one *is a mess!*.

> Quickbook already has some understanding of C++ - to process snippets.  If it had much more? ...
> wonderful!

Definitely.

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