Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-10-18 09:35:39

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Joel de Guzman
> Sent: Tuesday, October 18, 2011 12:08 AM
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] The beauty of LATEX
> 
> Yet, I value beauty as well. I'm sure you've seen the LaTex math. XeTex did it better with unicode
support.
> The support there is very mature and looks splendid!

OK - I'm fine with beauty too - and handling math is just nasty using current tools.
 
> To me, Doxygen is out of the question.

I'm not a fan of the Doxygen or its presentation either.

 >IMO, a C++ library is not just a bunch of Java-ish classes, member functions and functions API for
which Doxygen is designed for. 

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

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.

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

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]