Re: [Boost-build] Documentation toolchain, ease of use

Subject: Re: [Boost-build] Documentation toolchain, ease of use
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2011-02-04 13:18:23

AMDG

On 2/4/2011 10:06 AM, John Maddock wrote:
>> For tools that only support a single configuration,
>> when default initialization is good enough, it
>> would be nice if the configuration files didn't
>> need to be adjusted. (Just like a default
>> compiler is selected if none is configured).
>>
>> So, here's what I propose to do:
>>
>> a) Change all documentation Jamfiles to have
>> using quickbook ;
>> using boostbook ;
>> using doxygen ;
>> (or whatever's appropriate)
>
> Do you mean the users Jamfiles? It would be nice if that wasn't needed.
>

Yes.  I think it's reasonable for a Jamfile to
declare the tools that it uses.  For the most
part, it should be a matter of replacing import
with using.

>> b) boostbook should lazily initialize the
>> tools it depends on (xsltproc and fop).
>> doxygen should lazily initialize boostbook.
>
> Nod, anything we can do to make things easier here would be a good thing
> - especially on 'nix environments where most of the tools should be in
> the user's path anyway.
>
> What I'd like to see is:
>
> * If nothing is specified in the user-config.jam file, then default
> initialize the tool.

user-config.jam, site-config.jam, or project-config.jam that is.

> * Always check that the tool can be found OK by trying to run it with a
> "do nothing" command (version check or something), emit a decent error
> message if the tool can't be run.

We just need to be careful not to issue an
error message for tools that are not explicitly
initialized and not needed either.

> * For Docbook, make sure that the path to the stylesheets is correct and
> if not emit a useful message.
>

Yep.

> Hopefully that should take care of most of the new-user errors! ;-)
>

In Christ,
Steven Watanabe