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

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