Documentation updates

2 files changed, 98 insertions, 70 deletions

diff --git a/NEWS b/NEWS
index e16e5c7..260952c 100644
--- a/NEWS
+++ b/NEWS
@@ -2,8 +2,8 @@ Version 0.13.0
 
   * Support for project-specific configuration.
 
-    A project can now use the new config directive to define config.*
-    variables similar to the build system core and modules. For example:
+    A project can now use the config directive to define config.<porject>.*
+    variables, similar to the build system core and modules. For example:
 
     config [bool]   config.libhello.fancy    ?= false
     config [string] config.libhello.greeting ?= 'Hello'
@@ -21,18 +21,20 @@ Version 0.13.0
 
   * Support for ad hoc recipes.
 
-    With ad hoc recipes we can now provide custom implementation of operations
-    (update, test, etc) for certain targets. For example:
+    With ad hoc recipes it is now possible to provide custom implementations
+    of operations (update, test, etc) for certain targets. For example, this
+    is how we can pick a config header based on the platform:
 
-    hxx{config}: hxx{config-linux}:   include = ($cxx.target.class == 'linux')
-    hxx{config}: hxx{config-windows}: include = ($cxx.target.class == 'windows')
-    hxx{config}: hxx{config-macos}:   include = ($cxx.target.class == 'macos')
+    hxx{config}: hxx{config-linux}: include = ($cxx.target.class == 'linux')
+    hxx{config}: hxx{config-win32}: include = ($cxx.target.class == 'windows')
+    hxx{config}: hxx{config-macos}: include = ($cxx.target.class == 'macos')
     hxx{config}:
     {{
       cp $path($<) $path($>)
     }}
 
-    Another, more elaborate example:
+    Another, more elaborate example that shows how to embed binary data into
+    the source code with the help of the xxd(1) utility:
 
     import! xxd = xxd%exe{xxd}
 
@@ -49,6 +51,10 @@ Version 0.13.0
       #
       $xxd -s -1 -l 1 $i | sed -n -e 's/^([0-9]+):.*$/\1/p' - | set pos
 
+      if ($empty($pos))
+        exit "unable to extract input size from xxd output"
+      end
+
       # Write header and source.
       #
       echo "#pragma once"                         >$h
@@ -62,9 +68,9 @@ Version 0.13.0
     which means these recipes are portable. See the Testscript manual for the
     list of available builtins.
 
-    Ad hoc recipes can also be used to customize a part of the build chain
-    handled by rules. For example, in embedded systems development it is often
-    required to perform a custom link step:
+    Ad hoc recipes can also be used to customize a part of the update chain
+    otherwise handled by rules. For example, in embedded systems development
+    it is often required to perform a custom link step:
 
     obje{foo}: cxx{foo}
     obje{bar}: cxx{bar}
@@ -75,8 +81,8 @@ Version 0.13.0
         $cxx.libs $cc.libs
     }}
 
-    While the above recipes are for the update operation, ad hoc recipes can
-    be used for other operations, such as test. For example:
+    While the above examples are all for the update operation, ad hoc recipes
+    can be used for other operations, such as test. For example:
 
     exe{hello}: cxx{hello}
     % test
@@ -100,9 +106,9 @@ Version 0.13.0
       }
     }}
 
-    In this release support for ad hoc recipe is at the "technology preview"
-    stage. In particular, there is no documentation and are known rough edges,
-    especially around diagnostics.
+    Note that in this release support for ad hoc recipe is at the "technology
+    preview" stage. In particular, there is no documentation and are known
+    rough edges.
 
   * Support for project-local importation.
 
@@ -114,7 +120,7 @@ Version 0.13.0
     include ../libhello/
     exe{hello}: ../libhello/lib{hello}
 
-    Can now do this:
+    Can now do:
 
     import lib = lib{hello}
     exe{hello}: $lib
@@ -123,19 +129,21 @@ Version 0.13.0
     in the project's export stub. In other words, project-local importation
     goes through the same mechanism as normal import.
 
+    See the "Target Importation" section in the manual for details.
+
   * Support for ad hoc importation and "glue buildfiles".
 
     If the target being imported has no project name and is either absolute or
     is a relative directory, then this is treated as ad hoc importation.
-    Semantically it is similar to a normal import but with the location of the
-    project being imported hard-coded into the buildfile.
+    Semantically it is similar to normal importation but with the location of
+    the project being imported hard-coded into the buildfile.
 
-    This type of import can be used to create a special "glue buildfile" that
-    "pulls" together several projects, usually for convenience of development.
-    One typical case that calls for such a glue buildfile is a multi-package
-    project. To be able to invoke the build system driver directly in the
-    project root, we can add a glue buildfile that imports and builds all the
-    packages:
+    In particular, this type of import can be used to create a special "glue
+    buildfile" that "pulls" together several projects, usually for convenience
+    of development. One typical case that calls for such a glue buildfile is a
+    multi-package project. To be able to invoke the build system directly in
+    the project root, we can add a glue buildfile that imports and builds all
+    the packages:
 
     import pkgs = */
     ./: $pkgs
@@ -159,13 +167,13 @@ Version 0.13.0
 
     ./: ... doc{README} legal{LICENSE}
 
-    $ b install ... config.install.legal=/usr/share/licenses/hello/
+    $ b install ... config.install.legal='share/licenses/<project>/'
 
   * Support for <var>-substitutions in config.install.* values.
 
     The currently recognized variable names are <project> and <private> which
-    are substituted with the project name and private subdirectory,
-    respectively. This can be used along these lines:
+    are replaced with the project name and private subdirectory, respectively.
+    This can be used along these lines:
 
     $ b config.install.libexec='exec_root/lib/<project>/' install
 
@@ -183,25 +191,26 @@ Version 0.13.0
 
   * New $defined(<variable>) and $visibility(<variable>) functions.
 
-  * New $target.process_path() function analogous to $target.path().
+  * New $target.process_path() function for exe{} targets analogous to
+    $target.path().
 
   * New $bin.link_member() function.
 
-    Given a linker output target type ("exe", "lib[as]", or "libu[eas]") this
-    function returns the target type of lib{} group member ("liba" or "libs")
-    that will be picked when linking a lib{} group to this target type.
+    Given a linker output target type (exe, lib[as], or libu[eas]) this
+    function returns the target type of lib{} group member (liba or libs) that
+    will be picked when linking a lib{} group to this target type.
 
   * New scripting builtins: date, env.
 
   * New variable block applicability semantics in dependency chains.
 
-    Before the block used to apply to the set of prerequisites before the last
+    Prior the block used to apply to the set of prerequisites before the last
     colon. This turned out to be counterintuitive and not very useful since
     prerequisite-specific variables are less common than target-specific.
 
-    The new rule is if the chain ends with the colon, then the block applies
-    to the last set of prerequisites. Otherwise, it applies to the last set of
-    targets. For example:
+    The new rule is as follows: if the chain ends with the colon, then the
+    block applies to the last set of prerequisites. Otherwise, it applies to
+    the last set of targets. For example:
 
     ./: exe{test}: cxx{main}
     {
@@ -216,13 +225,14 @@ Version 0.13.0
   * Test and install modules are now implicitly loaded for simple projects.
 
     While these can be useful on their own, this also makes the test and
-    install operations available in simple projects, which is handy for "glue"
-    projects that "pull" (using ad hoc import) a bunch of other projects.
+    install operations available in simple projects, which is handy for "glue
+    buildfiles" that "pull" (using ad hoc import) a bunch of other projects.
 
   * The translated {c,cxx}.std options are now folded into the compiler mode
-    options. This makes them accessible from ad hoc recipes.
+    options ({c,cxx}.mode). This makes them accessible from ad hoc recipes.
 
-  * Common pkg-config .pc file in addition to static/shared-specific.
+  * Generation of a common pkg-config .pc file in addition to static/shared-
+    specific.
 
     The common .pc file is produced by ignoring any static/shared-specific
     poptions and splitting loptions/libs into Libs/Libs.private.
@@ -234,21 +244,21 @@ Version 0.13.0
   * The ~host configuration now only contains the cc and bin modules
     configuration.
 
-    Also added the ~build2 configuration that contains everything (except
-    config.dist.*) to be used for build system modules.
+    There is also the new ~build2 configuration that contains everything
+    (except config.dist.*) and is meant to be used for build system modules.
 
   * Reworked tool importation support.
 
     Specifically, now config.<tool> (like config.cli) is handled by the import
-    machinery (it is like a shorter alias for config.import.<tool>.<tool>.exe
-    that we already had).
+    machinery (it is a shorter alias for config.import.<tool>.<tool>.exe that
+    we already had).
 
     This also adds support for uniform tool metadata extraction that is
     handled by the import machinery. As a result, a tool that follows the
     "build2 way" can be imported with metadata by the buildfile and/or
     corresponding module without any tool-specific code or brittleness
     associated with parsing --version or similar outputs. See the cli
-    tool/module for details.
+    tool/module for an example of how this all fits together.
 
     Finally, two new flavors of the import directive are now supported:
     import! triggers immediate importation skipping any rule-specific logic
@@ -262,10 +272,10 @@ Version 0.13.0
     if ($cli != [null])
       info "cli version $($cli:cli.version)"
 
-  * Reserved backtick (`) and bit-or (|) in evaluation context for future use.
+  * Backtick (`) and bit-or (|) are reserved in eval context for future use.
 
-    Specifically, they are reserved for future support of arithmetic
-    evaluation contexts and evaluation pipelines, respectively.
+    Specifically, they are reserved for planned support of arithmetic eval
+    contexts and evaluation pipelines, respectively.
 
 Version 0.12.0
 
diff --git a/doc/manual.cli b/doc/manual.cli
index 5b54882..dd449ce 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -775,15 +775,22 @@ hello/
 inclusion scheme where each header is prefixed with its project name. It also
 has a predictable name where users can expect to find our project's source
 code. Finally, this layout prevents clutter in the project's root directory
-which usually contains various other files. See \l{intro#structure-canonical
-Canonical Project Structure} for more information.
+which usually contains various other files. See \l{intro#proj-struct Canonical
+Project Structure} for details.
+
+Note, however, that this layout is not mandatory and \c{build2} is flexible
+enough to support various arrangements used in today's C and C++ projects.
+Furthermore, the \l{bdep-new(1)} command provides a number of customization
+options and chances are you will be able to create your preferred layout
+automatically. See \l{bdep-new.xhtml#src-layout SOURCE LAYOUT} for more
+information and examples.
 
 Note also that while we can name our header and source files however we like
-(but, again, see \l{intro#structure-canonical Canonical Project Structure} for
-some sensible guidelines), C++ module interface files need to embed a
-sufficient amount of the module name suffix in their names to unambiguously
-resolve all the modules within a project. See \l{#cxx-modules-build
-Building Modules} for details.|
+(but, again, see \l{intro#proj-struct Canonical Project Structure} for some
+sensible guidelines), C++ module interface files need to embed a sufficient
+amount of the module name suffix in their names to unambiguously resolve all
+the modules within a project. See \l{#cxx-modules-build Building Modules} for
+details.|
 
 The source subdirectory \c{buildfile} is identical to the simple project's
 minus the parts moved to \c{root.build}:
@@ -854,7 +861,7 @@ Speaking of libraries, let's see what the standard project structure looks
 like for one, using \c{libhello} created by \l{bdep-new(1)} as an example:
 
 \
-$ bdep new --no-init -t lib libhello
+$ bdep new --no-init -l c++ -t lib libhello
 
 $ tree libhello/
 libhello/
@@ -883,6 +890,17 @@ contents of the project's source subdirectory, \c{libhello/}, look quite a bit
 different. We will examine all of these differences in the coming sections, as
 we learn more about the build system.
 
+\N|Again, this layout is not mandatory and \l{bdep-new(1)} can create a number
+of alternative library structures. For example, if you prefer the
+\c{include/src} split, try:
+
+\
+$ bdep new --no-init -l c++ -t lib,split libhello
+\
+
+See \l{bdep-new.xhtml#src-layout SOURCE LAYOUT} for more examples.|
+
+
 \N|The standard project structure is not type (executable, library, etc) or
 even language specific. In fact, the same project can contain multiple
 executables and/or libraries (for example, both \c{hello} and \c{libhello}).
@@ -1356,9 +1374,9 @@ values end up in the \c{=+} and \c{+=} results is to imagine the new value
 taking the position of \c{=} and the existing value \- of \c{+}.|
 
 The above \c{buildfile} allows us to include our headers using the project's
-name as a prefix, inline with the \l{intro#structure-canonical Canonical
-Project Structure} guidelines. For example, if we added the \c{utility.hxx}
-header to our \c{hello} project, we would include it like this:
+name as a prefix, inline with the \l{intro#proj-struct Canonical Project
+Structure} guidelines. For example, if we added the \c{utility.hxx} header to
+our \c{hello} project, we would include it like this:
 
 \
 #include <iostream>
@@ -2716,11 +2734,11 @@ covered in the source subdirectory \c{buildfile} in \c{libhello}. Here it is
 in its entirety:
 
 \
-int_libs = # Interface dependencies.
-imp_libs = # Implementation dependencies.
+intf_libs = # Interface dependencies.
+impl_libs = # Implementation dependencies.
 
 lib{hello}: {hxx ixx txx cxx}{** -version} hxx{version} \
-  $imp_libs $int_libs
+  $impl_libs $intf_libs
 
 # Include the generated version header into the distribution (so that
 # we don't pick up an installed one) and don't remove it when cleaning
@@ -2744,7 +2762,7 @@ objs{*}: cxx.poptions += -DLIBHELLO_SHARED_BUILD
 lib{hello}:
 {
   cxx.export.poptions = \"-I$out_root\" \"-I$src_root\"
-  cxx.export.libs = $int_libs
+  cxx.export.libs = $intf_libs
 }
 
 liba{hello}: cxx.export.poptions += -DLIBHELLO_STATIC
@@ -2788,15 +2806,15 @@ Here are the parts relevant to the library metadata protocol in the above
 \c{buildfile}:
 
 \
-int_libs = # Interface dependencies.
-imp_libs = # Implementation dependencies.
+intf_libs = # Interface dependencies.
+impl_libs = # Implementation dependencies.
 
-lib{hello}: ... $imp_libs $int_libs
+lib{hello}: ... $impl_libs $intf_libs
 
 lib{hello}:
 {
   cxx.export.poptions = \"-I$out_root\" \"-I$src_root\"
-  cxx.export.libs = $int_libs
+  cxx.export.libs = $intf_libs
 }
 
 liba{hello}: cxx.export.poptions += -DLIBHELLO_STATIC
@@ -2853,8 +2871,8 @@ can safely treat it as an implementation dependency. The corresponding
 \c{import} directives in our \c{buildfile} will therefore look like this:
 
 \
-import int_libs = libformat%lib{format}
-import imp_libs = libprint%lib{print}
+import intf_libs = libformat%lib{format}
+import impl_libs = libprint%lib{print}
 \
 
 The preprocessor options (\c{poptions}) of an interface dependency must be
@@ -2865,7 +2883,7 @@ listing the interface dependencies in the \c{cxx.export.libs} variable:
 \
 lib{hello}:
 {
-  cxx.export.libs = $int_libs
+  cxx.export.libs = $intf_libs
 }
 \