On Sunday 02 March 2003 01:10 pm, Jeff Garland wrote:
> I've been experimenting with a couple of modifications of the
> boostbook-xsl/docbook.xsl to support the generation of a 'Proposal Article'
> instead of the boost documentation. I use a different top level .xml file
> which includes some of the .xml files from the boost documentation as well
> as others suited only to my proposal article.
>
> In the xsl script I changed the result of output to create a docbook
> 'article' element instead of a 'book' element for the toplevel boostbook
> 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?
> So in my travels to do this I have come across a couple things that
> have me wondering.
>
> 1) Should we be using Docbook Set?
> In the current boostbook transformation we create the entire
> boost documentation as a Docbook 'book' element and each library
> then becomes a chapter. But Docbook also supports the idea of
> a Documentation set which allows for indexing of multiple books
> 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.
> 2) How many levels of TOC?
> With the default processing of the docbooks xsl stylesheets
> the TOC defaults to 2 levels of depth:
>
> That is, currently
>
> <section id="1st level">
> <section id="2nd level">
> <section id="3rd level">
>
> will only include up to "2nd level" in the TOC. This is
> pretty limiting for even moderately complex docs. So
> 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).
Doug
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
