On Monday 03 February 2003 03:07 am, Vladimir Prus wrote:
> Douglas Gregor wrote:
> > With Jeff Garland's Doxygen XML test data, I've started to build a
> > Doxygen XML->BoostBook translator. The XSL stylesheets are in the
> > sandbox, in the directory libs/documentation/boostbook-xsl/doxygen. There
> > are two stylesheets:
>
> Doug, I've tried it and it works.
That's a good sign :)
> The first obvious problem
> I've noticed is that I get
>
> bool at_option() const;
> Notes:
> Tells if the current element is option.
>
> While in fact the doc comment from source is closer to "Effects".
This is a good point. Without the user stating specifically what the text
means (e.g., preconditions/postconditions/throws/effects/notes), I can't put
it in one of those categories. So the XSL now handles loose <para> elements
(to eventually be placed into a <description> element), and the
Doxygen->BoostBook translation no longer puts everything in "notes".
I know Doxygen does have some of the clauses (e.g., returns). I'll work on
getting those mapped properly Real Soon Now (TM).
> There are
> some other nits, like missing class docs, but in general this is a good
> start.
Missing class docs problem fixed in CVS. I can't believe I missed that... If
you have any more nits, please post them. It's the only way I can fix bugs.
> BTW, I wonder if there's agreement on how Doxygen will be used. I think
> that the most reasonable way is to have a top-level in BoostBook, with
> selective inclusion of Doxygen fragments. I mean that it's probably not
> necessary to convert Doxygen output into complete BoostBook file. What is
> needed is the ability to include docs for a single class in an arbitrary
> place of the documentation. Do others feel the same? In that case there's
> no need to care about doxygen's separate doc pages, etc.
>
> - Volodya
I mostly agree.
I agree that the Doxygen->BoostBook XSLT probably won't create complete
BoostBook documentation. Overview documentation, tutorials, FAQs, etc. I
would expect to be written directly in BoostBook (DocBook, really); Doxygen
XML and the resulting BoostBook would be responsible for everything in the
<libraryreference> tag, e.g., the documentation of headers, classes,
functions, etc. So my disagreement is that I do not believe we should be able
to include docs for a single class at an arbitrary place in the
documentation. I think that documentation of _all_ types/functions for a
library should stay in one place, so we have a complete reference section for
each library.
Part of the reason for my pickiness is that I'm trying to give the BoostBook
reference material the same "feel" as the C++ standard. I plan to provide
options in the stylesheets to select a specific set of libraries for
transformation and to process only reference documentation. So, for instance,
a user could say "build a PDF of the reference documentation for Function and
Bind", perhaps with a bjam invocation such as:
bjam pdf -sLIBRARIES="function bind" -sSECTIONS="reference"
By forcing developers to keep the reference material together, it forces them
(err, us) to keep the reference material consistent. My dream would be that
we could generate library proposals with just a few switches passed to the
XSL stylesheets :)
Doug
-------------------------------------------------------
This SF.NET email is sponsored by:
SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See!
http://www.vasoftware.com
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
