Changes in introduction/welcome/conventions.xml [4a570af1:3f2db3a6]

File:

• introduction/welcome/conventions.xml (modified) (23 diffs)

introduction/welcome/conventions.xml

@@ -9 +9 @@
   <?dbhtml filename="conventions.html"?>
 
-  <sect1info>
-    <date>$Date$</date>
-  </sect1info>
 
   <title>Conventions Used in this Book</title>
@@ -17 +14 @@
   <sect2>
   <title>Typographical Conventions</title>
-  <para>To make things easy to follow, there are a number of conventions used
-  throughout the book.  Following are some examples:</para>
+  <para>To make things easy to follow, a number of conventions are used
+  throughout the book.  Here are some examples:</para>
 
 <screen><userinput>./configure --prefix=/usr</userinput></screen>
 
   <blockquote>
-    <para>This form of text is designed to be typed exactly as seen unless
+    <para>This form of text should be typed exactly as shown unless
     otherwise noted in the surrounding text. It is also used to identify
     references to specific commands.</para>
@@ -32 +29 @@
 
   <blockquote>
-    <para>This form of text (fixed width text) is showing screen
-    output, probably a result from issuing a command. It is also used to
+    <para>This form of text (fixed width font) shows screen
+    output, probably the result of issuing a command. It is also used to
     show filenames such as <filename>/boot/grub/grub.conf</filename></para>
   </blockquote>
@@ -40 +37 @@
 
   <blockquote>
-    <para>This form of text is used for several purposes in the
-    book but mainly to emphasize important points or to give examples as to
+    <para>This form of text is used for several purposes,
+    but mainly to emphasize important points, or to give examples of
     what to type.</para>
   </blockquote>
@@ -49 +46 @@
   <blockquote>
     <para>This form of text is used for hypertext links external to
-    the book such as HowTos, download locations, websites, etc.</para>
+    the book, such as HowTos, download locations, websites, etc.</para>
   </blockquote>
 
@@ -56 +53 @@
   <blockquote>
     <para>This form of text is used for links internal to
-    the book such as another section describing a different package.</para>
+    the book, such as another section describing a different package.</para>
   </blockquote>
 
@@ -66 +63 @@
 
   <blockquote>
-    <para>This type of section is used mainly when creating configuration
+    <para>This style is mainly used when creating configuration
     files.  The first command (in bold) tells the system to create
     the file <filename>$LFS/etc/group</filename> from whatever is typed on the
-    following lines until the sequence EOF is encountered.
-    Therefore, this whole section is generally typed as seen.</para>
+    following lines, until the sequence EOF is encountered.
+    Therefore, this whole section is usually typed exactly as shown.
+    Remember, copy and paste is your friend!</para>
   </blockquote>
 
@@ -77 +75 @@
   <blockquote>
     <para>This form of text is used to encapsulate text that should be
-    modified and is not to be typed as seen, or copy and pasted. Note that
-    the square brackets are not part of the text, but should be substituted
-    for as well.</para>
+    modified, and is not to be typed as shown, or copied and pasted. 
+    The angle brackets are not part of the literal text; they are part of the
+    substitution.</para>
   </blockquote>
 
@@ -89 +87 @@
   </blockquote>
 
+  <para>&nbsp;</para> <!-- add extra white space to improve readability -->
   </sect2>
 
@@ -94 +93 @@
   <title>Conventions Used for Package Dependencies</title>
 
-    <para>When packages are created, the authors depend on prior work.  In
-    order to build a package in BLFS, these dependencies must be built prior to
-    the desired package.  For each package, any prerequisite packages are listed
+    <para>When new packages are created, the software's authors depend on prior work.  In
+    order to build a package in BLFS, these dependencies must be built before
+    the desired package can be compiled.  For each package, prerequisites are listed
     in one or more separate sections:  Required, Recommended, and Optional.</para>
 
     <bridgehead renderas="sect3">Required Dependencies</bridgehead>
 
-    <para>These dependencies are the minimum prerequisite packages required to
-    build the package.  Omitted from the list are packages in LFS and required
-    dependencies of other required packages.</para>
+    <para>These dependencies are the bare minimum needed to
+    build the package.  Packages in LFS, and the required
+    dependencies of these required packages, are omitted from this list.
+    Always remember to check for nested dependencies.</para>
 
     <bridgehead renderas="sect3">Recommended Dependencies</bridgehead>
 
-    <para>These dependencies are those that the BLFS editors have determined
+    <para>These are dependencies the BLFS editors have determined
     are important to give the package reasonable capabilities.  Package
     installation instructions assume they are installed.  If a recommended
-    package is not desired, the instructions may need to be modified to
+    package is not installed, the instructions may require modification, to
     accommodate the missing package.</para>
 
     <bridgehead renderas="sect3">Optional Dependencies</bridgehead>
 
-    <para>These dependencies are those that the package may use.  Integration
-    of optional dependencies may be automatic by the package or may need
-    additional instructions not presented by BLFS.  Optional packages may be
-    listed without corresponding BLFS instructions.  In this case it is up to
-    the user to determine appropriate installation instructions. </para>
-
+    <para>These are dependencies the package <emphasis>may</emphasis> use.  Integration
+    of optional dependencies may be automatic by the package, or 
+    additional steps not presented by BLFS may be necessary.  Optional dependencies are
+    sometimes listed without explicit BLFS instructions.  In this case you must
+    determine how to perform the installation yourself. </para>
+
+    <para>&nbsp;</para> <!-- add extra white space to improve readability -->
   </sect2>
 
@@ -126 +127 @@
   <title>Conventions Used for Kernel Configuration Options</title>
 
-    <para>Some packages have specific needs regarding the kernel configuration.
-    The general layout is the following:</para>
+    <para>Some packages require specific kernel configuration options.
+    The general layout for these looks like this:</para>
 
 <screen><literal>Master section ---&gt;
@@ -139 +140 @@
 
     <para>[CONFIG_...] on the right gives the name of the option, so you can
-    easily check whether it is set in your <filename>config</filename> file.
+    easily check whether it is set in your <filename>.config</filename> file.
     The meaning of the various entries is:
 
@@ -157 +158 @@
           <emphasis role="bold">Required parameter</emphasis></entry>
         <entry>
-          the option could be either built-in or not selected: it must be
+          the option can either be built-in, or not selected: it must be
           selected
         </entry>
@@ -167 +168 @@
         </entry>
         <entry>
-          the option could be either built-in, module, or not selected:
+          the option can be built-in, a module, or not selected (tri-state):
           it must be selected as built-in
         </entry>
@@ -177 +178 @@
         </entry>
         <entry>
-          the option could be either built-in, module, or not selected:
-          it must be selected, either as built-in or module
+          the option can be built-in, a module, or not selected:
+          it must be selected, either as built-in or as a module
         </entry>
       </row>
@@ -186 +187 @@
         </entry>
         <entry>
-          rarely used: the option could be either built-in, module, or not
-          selected: it may be selected at will
+          rarely used: the option can be built-in, a module, or not
+          selected: it may be set any way you wish
         </entry>
       </row>
@@ -195 +196 @@
         </entry>
         <entry>
-          the option could be either built-in or not selected: it must
+          the option can either be built-in or not selected: it must
           <emphasis>not</emphasis> be selected
         </entry>
@@ -204 +205 @@
         </entry>
         <entry>
-          the option could be either built-in, module, or not selected:
+          the option can be built-in, a module, or not selected:
           it must <emphasis>not</emphasis> be selected
         </entry>
@@ -213 +214 @@
 
     <para>Note that, depending on other selections, the angle brackets
-    (&lt;&gt;) may appear as braces ({}), if the option cannot be unselected,
-    or even dashes (-*- or -M-), when the choice is imposed.
-    The help text about the option specifies the other selections on which this
+    (&lt;&gt;) in the configuration menu may appear as braces ({}) if the option cannot be unselected,
+    or even as dashes (-*- or -M-), when the choice is imposed.
+    The help text describing the option specifies the other selections on which this
     option relies, and how those other selections are set.</para>
 
+    <para>&nbsp;</para> <!-- add extra white space to improve readability -->
   </sect2>
 
@@ -225 +227 @@
     <para>As in LFS, each package in BLFS has a build time listed in Standard
     Build Units (SBUs).   These times are relative to the time it took to build
-    binutils in LFS and are intended to provide some insight into how long it
+    binutils in LFS, and are intended to provide some insight into how long it
     will take to build a package. Most times listed are for a single processor
     or core to build the package. In some cases, large, long running builds
@@ -232 +234 @@
     multiple cores.  Note that while this speeds up the build on systems with
     the appropriate hardware, the speedup is not linear and to some extent
-    depends on the individual package and specific hardware used.  </para>
-
-    <para>For packages which use ninja (e.g. anything using meson) or rust, by
-    default all cores are used so similar comments will be seen on such packages
+    depends on the individual package and the specific hardware used.  </para>
+
+    <para>For packages which use ninja (i.e., anything using meson) or rust, by
+    default all cores are used; similar comments will be seen on such packages
     even when the build time is minimal.</para>
 
@@ -241 +243 @@
     machines the time may be considerably greater even when the build does not
     use swap. In particular, different micro-architectures will build some
-    files at different relative speeds and this can introduce delays when
+    files at different relative speeds, and this can introduce delays when
     certain make targets wait for another file to be created. Where a large
     build uses a lot of C++ files, processors with Simultaneous Multi Threading
@@ -248 +250 @@
     other cores idle).</para>
 
-    <para>Some packages do not support parallel builds and using -j1 for the
-    make command is required.  Packages that are known to have such limits are
-    marked as such in the text.</para>
+    <para>Some packages do not support parallel builds; for these, the
+    make command must specify -j1.  Packages that are known to impose such limits are
+    so marked in the text.</para>
 
   </sect2>