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

From: Vladimir Prus (ghost_at_[hidden])
Date: 2003-03-18 06:59:56

Douglas Gregor wrote:

> > "I could" means you can teach your stylesheet to do that? It will be very
> > good.
>
> 'Tis done now, but not (IMHO) cleanly. HTML (multiple files) and man pages
> are now supported in the BoostBook module. 

In my case, all I get is

Chunking isn't supported with libxslt

message, and no output, but I guess this is configuration problem on my side.

> Here's how I did it:
>
> - Added HTMLDIR and MANPAGES types, but with no extension because they
> won't really by files.
> - When creating targets of type HTMLDIR (or MANPAGES) from a BoostBook
> document:
> 1) Create a DocBook target (a single file) like we normally would
> 2) Create a HTMLDIR (or MANPAGES) target whose source is the DocBook
> file, and override the name to be the name of the manifest file
> 3) The DocBook -> HTML (multiple files) and DocBook -> man pages
> actions call a special version of the XSLT rule that also accepts a
> directory name ('html' for HTML, 'man' for man pages).
>
> Everything seems to be working well. There are a few things that bother me:
> - BBv2 correctly looks for 'html/HTML.manifest' (or 'man/man,manifest'),
> but I've only given it the name 'manifest'. I'm guessing this comes from
> the "format" parameter name, but it's at least a little scary how this just
> magically works :). 

I certainly miss something. There's code from boostbook.jam:

...
manifest = HTML.manifest ;
....
local target = [ generators.construct $(self.project) $(manifest)
: $(type) : $(property-set) : $(base-target) ] ;

You ask to create a target called HTML.manifest, and get it. 

> Also, the rest of the path that is used for single
> files (e.g., bin/gcc/debug/boost.docbook) doesn't show up. That's good, but
> I don't see where it went...

# TBD: this is NOT correct, but it works for now...
LOCATE on $(target) = $(dirname) ;

This line changes LOCATE setting on the manifest file, as I understand it. If
I comment out this line, the disappeared part goes back (but "html" part 
disappeares).

Your comment is right. The thing you do with LOCATE/MkDir are bypassing 
builtin V2 mechnisms. More comments later.

> - Not sure how to handle "clean" targets here

I have no idea -- we are not prepared that one action
creates unknown number of targets. Need some design. 

> - The whole thing just feels like a hack to me. Or maybe I'm paranoid?

Well, the way you've described it really looks not very nice. However, I see 
quite clear approach in the implementation. We can't handle directories 
directly. So, insread of generating directory from the docbook source, you
generate manifest file. The action which generates manifest file, also creates
a buch on html files. 

What's not nice currently, is relocating of manifest file. We've two 
approaches

1. Don't do anything. The manifest file will be generated to 
"bin/gcc/debug/HTML.manifest". The xsl-dir rule will find out the location
of manifest file and store generated files in the same location. That's as 
clean as possible. Of course, the path "bin/gcc/debug"... is wierd. But this
should be fixed.

2. Change manifest location in another way. The 'virtual-target' class has
'set-path' method. This will eliminate the need for 'common.MkDir' call. 
It's still not quite clean, but will avoid deep directories right now.

> Still no clue how to handle catalogs, unfortunately :(

Frankly, I don't know how they should work. I'd imagine that 
some Jamfile has

xml-catalog boostbook : "http://nowhere.com"="/home/ghost/dtd/nowhere" ;

And that there's <xml-catalog> feature, which is honored by xslt actions. On 
the other hand, you was trying to make the docbook rule to automatically 
create a new target locally. I don't know what is better.

- Volodya