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-17 23:08:06

On 10/17/2011 9:24 PM, Paul A. Bristow wrote:

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

This is my first post on "beauty". Why do you think I am focusing
too much on appearance? Perhaps because of recent threads regarding
"rockstar" documentation? I am not involved in that thread, Paul.
This is an entirely new thread. Given my history on this list that
dates back to QuickDoc and QuickBook times many years ago, you will
see that I focus on function first before form.

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!

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

To me, Doxygen is out of the question. IMO, a C++ library is not just a
bunch of Java-ish classes, member functions and functions API for which
Doxygen is designed for. Then again, this is not my question.

[snip more Doxygen stuff]

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

Definitely! And a cleaner/easier tool chain will help. The LaTeX toolchain
is very mature in that area compared to DocBook.

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

Right. And Matias reminded me that the very fact that they are templates
means that they can be retargetted.

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

First, I am not trying to fix anything. I am proposing an "optional"
replacement. But yeah, I'd say that the XSLT/FOP is very broken. Some
very bright folks, John M included, got around the problems with some
workarounds, but the current state is very very fragile.

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

Let's not do a revolution, please. Evolution, not revolution.

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