Porting: commit the overhaul I started a while back but never finished

2 files changed, 34 insertions, 70 deletions

diff --git a/src/porting/1_intro.xml b/src/porting/1_intro.xml
index 2c59bc7..7b20fe6 100644
--- a/src/porting/1_intro.xml
+++ b/src/porting/1_intro.xml
@@ -1,38 +1,18 @@
 <?xml version="1.0" encoding="utf-8"?>
 <chapter label="1" id="intro">
     <title>Introduction to Porting</title>
-    <para>Welcome to the Adélie Linux New Port Guide.
-        This guide will provide everything you need to know to bootstrap a new platform to run Adélie Linux.
-        It is organised into three main parts: this Introduction, the Bootstrapping phase, and the Native Hardware phase.</para>
+    <highlights><para>Welcome to the Adélie Linux Porting Handbook.  This handbook will provide everything you need to know to bootstrap a new platform to run Adélie Linux.  It is organised into three main parts: this Introduction, the Bootstrapping phase, and the Native Hardware phase.</para></highlights>
     <section>
         <title>Before You Begin</title>
-        <para>There are a few things you need to be aware of before you begin.
-            First of all, bootstrapping a new platform can be difficult at times.  Don't get discouraged if it doesn't work the first time.
-            Build issues and instability are common at the beginning.
-            If you need help, you can ask the maintainers of the software you are building, or you can contact the Adélie Linux Platform Group.
-            They are the group assigned to maintaining cross-platform compatibility and accepting new ports to the main Adélie Linux distribution.</para>
+        <para>There are a few things you need to be aware of before you begin.  First of all, bootstrapping a new platform can be difficult at times.  Don't get discouraged if your build doesn't work perfectly the first time.  Build issues and instability are common at the beginning of every port.  If you need help, you can ask the maintainers of the software you are building, or you can contact the Adélie Linux Platform Group.  They are the group assigned to maintaining cross-platform compatibility and accepting new ports to the main Adélie Linux distribution.</para>
     </section>
     <section>
         <title>Requirements</title>
-        <para>You will need two computers.
-            The first one, which we will term the "host", must be a computer that is already running a Linux;
-            it is recommended that the host is already running Adélie Linux.
-            It will also need a decent CPU and disk,
-            because it will need to compile two full toolchains (compiler and other build tools).</para>
-        <warning>
-            <para>While it is theoretically possible to bootstrap from any POSIX system that supports GCC or Clang,
-                it is unsupported to use a non-Linux environment to bootstrap Adélie.</para>
-        </warning>
-        <para>You may need Internet access on the host to download packages.
-            If you do not have Internet access on the host, you will need to obtain the Adélie Linux Platform Group Resource Disc,
-            which contains the packages and source code you will need to bootstrap your new platform.</para>
-        <para>On the computer you will run Adélie Linux on, which we will term the "target",
-            you will need a computer platform supported by the Linux kernel and one of its compilers (at the time of this writing, GCC or Clang).
-            The Linux kernel, as of version 4.3, supports over 30 CPU architectures, so odds are good that your computer will be supported.
-            Nonetheless, you should still ensure that the Linux kernel and a recent toolchain have been ported and tested on your hardware before proceeding.</para>
-        <para>You will also need a way to boot Linux on your target.  The specifics of this are beyond the scope of this guide.
-            Usually most embedded systems support booting off flash media which is easily obtained and writable by most host computers;
-            they may alternatively support booting from a network.</para>
+        <para>You will need two computers.  The first one, which we will term the "host", must be a computer that is already running a Linux distribution; it is recommended that the host is already running Adélie Linux.  It will also need a performant CPU and adequate disk space, because it will need to compile two full toolchains (compiler and other build tools).</para>
+        <warning><title>Warning</title><para>While it is theoretically possible to bootstrap from any POSIX system that supports GCC or Clang, it is unsupported to use a non-Linux environment to bootstrap Adélie.</para></warning>
+        <para>You may need Internet access on the host to download packages.  If you do not have Internet access on the host, you will need to obtain the Adélie Linux Platform Group Resource Disc, which contains the packages and source code you will need to bootstrap your new platform.</para>
+        <para>On the computer you will run Adélie Linux on, which we will term the "target", you will need a computer platform supported by the Linux kernel and one of its compilers (at the time of this writing, GCC or Clang).  The Linux kernel, as of version 4.3, supports over 30 CPU architectures, so odds are good that your computer will be supported.  Nonetheless, you should still ensure that the Linux kernel and a recent toolchain have been ported and tested on your hardware before proceeding.</para>
+        <para>You will also need a way to boot Linux on your target.  The specifics of this are beyond the scope of this guide.  Usually most embedded systems support booting off flash media which is easily obtained and writable by most host computers; they may alternatively support booting from a network.</para>
         <section>
             <title>Host Requirements</title>
             <itemizedlist>
@@ -60,8 +40,6 @@
             <listitem><para>Build essential libraries and system software for your target using the cross-compiler on the host;</para></listitem>
             <listitem><para>Re-build these essential libraries on your target.</para></listitem>
         </itemizedlist>
-        <para>Once these goals have been completed, you will have a functional Adélie Linux system on your target.
-            After you have tested it and are satisfied with the stability and functionality of the port,
-            you may also wish to contact the Adélie Linux Platform Group for consideration on including the new port in the distribution.</para>
+        <para>Once these goals have been completed, you will have a functional Adélie Linux system on your target.  After you have tested it and are satisfied with the stability and functionality of the port, you may also wish to contact the Adélie Linux Platform Group to consider including the new port in the official distribution.</para>
     </section>
 </chapter>
diff --git a/src/porting/2_bootstrapping.xml b/src/porting/2_bootstrapping.xml
index cf6f278..d46080b 100644
--- a/src/porting/2_bootstrapping.xml
+++ b/src/porting/2_bootstrapping.xml
@@ -1,24 +1,19 @@
 <?xml version="1.0" encoding="utf-8"?>
 <chapter label="2" id="bootstrapping">
     <title>Bootstrapping Phase</title>
-    <para>During this phase, you will create a number of necessary tools:
+    <highlights>
+        <para>During this phase, you will create a number of necessary tools:</para>
         <itemizedlist>
-            <listitem><para>You will create a toolchain to use on your host to compile software for your target.
-                    This is called a "cross-compilation" toolchain.</para></listitem>
-            <listitem><para>You will build an essential set of software to bootstrap your target,
-                    including a toolchain to use on your target to directly compile software (or <firstterm>self host</firstterm>).</para></listitem>
+            <listitem><para>You will create a toolchain to use on your host to compile software for your target.  This is called a "cross-compilation" toolchain.</para></listitem>
+            <listitem><para>You will build an essential set of software to bootstrap your target, including a toolchain to use on your target to directly compile software (or <firstterm>self host</firstterm>).</para></listitem>
             <listitem><para>You will configure a kernel to boot on your target.</para></listitem>
             <listitem><para>You will then create a bootable image that you will use to boot your target into Adélie Linux.</para></listitem>
         </itemizedlist>
-    </para>
+    </highlights>
     <section>
         <title>Ensuring the musl C library is ported</title>
-        <para>Before you begin porting Adélie Linux to your target, you must ensure that the musl C library has been ported to it.
-            You can view a list of supported architectures for musl on <ulink url="http://git.musl-libc.org/cgit/musl/tree/arch">the online musl Git repository</ulink>,
-            or in the <filename class="directory">arch/</filename> directory of the musl source code found on the Adélie Linux Platform Group Resource Disc.</para>
-        <para>If your target is not yet supported by musl, you will need to port it first.
-            Porting the musl C library is beyond the scope of this guide.  If you have an Internet connection,
-            you may consult <ulink url="https://wiki.musl-libc.org/porting.html">the official musl porting documentation</ulink>.</para>
+        <para>Before you begin porting Adélie Linux to your target, you must ensure that the musl C library has been ported to it.  You can view a list of supported architectures for musl on <ulink url="http://git.musl-libc.org/cgit/musl/tree/arch">the online musl Git repository</ulink>,or in the <filename class="directory">arch/</filename> directory of the musl source code found on the Adélie Linux Platform Group Resource Disc.</para>
+        <para>If your target is not yet supported by musl, you will need to port it first.  Porting the musl C library is beyond the scope of this guide.  If you have an Internet connection, you may consult <ulink url="https://wiki.musl-libc.org/porting.html">the official musl porting documentation</ulink>.</para>
     </section>
     <section>
         <title>Creating the cross-compilation toolchain</title>
@@ -32,50 +27,41 @@
         <para>Please make sure that you are at your host computer's terminal before continuing.</para>
         <section>
             <title>Making <package>abuild</package> aware of your target</title>
-            <para>Before you can build packages for your target,
-                you will need to ensure <package>abuild</package> is aware of the architecture.
-                This is accomplished by modifying a few files in the abuild source code.
-                You will need to check out a clone of the <ulink url="https://code.foxkit.us/adelie/abuild">abuild Git repository</ulink>,
-                or use the copy of the abuild Git tree found on the Adélie Linux Platform Group Resource Disc.</para>
-            <para>In the abuild Git tree, open the <filename>functions.sh.in</filename> file.
-                Locate the <function>arch_to_hostspec</function> function,
-                and add the short name of your target's architecture as a case to the case statement;
-                it should echo the full build triplet for your target (see <xref linkend="example_arch"/>).</para>
+            <para>Before you can build packages for your target, you will need to ensure <package>abuild</package> is aware of the architecture.  This is accomplished by modifying a few files in the abuild source code.  You will need to check out a clone of the <ulink url="https://code.foxkit.us/adelie/abuild">abuild Git repository</ulink>, or use the copy of the abuild Git tree found on the Adélie Linux Platform Group Resource Disc.</para>
+            <para>In the abuild Git tree, open the <filename>functions.sh.in</filename> file.  Locate the <function>arch_to_hostspec</function> function, and add the short name of your target's architecture as a case to the case statement; it should echo the full build triplet for your target (see <xref linkend="example_arch"/>).</para>
             <example id="example_arch"><title>Example addition of PA-RISC to <function>arch_to_hostspec</function></title>
-                <programlisting>
+<programlisting>
         armhf)          echo "armv6-foxkit-linux-muslgnueabihf" ;;
         armv7)          echo "armv7-foxkit-linux-musleabihf" ;;
         <emphasis role="bold">hppa)           echo "hppa-foxkit-linux-musl" ;;</emphasis>
         i528)           echo "pentium4-foxkit-linux-musl" ;;
         mips)           echo "mips-foxkit-linux-musl" ;;
-                </programlisting>
+</programlisting>
             </example>
-            <para>Next, locate the <function>hostspec_to_arch</function> function,
-                and add a string that would match any build triplet for your target's architecture as a case to the case statement;
-                it should echo the short name you specified in <function>arch_to_hostspec</function> (see <xref linkend="example_hostspec"/>).</para>
+            <para>Next, locate the <function>hostspec_to_arch</function> function, and add a string that would match any build triplet for your target's architecture as a case to the case statement; it should echo the short name you specified in <function>arch_to_hostspec</function> (see <xref linkend="example_hostspec"/>).</para>
             <example id="example_hostspec"><title>Example addition of PA-RISC to <function>hostspec_to_arch</function></title>
-                <programlisting>
+<programlisting>
         armv6*-*-*-*eabihf)     echo "armhf" ;;
         armv7*-*-*-*eabihf)     echo "armv7" ;;
-        <emphasis role="bold">        hppa-*-*-*)             echo "hppa" ;;</emphasis>
+        <emphasis role="bold">hppa-*-*-*)             echo "hppa" ;;</emphasis>
         i486-*-*-*)             echo "x86" ;;
         i586-*-*-*)             echo "pmmx" ;;
-                </programlisting>
+</programlisting>
             </example>
-            <para>Now that you have added your target to <package>abuild</package>,
-                you will need to create a patch to apply to the <filename>APKBUILD</filename>.
-                Commit your work with a descriptive message (such as <emphasis>"Add the PA-RISC architecture to functions"</emphasis>),
-                then run <userinput>git format-patch HEAD^</userinput> to have Git provide you a patch file.
-                This patch file will typically be named similar to <filename>0001-Add-<replaceable>foo</replaceable>-architecture-to-functions.patch</filename>.</para>
-            <para>Move (or copy) the patch file you have generated to the directory with <package>abuild</package>'s <filename>APKBUILD</filename>,
-                then add it to the <varname>source</varname> list in the <filename>APKBUILD</filename> and rerun
-                <userinput>abuild checksum</userinput> as with any package update.
-                Build this new copy of <package>abuild</package> locally, and install it to your host computer.</para>
+            <para>Now that you have added your target to <package>abuild</package>, you will need to create a patch to apply to the <filename>APKBUILD</filename>.  Commit your work with a descriptive message (such as <emphasis>"Add the PA-RISC architecture to functions"</emphasis>), then run <userinput>git format-patch HEAD^</userinput> to have Git provide you a patch file.  This patch file will typically be named similar to <filename>0001-Add-<replaceable>foo</replaceable>-architecture-to-functions.patch</filename>.</para>
+            <para>Move (or copy) the patch file you have generated to the directory with <package>abuild</package>'s <filename>APKBUILD</filename>, then add it to the <varname>source</varname> list in the <filename>APKBUILD</filename> and rerun <userinput>abuild checksum</userinput> as with any package update.  Build this new copy of <package>abuild</package> locally, and install it to your host computer.</para>
         </section>
         <section>
             <title>Adding your target to essential software build recipes</title>
-            <para>A few of the essential system software packages for Adélie Linux are customised per target.
-                In this section, you will add support for your target to these packages.</para>
+            <para>A few of the essential system software packages for Adélie Linux are customised per target.  In this section, you will add support for your target to these packages.</para>
+            <section>
+                <title>GCC</title>
+                <para>Add the appropriate line to <filename>system/gcc/APKBUILD</filename> (the case in build() with default arch/tune etc).</para>
+            </section>
+            <section>
+                <title>musl</title>
+                <para>Add the appropriate line to <filename>system/musl/APKBUILD</filename> (the ARCH case in package()).</para>
+            </section>
         </section>
     </section>
 </chapter>