RE: [Boost-docs] TOC's, Articles, and Docbook sets

From: Jeff Garland (jeff_at_[hidden])
Date: 2003-03-02 18:39:17

> > match.  Using the docbook-xsl-1.60.1/onchunk.xsl to transform to html
> > creates a nice TOC with the proposal in a single html file.
> 
> Does this do a better job than the BoostBook html-single.xsl? 

Don't know, I'll have to try html-single.xsl.  I didn't see that...
 
> > in a combined set of docs.  I'm wondering if there would be some
> > advantage to in converting to a docbook book for each library?
> > I haven't done any experiments, so I'm hoping someone with more
> > experience with docbook will make suggestions here...
> 
> The only advantage I can see of using a set (I haven't tried!) is that it will 
> give us another level in the hierarchy. Things can get pretty deeply nested 
> in library documentation, and there is a warning that some processing systems 
> act badly when there are many nested sections (I can think of one example: 
> HTML only has <h1> to <h6>, no further). Anyway, I'll try it out sometime.

I was thinking there might be special treatment that the standard
docbook scripts give to book/chapter level sections.  Not sure
what that might be, hence the question.  One thing I am a bit
leery of, however, is that I don't think I want to start writing
docs with 'chapter' divisions b/c I think that means that it must
be used within a 'book'.  The nice thing about 'section' is that
it just fits in at whatever level it happens to be included.
 
> > 2) How many levels of TOC?
> > ...
> > I've figured out that we can set toc.section.depth parameter
> > when using the docbook scripts.  If we need to set these
> > types of parameters we will either need to do this as a
> > set of command line parameters in the Jamfile or as a
> > wrapper xsl script.  Any thoughts on how we want to handle
> > these?
> >
> > Jeff
> 
> I think we should do both. We have customization XSL stylesheets for DocBook 
> HTML and FO output already (see boostbook-xsl/html.xsl, 
> boostbook-xsl/html-single.xsl, and boostbook-xsl/fo.xsl), and anything we 
> consider a good default should go into those. However, I would _really_ like 
> for the Jam rules to be able to customize these parameters further; maybe add 
> Jam "features" for stylesheet parameters, so one could add, e.g.,  
> "<toc.section.depth>3" to the command line to set a stylesheet parameter (the 
> same syntax would work within a Jamfile). 

Sounds good to me.  Anyway, I think 3 levels of TOC would be good default setting...

Jeff