Boost logo

Boost-Build :

From: Douglas Gregor (gregod_at_[hidden])
Date: 2003-03-13 12:21:41


On Thursday 13 March 2003 10:56 am, Vladimir Prus wrote:
> Douglas Paul Gregor wrote:
> > 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
> ;

Fine by me.

> > 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 :-(

I could generate a manifest file in the output directory. Then the manifest
timestamp could be used instead of the directory timestamp. Actually, a
manifest file is a good idea anyway for "clean" targets and, eventually,
installation.

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

Okay.

> > 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
>
> ;
>
> ?

Whoops, my mistake. Free features are the way to go.

> > 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.

I don't expect the 'docbook' rule to be directly used by the user. Here's the
interface I'm hoping for:

The interface would be similar to the interface we have with the regression
testing system. That is, in each library "doc" directory we have a
Jamfile[.v2] that contains a few invocations of the "boostbook" rule, e.g.,

boostbook function : function.xml ;

"function" is a pseudotarget for building documentation of the 'function'
library from 'function.xml'. If the user invokes "bjam" (no arguments) some
default documentation types will be built from "function.xml" (e.g., HTML
documentation)

Then in $(BOOST_ROOT)/doc, we have a Jamfile that subincludes all of the
doc/Jamfiles. It's default target is something like:

boostbook boost : boost.xml ;

A user should be able to specify what types of documents to build (html, man
pages, whatever). Could these just be "build" variants, but for
documentation? For instance, the feature might be "docformat", the values
would be "html", "html-single", "man", etc., and the default would probably
be "html". Then the user could cd to $(BOOST_ROOT)/doc, run

bjam html man

and get HTML documentation in 'html/', man pages in 'man/', etc.

We probably don't need generators for this, then.

> > 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?

Okay by me.

Thank you for your help!

Doug

 


Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk