Re: [boost] [doxygen] CSS/Temple files for Doxygen

Subject: Re: [boost] [doxygen] CSS/Temple files for Doxygen
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-07-09 06:50:54

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]] On Behalf Of Daniel
Pfeifer
> Sent: Saturday, July 09, 2011 9:03 AM
> To: boost_at_[hidden]
> Subject: Re: [boost] [doxygen] CSS/Temple files for Doxygen
> 
> 
>  Am Freitag, den 08.07.2011, 13:18 +0200 schrieb Rene Rivera
>  <grafikrobot_at_[hidden]>:
> > On 7/8/2011 10:29 AM, Paul A. Bristow wrote:
> >>> [mailto:boost-bounces_at_[hidden]] On Behalf Of Artyom
> >> Beilis
> >>> I mean I want to Boostify this:
> >>>
> >>> http://cppcms.sourceforge.net/boost_locale/html/index.html
> >>>
> >>> So it seems to me that I'll need to hack Doxygen styles a little to
> >>> make them more "Boosty"
> >>
> >> I know you don't want to hear this, but IMO re-factoring your (very
> >> nice) docs into Quickbook is the only way to get it more Boosty (but
> >> with the Doxygen reference section - and an index).
> >
> > I highly recommend moving to the regular Boost documentation
> > toolchain. Not only do you get the look & feel. But you also get the
> > benefit of inclusion with the rest of the libraries that produce
> > BoostBook documentation. Hence increasing the exposure of your library
> > to users. When the SF file download stats come back, you might want to
> > look at the count for the PDF docs to give you and idea of the added
> > exposure.
> 
>  Actually neither Quickbook nor BoostBook is strictly required for a  consistent look and feel of
the
> generated HTML and PDF files.
> 
>  The common base is DocBook. Therefore, Boosty documentation may be  generated from any markup
> language that can somehow be transformed into  DocBook. This includes AsciiDoc, BoostBook,
> markdown, reStructuredText,  textile, HTML, LaTeX, Quickbook, and maybe more. Doxygen is not
(fully*)
> supported, unfortunately.
> 
>  Instead of hacking the Doxygen CSS files, you might also hack some XSL  files that allow Doxygen
XML
> output to be transformed into DocBook. This  would be a huge benefit for other projects too.

What you say is entirely correct, but ignores the maintainability benefits if everyone generates
their docs in the same way using Quickbook (with Doxygen reference section).   We need to consider
what happens when the original author stops maintaining, the fate of nearly all older Boost
libraries.

Quickbook is such an easy and yet powerful tool to use and works with any text editor (though
coloring is nice).

OK, setting up the toolchain is a PITA (but I fear so is any toolchain), but once one is over that
hurdle, writing the docs is a doddle.

Even a re-write of the Pool docs from html didn't take that long (and revealed some deficiencies in
the original). 'Automatic' conversion didn't really help much more than lots of cut'n'paste. (It
revealed that you need to know what the software does - and in places I didn't!)

Paul

PS Long term, a tool that *really* understands C++ like the Clang compiler should be able to
generate a better reference section than Doxygen which does impressively well considering but can
get confused).

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