Re: Recomended way of generating documentation

From: Robert Ramey (ramey_at_[hidden])
Date: 2020-01-01 15:32:21

On 1/1/20 4:03 AM, Richard Hodges via Boost wrote:

> 
>> And it's Doxygen to XML, XML to Boostbook. Then of course Boostbook to
> Docbook, and Docbook to HTML.

Doxygen to XML,  Renders Doxygen meta information in a form that it can 
be combined with something else.  Presumable this is done by some 
Doxygen defined magic.

XML to Boostbook - BoostBook is DocBook with a bunch of extra tags for 
handling C++ specific vocabulary types.  The hope would be that this 
extra "semantic" information would permit facilities like better 
generation of things like better cross reference information, better 
formating of C++ "things" - like typenames vs variable names, vs 
examples, vs ....  Boostbook can and does get created different ways: 
Doxygen, QuikBook, by hand, by XMLMind (in my case) and perhaps other 
ways I'm not familiar with. Not everyone actually uses BoostBook tags. 
Strictly speaking it is not necessary as it's an extension of DocBook.

BoostBook->DocBook (xslt) - converts the special boostbook tags to more 
generic DocBook tags.

DocBook -> html, pdf, etc.. (xslt, fop, ...) - renders the Docbook in a 
device specific format.

So the question is: Which of the above steps is superfluous?  Which do 
you think you can eliminated.  Or do you want to consolidate them to 
eliminate steps?  But composing the above steps is much simpler than 
than trying to do it in less steps.  Time spent to execute the above 
steps is not significant in the scheme of things.

> Other than the very pleasing boost documentation styling, is this seemingly
> convoluted conversion route necessary? Is it not possible to configure a
> Doxyfile to contain the correct styling?

I do not believe that Doxygen can be configured to capture semantics of 
much of C++ code to generated reference documentation.  And of course 
that doesn't even touch upon other necessary things like narrative, 
examples, references, illustrations, etc.

> I have no knowledge of the evolution of boost documentation and have no axe
> to grind, but as a newcomer it seems to me that there is a lot of
> 'unnecessary' compication in the production of documentation. 

Right.

 >> I appreaciate
> that there's no real sense in revisting existing libraries, but for new
> ones wouldn't it be prudent to choose the shortest possible path which
> involves the least learning and maintenance?

LOL - feel free to suggest another path.

Robert Ramey