[boost] [Bug][Tools] Incomplete tool documentation, especially for building

From: Daryle Walker (darylew_at_[hidden])
Date: 2005-10-13 13:03:03

[This is for the versions at <http://www.boost.org>.]
[I don't know if this should/could be placed in the Bug Tracker.]

While answering a post about BCP on another list, I noticed that the docs
for BCP (at <http://www.boost.org/tools/bcp/bcp.html>) never actually say
where one would get BCP from!  Looking at my local archive, I see the BCP
source files are in the same directory as the BCP doc file.  I noticed that
they are C++ code; I suspected that BCP could have been a (Python) script or
(if I didn't respond to a question asking why not) pre-made executables.  I
feel that the BCP docs should explain how to get BCP.

In fact the QuickBook and Wave tools have the same problem.  (The source for
both is C++-based and in different subdirectories in the "tools" directory,
but the docs never tell you that!)  The other tools (build, regression,
inspect, and BoostBook) do have building directions, but they're either
indirectly linked or plainly presented.

QuickBook has another problem in that it has no table of contents.  I
thought the docs were severely incomplete until I finally saw the little
right arrow symbols at the two right-side corners.  Nor did I know how big
the QB docs were until I had to traverse every page through a chain of right
arrow links.

The Wave-tool docs have a different additional problem in that it's mixed in
the Wave-library docs.  The traversal symbols on that page shouldn't be
followed since they can't help with the tool (just with Wave-library).  The
page isn't next to the Wave-tool source code, either.

-- 
Daryle Walker
Mac, Internet, and Video Game Junkie
darylew AT hotmail DOT com