From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-10-29 15:21:22
On Tuesday 29 October 2002 10:31 am, William E. Kempf wrote:
> Douglas Gregor said:
> > I looked at DocBook a bit, but I'm no expert in it. With DocBook alone
> > we can't express our reference documentation by the C++ code structure
> > and end up with a useful document.
> You can't? I'm not a DocBook expert, as pointed out in another posting.
> But I thought the DocBook structure was specifically open ended enough to
> allow for complex structures similar to what we need?
Sorry, my claim may very well just be FUD. I'll research DocBook more before
drawing such a conclusion.
> > The answer is probably to use both. The overall document structure comes
> > from DocBook, but the nitty-gritty C++ reference details are specified
> > with some simple C++ declaration/documentation DTD and transformed into
> > DocBook.
> Sounds like a reasonable approach. My concern is still the complexity,
> however. Developers make lousy enough documentors as it is. Make it more
> difficult for them to write the documenation and I bet you'll see the
> quality go down even more. Not to mention you may very well scare away
> some potential Boost submissions if we require them to use this stuff,
> even if it stems solely from FUD and not fact.
My hope was that if reference documentation is centered around C++ structure
(which developers know), with tags clearly specifying what information they
should give (return type, function parameters, template arguments,
requires/effects/postconditions/throws/etc. clauses), it would become easier
to write reference documentation. Maybe that's just wishful thinking :)
> I'm very interested in this, regardless. So maybe some of us should
> collaborate on our research and findings?
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk