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

From: Vladimir Prus (ghost_at_[hidden])
Date: 2003-03-14 03:24:28

Douglas Gregor wrote:

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

I don't like my own idea any longer ;-) What's going on is that one XML and 
one XSL files are combined to create XML file. That's directly reflectable by
a generator and a rule.

xml foo.xml : bar.xml something.xsl : {properties} ;

I had some purpose for <stylesheet>, but I don't see any purpose now.

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

"I could" means you can teach your stylesheet to do that? It will be very 
good.

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

Let's decide the actual syntax later.

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

Excellent. So, the interface for basic "XML + XSL -> XML" transformation is
agreed upon? Would you like to try making it real, by creating the needed
generator? If so, what information do you need. I'm going add a section on
custom tools to tutorial anyway, but probably you'd need specific information
quickly.

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

Yep, this is reasonable interface. Under the cover, the system will 
1. Generate docbook from "function.xml" and a predefined stylesheet.
2. Depending on requested documentation type, will covnert it to
html, chunked hmtl or fo/pdf, or man, or whatever. 

I believe it's not that hard. I can't explain in detail when you'll be willing 
to try.

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

How will this be related to "boostbook function : function.xml ;"? If
"boost.xml" includes "function.xml", then I guess there's no need to
subincude all doc/Jamfiles...

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

That's what I think too. 

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

What's your plan of action now? I'd suggest that "XML + XSL -> XML" 
transformation should be implemented first, followed by "XML + XSL -> dir + 
manifest file". This will allow to do complete generation sequence for one 
format. The 'docbook' rule on top of that (with feature to select format). 
Lastly, dependency scanning.

- Volodya