Re: V2 documentation feedback from a newbie

From: Samuel Krempp (krempp_at_[hidden])
Date: 2004-01-23 09:03:48

le Friday 23 January 2004 12:23, ghost_at_[hidden] écrivit :

>> I feel the docu should state the obvious here, and just plainly explain
>> in the very beginning that when invoked bjam will use the directory
>> hierarchy rooted at boost_build_root and parse the jam files there as a
>> first step.
> 
> Ok.. I'll see where I can put this statements.

I saw it's in fact stated inside the detailed reference, 
http://boost.sourceforge.net/boost-build2/boost_build_v2.html#initialization
with all details.
What do you think of modifying the beginning of the file this way :
(html patch attached, it also moves the "Synopsis" and "how tu use this
document" paragraph on top of the file before the TOC - it seemed weird
having a synopsis after the TOC)

-----------------------------
Synopsis

Boost.Build is a system for large project software construction
built on Boost.Jam, a descendant of " Perforce Jam", an open-source
make replacement[1].
Boost.Build v2 is an onging project to rewrite Boost.Build, improving
design and making it more extensible

Boost.Jam implements the core language, and is responsible for parsing 
jam files. The various rules, advanced features, and platforms
knowledge of Boost.Buildv2 are then implemented in jam files 
parsed at each invocation. These support
files are placed under the Boost.Build root directory (which is the
directory with the document you are reading. e.g.
$boost_root/tools/build/v2 in a Boost distribution). 
You shouldn't be afraid to have a look at the support jam files
if you want to see how everything works, the core language is meant
to be human readable.
Note that the core language features evolve along with the support
files, thus the Boost.Jam executable should always be up-to-date
with the Boost.Build source.
[ I suggest merging index.html's synopsis here, I think it's better to have
it here than index.html.. ]

Installation
After decompressing a Boost.Build source distribution, the following steps
are needed. All paths are given relatively to Boost.Build root directory 
1.
2.
..
4.

[remove the paragraph :
If you use Boost distribution, or Boost CVS, the Boost.Build root is located 
.. ]

When starting a new project ...
-----------------------------

if you're happy with it I can commit that. (and move the synopsis part of
index.html into this file)

-- 
Samuel --nextPart1102452.yHzdBF29Bd Content-Type: text/x-diff; name="html.patch"
Content-Transfer-Encoding: 8Bit
Content-Disposition: attachment; filename="html.patch"
--- boost_build_v2.html	2004-01-23 14:01:03.000000000 +0000
+++ sam_boost_build_v2.html	2004-01-23 13:53:41.000000000 +0000
@@ -44,6 +44,50 @@
<th align="left">Other documents</th>
</tr>
+ <h2 id="synopsis">Synopsis</h2>
+ <p>Boost.Build is a system for large project software construction built 
+ on Boost.Jam, a descendant of "
+ Perforce Jam", an 
+ open-source make replacement[1].
+ <br>
+ Boost.Build v2 is an onging project to rewrite Boost.Build, improving
+ design and making it more extensible
+ </p>
+ <p> Boost.Jam implements the core language, and is responsible for parsing 
+ jam files. The various rules, advanced features, and platforms
+ knowledge of Boost.Buildv2 are then implemented in jam files 
+ parsed at each invocation. These support
+ files are placed under the Boost.Build root directory (which is the
+ directory with the document you are reading. e.g.
+ <tt>$boost_root/tools/build/v2</tt> in a Boost distribution). 
+ You shouldn't be afraid to have a look at the support jam files
+ if you want to see how everything works, the core language is meant
+ to be human readable.
+ <br>Note that the core language features evolve along with the support
+ files, thus the Boost.Jam executable should always be up-to-date
+ with the Boost.Build source.
+ </p>
+ <h2>How to use this document</h2>
+
+ <p>If you've just found out about Boost.Build V2 and want to know if it
+ will work for you, start with tutorial. You
+ can continue with the reference. When you're
+ ready to try Boost.Build in practice, go to <a href=
+ "#installation">installation</a>.</p>
+
+ <p>If you are about to use Boost.Build on your project, or already using
+ it and have a problem, look at the <a href=
+ "#sec-reference">reference</a>.</p>
+
+ <p>If you're trying to build a project which uses Boost.Build, look at <a
+ href="#installation">installation</a> and then read about <a href=
+ "#command_line">command line</a>.</p>
+
+ <p>Finally, if nothing applies to you, write to our mailing list, telling
+ what information you'd like to know.</p>
+
+ <hr>
+
<tr>
<td>
<dl class="page-index">
@@ -156,31 +200,12 @@
</table>
<hr>
- <h2>How to use this document</h2>
-
- <p>If you've just found out about Boost.Build V2 and want to know if it
- will work for you, start with tutorial. You
- can continue with the reference. When you're
- ready to try Boost.Build in practice, go to <a href=
- "#installation">installation</a>.</p>
-
- <p>If you are about to use Boost.Build on your project, or already using
- it and have a problem, look at the <a href=
- "#sec-reference">reference</a>.</p>
-
- <p>If you're trying to build a project which uses Boost.Build, look at <a
- href="#installation">installation</a> and then read about <a href=
- "#command_line">command line</a>.</p>
-
- <p>Finally, if nothing applies to you, write to our mailing list, telling
- what information you'd like to know.</p>
-
<h2 id="installation">Installation</h2>
- Assuming you're installing Boost.Build from released source distribution,
- the following steps are needed. All paths are given relatively to
- Boost.Build root directory, which is the directory with the document you
- are reading. 
-
+ <p>
+ After decompressing a Boost.Build source distribution, the following
+ steps are needed (All paths are given relatively to Boost.Build root 
+ directory) :
+ </p>
<ol>
<li>Go to "jam_src" directory and build Boost.Jam. Two convenient
scripts are provided, "build.sh" (for Unix systems) and "build.bat"
@@ -217,14 +242,8 @@
</li>
</ol>
- <p>If you use Boost distribution, or Boost CVS, the Boost.Build root is
- located at <tt>$boost_root/tools/build/v2</tt> and the installation steps
- are the same. However, don't skip the bjam rebuilding step, even if you
- have a previous version. CVS version of Boost.Build requires CVS version
- of Boost.Jam.</p>
-
<p>When starting a new project which uses Boost.Build, you need to make
- sure that build system can be found. There are two ways.</p>
+ sure that the Boost.Build support files can be found. There are two ways.</p>
<ul>
<li>Set enviromnetal variable <tt>BOOST_BUILD_PATH</tt> to the absolute
 --nextPart1102452.yHzdBF29Bd--