Re: [jamboost] Re: [BBv2] quickbook.jam and boostbook question

From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-01-28 10:28:02

On Friday 28 January 2005 16:43, Joao Abecasis wrote:

> > Sorry that it took so long!
>
> No hurries! I was beginning to think maybe this is not exactly a BB
> issue... More of a boostbook one. Maybe the documentation list would
> have been more appropriate (?).

No, I think this is purely Boost.Build question.

> Anyway I have to say I have been trying out BBv2 and I like what I've seen!
>
> >>I wrote a quickbook toolset to generate boostbook documentation from
> >>quickbook sources. The toolset is attached to the original post. I would
> >>like to propose the addition of the toolset to BB v2, under the tools
> >>directory. Is this ok?
>
> Since no one has objected and since quickbook now lives in the tools
> directory I guess that somehow grants me the right to add the toolset to
> BB... ;)

Sure. But please provide more complete comment at the top of the file than:

# Provides quickbook rule to handle generation of documentation from QuickBook 
# Sources.
# Interesting stuff is in boostbook...

At least say where QuickBook HTML docs can be found. Preferrable both URL and 
Boost tree location. A sentence describing what QuickBook will also help.

Also, 

# Make boostbook rule visible as quickbook.quickbook
IMPORT boostbook : boostbook : $(__name__) : quickbook ;
# And then as global quickbook
IMPORT $(__name__) : quickbook : : quickbook ;

seems like a mistake. It makes global "quickbook" rule do exactly the same as 
"boostbook" rule. I've just did some testing and was very confused by this 
behaviour.

> >>>boostbook.jam defines the BOOSTBOOK type. However, it's generators
> >>>are defined as XML -> <something>. Given this I found 2 ways to make
> >>>quickbook work:
> >>> a) define generator QUICKBOOK -> XML, which leaves me with the
> >>> feeling that the generator is not sufficiently "typed"...
> >>>
> >>> b) define generators BOOSTBOOK -> DOCBOOK (and BOOSTBOOK -> TESTS)
> >>> and QUICKBOOK -> BOOSTBOOK. This seems better, but I shouldn't
> >>> be messing with boostbook within the quickbook toolset.
> >
> > That's right. I suggest that you take the same approach that doxygen.jam
> > uses: you declare QUICKBOOK -> BOOSTBOOK generator, but do not define any
> > other generator. Instead, you add "import bookbook ; " so that the
> > declaration of BOOSTBOOK type is seen.
>
> If you look at the toolset I posted initially you'll see that the
> "import boostbook ;" call is there, so the BOOSTBOOK type should be
> visible. But I don't think that's the issue.
>
> I tried to define only the QUICKBOOK -> BOOSTBOOK generator, figuring BB
> would see BOOSTBOOK as an XML type anyway. But, it turns out it doesn't
> work that way (attached are the error messages I got trying this approach).

This looks like a bug! When we're trying to create XML type (that what 
boostbook's generator want), we don't consider generators which produce types 
derived from XML -- in this case Boostbook. Some hacking is in order, but in 
the meantime, you'd have to create XML type.

> >>>Are there other alternatives I am missing? How bad could it be to define
> >>>the generator as QUICKBOOK -> XML?
> >
> > I don't think that's all that bad. I suggested another variant only
> > because it's consistent with doxygen.jam.
>
> I can settle for QUICKBOOK -> XML. Anyway, I'll give doxygen.jam a
> closer look.

I've just tried locally with QUICKBOOK -> XML and it seems to work.

> BTW, is there a way for the build process to generate the quickbook
> executable once with a single compiler and always use that executable,
> regardless of the number of compiler toolsets available?

In some form it's possible. If you want quickbook to be automatically built 
the first time I add .qbk file in the list of sources, right? The attached 
works for me, but needs to avoid hardcoding the path to quickbook.

- Volodya
 --Boundary-00=_Dol+BUPHd9rm7e0 Content-Type: text/x-java;
charset="iso-8859-1";
name="quickbook.jam"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
filename="quickbook.jam"

#
# Copyright (c) 2005 Joao Abecasis
#
# Distributed under the Boost Software License, Version 1.0. (See
# accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
#

# Provides quickbook rule to handle generation of documentation from QuickBook Sources.
# Interesting stuff is in boostbook...

import boostbook ;
import common ;
import generators ;
import modules ;
import type ;
import "class" : new ;
import feature ;
import toolset ;

type.register QUICKBOOK : qbk ;
feature.feature <quickbook-binary> : : free dependency ;

class quickbook-generator : generator
{
import targets property-set ;
rule run ( project name ? : property-set : sources * : multiple ? )
{
local quickbook-main-target = [ targets.resolve-reference 
/home/ghost/Work/boost/tools/quickbook : $(project) ] ;
# The first element is the targets, the second is properties
# found in target-id, which we don't care about since we've
# passed the id ourself.
quickbook-main-target = $(quickbook-main-target[1]) ;

# Request the build with the empty property set. This
# will built the target with default toolset, no matter
# what's specified in 'property-set'.
local targets = [ $(quickbook-main-target).generate 
[ property-set.empty ] ] ;
# Ignore usage-requirements returned as the first element
# of the list.
targets = $(targets[2-]) ;

# Add the dependecy on the created target and record the
# executable to use.
property-set = [ $(property-set).add-raw 
<dependency>$(targets) 
<quickbook-binary>$(targets)
] ;

return [ generator.run $(project) $(name) : $(property-set)
: $(sources) : $(multiple) ] ;
} 
}

rule init ( command ? )
{
if ! $(.initialized)
{
.initialized = true ;

.quickbook-command = [ common.get-invocation-command quickbook : quickbook : $(command) ] ;

if --debug-configuration in [ modules.peek : ARGV ] 
{
ECHO "notice: QuickBook: using command " $(.quickbook-command) ;
}

# These generators should not be here... Must mail the BB guys and ask
# for advice or go the (other) easy way out by defining QUICKBOOK to XML
# generator, below.
#generators.register-standard boostbook.boostbook-to-docbook : BOOSTBOOK : DOCBOOK ;
#generators.register-standard boostbook.boostbook-to-tests : BOOSTBOOK : TESTS ;

# Registering the generator here requires 'using quickbook ;' somewhere else
ECHO "REGISTERING QUICKBOOK GENERATOR" ;
generators.register [ new quickbook-generator
quickbook.quickbook-to-boostbook : QUICKBOOK : XML ] ;
}
}

toolset.flags quickbook.quickbook-to-boostbook COMMAND <quickbook-binary> ;

rule quickbook-to-boostbook ( target : source : properties * )
{
DEPENDS $(target) : [ on $(target) return $(COMMAND) ] ; 
}

# $(1) target
# $(2) source
actions quickbook-to-boostbook bind COMMAND
{
$(COMMAND) $(2) $(1) ;
}

 --Boundary-00=_Dol+BUPHd9rm7e0--