[Boost-docs] documentation bug

Subject: [Boost-docs] documentation bug
From: Jason Scherer (jason.scherer_at_[hidden])
Date: 2011-08-05 18:47:48

Hi,

I'd like to report a documentation bug.

Here's my issue: this document:
http://www.boost.org/doc/libs/1_47_0/more/getting_started/unix-variants.html

The getting started guide, goes into detail about how to use an executable called "b2" to build boost libraries.

This document:
http://www.boost.org/boost-build2/doc/html/index.html

Goes into great detail about a fully-featured build system called "Boost.Build" which is driven from an executable called bjam.

The problem is that nowhere does it state that b2 and bjam are the same thing.  I only found this out by doing a diff on the command line and finding out that the executables are the same.

So as a reader of this documentation, and novice user of boost, what happens is that I get sent down a path where I'm using something called "b2" and I want to find out how to pass extra options to it, and then I get sent off to an article about using a tool called bjam, and it seems like I'm on the wrong track when I'm actually on the right track.  Then I post something to Stack Overflow and everybody who is a seasoned Boost user thinks I'm an idiot who doesn't read documentation.  The trouble is, I did read the documentation, but A wasn't connected to B, so nothing made sense.

IMO this is a documentation bug.  It's reasonable to assume that if there are two differently-named executables in a directory, they probably do something different.  Can't we add a sentence somewhere to the getting started guide that explains that b2 and bjam are the same thing, that they are both part of a system called Boost.Build, explains a little bit about how Boost.Build actually works, or something that helps ease the reader into understanding what is going on?

Thanks.
Jason Scherer

R/GA 350 West 39th Street New York, NY 10018
www.rga.com<http://www.rga.com/>  www.twitter.com/rga<http://www.twitter.com/rga>  www.facebook.com/rga<http://www.facebook.com/rga>

The Agency for the Digital Age(tm)

This message contains information which may be confidential and privileged. Unless you are intended recipient (or authorized to receive this message for the intended recipient), you may not copy, disseminate or disclose to anyone the message or any information contained in the message. If you have received the message in error, please notify the sender by reply e-mail or forward the message to postmaster_at_[hidden]<mailto:postmaster_at_[hidden]> and delete the message. Thank you very much.