Re: [jamboost] BoostBook and Boost.Build version 2

From: Vladimir Prus (ghost_at_[hidden])
Date: 2003-03-13 10:56:22

Douglas Paul Gregor wrote:
> As most of you probably know, I'm hoping to get support for building
> BoostBook user documentation with BBv2, and I would like your
> help.
>
> This message is long. Really long. 

Indeed :-) This is the first pass of my comments. 

> === XSLT ===
> XSLT is a language that describes a transformation from an XML
> document type into another document (or several documents). For our
> purposes, an XSLT transformation can be described by:
>
> 1) An XML document for input
> 2) An XSLT stylesheet
> 3) A set of stylesheet parameters (name/value pairs)
> 4) An output file or an output directory
>
> As I see it, we could have an "xslt" rule of the form:
>
> rule xslt target : source : stylesheet : parameters *

Yep, that's looks reasonable. On the other hand, I'd prefer a slighlt 
different version.

xstl foo.xml : bar.xml 
<stylesheet>something.xsl
;

> If "target" is a normal file, then it's just a normal target in
> Jam. If "target" is a directory, it would have to be a pseudo-target
> because we can't generally guess at what the output files will be to
> build a target set.

One gotcha here: if we generate a directory, then I don't know any
way to track dependencies. I would assume that timestamp of directory
is changed whenver anything in it changes, but it's not so :-(

And another gotcha: you have some syntax to tell if "target" is directory or
not.

> There is only a single source file, but like C++ source files it may
> include (via XIncludes) other XML files, and should depend on those
> files. We can probably restrict ourselves to XIncludes that look like
> this:
> <xi:include href="xml-file-we-depend-on"/>
>
> XSLT stylesheets are also XML files, but with a slightly different
> include mechanism. Stylesheet inclusion in XSLT takes one of these
> forms:
> <xsl:include href="xslt-file-we-depend-on"/>
> <xsl:import href="xslt-file-we-depend-on"/>

Ah.. so we need a scanner for xml/xslt. That's good from testing purposes :-)

> Both XIncludes and XSL stylesheet inclusion the text in the href
> attribute can be either a local file (relative to the file including
> it; there is no search path) or a web address (e.g.,
> http://www.etc.etc./). We should probably just ignore anything of the
> form "http://*" and assume everything else is a file.

OK.

> XSL stylesheet parameters can probably be implemented via BBv2
> features, e.g.,
>
> xslt array-proposal.docbook : array.xml : docbook.xsl
>
> : <boost.generation.mode>standardese
>
> ;
>
> However, unlike compiler features that are properties of the compiler,
> stylesheet parameters are a property of the stylesheet so we can't
> easily maintain a list of all of the parameters for each
> stylesheet. We generally have to just "trust" the user. Perhaps an
> "xsl:" prefix to an arbitrary string? For instance, something like:
>
> xslt array-proposal.docbook : array.xml : docbook.xsl
>
> : <xsl:boost.generation.mode>standardese
>
> ;

Eh... that requires Boost.Build internal changes. Why can't we get away with 
free features

xslt array-proposal.docbook : array.xml : docbook.xsl
: <xslt-param>boost.generation.mode=standardese
;

?

> There are several XSLT processors available, so in its final form I
> would expect we'll want XSLT toolsets just like we have compiler
> toolsets. For now, however, I'm only recommending one XSLT processor
> (xsltproc). Here is the command line information for using xsltproc:
>
> xsltproc --xinclude <parameters> -o <target>? <stylesheet> <source>
>
> <parameters> is composed of strings "--stringparam feature value" for
> each property.
>
> <target> is the target (file or directory; doesn't matter)
>
> <stylesheet> is the stylesheet
>
> <source> is the source file
>
> So for the example above, the command line would be:
> xsltproc --xinclude --stringparam boost.generation.mode standardese \
> -o array-proposal.docbook docbook.xsl array.xml

OK. This seems straight-forward.

> === BoostBook, DocBook, HTML, and Man pages ===
> Given a BoostBook document we apply a series of XSLT transformations
> to get to end-user documentation (e.g., HTML or man pages). The
> transformations are:
> BoostBook file (.xml) --> DocBook file (.docbook) via stylesheet
> tools/boostbook/xsl/docbook.xsl
>
> DocBook (.docbook) --> single HTML file (.html) via stylesheet
> tools/boostbook/xsl/html-single.xsl
>
> DocBook (.docbook) --> HTML output directory via stylesheet
> tools/boostbook/xsl/html.xsl
>
> DocBook (.docbook) --> Man pages output directory via stylesheet
> tools/boostbook/xsl/man.xsl
>
> I expect that the Jamfile for these would look something like this:
>
> type.register BOOSTBOOK : xml bbk ;
> type.register DOCBOOK : docbook ;
> type.register HTML : html ;
> generators.register-standard boostbook.docbook : BOOSTBOOK : DOCBOOK ;
> generators.register-standard boostbook.html-single : HTML : DOCBOOK ;
>
> # ------- Most definitely broken attempt at a Jamfile --------
> rule docbook ( target : source : parameters * )
> {
> xslt $(target)
>
> : $(source)
> : $(BOOST_ROOT)/tools/boostbook/xsl/docbook.xsl
> : $(parameters)
>
> ;
> }

I'm not sure I get you right. Do you mean that 'docbook' rule will be directly 
used by user? This will be OK, but does not requires generators at all.

> XML catalogs remap remote web addresses (and, optionally, XML public
> identifiers like "-//Boost//DTD BoostBook XML V1.0//EN") to local
> files and directories. The XML catalog (just an XML file) is then
> passed to the XSLT processor, which does the remappings
> on-the-fly. XML catalogs can easily be generated when we know the
> local directories for:
> 1) The DocBook XSL stylesheets
> 2) The DocBook DTD
> 3) The BoostBook DTD (in $(BOOST_ROOT)/tools/boostbook/dtd)
>
> Ideally, the user could "configure" BBv2 with the locations of the
> first two (so that the user need not specify the directories each
> time), and BBv2 would build and use the XML catalog with whatever
> directory information it has, omitting the rest of the information so
> that the XSLT processor can download it as needed. For reference, the
> XML catalog I use (generated by the configure script at the end of
> this e-mail) is:

I think we can make special rule which will make catalog, which can later be
used. This will require that the user edit top-level Jamfile, or 
project-root.jam. Guess it's OK?

> The DocBook XSL stylesheet can also output XSL Formatting Object files
> (.fo), which are used for generating hardcopy versions of DocBook
> documents. However, FO->PS and FO->PDF conversion isn't done with
> XSLT, but with another external program (e.g., Apache's FOP). Again,
> no need to worry about this now, and it should be quite easy, but it's
> a hint that we may need yet another type of toolset in the future.

OK, let's address this when needed.

- Volodya