Re: [Boost-build] Boost.Build Documentation (on Steriods) for Newbies?

From: Vladimir Prus (ghost_at_[hidden])
Date: 2007-01-16 02:33:07

On Monday 15 January 2007 14:18, Dean Michael Berris wrote:
> Hi Everyone,
> 
> It might just be me, but I think it's pretty obvious that we need to
> generate documentation that's easily accessible and easily editable by
> the community at large. I see there's
> http://zigzag.cs.msu.su/boost.build/wiki and
> http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost.Build_V2
> -- which one should be used, and is there an effort to actually start
> generating (more) documentation about Boost.Build and Boost.Jam ?

Just to clarify: did you saw:

        http://boost.org/boost-build2/doc/html/index.html

If yes, what are the problems with that?

> I feel there's nothing wrong with using quickbook+boostbook to
> document Boost.Jam and Boost.Build, but downloading the Boost
> Distribution and having to wade through how to actually build Boost
> and the other tools causes somewhat a circular dependency problem --
> and can be considered a serious barrier to entry. 

If "Boost Distibution" means Boost release, that it has all the documentation
already generated for you.

> Not to mention that 
> it's pretty complex to develop documentation collaboratively in this
> method, where it takes a considerable while between writing and
> copy-editing and eventual release (and even the full cycle).

The URL I gave updates every night.

> Though some of us have been successful and able to figure out how
> Boost.Build and Boost.Jam (and even quickbook+boostbook) work, some of
> us (me included) have very short attention spans and wouldn't want to
> go through all that again just to explain it to someone else.

If you're talking about quickbook/Boost.Book setup, then it should be
documented at 

http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/index.html

more specifically

http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/boostbook.html

> So if there isn't already an effort, I would like to volunteer some of
> my time going over what we already have and collate information and
> have it consolidated somewhere convenient.
> 
> Now the question is, where should I start?

I suggest that you start by making a list of thing that the above docs lack,
in your opinion. Then, document those things and send a patch to the docs.

Thanks,
Volodya