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-19 09:08:54

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> John Maddock
> Sent: Wednesday, October 19, 2011 9:20 AM
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] The beauty of LATEX

> 1) What's the issue with XEP produced PDF's

I'm also puzzled by some 'yetch' reactions to the PDF versions.  Can anyone be more specific about
what they dislike about the appearance (the content is pretty much identical to the HTML)?  Is it
the font?  Or?

> 2) I suspect that folks are using Doxygen+Quickbook because (a) they're familiar with Doxygen, and
(b)
> there's nothing better currently available.
> That said I'm no fan of Doxygen (even in conjunction with quickbook), and personally prefer the
control
> you get with manually quickbook'ed docs.

John is quite right that you can get much finer control of manually written docs.

I suspect that the reason for strongly differing views on Doxygen is purpose.

I see Doxygen/Quickbook useful for providing a *C++ Reference* - where automatic production , C++
source-linked accuracy and thus *completeness* are the key requirements.  Size and space are not
relevant - we are not going to print it.

For text section 'tutorial' and examples, doing it by hand is essential : Doxygen is no help here.

Users need *both* - they will probably jump straight into the examples to find one that looks close
to what they want to do, and try it, then they may need to RTFM using the manually written
text/tutorial description, but if all else fails they will consult the C++ reference section,
probably via the index.

If the user starts by knowing the name of the function or class, the index should get you to all of
the text/tutorial, any examples, and the C++ reference info.

Paul

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