RE: [boost] Re: Reference documentation: one approach

From: David Bergman (davidb_at_[hidden])
Date: 2002-11-01 19:45:23

After playing around a bit with DocBook, it does not seem too bad (even
for a TeX-guy, like myself...)

Is it still valid that we need some tool that extracts in-document
comments and source structure, to merge with hand-written documents?

If so, there is a choice of merge route:

DocBook produceConcurrently() {
        // Use the source code and high-level specification as input to
Synopsis (or Doxygen)

        SourceCode sourceCode = CVS.updateSource();
        DocBook highLevelSpecification = Developer.writeSpecification();
        DocBook lowLevelSpecification =
Synopsis.extractSpecification(sourceCode);

        // Combine the hand-written and automatic parts 

        XSL combinerStyle = Boost.getStandardCombiner();
      return Xalan.mergeDocuments(highLevelSpecification,
lowLevelSpecification, combinerStyle);
}

DocBook produceSequentially() {
        // Use the source code to produce a low-level specification,
which is then refined

        SourceCode sourceCode CVS.updateSource();
        DocBook lowLevelSpecification =
Synopsis.extractSpecification(sourceCode);
        return Developer.refineSpecification(lowLevelSpecification);
}

And, of course a choice of generating final output from the DocBook
specification (among other uses for the DocBook document, such as
Boost-global cross-referencing):

PDF renderViaFO(DocBook specification) {
        XSL xslfo = dbx2pdf.produceXSLFO(specification);
        return pdfSpecification = ApacheFOP.renderPDF(xslfo);
}

PDF renderViaTeX(DocBook specification) {
        TeX texSpecification = db2tex.produceTeX(specification);
        return pdftex.renderPDF(texSpecification);
}

/David

-----Original Message-----
From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]] On Behalf Of Douglas Gregor
Sent: Friday, November 01, 2002 4:43 PM
To: Boost mailing list
Subject: Re: [boost] Re: Reference documentation: one approach

On Friday 01 November 2002 01:55 pm, David B. Held wrote:
> P.S.  I like the documentation discussion, but hope that some 
> consensus is reached soon, so I know what tools to look for and learn.

It looks like it will be either DocBook or LaTeX, but we won't know
until we 
have prototypes each and can make an informed decision. We don't want to
make 
the wrong choice here, because it will require a significant amount of
effort 
for developers to change to a new documentation style (we _don't_ want
to do 
it twice).

FWIW, the LaTeX prototype would have to be pretty amazing to get my
vote. I've 
been using DocBook as the target of the my own prototype and have found
it to 
work very well. DocBook is a good intermediate format, because it is
easy to 
parse, generate, and transform. 

        Doug
_______________________________________________
Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost