Re: [Boost-docs] [quickbook] Where are the docs for Jamfiles?

Subject: Re: [Boost-docs] [quickbook] Where are the docs for Jamfiles?
From: Beman Dawes (bdawes_at_[hidden])
Date: 2011-10-06 11:29:18

On Thu, Oct 6, 2011 at 6:38 AM, Daniel James <dnljms_at_[hidden]> wrote:
> On 6 October 2011 11:30, Beman Dawes <bdawes_at_[hidden]> wrote:
>>
>> The simplest possible Jamfile would be a much gentler start. See the
>> attached files for an example.
>
> The regex Jamfile is good. Also, I created an example of how a sandbox
> library could be organised at:
>
> https://svn.boost.org/svn/boost/sandbox/example
>
> The documentation build includes doxygen support so it's a little more
> complicated.

But still understandable. If a "Quickbook Users Guide and Tutorial"
had a graduated set of examples, this might make a good second
example, after a first example that didn't use doxygen.

> It also copies the images and css from boost because it's
> meant to be standalone, libraries included in boost shouldn't do that.

A comment to that effect would be helpful.

> It isn't commented as I didn't create it for documentation.

Quickbook is currently a disaster to learn to use. The markup itself
seems easy, and the "Chapter 33. Quickbook 1.5" docs are fine as far
as they go. But without a Users Guide, a new user is left groping in
the dark. It's a waste of effort to put explanatory material in the
sandbox or on a wiki; new users won't find them.

I've created a ticket #5985 requesting a Users Guide be created.

Your https://svn.boost.org/svn/boost/sandbox/example material would be
useful as part of the solution to the Users Guide problem!

--Beman