Boost Docs :
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...