Re: [boost] Documentation Redux (was Re: Boost 1.36.0 releasenotice)

From: Bjørn Roald (bjorn_at_[hidden])
Date: 2008-08-18 18:18:34

John Maddock wrote:
> 4) The only drawback I see, is the difficulty of one library 
> linking/referencing to another, I guess it would be possible to 
> generate a Docbook file containing just the link URL's to all the 
> libraries sections that could be included and referenced?  Don't know 
> if it's worth the hassle though?

I have done exactly that on other docbook based documentation.  But I 
think the primary goal then was to allow XML validation of idref --> id 
consistency without pulling in the whole project.  It worked Ok and I 
think it was a simple XSL script that pulled out all the tags with id 
and some minimal context such as related titles into a small index file 
for each section.  Then each section used a dummy wrapper referring all 
those indexes rather then the real sections surrounding it.  The 
generated index was also useful for work in tools like XMLMind or OXygen 
which provide nice author features for those allergic to XML text.  If 
you generate your document with the  stub, all your links to other 
sections take you into the index of that section.

For external url based links the same approach may be useful, but it may 
be nicer to have a daily special purpose server building all the docs 
with custom processing which expose additional information useful for 
authors that is noise to readers.  That way a standard web browser can 
be used to find information you need in a simple way.  

-- 
Bjørn