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.
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.
> > 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.
-- Mateusz Loskot, http://mateusz.loskot.net
Geometry list run by mateusz at loskot.net