Changeset ea93c11

Timestamp:

01/25/2024 05:59:06 PM (3 months ago)

Author:

Xi Ruoyao <xry111@…>

Branches:

12.1, 12.1-rc1, multilib, trunk, xry111/arm64, xry111/clfs-ng, xry111/loongarch, xry111/loongarch-12.1, xry111/mips64el, xry111/update-glibc

Children:

31a18d02, 44850bb

Parents:

9ac6ff5

git-author:

Xi Ruoyao <xry111@…> (01/25/2024 05:49:29 PM)

git-committer:

Xi Ruoyao <xry111@…> (01/25/2024 05:59:06 PM)

Message:

treewide: Use <ulink> instead of <filename> for man pages

"gcc(1)" is really not a file name.

Use <ulink> and link to the online man page on
​https://man.archlinux.org/ so the user can refer to the man pages more
easily.

The change is done via a sed command and long lines are wrapped
manually.

Files:

• chapter02/creatingpartition.xml (modified) (1 diff)
• chapter04/addinguser.xml (modified) (1 diff)
• chapter04/settingenviron.xml (modified) (1 diff)
• chapter05/glibc.xml (modified) (1 diff)
• chapter08/e2fsprogs.xml (modified) (1 diff)
• chapter08/openssl.xml (modified) (2 diffs)
• chapter08/shadow.xml (modified) (1 diff)
• chapter08/util-linux.xml (modified) (1 diff)
• chapter09/networkd.xml (modified) (3 diffs)
• chapter09/systemd-custom.xml (modified) (4 diffs)
• chapter09/udev.xml (modified) (1 diff)
• chapter09/usage.xml (modified) (2 diffs)
• chapter10/fstab.xml (modified) (1 diff)
• chapter10/kernel.xml (modified) (1 diff)
• general.ent (modified) (1 diff)
• prologue/typography.xml (modified) (3 diffs)

chapter02/creatingpartition.xml

@@ -41 +41 @@
   disk drive. Create a Linux native partition and a
   <systemitem class="filesystem">swap</systemitem> partition, if needed. Please
-  refer to <filename>cfdisk(8)</filename> or <filename>fdisk(8)</filename> if
+  refer to <ulink role='man' url='&man;cfdisk.8'>cfdisk(8)</ulink> or
+  <ulink role='man' url='&man;fdisk.8'>fdisk(8)</ulink> if
   you do not yet know how to use the programs.</para>
 

chapter04/addinguser.xml

@@ -100 +100 @@
   <command>su</command> to start a login shell as opposed to a non-login shell.
   The difference between these two types of shells is described in detail in
-  <filename>bash(1)</filename> and <command>info bash</command>.</para>
+  <ulink role='man' url='&man;bash.1'>bash(1)</ulink> and <command>info
+  bash</command>.</para>
 
 </sect1>

chapter04/settingenviron.xml

@@ -80 +80 @@
   created files and directories are only writable by their owner, but are
   readable and executable by anyone (assuming default modes are used by the
-  <filename>open(2)</filename> system call, new files will end up with
-  permission mode 644 and directories with mode 755).</para>
+  <ulink role='man' url='&man;open.2'>open(2)</ulink> system call, new files
+  will end up with permission mode 644 and directories with mode 755).</para>
       </listitem>
     </varlistentry>

chapter05/glibc.xml

@@ -60 +60 @@
         The above command is correct.  The <command>ln</command> command has
         several syntactic versions, so be sure to check
-        <command>info coreutils ln</command> and <filename>ln(1)</filename>
-        before reporting what may appear to be an error.
+        <command>info coreutils ln</command> and <ulink role='man'
+        url='&man;ln.1'>ln(1)</ulink> before reporting what may appear to be
+        an error.
       </para>
     </note>

chapter08/e2fsprogs.xml

@@ -160 +160 @@
 
     <para>
-      Read the man page <filename>mke2fs.conf(5)</filename> for details.
+      Read the man page <ulink role='man'
+      url='&man;mke2fs.conf.5'>mke2fs.conf(5)</ulink> for details.
     </para>
   </sect2>

chapter08/openssl.xml

@@ -164 +164 @@
             of <application>OpenSSL</application>'s crypto library from the
             shell. It can be used for various functions which are documented in
-            <filename>openssl(1)</filename>
+            <ulink role='man' url='&man;openssl.1'>openssl(1)</ulink>
           </para>
           <indexterm zone="ch-system-openssl openssl-prog">
@@ -196 +196 @@
             implements the Transport Layer Security (TLS v1) protocol.
             It provides a rich API, documentation
-            on which can be found in <filename>ssl(7)</filename>
+            on which can be found in <ulink role='man'
+            url='&man;ssl.7'>ssl(7)</ulink>
           </para>
           <indexterm zone="ch-system-openssl libssl">

chapter08/shadow.xml

@@ -204 +204 @@
     parameter to <command>useradd</command>, or else change the setting of
     <parameter>USERGROUPS_ENAB</parameter> in
-    <filename>/etc/login.defs</filename>. See <filename>useradd(8)</filename>
-    for more information.</para>
+    <filename>/etc/login.defs</filename>. See <ulink role='man'
+    url='&man;useradd.8'>useradd(8)</ulink> for more information.</para>
 
     <para>Second, to change the default parameters, the file

chapter08/util-linux.xml

@@ -585 +585 @@
         <listitem>
           <para>Displays kernel interrupt counter information in
-          <filename>top(1)</filename> style view</para>
+          <ulink role='man' url='&man;top.1'>top(1)</ulink> style
+          view</para>
           <indexterm zone="ch-system-util-linux irqtop">
             <primary sortas="b-irqtop">irqtop</primary>

chapter09/networkd.xml

@@ -51 +51 @@
     <filename class="extension">.network</filename> files. For detailed
     descriptions and example contents of these configuration files, consult
-    the <filename>systemd-link(5)</filename>,
-    <filename>systemd-netdev(5)</filename> and
-    <filename>systemd-network(5)</filename> manual pages.</para>
+    the <ulink role='man' url='&man;systemd-link.5'>systemd-link(5)</ulink>,
+    <ulink role='man' url='&man;systemd-netdev.5'>systemd-netdev(5)</ulink>,
+    and <ulink role='man'
+    url='&man;systemd-network.5'>systemd-network(5)</ulink> manual
+    pages.</para>
 
     <sect3 id="systemd-network-devices">
@@ -114 +116 @@
 
           <para>
-            See <filename>systemd.link(5)</filename> for more information.
+            See <ulink role='man' url='&man;systemd.link.5'>systemd.link(5)</ulink> for more information.
           </para>
         </listitem>
@@ -358 +360 @@
      domain) because they are handled by the
      <systemitem class='library'>myhostname</systemitem> NSS module, read
-     the man page <filename>nss-myhostname(8)</filename> for details.</para>
+     the man page <ulink role='man'
+     url='&man;nss-myhostname.8'>nss-myhostname(8)</ulink> for
+     details.</para>
 
      <para>The ::1 entry is the IPv6 counterpart of 127.0.0.1 and represents

chapter09/systemd-custom.xml

@@ -22 +22 @@
     entries commented out with the default settings indicated. This file is
     where the log level may be changed as well as some basic logging settings.
-    See the <filename>systemd-system.conf(5)</filename> manual page for details
-    on each configuration option.</para>
+    See the <ulink role='man'
+    url='&man;systemd-system.conf.5'>systemd-system.conf(5)</ulink> manual
+    page for details on each configuration option.</para>
 
   </sect2>
@@ -90 +91 @@
     files with the same name in
     <filename class="directory">/usr/lib/tmpfiles.d</filename>. See
-    <filename>tmpfiles.d(5)</filename> manual page for file format
-    details.</para>
+    <ulink role='man' url='&man;tmpfiles.d.5'>tmpfiles.d(5)</ulink> manual
+    page for file format details.</para>
 
     <para>
@@ -136 +137 @@
 EOF</userinput></screen>
 
-     <para>See <filename>systemd.unit(5)</filename> manual page for more
+     <para>See <ulink role='man'
+     url='&man;systemd.unit.5'>systemd.unit(5)</ulink> manual page for more
      information. After creating the configuration file, run
      <userinput>systemctl daemon-reload</userinput> and <userinput>systemctl
@@ -252 +254 @@
 EOF</userinput></screen>
 
-    <para>See the <filename>systemd-coredump(8)</filename>,
-    <filename>coredumpctl(1)</filename>, and
-    <filename>coredump.conf.d(5)</filename> manual pages for more
-    information.</para>
+    <para>See the <ulink role='man' url='&man;systemd-coredump.8'>systemd-coredump(8)</ulink>,
+    <ulink role='man' url='&man;coredumpctl.1'>coredumpctl(1)</ulink>, and
+    <ulink role='man'
+    url='&man;coredump.conf.d.5'>coredump.conf.d(5)</ulink> manual pages for
+    more information.</para>
   </sect2>
 

chapter09/udev.xml

@@ -226 +226 @@
       <literal>pre:</literal> dependencies, or a mixture of both
       <literal>pre:</literal> and <literal>post:</literal> dependencies.  See
-      the <filename>modprobe.d(5)</filename> manual page for more information
-      on <quote>softdep</quote> syntax and capabilities.</para>
+      the <ulink role='man' url='&man;modprobe.d.5'>modprobe.d(5)</ulink>
+      manual page for more information on <quote>softdep</quote> syntax and
+      capabilities.</para>
 
       <para revision="sysv">If the module in question is not a wrapper and is

chapter09/usage.xml

@@ -33 +33 @@
     uses a run levels scheme. There are seven run levels, numbered 0 to 6.
     (Actually, there are more run levels, but the others are for special cases and are
-    generally not used. See <filename>init(8)</filename> for more details.)
+    generally not used. See <ulink role='man'
+    url='&man;init.8'>init(8)</ulink> for more details.)
     Each one of the seven corresponds to actions the computer is supposed to
     perform when it starts up or shuts down. The default run level is 3. Here are the
@@ -342 +343 @@
   doubt, look in the <filename class="directory">/usr/share/keymaps</filename>
   and <filename class="directory">/usr/share/consolefonts</filename> directories
-  for valid keymaps and screen fonts. Read the <filename>loadkeys(1)</filename> and
-  <filename>setfont(8)</filename> manual pages to determine the correct
-  arguments for these programs.</para>
+  for valid keymaps and screen fonts. Read the <ulink role='man'
+  url='&man;loadkeys.1'>loadkeys(1)</ulink> and <ulink role='man'
+  url='&man;setfont.8'>setfont(8)</ulink> manual pages to determine the
+  correct arguments for these programs.</para>
 
   <para>The <filename>/etc/sysconfig/console</filename> file should contain lines

chapter10/fstab.xml

@@ -57 +57 @@
   class="partition">sda5</filename>, and <systemitem
   class="filesystem">ext4</systemitem>. For details on the six
-  fields in this file, see <filename>fstab(5)</filename>.</para>
+  fields in this file, see <ulink role='man' url='&man;fstab.5'>fstab(5)</ulink>.</para>
 
   <para>Filesystems with MS-DOS or Windows origin (i.e. vfat, ntfs, smbfs,

chapter10/kernel.xml

@@ -325 +325 @@
     documentation in the <filename
     class="directory">linux-&linux-version;/Documentation</filename> directory.
-    Also, <filename>modprobe.d(5)</filename> may be of interest.</para>
+    Also, <ulink role='man' url='&man;modprobe.d.5'>modprobe.d(5)</ulink>
+    may be of interest.</para>
 
     <para>Unless module support has been disabled in the kernel configuration,

general.ent

@@ -126 +126 @@
 <!ENTITY pypi-home       "https://pypi.org/project">
 <!ENTITY pypi-src        "https://pypi.org/packages/source">
+<!ENTITY man             "https://man.archlinux.org/man/">
 
 <!ENTITY root            "<systemitem class='username'>root</systemitem>">

prologue/typography.xml

@@ -75 +75 @@
   <para>This format is used to encapsulate text that is optional.</para>
 
-  <para><filename>passwd(5)</filename></para>
+  <para><ulink role='man' url='&man;passwd.5'>passwd(5)</ulink></para>
 
   <para>This format is used to refer to a specific manual (man) page. The number inside parentheses
@@ -82 +82 @@
   those two man pages will be located at
   <filename>/usr/share/man/man1/passwd.1</filename> and
-  <filename>/usr/share/man/man5/passwd.5</filename>. When the book uses <filename>passwd(5)</filename> it is
+  <filename>/usr/share/man/man5/passwd.5</filename>. When the book uses
+  <ulink role='man' url='&man;/passwd.5'>passwd(5)</ulink> it is
   specifically referring to <filename>/usr/share/man/man5/passwd.5</filename>.
   <command>man passwd</command> will print the first man page it finds that
@@ -90 +91 @@
   being specified. Note that most man pages do not have duplicate
   page names in different sections. Therefore, <command>man <replaceable>&lt;program
-  name&gt;</replaceable></command> is generally sufficient.</para>
+  name&gt;</replaceable></command> is generally sufficient.  In the LFS
+  book these references to man pages are also hyperlinks, so clicking on
+  such a reference will open the man page rendered in HTML from
+  <ulink url='https://man.archlinux.org/'>Arch Linux manual
+  pages</ulink>.</para>
 
 </sect1>