Geometry Boost List: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook

Subject: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook
From: Mateusz Loskot (mateusz)
Date: 2010-09-04 08:23:05

On Sat, 2010-09-04 at 11:27 +0200, Barend Gehrels wrote:
> > Perhaps I owe some explanation, especially to new folks on the
> > list: mentioned XSL-based generate of Quickbook documentation has been
> > stolen from Boost.Asio and customised (work still in progress) for
> > Boost.Geometry.
> 
> Sure, it was (or seemed) basically a good idea. And there is also an XSL 
> process to translate Doxygen to BoostBook (instead of QuickBook) within 
> Boost. The last one is not our choice because we want QuickBook. The XSL 
> in general is hard and in some cases limited (AFAIK), and besides that 
> most C++ programmers do not have all XSL skills. At last I don't.

Barend,

Theses are very good points indeed.
I'm not a die hard for the XSL solution.
However, I think it's a good idea to follow path aligned, in general,
with Boost roadmap. The problem is, AFAIU, there is no official
roadmap for Doxygen to Quickbook.

> One of the things done here is e.g. the combination of 
> template-parameters and their concept descriptions, and the function 
> arguments and there descriptions. Will probably be hard in XSL.

For XSL zealot, should not be a problem.

> Another thing is outputing the headers and convenience headers, and therefore on 
> the fly parse another (header-inclusion) file, which is uncommon or not 
> possible in XSL.

Speaking of XSL approach, I think this should be done with Doxygen.
Then Doxygen outputs self-contained XML and XSL generates final output.

> On the other hand, the Doxygen ALIAS constructs I'm using now, and 
> QuickBook macro's (a similar thing), make all things more structured, 
> and less verbose in the sources (but more cryptic). They are new and can 
> probably also be processed by XSL, like they are now by RapidXML.

Sounds good.

> > Shortly, the question is: to (re)invent Doxygen to Quickbook generator 
> > or not.
> 
> Yes, that is a good summary. Stated as this it actually does not belong 
> to this mailing list, so I reformulate the question here as "to start a 
> Doxygen to Quickbook generator for Boost.Geometry or not?".
> 
> My opinion is that the RapidXML/C++ tool I drafted has less lines, is 
> more powerful, more readable and easier extendable than the XSL. 
> Actually, I can't make the docs, as they are looking now, without it. So 
> I advocate a yes on it. See also my answer to Luke about to make it more 
> generic than for Boost.Geometry alone.

Point taken and agreed.
Actually, as I've mentioned, the XSL approach is nothing official in
Boost. It has been incorporated by Boost.Asio as a custom generator used
within Boost.Asio only (AFAIK). So, having no official tools in Boost,
if Boost.Geometry finds its own way to make its docs well-looking and
well-incorporated with Boost documentation, I'm sure it's fine.

> Another question is:
> Do we still want to keep Doxygen HTML output or not.

Personally, I don't like Doxygen HTML output much
especially as a general purpose documentation.
It's a good API reference, but we are generating much more than that.
Boost Quickbook is way better.

Now, could you summarise how can I use your tool?
I'd like to start updating the docs content ASAP, so a bunch of
guidelines would help.

Best regards
-- 
Mateusz Loskot, http://mateusz.loskot.net