|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r77604 - trunk/tools/build/v2/doc/src
From: steven_at_[hidden]
Date: 2012-03-28 11:37:06
Author: steven_watanabe
Date: 2012-03-28 11:37:05 EDT (Wed, 28 Mar 2012)
New Revision: 77604
URL: http://svn.boost.org/trac/boost/changeset/77604
Log:
More grammar fixes
Text files modified:
trunk/tools/build/v2/doc/src/overview.xml | 131 ++++++++++++++++++++-------------------
1 files changed, 66 insertions(+), 65 deletions(-)
Modified: trunk/tools/build/v2/doc/src/overview.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/overview.xml (original)
+++ trunk/tools/build/v2/doc/src/overview.xml 2012-03-28 11:37:05 EDT (Wed, 28 Mar 2012)
@@ -21,7 +21,7 @@
<orderedlist>
<listitem>
<para>
- Boost.Build executable tries to find Boost.Build modules and
+ The Boost.Build executable tries to find Boost.Build modules and
loads the top-level module. The exact process is described in <xref linkend=
"bbv2.reference.init"/>
</para>
@@ -29,8 +29,8 @@
<listitem>
<para>
The top-level module loads user-defined configuration files,
- <filename>user-config.jam</filename> and <filename>site-config.jam
- </filename>, which define available toolsets.
+ <filename>user-config.jam</filename> and
+ <filename>site-config.jam</filename>, which define available toolsets.
</para>
</listitem>
<listitem>
@@ -97,8 +97,8 @@
a.o: a.c
g++ -o a.o -g a.c
</programlisting>
- This is rather low-level description mechanism and it's hard to adjust commands, options,
- and sets of created targets depending on the used compiler and operating system.
+ This is a rather low-level description mechanism and it's hard to adjust commands, options,
+ and sets of created targets depending on the compiler and operating system used.
</para>
<para>
@@ -107,20 +107,20 @@
<programlisting>
add_program ("a", "a.c")
</programlisting>
- This is a function call that creates targets necessary to create executable file
- from source file <filename>a.c</filename>. Depending on configured properties,
- different commands line may be used. However, <code>add_program</code> is higher-level,
- but rather thin level. All targets are created immediately when build description
+ This is a function call that creates the targets necessary to create a executable file
+ from the source file <filename>a.c</filename>. Depending on configured properties,
+ different command lines may be used. However, <code>add_program</code> is higher-level,
+ but rather thin level. All targets are created immediately when the build description
is parsed, which makes it impossible to perform multi-variant builds. Often, change
- in any build property requires complete reconfiguration of the build tree.
+ in any build property requires a complete reconfiguration of the build tree.
</para>
<para>
- In order to support true multivariant builds, Boost.Build introduces the concept of
+ In order to support true multivariant builds, Boost.Build introduces the concept of a
<indexterm> <primary>metatarget</primary> <secondary>definition</secondary></indexterm>
<indexterm> <primary>main target</primary> <see>metataget</see> </indexterm>
- <firstterm>metatarget</firstterm>—object that is created when build description
- is parsed and can be later called with specific build properties to generate
+ <firstterm>metatarget</firstterm>—an object that is created when the build description
+ is parsed and can be called later with specific build properties to generate
actual targets.
</para>
@@ -130,8 +130,8 @@
exe a : a.cpp ;
</programlisting>
When this declaration is parsed, Boost.Build creates a metatarget, but does not
- yet decides what files must be created, or what commands must be used. After
- all build files are parsed, Boost.Build considers properties requested on the
+ yet decide what files must be created, or what commands must be used. After
+ all build files are parsed, Boost.Build considers the properties requested on the
command line. Supposed you have invoked Boost.Build with:
<screen>
b2 toolset=gcc toolset=msvc
@@ -142,9 +142,9 @@
</para>
<para>
- Another key concept is
+ Another key concept is
<indexterm><primary>property</primary><secondary>definition</secondary></indexterm>
- <firstterm>build property</firstterm>. Build property is a variable
+ <firstterm>build property</firstterm>. A build property is a variable
that affects the build process. It can be specified on the command line, and is
passed when calling a metatarget. While all build tools have a similar mechanism,
Boost.Build differs by requiring that all build properties are declared in advance,
@@ -158,12 +158,12 @@
"top-level" metatargets are called with the properties specified on the command line.
Each metatarget can elect to augment or override some properties (in particular,
using the requirements mechanism, see <xref linkend="bbv2.overview.targets.requirements"/>).
- Then, the dependency metatargets are called with modified properties and produce
- concrete targets that are then used in build process. Of course, dependency metatargets
+ Then, the dependency metatargets are called with the modified properties and produce
+ concrete targets that are then used in the build process. Of course, dependency metatargets
maybe in turn modify build properties and have dependencies of their own.
</para>
- <para>For more in-depth treatment of the requirements and concepts, you may refer
+ <para>For a more in-depth treatment of the requirements and concepts, you may refer
to <ulink url="http://syrcose.ispras.ru/2009/files/04_paper.pdf">SYRCoSE 2009 Boost.Build article</ulink>.
</para>
@@ -173,8 +173,8 @@
<title>Boost.Jam Language</title>
<para>
- This section will describe the basics of the Boost.Jam language—
- just enough for writing Jamfiles. For more information, please see the
+ This section will describe the basics of the Boost.Jam language—just
+ enough for writing Jamfiles. For more information, please see the
<link linkend="bbv2.jam">Boost.Jam</link> documentation.
</para>
@@ -182,8 +182,8 @@
<link linkend="bbv2.jam">Boost.Jam</link> has an interpreted, procedural
language. On the lowest level, a <link linkend="bbv2.jam">Boost.Jam
</link> program consists of variables and <indexterm><primary>rule
- </primary></indexterm> <firstterm>rules</firstterm> (Jam term for
- function). They are grouped into modules—there is one global
+ </primary></indexterm> <firstterm>rules</firstterm> (the Jam term for
+ functions). They are grouped into modules—there is one global
module and a number of named modules. Besides that, a <link linkend=
"bbv2.jam">Boost.Jam</link> program contains classes and class
instances.
@@ -333,8 +333,8 @@
</para>
<para id="bbv2.overview.jam_language.actions">
- Sometimes, you'd need to specify the actual command lines to be used
- when creating targets. In jam language, you use named actions to do
+ Sometimes, you need to specify the actual command lines to be used
+ when creating targets. In the jam language, you use named actions to do
this. For example:
<programlisting>
actions create-file-from-another
@@ -350,8 +350,8 @@
</para>
<para>
- To flexibly adjust the command line, you can define a rule with the same
- name as the action and taking three parameters -- targets, sources and
+ To adjust the command line flexibly, you can define a rule with the same
+ name as the action and taking three parameters—targets, sources and
properties. For example:
<programlisting>
rule create-file-from-another ( targets * : sources * : properties * )
@@ -366,8 +366,8 @@
create-file-from-another $(OPTIONS) $(<) $(>)
}
</programlisting>
- In this example, the rule checks if certain build property is specified.
- If so, it sets variable <varname>OPIONS</varname> that is then used
+ In this example, the rule checks if a certain build property is specified.
+ If so, it sets the variable <varname>OPIONS</varname> that is then used
inside the action. Note that the variables set "on a target" will be
visible only inside actions building that target, not globally. Were
they set globally, using variable named <varname>OPTIONS</varname> in
@@ -375,7 +375,7 @@
</para>
<para>
- More details can be found in Jam reference, <xref
+ More details can be found in the Jam reference, <xref
linkend="jam.language.rules"/>.
</para>
</section>
@@ -386,9 +386,9 @@
<para>
On startup, Boost.Build searches and reads two configuration files:
<filename>site-config.jam</filename> and <filename>user-config.jam</filename>.
- The first one is usually installed and maintained by system administrator, and
- the second is for user to modify. You can edit the one in the top-level
- directory of Boost.Build installation or create a copy in your home
+ The first one is usually installed and maintained by a system administrator, and
+ the second is for the user to modify. You can edit the one in the top-level
+ directory of your Boost.Build installation or create a copy in your home
directory and edit the copy. The following table explains where both files
are searched.
</para>
@@ -453,7 +453,7 @@
</tip>
<para>
- Usually, <filename>user-config.jam</filename> just defines available compilers
+ Usually, <filename>user-config.jam</filename> just defines the available compilers
and other tools (see <xref linkend="bbv2.recipies.site-config"/> for more advanced
usage). A tool is configured using the following syntax:
</para>
@@ -462,7 +462,7 @@
using <replaceable>tool-name</replaceable> : ... ;
</programlisting>
<para>
- The <functionname>using</functionname> rule is given a name of tool, and
+ The <functionname>using</functionname> rule is given the name of tool, and
will make that tool available to Boost.Build. For example,
<programlisting>
using gcc ;
@@ -476,7 +476,7 @@
</para>
<para>
- For all the C++ compiler toolsets Boost.Build supports
+ For all the C++ compiler toolsets that Boost.Build supports
out-of-the-box, the list of parameters to
<functionname>using</functionname> is the same: <parameter
class="function">toolset-name</parameter>, <parameter
@@ -509,8 +509,8 @@
<para>
Some Boost.Build toolsets will use that path to take additional actions
required before invoking the compiler, such as calling vendor-supplied
- scripts to set up its required environment variables. When compiler
- executables for C and C++ are different, path to the C++ compiler
+ scripts to set up its required environment variables. When the compiler
+ executables for C and C++ are different, the path to the C++ compiler
executable must be specified. The command can
be any command allowed by the operating system. For example:
<programlisting>
@@ -587,7 +587,7 @@
<varlistentry>
<term>options</term>
- <listitem><para>Options start with either dash, or two dashes. The standard options
+ <listitem><para>Options start with either one or two dashes. The standard options
are listed below, and each project may add additional options</para></listitem>
</varlistentry>
@@ -595,8 +595,8 @@
<term>properties</term>
<listitem><para>Properties specify details of what you want to build (e.g. debug
- or release variant). Syntactically, all command line tokens with equal sign in them
- are considered to specify properties. In the simplest form, property looks like
+ or release variant). Syntactically, all command line tokens with an equal sign in them
+ are considered to specify properties. In the simplest form, a property looks like
<command><replaceable>feature</replaceable>=<replaceable>value</replaceable></command>
</para></listitem>
</varlistentry>
@@ -613,7 +613,7 @@
<section id="bbv2.overview.invocation.examples">
<title>Examples</title>
- <para>To build all targets defined in Jamfile in the current directory with default properties, run:
+ <para>To build all targets defined in the Jamfile in the current directory with the default properties, run:
<screen>
b2
</screen>
@@ -673,8 +673,8 @@
<varlistentry>
<term><option>--build-dir</option></term>
<listitem>
- <para>Changes build directories for all project roots being built. When
- this option is specified, all Jamroot files should declare project name.
+ <para>Changes the build directories for all project roots being built. When
+ this option is specified, all Jamroot files must declare a project name.
The build directory for the project root will be computed by concatanating
the value of the <option>--build-dir</option> option, the project name
specified in Jamroot, and the build dir specified in Jamroot
@@ -690,7 +690,7 @@
<varlistentry>
<term><option>--version</option></term>
<listitem>
- <para>Prints information on Boost.Build and Boost.Jam
+ <para>Prints information on the Boost.Build and Boost.Jam
versions.
</para>
</listitem>
@@ -713,7 +713,7 @@
<varlistentry>
<term><option>-q</option></term>
<listitem>
- <para>Stop at first error, as opposed to continuing to build targets
+ <para>Stop at the first error, as opposed to continuing to build targets
that don't depend on the failed ones.</para>
</listitem>
</varlistentry>
@@ -728,7 +728,7 @@
<varlistentry>
<term><option>--debug-configuration</option></term>
<listitem>
- <para>Produces debug information about loading of Boost.Build
+ <para>Produces debug information about the loading of Boost.Build
and toolset files.</para>
</listitem>
</varlistentry>
@@ -744,7 +744,7 @@
<varlistentry>
<term><option>--debug-generators</option></term>
<listitem>
- <para>Produces debug output from generator search process.
+ <para>Produces debug output from the generator search process.
Useful for debugging custom generators.
</para>
</listitem>
@@ -753,8 +753,8 @@
<varlistentry>
<term><option>--ignore-config</option></term>
<listitem>
- <para>Do not load <literal>site-config.jam</literal> and
- <literal>user-config.jam</literal> configuration files.
+ <para>Do not load <literal>site-config.jam</literal> or
+ <literal>user-config.jam</literal>.
</para>
</listitem>
</varlistentry>
@@ -937,11 +937,12 @@
</tgroup>
</table>
- If you have more than one version of a given C++ toolset (e.g. configured in
+ <para>If you have more than one version of a given C++ toolset (e.g. configured in
<filename>user-config.jam</filename>, or autodetected, as happens with msvc), you can
request the specific version by passing
<code><replaceable>toolset</replaceable>-<replaceable>version</replaceable></code> as
the value of the <code>toolset</code> feature, for example <code>toolset=msvc-8.0</code>.
+ </para>
<para>
@@ -956,13 +957,13 @@
<para>
Then a total of 4 builds will be performed. For convenience,
instead of specifying all requested values of a feature in separate command line elements,
- you can separate the values with commands, for example:
+ you can separate the values with commas, for example:
</para>
<screen>
b2 link=static,shared threading=single,multi
</screen>
<para>
- The comma has special meaning only if the feature has a fixed set of values, so
+ The comma has this special meaning only if the feature has a fixed set of values, so
</para>
<screen>
b2 include=static,shared
@@ -1068,7 +1069,7 @@
</para>
<para>The actual requirements for a target are obtained by refining
- requirements of the project where a target is declared with the
+ the requirements of the project where the target is declared with the
explicitly specified requirements. The same is true for
usage-requirements. More details can be found in
<xref linkend="bbv2.reference.variants.proprefine"/>
@@ -1158,7 +1159,7 @@
<programlisting>
exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ;
</programlisting>
- There is a number of other features, listed in
+ There are a number of other features, listed in
<xref linkend="bbv2.overview.builtins.features"/>. For example if
a library can only be built statically, or a file can't be compiled
with optimization due to a compiler bug, one can use
@@ -1221,13 +1222,13 @@
<para>Requirements explicitly specified for a target are usually
combined with the requirements specified for the containing project. You
- can cause a target to completely ignore specific project's requirement
- using the syntax by adding a minus sign before a property, for example:
+ can cause a target to completely ignore a specific project requirement
+ using the syntax by adding a minus sign before the property, for example:
<programlisting>
exe main : main.cpp : <emphasis role="bold">-<define>UNNECESSARY_DEFINE</emphasis> ;
</programlisting>
- This syntax is the only way to ignore free properties from a parent,
- such as defines. It can be also useful for ordinary properties. Consider
+ This syntax is the only way to ignore free properties, such as defines,
+ from a parent. It can be also useful for ordinary properties. Consider
this example:
<programlisting>
project test : requirements <threading>multi ;
@@ -1235,12 +1236,12 @@
exe test2 : test2.cpp : <threading>single ;
exe test3 : test3.cpp : -<threading>multi ;
</programlisting>
- Here, <code>test1</code> inherits project requirements and will always
+ Here, <code>test1</code> inherits the project requirements and will always
be built in multi-threaded mode. The <code>test2</code> target
- <emphasis>overrides</emphasis> project's requirements and will
+ <emphasis>overrides</emphasis> the project's requirements and will
always be built in single-threaded mode. In contrast, the
<code>test3</code> target <emphasis>removes</emphasis> a property
- from project requirements and will be built either in single-threaded or
+ from the project requirements and will be built either in single-threaded or
multi-threaded mode depending on which variant is requested by the
user.</para>
@@ -1260,7 +1261,7 @@
</programlisting>
would build a multi-threaded target unless the user
explicitly requests a single-threaded version. The difference between
- requirements and default-build is that requirements cannot be
+ the requirements and the default-build is that the requirements cannot be
overridden in any way.
</para>
</section>
@@ -1276,7 +1277,7 @@
it. We can express this situation using <firstterm>target
alternatives</firstterm>:
<programlisting>
-lib demangler : dummy_demangler.cpp ; # alternative 1
+lib demangler : dummy_demangler.cpp ; # alternative 1
lib demangler : demangler_gcc.cpp : <toolset>gcc ; # alternative 2
lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3
</programlisting>
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk