Changeset 1e9ccfa


Ignore:
Timestamp:
10/07/2022 04:58:29 PM (2 months ago)
Author:
David Bryant <davidbryant@…>
Branches:
plabs/python-mods, trunk
Children:
f2ae6ba8
Parents:
1f1f2230
Message:

Corrected for English idiom, cleaned up punctuation, etc. Added some white space.
Re-phrased a few things here and there, to improve clarity.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • introduction/welcome/conventions.xml

    r1f1f2230 r1e9ccfa  
    1717  <sect2>
    1818  <title>Typographical Conventions</title>
    19   <para>To make things easy to follow, there are a number of conventions used
    20   throughout the book.  Following are some examples:</para>
     19  <para>To make things easy to follow, a number of conventions are used
     20  throughout the book.  Here are some examples:</para>
    2121
    2222<screen><userinput>./configure --prefix=/usr</userinput></screen>
    2323
    2424  <blockquote>
    25     <para>This form of text is designed to be typed exactly as seen unless
     25    <para>This form of text should be typed exactly as shown unless
    2626    otherwise noted in the surrounding text. It is also used to identify
    2727    references to specific commands.</para>
     
    3232
    3333  <blockquote>
    34     <para>This form of text (fixed width text) is showing screen
    35     output, probably a result from issuing a command. It is also used to
     34    <para>This form of text (fixed width font) shows screen
     35    output, probably the result of issuing a command. It is also used to
    3636    show filenames such as <filename>/boot/grub/grub.conf</filename></para>
    3737  </blockquote>
     
    4040
    4141  <blockquote>
    42     <para>This form of text is used for several purposes in the
    43     book but mainly to emphasize important points or to give examples as to
     42    <para>This form of text is used for several purposes,
     43    but mainly to emphasize important points, or to give examples of
    4444    what to type.</para>
    4545  </blockquote>
     
    4949  <blockquote>
    5050    <para>This form of text is used for hypertext links external to
    51     the book such as HowTos, download locations, websites, etc.</para>
     51    the book, such as HowTos, download locations, websites, etc.</para>
    5252  </blockquote>
    5353
     
    5656  <blockquote>
    5757    <para>This form of text is used for links internal to
    58     the book such as another section describing a different package.</para>
     58    the book, such as another section describing a different package.</para>
    5959  </blockquote>
    6060
     
    6666
    6767  <blockquote>
    68     <para>This type of section is used mainly when creating configuration
     68    <para>This style is mainly used when creating configuration
    6969    files.  The first command (in bold) tells the system to create
    7070    the file <filename>$LFS/etc/group</filename> from whatever is typed on the
    71     following lines until the sequence EOF is encountered.
    72     Therefore, this whole section is generally typed as seen.</para>
     71    following lines, until the sequence EOF is encountered.
     72    Therefore, this whole section is usually typed exactly as shown.
     73    Remember, copy and paste is your friend!</para>
    7374  </blockquote>
    7475
     
    7778  <blockquote>
    7879    <para>This form of text is used to encapsulate text that should be
    79     modified and is not to be typed as seen, or copy and pasted. Note that
    80     the square brackets are not part of the text, but should be substituted
    81     for as well.</para>
     80    modified, and is not to be typed as shown, or copied and pasted.
     81    The angle brackets are not part of the literal text; they are part of the
     82    substitution.</para>
    8283  </blockquote>
    8384
     
    8990  </blockquote>
    9091
     92  <para>&nbsp;</para> <!-- add extra white space to improve readability -->
    9193  </sect2>
    9294
     
    9496  <title>Conventions Used for Package Dependencies</title>
    9597
    96     <para>When packages are created, the authors depend on prior work.  In
    97     order to build a package in BLFS, these dependencies must be built prior to
    98     the desired package.  For each package, any prerequisite packages are listed
     98    <para>When new packages are created, the software's authors depend on prior work.  In
     99    order to build a package in BLFS, these dependencies must be built before
     100    the desired package can be compiled.  For each package, prerequisites are listed
    99101    in one or more separate sections:  Required, Recommended, and Optional.</para>
    100102
    101103    <bridgehead renderas="sect3">Required Dependencies</bridgehead>
    102104
    103     <para>These dependencies are the minimum prerequisite packages required to
    104     build the package.  Omitted from the list are packages in LFS and required
    105     dependencies of other required packages.</para>
     105    <para>These dependencies are the bare minimum needed to
     106    build the package.  Packages in LFS, and the required
     107    dependencies of these required packages, are omitted from this list.
     108    Always remember to check for nested dependencies.</para>
    106109
    107110    <bridgehead renderas="sect3">Recommended Dependencies</bridgehead>
    108111
    109     <para>These dependencies are those that the BLFS editors have determined
     112    <para>These are dependencies the BLFS editors have determined
    110113    are important to give the package reasonable capabilities.  Package
    111114    installation instructions assume they are installed.  If a recommended
    112     package is not desired, the instructions may need to be modified to
     115    package is not installed, the instructions may require modification, to
    113116    accommodate the missing package.</para>
    114117
    115118    <bridgehead renderas="sect3">Optional Dependencies</bridgehead>
    116119
    117     <para>These dependencies are those that the package may use.  Integration
    118     of optional dependencies may be automatic by the package or may need
    119     additional instructions not presented by BLFS.  Optional packages may be
    120     listed without corresponding BLFS instructions.  In this case it is up to
    121     the user to determine appropriate installation instructions. </para>
    122 
     120    <para>These are dependencies the package <emphasis>may</emphasis> use.  Integration
     121    of optional dependencies may be automatic by the package, or
     122    additional steps not presented by BLFS may be necessary.  Optional dependencies are
     123    sometimes listed without explicit BLFS instructions.  In this case you must
     124    determine how to perform the installation yourself. </para>
     125
     126    <para>&nbsp;</para> <!-- add extra white space to improve readability -->
    123127  </sect2>
    124128
     
    126130  <title>Conventions Used for Kernel Configuration Options</title>
    127131
    128     <para>Some packages have specific needs regarding the kernel configuration.
    129     The general layout is the following:</para>
     132    <para>Some packages require specific kernel configuration options.
     133    The general layout for these looks like this:</para>
    130134
    131135<screen><literal>Master section ---&gt;
     
    139143
    140144    <para>[CONFIG_...] on the right gives the name of the option, so you can
    141     easily check whether it is set in your <filename>config</filename> file.
     145    easily check whether it is set in your <filename>.config</filename> file.
    142146    The meaning of the various entries is:
    143147
     
    157161          <emphasis role="bold">Required parameter</emphasis></entry>
    158162        <entry>
    159           the option could be either built-in or not selected: it must be
     163          the option can either be built-in, or not selected: it must be
    160164          selected
    161165        </entry>
     
    167171        </entry>
    168172        <entry>
    169           the option could be either built-in, module, or not selected:
     173          the option can be built-in, a module, or not selected (tri-state):
    170174          it must be selected as built-in
    171175        </entry>
     
    177181        </entry>
    178182        <entry>
    179           the option could be either built-in, module, or not selected:
    180           it must be selected, either as built-in or module
     183          the option can be built-in, a module, or not selected:
     184          it must be selected, either as built-in or as a module
    181185        </entry>
    182186      </row>
     
    186190        </entry>
    187191        <entry>
    188           rarely used: the option could be either built-in, module, or not
    189           selected: it may be selected at will
     192          rarely used: the option can be built-in, a module, or not
     193          selected: it may be set any way you wish
    190194        </entry>
    191195      </row>
     
    195199        </entry>
    196200        <entry>
    197           the option could be either built-in or not selected: it must
     201          the option can either be built-in or not selected: it must
    198202          <emphasis>not</emphasis> be selected
    199203        </entry>
     
    204208        </entry>
    205209        <entry>
    206           the option could be either built-in, module, or not selected:
     210          the option can be built-in, a module, or not selected:
    207211          it must <emphasis>not</emphasis> be selected
    208212        </entry>
     
    213217
    214218    <para>Note that, depending on other selections, the angle brackets
    215     (&lt;&gt;) may appear as braces ({}), if the option cannot be unselected,
    216     or even dashes (-*- or -M-), when the choice is imposed.
    217     The help text about the option specifies the other selections on which this
     219    (&lt;&gt;) in the configuration menu may appear as braces ({}) if the option cannot be unselected,
     220    or even as dashes (-*- or -M-), when the choice is imposed.
     221    The help text describing the option specifies the other selections on which this
    218222    option relies, and how those other selections are set.</para>
    219223
     224    <para>&nbsp;</para> <!-- add extra white space to improve readability -->
    220225  </sect2>
    221226
     
    225230    <para>As in LFS, each package in BLFS has a build time listed in Standard
    226231    Build Units (SBUs).   These times are relative to the time it took to build
    227     binutils in LFS and are intended to provide some insight into how long it
     232    binutils in LFS, and are intended to provide some insight into how long it
    228233    will take to build a package. Most times listed are for a single processor
    229234    or core to build the package. In some cases, large, long running builds
     
    232237    multiple cores.  Note that while this speeds up the build on systems with
    233238    the appropriate hardware, the speedup is not linear and to some extent
    234     depends on the individual package and specific hardware used.  </para>
    235 
    236     <para>For packages which use ninja (e.g. anything using meson) or rust, by
    237     default all cores are used so similar comments will be seen on such packages
     239    depends on the individual package and the specific hardware used.  </para>
     240
     241    <para>For packages which use ninja (i.e., anything using meson) or rust, by
     242    default all cores are used; similar comments will be seen on such packages
    238243    even when the build time is minimal.</para>
    239244
     
    241246    machines the time may be considerably greater even when the build does not
    242247    use swap. In particular, different micro-architectures will build some
    243     files at different relative speeds and this can introduce delays when
     248    files at different relative speeds, and this can introduce delays when
    244249    certain make targets wait for another file to be created. Where a large
    245250    build uses a lot of C++ files, processors with Simultaneous Multi Threading
     
    248253    other cores idle).</para>
    249254
    250     <para>Some packages do not support parallel builds and using -j1 for the
    251     make command is required.  Packages that are known to have such limits are
    252     marked as such in the text.</para>
     255    <para>Some packages do not support parallel builds; for these, the
     256    make command must specify -j1.  Packages that are known to impose such limits are
     257    so marked in the text.</para>
    253258
    254259  </sect2>
Note: See TracChangeset for help on using the changeset viewer.