Merge branch 'trunk' of git.linuxfromscratch.org:lfs into trunk

6 files changed, 63 insertions, 17 deletions

diff --git a/chapter08/bash.xml b/chapter08/bash.xml
index 787882b59..4ea981d5b 100644
--- a/chapter08/bash.xml
+++ b/chapter08/bash.xml
@@ -73,7 +73,7 @@
 
 <screen><userinput remap="test">chown -Rv tester .</userinput></screen>
 
-    <para>The testsuite of the package is designed to be run as a non-root
+    <para>The testsuite of the package is designed to be run as a non-&root;
     user that owns the terminal connected to standard input.  To satisfy the
     requirement, spawn a new pseudo terminal using
     <application>Expect</application> and run the tests as the <systemitem
diff --git a/chapter08/coreutils.xml b/chapter08/coreutils.xml
index 08b090fc0..cc8fc42ad 100644
--- a/chapter08/coreutils.xml
+++ b/chapter08/coreutils.xml
@@ -119,8 +119,8 @@ FORCE_UNSAFE_CONFIGURE=1 ./configure \
 
 <screen><userinput remap="test">echo "dummy:x:102:tester" &gt;&gt; /etc/group</userinput></screen>
 
-    <para>Fix some of the permissions so that the non-root user can compile and
-    run the tests:</para>
+    <para>Fix some of the permissions so that the non-&root; user can
+    compile and run the tests:</para>
 
 <screen><userinput remap="test">chown -Rv tester . </userinput></screen>
 
diff --git a/chapter08/meson.xml b/chapter08/meson.xml
index 91b4b61bc..d2132b5a1 100644
--- a/chapter08/meson.xml
+++ b/chapter08/meson.xml
@@ -70,14 +70,16 @@ install -vDm644 data/shell-completions/zsh/_meson /usr/share/zsh/site-functions/
       <varlistentry>
         <term><parameter>-w dist</parameter></term>
         <listitem>
-           <para>Put the created wheels into the `dist` directory.</para>
+           <para>Put the created wheels into the
+           <filename class='directory'>dist</filename> directory.</para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
         <term><parameter>--find-links dist</parameter></term>
         <listitem>
-           <para>Install wheels from the 'dist' directory.</para>
+           <para>Install wheels from the
+           <filename class='directory'>dist</filename> directory.</para>
         </listitem>
       </varlistentry>
 
diff --git a/chapter08/python.xml b/chapter08/python.xml
index 76530d782..b7f2da6b9 100644
--- a/chapter08/python.xml
+++ b/chapter08/python.xml
@@ -93,16 +93,43 @@
 <screen><userinput remap="install">make install</userinput></screen>
 
     <para>In serveral places we use the <command>pip3</command> command to
-    install Python 3 programs and modules for all users as root. This conflicts
-    with the Python developers recommendation to build packages in a virtual
-    environment as a regular user. To this end, a multi-line warning is
-    written when using <command>pip3</command> as the root user.  If desired,
-    supress this warning by running the following command:</para>
+    install Python 3 programs and modules for all users as
+    <systemitem class='username'>root</systemitem>. This conflicts
+    with the Python developers recommendation to install packages into a
+    virtual environment or the home directory of a regular user (by running
+    <command>pip3</command> as this user). To this end, a multi-line warning
+    is written when using <command>pip3</command> as the
+    <systemitem class='username'>root</systemitem> user.  The main reason
+    of this recommendation is for avoiding a conflict with the system
+    package manager (<command>dpkg</command> for example), but LFS does not
+    have a system-wide package manager so this is not a problem.  If desired,
+    suppress this warning by running the following command:</para>
 
 <screen><userinput remap="install">sed -e '/def warn_if_run_as_root/a\    return' \
     -i /usr/lib/python3.10/site-packages/pip/_internal/cli/req_command.py
 </userinput></screen>
 
+    <important>
+      <para>
+        In LFS and BLFS we normally build and install Python modules with the
+        <command>pip3</command> command.  Please take care that the
+        <command>pip3 install</command> commands in both the books should be
+        run as the &root; user unless it's for a Python virtual environment.
+        Running a <command>pip3 install</command> as a non-&root; user may seem
+        to work fine, but it will cause the installed module to be inaccessible
+        by other users.
+      </para>
+
+      <para>
+        <command>pip3 install</command> will not reinstall an already installed
+        module by default.  For using the <command>pip3 install</command>
+        command to upgrade a module (for example, from meson-0.61.3 to
+        meson-0.62.0), insert the option <parameter>--upgrade</parameter> into
+        the command line.  If it's really necessary to downgrade a module or
+        reinstall the same version for some reason, insert 
+        <parameter>--force-reinstall</parameter> into the command line.
+      </para>
+    </important>
 
     <para>If desired, install the preformatted documentation:</para>
 
diff --git a/chapter08/util-linux.xml b/chapter08/util-linux.xml
index 7aba82c85..d90936b78 100644
--- a/chapter08/util-linux.xml
+++ b/chapter08/util-linux.xml
@@ -84,7 +84,7 @@
 
 <screen><userinput remap="make">make</userinput></screen>
 
-    <para>If desired, run the test suite as a non-root user:</para>
+    <para>If desired, run the test suite as a non-&root; user:</para>
 
     <warning><para>Running the test suite as the
     <systemitem class="username">root</systemitem> user can be harmful to
diff --git a/chapter08/wheel.xml b/chapter08/wheel.xml
index 78fa94fd8..8e8436ffd 100644
--- a/chapter08/wheel.xml
+++ b/chapter08/wheel.xml
@@ -14,7 +14,7 @@
     <address>&wheel-url;</address>
   </sect1info>
 
-  <title>wheel-&wheel-version;</title>
+  <title>Wheel-&wheel-version;</title>
 
   <indexterm zone="ch-system-wheel">
     <primary sortas="a-wheel">wheel</primary>
@@ -23,7 +23,7 @@
   <sect2 role="package">
     <title/>
 
-    <para>Wheel is a Python library that implements the reference
+    <para>Wheel is a Python library that is the reference
     implementation of the Python wheel packaging standard.</para>
 
     <segmentedlist>
@@ -50,7 +50,7 @@
       <varlistentry>
         <term><command>install</command></term>
         <listitem>
-           <para>Install the package</para>
+           <para>Install the package.</para>
         </listitem>
       </varlistentry>
 
@@ -79,16 +79,33 @@
     <title>Contents of Wheel</title>
 
     <segmentedlist>
-      <segtitle>Installed module</segtitle>
+      <segtitle>Installed program</segtitle>
       <segtitle>Installed directory</segtitle>
 
       <seglistitem>
-        <seg>wheel.py</seg>
+        <seg>wheel</seg>
         <seg>/usr/lib/python&python-minor;/site-packages/wheel</seg>
       </seglistitem>
-
     </segmentedlist>
 
+    <variablelist>
+      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
+      <?dbfo list-presentation="list"?>
+      <?dbhtml list-presentation="table"?>
+
+      <varlistentry id="wheel-wheel">
+        <term><command>wheel</command></term>
+        <listitem>
+          <para>
+            is an utility to unpack, pack, or convert wheel packages
+          </para>
+          <indexterm zone="ch-system-wheel">
+            <primary sortas="b-wheel">wheel</primary>
+          </indexterm>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
   </sect2>
 
 </sect1>