Dev: ch01: initial work on fixing

1 files changed, 38 insertions, 66 deletions

diff --git a/src/devel/1_preparing.xml b/src/devel/1_preparing.xml
index 8ca764c..8b37df8 100644
--- a/src/devel/1_preparing.xml
+++ b/src/devel/1_preparing.xml
@@ -1,36 +1,37 @@
 <?xml version="1.0" encoding="utf-8"?>
 <chapter label="1" id="preparing">
     <title>Preparing Your System</title>
-    <para>Welcome to the Adélie Linux 1.0 Developer's Handbook.  This handbook will teach you how to develop the software and packages that powers the Adélie Linux distribution.  You may follow along at your own pace.</para>
-    <para>We'll start with installing the software and writing the configuration files necessary to perform development.</para>
-    <section>
+    <highlights>
+        <para>Welcome to the Adélie Linux 1.0 Developer's Handbook.  This handbook will teach you how to develop the software and packages that powers the Adélie Linux distribution.  You may follow along at your own pace.</para>
+        <para>We'll start with installing the software and writing the configuration files necessary to perform development.</para>
+    </highlights>
+    <section id="installing">
         <title>Installing Development Software</title>
-        <para>In this section, you will learn:</para>
-        <itemizedlist>
-            <listitem><para>How to install software on Adélie Linux;</para></listitem>
-            <listitem><para>What software you will use to develop Adélie Linux; and</para></listitem>
-            <listitem><para>What task each utility in the Adélie Linux development system performs.</para></listitem>
-        </itemizedlist>
+        <highlights>
+            <para>In this section, you will learn:</para>
+            <itemizedlist>
+                <listitem><para>How to install software on Adélie Linux;</para></listitem>
+                <listitem><para>What software you will use to develop Adélie Linux; and</para></listitem>
+                <listitem><para>What task each utility in the Adélie Linux development system performs.</para></listitem>
+            </itemizedlist>
+        </highlights>
         <para>Please make sure that you are at an Adélie Linux terminal before continuing.</para>
-        <section>
+        <section id="how2apk">
             <title>Using <command>apk</command> to Install Software</title>
-            <para>The <productname>Alpine Package Keeper</productname> or <command>apk</command> package manager is the central software management tool on the Adélie Linux distribution.
-                For a more thorough introduction to the <command>apk</command> package manager, please consult the Adélie Linux 1.0 Administrator's Guide, chapter 3: "Packages".</para>
-            <para>The <command>apk</command> package manager automatically resolves dependencies for requested software packages, and will automatically remove or "clean up" unneeded dependencies when a software package is removed.
-                If a software package's files become corrupted, it can be reinstalled with the <parameter class="command">fix</parameter> subcommand.</para>
-            <para>The <parameter class="command">add</parameter> subcommand will add the specified package(s) to the system's list of packages, and then resolve all necessary dependent libraries and other software packages to ensure the system has the requested packages installed.
-                The <parameter class="command">del</parameter> subcommand will remove the specified package(s) from the system's list of packages, and then remove any other libraries and software packages that are no longer required for the system's operation.  For example, the command:</para>
+            <para>The <command>apk</command> package manager is the central software management tool on the Adélie Linux distribution.  For a more thorough introduction to the <command>apk</command> package manager, please consult the Adélie Linux 1.0 Administrator's Guide, chapter 3: "Packages".</para>
+            <para>The <command>apk</command> package manager automatically resolves dependencies for requested software packages, and will automatically remove or "clean up" unneeded dependencies when a software package is removed.  If a software package's files become corrupted, it can be reinstalled with the <parameter class="command">fix</parameter> subcommand.</para>
+            <para>The <parameter class="command">add</parameter> subcommand will add the specified package(s) to the system's list of packages, and then resolve all necessary dependent libraries and other software packages to ensure the system has the requested packages installed.  The <parameter class="command">del</parameter> subcommand will remove the specified package(s) from the system's list of packages, and then remove any other libraries and software packages that are no longer required for the system's operation.  For example, the command:</para>
             <para><prompt>#</prompt> <command>apk <parameter>add</parameter> <userinput>build-tools</userinput></command></para>
             <para>will install the <userinput>build-tools</userinput> package, and any packages and libraries it requires.  Similarly,</para>
             <para><prompt>#</prompt> <command>apk <parameter>del</parameter> <userinput>libressl-dev</userinput></command></para>
             <para>will remove the <userinput>libressl-dev</userinput> package, and any packages and libraries that it required and no other package on the system requires.</para>
         </section>
-        <section>
+        <section id="install_cmd">
             <title>Installing the Adélie Linux Development System</title>
             <para>The development environment is made of two essential parts: the <package>build-tools</package> package, which provides the basic compiler infrastructure, including a C compiler, build system, linker, assembler, and other utilities; and the <package>abuild</package> package, which takes package "recipe" files with build instructions, and creates the <filename class="extension">APK</filename> package files using them.  You may install these two packages by executing the following command:</para>
             <para><prompt>#</prompt> <command>apk <parameter>add</parameter> <package>abuild</package> <package>build-tools</package></command></para>
         </section>
-        <section>
+        <section id="dev_pkgs">
             <title>Components of the Adélie Linux Development System</title>
             <para>The development system uses many open-source technologies that work together to provide a responsive, cohesive, libre environment.</para>
             <variablelist>
@@ -48,10 +49,6 @@
                     <listitem><para>The <orgname>GNU</orgname> package for generating <filename>Makefile</filename>s in packages that use the <package>autoconf</package> package.</para></listitem>
                 </varlistentry>
                 <varlistentry>
-                    <term><package>attr</package></term>
-                    <listitem><para>A framework for <firstterm>ACL</firstterm>s or <firstterm>access control list</firstterm>s.</para></listitem>
-                </varlistentry>
-                <varlistentry>
                     <term><package>bash</package> (<command>bash</command>, <command>sh</command>)</term>
                     <listitem><para>A Unix shell mostly compliant with the <productname>POSIX</productname> standard, used by many packages for build scripts and testing.</para></listitem>
                 </varlistentry>
@@ -60,10 +57,6 @@
                     <listitem><para>Low-level development utilities including assembler (<command>as</command>), linker (<command>ld</command>), and others.</para></listitem>
                 </varlistentry>
                 <varlistentry>
-                    <term><package>bison</package> (<command>yacc</command>)</term>
-                    <listitem><para>The <orgname>GNU</orgname> version of the <command>yacc</command> compiler generation command.</para></listitem>
-                </varlistentry>
-                <varlistentry>
                     <term><package>bzip2</package> (<command>bzip2</command>, <command>bunzip2</command>, <command>bzless</command>, …)</term>
                     <listitem><para>A popular compression format, included for the ability to unpack <filename class="extension">.bz2</filename> archives within which packages may be distributed.</para></listitem>
                 </varlistentry>
@@ -71,18 +64,10 @@
                     <term><package>cmake</package> (<command>cmake</command>, <command>ctest</command>)</term>
                     <listitem><para>The CMake build system, used to build many packages, and the CTest test system, used to prove packages are functioning correctly on the local system.</para></listitem>
                 </varlistentry>
-                 <varlistentry>
+                <varlistentry>
                     <term><package>diffutils</package> (<command>diff</command>, <command>cmp</command>)</term>
                     <listitem><para>Compares two or more files together, showing the differences.  Used by many test suites, and also useful for troubleshooting and generating <filename class="extension">.patch</filename> files.</para></listitem>
                 </varlistentry>
-               <varlistentry>
-                    <term><package>fakeroot</package></term>
-                    <listitem><para>An environment where a package believes it is running as the root user, but is actually running as the build user.  <!-- Why is this necessary? --></para></listitem>
-                </varlistentry>
-                <varlistentry>
-                    <term><package>flex</package> (<command>lex</command>)</term>
-                    <listitem><para>The <orgname>GNU</orgname> version of the <command>lex</command> lexer, used for creating parsers in many projects.</para></listitem>
-                </varlistentry>
                 <varlistentry>
                     <term><package>gcc</package> (<command>c99</command>, <command>c11</command>, <command>gcc</command>, <command>g++</command>)</term>
                     <listitem><para>The <orgname>GNU</orgname> Compiler Collection, a mostly standards-compliant C and C++ compiler.</para></listitem>
@@ -104,10 +89,6 @@
                     <listitem><para>The <orgname>GNU</orgname> library manipulation tool, used by many packages to create shared (<filename class="extension">.so</filename>) and static (<filename class="extension">.a</filename>) library files.</para></listitem>
                 </varlistentry>
                 <varlistentry>
-                    <term><package>lzip</package> (<command>lzip</command>)</term>
-                    <listitem><para>A compression format, included for the ability to unpack <filename class="extension">.lz</filename> archives within which packages may be distributed.</para></listitem>
-                </varlistentry>
-                <varlistentry>
                     <term><package>make</package> (<command>make</command>)</term>
                     <listitem><para>The <orgname>GNU</orgname> version of the standard Unix <command>make</command> command.</para></listitem>
                 </varlistentry>
@@ -124,10 +105,6 @@
                     <listitem><para>The <orgname>GNU</orgname> version of <personname><firstname>Larry</firstname><surname>Wall</surname></personname>'s standard <command>patch</command>utility.</para></listitem>
                 </varlistentry>
                 <varlistentry>
-                    <term><package>pax-utils</package> (<command>dumpelf</command>, <command>symtree</command>)</term>
-                    <listitem><para>A collection of utilities to enable the building of packages for the PaX secure operating environment.</para></listitem>
-                </varlistentry>
-                <varlistentry>
                     <term><package>pkgconf</package> (<command>pkgconf</command>, <command>pkg-config</command>)</term>
                     <listitem><para>A freely licensed, mathematically proven <command>pkg-config</command> implementation, used by package build systems to determine the location of libraries on the system.</para></listitem>
                 </varlistentry>
@@ -136,42 +113,37 @@
                     <listitem><para>The <orgname>GNU</orgname> version of the Unix <command>sed</command> command.</para></listitem>
                 </varlistentry>
                 <varlistentry>
-                    <term><package>sudo</package> (<command>sudo</command>)</term>
-                    <listitem><para>Allows a user to run a command as the root user without using the root user's password.</para></listitem>
-                </varlistentry>
-                <varlistentry>
                     <term><package>xz</package> (<command>xz</command>, <command>unxz</command>)</term>
                     <listitem><para>An efficient compression format, included for the ability to unpack <filename class="extension">.xz</filename> archives within which packages may be distributed.</para></listitem>
                 </varlistentry>
             </variablelist>
         </section>
     </section>
-    <section>
+    <section id="primer">
         <title>Packaging Primer</title>
-        <para>In this section, you will learn:</para>
-        <itemizedlist>
-            <listitem><para>How repositories and packages work in the Adélie Linux distribution;</para></listitem>
-            <listitem><para>How to use the <command>abuild</command> command; and</para></listitem>
-            <listitem><para>The options and commands available in <command>abuild</command>.</para></listitem>
-        </itemizedlist>
-        <section>
+        <highlights>
+            <para>In this section, you will learn:</para>
+            <itemizedlist>
+                <listitem><para>How repositories and packages work in the Adélie Linux distribution;</para></listitem>
+                <listitem><para>How to use the <command>abuild</command> command; and</para></listitem>
+                <listitem><para>The options and commands available in <command>abuild</command>.</para></listitem>
+            </itemizedlist>
+        </highlights>
+        <section id="what_is_a_pkg">
             <title>Packages and Repositories</title>
             <para>The <command>abuild</command> command enables you to build a package file for later installation on to one or more computers running the Adélie Linux dsitribution.  A <firstterm>package file</firstterm> is a kind of archive file that contains two key parts: package metadata, and package content files.</para>
             <para><firstterm>Package metadata</firstterm> is a collection of information used by a package manager, such as <command>apk</command>, to determine information about the package and the package file, including its name, version, maintainer contact information, installed size on disk, and more.  The <firstterm>package content files</firstterm> are a collection of one or more files that comprise the package itself, including executables, default configuration, data files, and any other files needed for the package to work properly.  In some cases it may also include templates, examples, or documentation.</para>
-            <para>All packages belong to a <firstterm>package repository</firstterm> or <firstterm>repo</firstterm>.  A repository is a collection of related packages.  The Adélie Linux distribution has two main repositories: the <database>system</database> repository, used for system software and important libraries; and the <database>user</database> repository, used for the majority of packages that users may be interested in.
-                While you are developing on your own computer, you may have as many, or as few, repositories as you like.  It can use any name except the above two ('system' and 'user').  You may use a name such as <database>mypackages</database>, or just your username.  The repository is a directory on your computer's hard disk.  You may create it anywhere, but it is highly recommended that you store your repository as a subdirectory of your home directory (<filename class="directory">/home/<userinput>yourname</userinput>/<userinput>yourrepository</userinput></filename>).</para>
-            <para>Each package you create will have its own directory inside your repository.  If you use the <command>newapkbuild</command> command (discussed later), this will be created for you automatically.  Inside this directory will be at least an <filename>APKBUILD</filename> file, which tells <command>abuild</command> the commands to run to build the package.  It may also contain patches or other files necessary for building the package, if necessary.</para>
-            <para>Typically, the <command>abuild</command> command is executed inside the package's directory (for example, <filename class="directory">/home/<userinput>yourname</userinput>/packages/<userinput>pkgname</userinput></filename>).  However, by setting the <envar>APKBUILD</envar> environment variable to the absolute path on disk to an <filename>APKBUILD</filename> file, you may run <command>abuild</command> from any directory.</para>
+            <para>All packages belong to a <firstterm>package repository</firstterm> or <firstterm>repo</firstterm>.  A repository is a collection of related packages.  The Adélie Linux distribution has two main repositories: the <database>system</database> repository, used for system software and important libraries; and the <database>user</database> repository, used for the majority of packages that users may be interested in.  While you are developing on your own computer, you may have as many, or as few, repositories as you like.  It can use any name except the above two ('system' and 'user').  You may use a name such as <database>mypackages</database>, or just your username.  Your repository is named after the directory where it is stored on your computer's hard disk.  You may create it anywhere, but it is highly recommended that you store your repository as a subdirectory of your home directory (<filename class="directory">/home/<userinput>yourname</userinput>/<userinput>yourrepository</userinput></filename>).</para>
+            <para>Each package you create will have its own directory inside your repository.  If you use the <command>newapkbuild</command> command (discussed later), this will be created for you automatically.  Inside this directory will be at least an <filename>APKBUILD</filename> file, which tells <command>abuild</command> the commands to run to build the package.  It may also contain patches or other files required for building the package, if necessary.</para>
+            <para>Typically, the <command>abuild</command> command is executed inside the package's directory (for example, <filename class="directory">/home/<userinput>yourname</userinput>/mypackages/<userinput>pkgname</userinput></filename>).  However, by setting the <envar>APKBUILD</envar> environment variable to the absolute path on disk to an <filename>APKBUILD</filename> file, you may run <command>abuild</command> from any directory.</para>
         </section>
-        <section>
+        <section id="abuild_intro">
             <title>Using the <command>abuild</command> Command</title>
-            <para>Running the <command>abuild</command> command with no arguments in a directory containing an <filename>APKBUILD</filename> file will cause it to fetch the package's sources (if necessary), build the package, and create the package file.  Passing the <parameter>-r</parameter> parameter to <command>abuild</command> will cause it to install the dependencies of the package as listed in the <filename>APKBUILD</filename>, and then build the package.  Afterwards, the dependencies of the package that were not already installed on your computer are removed.
-                If the build concluded successfully, the directory tree created for the source code and build system are removed by default.  You may configure what <command>abuild</command> removes when a package concludes building.
-                If the build fails to conclude successfully, no directories are removed by default.  You may configure what <command>abuild</command> removes when a package fails to build.</para>
+            <para>Running the <command>abuild</command> command with no arguments in a directory containing an <filename>APKBUILD</filename> file will cause it to fetch the package's sources (if necessary), build the package, and create the package file.  Passing the <parameter>-r</parameter> parameter to <command>abuild</command> will cause it to install the dependencies of the package as listed in the <filename>APKBUILD</filename>, and then build the package.  Afterwards, the dependencies of the package that were not already installed on your computer are removed.  If the build concluded successfully, the directory tree created for the source code and build system are removed by default.  If the build fails to conclude successfully, no directories are removed by default.  You may configure what <command>abuild</command> removes when a package concludes building; refer to <xref linkend="abuild_conf" /> for more information.</para>
             <para><command>abuild</command> has many subcommands that you may use, for finer-grained control over the build process.  You may use the <command>abuild <parameter class="command">deps</parameter></command> subcommand to only install the dependencies of the package, and use the <command>abuild <parameter class="command">unpack</parameter></command> subcommand to unpack the source archive into the directory tree where it can later be built.  These and many other subcommands are described in more detail in the following section.</para>
             <para>There are additionally a number of options that you may pass to <command>abuild</command>, which are also described in more detail in the next section.</para>
         </section>
-        <section>
+        <section id="abuild_cmds">
             <title><command>abuild</command> Subcommands</title>
             <para>The <command>abuild</command> command provides many subcommands that you may use while packaging software.</para>
             <variablelist>
@@ -206,7 +178,7 @@
             </variablelist>
         </section>
     </section>
-    <section>
+    <section id="configuring">
         <title>Configuring Your System</title>
         <para>In this section, you will learn:</para>
         <itemizedlist>
@@ -215,7 +187,7 @@
             <listitem><para>The directory layout used by <command>abuild</command> and how to create it.</para></listitem>
         </itemizedlist>
         <para>Please make sure that you are at an Adélie Linux terminal before continuing.</para>
-        <section>
+        <section id="abuild_conf">
             <title>Configuring <command>abuild</command> for Your Environment</title>
             <para>The <command>abuild</command> system reads its configuration from two files on your system, if they exist.
                 The <filename>/etc/abuild.conf</filename> file contains system-wide configuration, used by all users on a system.