From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-29 16:13:48
Douglas Gregor said:
> On Tuesday 29 October 2002 10:31 am, William E. Kempf wrote:
>> Douglas Gregor said:
>> > 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 don't think so. What you have posted is very understandable and
produces useful documentation. I can definately see using that to
automate at least some of the documenation that I'm currently just cut and
pasting from the HTML templates I created for Boost a while ago. The
problem (if there is one) is in produce the rest of the documentation,
especially indexes, citations, references, etc. I believe DocBook could
solve all of those issues, but it's complexity is daunting, and may make
it a non-candidate for Boost.
>> I'm very interested in this, regardless. So maybe some of us should
>> collaborate on our research and findings?
Should we move the discussion off line, then?
-- William E. Kempf
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk