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-17 13:24:36

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Mateusz Loskot
> Sent: Monday, October 17, 2011 11:41 AM
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] The beauty of LATEX
> 
> On 17 October 2011 08:55, Matias Capeletto <matias.capeletto_at_[hidden]> wrote:
> > 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
> 
> I think this numbers are a bit biased.
> Boost.Asio, for instance, generates documentation from Doxygen comments and uses QuickBook for all
> the rest, it is non-code-comments content.

It also does not take account of nearly all new and upcoming libraries, most of which use Quickbook *and* Doxygen  (and Autoindexing).  And also that the biggest libraries, like Boost.Math, use Quickbook.

I see a major weakness of Boost documentation is that documentation is rarely updated to reflect, for example, user experience.  Establishing a 'standard' portable way of preparation is one factor in making it easier to new maintainers to also maintain the documentation.  (Using a proprietary tool, like DreamWeaver might make initial documentation easier, but it makes collaborative working nearly impossible). 

I also suspect we are focussing too much on appearance.  Function first! But beauty is also in the eye of the beholder - and I don't share the 'yetch' reaction of some to the current PDF appearance.  We could (we have!) spent a lot of time fruitlessly opining about what is most beautiful.

IMO it is *content* that is most important, which I why I am so keen on using a tool, for example Doxygen, for helping to automate the documentation of what classes and functions do, what parameters (and template parameters) do, what their pre and post-conditions are, when functions return, if and when they throw exceptions or return error code.  A tool that can examine the information provided and warn which bits are missing is especially encouraging to nag authors to document fully.  I don't care which format this documentation is in, but Doxygen's comment syntax seems as good as any, and it understands C++ well enough to work OK with C++.  These documentation-as-comments could equally well be processed by another tool that knew C++ better, perhaps an output from a Clang-derived tool? 

(Much of the opposition to use Doxygen is that some believe that you just chuck the source code into it, and it does everything.  This is a complete delusion:  the author must document what each function does, what parameter are etc.  It's tedious work, but without that the output is just an outline of the overall C++ structure and lists of classes etc).

 So far, there are *no* libraries that use Doxygen comments *fully* to document what things need and do, not even, for example, the very nice (and big) Boost.Units which only has a bare C++ reference section, with no guidance on parameters, template parameters etc.  As a user I found that seriously lacking and fell back on the text and examples.  John Maddock and I have put some work into updating the small Boost.Pool library documentation with complete (enforced by Doxygen) documentation of all functions, class parameters...  but it has yet to be released.  (Doing it retrospectively was hard work, and required more knowledge that I have - documenting when writing is better?)

I also think we should build in a requirement for *indexing tools*.  How many times have you known that the meaning of a parameter or macro is documented somewhere is Boost - but can't find it?  I've found myself searching whole PDF documents!   (And you even can't do that with HTML, of course)  Pity then the poor newcomer to the library who doesn't even have any 'senior-moments' remembrance of what is there.  Tables of contents are vital, but *indexes are also essential*.

For writing documentation, I *really, really* like Quickbook.  It does the easy bits intuitively, and still allows one to do much more fancy things.  And many of the *fancy* things are really crucial to providing information in the format users expect.  We must have Greek, Math squiggles and formulae, diagrams, flow charts, C++ structures. Templates have proved absolutely vital for this in my experience in documenting several large libraries.  

The current Quickbook/Doxygen/autoindex/PDF toolchain is almost absurdly complex, but it works.  It's the devil some of us know - but as a whole Toolchain, it isn't documented well.

If some other toolchain (or even a single tool) can meet the needs for *content* and *indexing*, and yet be prettier, I'm all for it, but I have an "if it ain't broke, don't fix it" feeling. 

But whatever is devised and chosen, I think it should be made 'Standard' for all Boost documentation.  This might trigger a revision of existing documentation?

Paul

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