Re: [V2] Completely confused.

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-03 03:43:57

Vladimir Prus wrote:

> Hi Dave,

Hi Volodya!

>>generators.register-standard docutils.html : ReST : HTML ;
>>
>>rule init ( docutils-dir )
>>{
>> docutils-dir ?= [ modules.peek : DOCUTILS_DIR ] ;
>>
>> if ! $(.initialized)
>> {
>> .initialized = true ;
>> .docutils-dir = [ path.make $(docutils-dir) ] ;
>> }
>
>
> It's not clear to me that duplicate initialization of this module 
should be
> ignored. I'd check if the specified 'docutils-dir' is different from 
the
> first invocation. If yet, I'd issue an error, otherwise, I'd ignore the
> second invocation. That's not very important however.

Okay, I'll get to that eventually.

>>rule html ( target : source )
>
>
> This should be
>
> rule html ( target : source : properties * )
> {

Okay, I just want to point out that from reading
http://www.boost.org/doc/html/bbv2/extending/tools.html there's
no clue about that third parameter. In fact, unless you were
already deeply familiar with Jam you'd have no reason to think
that a rule called 'html' would have any significance, because
it only prescribes writing actions. The doc should talk about
what you might want to do in such a rule.

>>{
>> docutils-dir on $(target) = $(.docutils-dir) ;
>>}
>>
>>if [ os.name ] = NT
>>{
>> .setup = "set 
PYTHONPATH="$(.docutils-dir);$(.docutils-dir)\\extras ;
>>}
>>else
>>{
>> .setup = PYTHONPATH=$(.docutils-dir):"$(.docutils-dir)/extras ; 
export PYTHONPATH" ;
>>}
>
>
> I think you might want to look at 
common.path-variable-setting-command, which
> should take care of system differences.

.setup = [ common.path-variable-setting-command
PYTHONPATH
: $(.docutils-dir) $(.docutils-dir)/extras
: exported ] ;

Great! But what if I wanted the current value of PYTHONPATH
incorporated there somehow? ;-)

>>---- end docutils.jam ----
>>
>>So, did I get this right,
>
>
> Except for 'html' parameter, everithing should be working.

Thanks.

>
>>and if so, how do I use it in a Jamfile? My
>>Jamroot looks like:
>>
>>project mplbook ;
>>import boostbook ;
>>
>>for src in [ glob *.rst ]
>>{
>> ### What goes here?? ###
>>}
>
>
> Obviously, there should be an invocation of main target rule. You can 
either
> define it yourself (like boostbook.jam defined the 'boostbook'
> rule

I will look, but as I remember everything in boostbook.jam
looked quite complicated. Yep, just as I recall. It's
completely unclear to me how one asks for a particular kind of
boostbook output.

> or let V2 do it for you:
>
> http://boost.org/boost-build2/doc/html/bbv2/extending/rules.html
>
> (Look for "the second approach" phrase). In your case, you want to 
convert rst
> to html, so the main target rules can be reasonably called "html". 
This patch
> does the trick:
>
> Index: boostbook.jam
> ===================================================================
> RCS file: /cvsroot/boost/boost/tools/build/v2/tools/boostbook.jam,v
> retrieving revision 1.27
> diff -u -r1.27 boostbook.jam
> --- boostbook.jam 13 Nov 2004 09:29:55 -0000 1.27
> +++ boostbook.jam 3 Dec 2004 07:21:26 -0000
> @@ -32,7 +32,7 @@
> type.register XML : xml : : main ;
> type.register BOOSTBOOK : boostbook : XML ;
> type.register DOCBOOK : docbook : XML ;
> -type.register HTML : html ;
> +type.register HTML : html : : main ;

Pretty simple. But isn't there something wrong, somewhere, if I
have to edit boostbook.jam just to add a new way to generate
html files via the simple mechanism?

And ultimately, aren't there likely to be very many ways to get
HTML from XML? Are those generators that boostbook.jam is
registering going to conflict with the other ways?

> After applying this change, and fixing 'html' parameters list, I get:
>
> $ bjam -n
> ....found 7 targets...
> ....updating 1 target...
> docutils.html bin/gcc-3.4/debug/a.html
>
>
> python foo/tools/rst2html.py
> a.rst bin/gcc-3.4/debug/a.html
>
> With Jamroot of:
>
> using docutils : foo ;
> import boostbook ;
>
> html a : a.rst ;

Hmm, didn't work for me because paths were coming out in
"portable representation" -- but then, I was using path.make
because boostbook did the same. But I fixed that and had
success! Thank you!

I feel like I'm beating a dead horse here, but requiring all this
conversion between native and portable representation outside of
path.jam seems like an incredibly unwieldy and inefficient thing
for the programmer. Why shouldn't path.jam just handle this for
us internally?

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com