Skip site navigation (1)Skip section navigation (2)
Date:      Tue, 9 Apr 2002 06:56:28 +0200
From:      Udo Erdelhoff <ue@nathan.ruhr.de>
To:        freebsd-doc@freebsd.org, freebsd-sparc@freebsd.org
Subject:   Request for review: Restructuring of sparc installation guide
Message-ID:  <20020409045627.GO51146@nathan.ruhr.de>

next in thread | raw e-mail | index | archive | help

--HuXIgs6JvY9hJs5C
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

Hi,
for some time, I've been thinking dark thoughts about modifying the
structure of the sparc64 installation instructions.  This is not
some kind of legal text and it should be possible to structure it
in a way that removes the 4th level headings.

Additionally, just about style rule my teacher drummed into me
complains about the fact that chapter 1.3 does not have any text
except the other chapters.

And most of the steps in 'network installation' do not describe the
installation over the network, but the preparations neccessary for
it.

I've attached a patch that solves most of these problems.  It splits
the installations preparations into seperate chapters and moves
things around a bit.  I did not adjust the indentation of the moved
chapters in order to minimize the diff and to make life easier for
the translators.  The neccessary cleanup would follow in a second
patch.

I was tempted to move almost all 1.3.* chapters (the various steps
needed to set up a network installaiton) into one gigantic <procedure>.
The only thing that stopped me was the length of the output (about
150 lines in lynx).

Comments?

/s/Udo
-- 
It's always a long day, 86400 doesn't fit into a short.

--HuXIgs6JvY9hJs5C
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename=sparc64-review

Index: install.sgml
===================================================================
RCS file: /home/ncvs/src/release/doc/en_US.ISO8859-1/installation/sparc64/install.sgml,v
retrieving revision 1.9
diff -u -r1.9 install.sgml
--- install.sgml	8 Apr 2002 05:19:32 -0000	1.9
+++ install.sgml	8 Apr 2002 05:32:01 -0000
@@ -29,9 +29,6 @@
     optionally to copy the &os; distribution to the local disk to make
     a stand-alone machine.</para>
 
-  <sect2>
-    <title>Preparation</title>
-
     <para>Currently, there are two ways to install &os;/&arch; on a
       new machine.  By far the easier of the two is to install from
       CDROM; this method allows you to install &os; without any
@@ -50,14 +47,7 @@
       you need to download (if any), as well as the steps required to
       do the installation.</para>
 
-    <sect3 id="downloading">
-      <title>Downloading Required Files</title>
-
-      <para>This section describes the files you will need for a
-	&os;/&arch; installation.  The links in this document point to
-	the main &os; FTP server.  Please use a mirror site instead if
-	possible.</para>
-
+<!-- this should read "in this document" after the re-structure -->
       <important>
 	<para>The URLs in this section are provisional and subject to
 	  change.  Please see the archives of the &a.sparc; for the
@@ -65,51 +55,7 @@
 	  when more permanent URLs have been determined.</para>
       </important>
 
-      <sect4>
-        <title>Required Files for CDROM Installation</title>
-
-	<para>If you want to do a CDROM installation, an ISO
-	  image with a snapshot of &os;/&arch; can be found at
-	  <ulink url="&release.url;"></ulink>.  This file can be used
-	  to create a bootable CDROM which contains everything
-	  necessary to boot and load at least a minimal &os;
-	  installation.</para>
-
-<!-- XXX ISO location?-->
-      </sect4>
-
-      <sect4>
-
-	<title>Required Files for Network Installation</title>
-
-	<para>For a network installation, you will need several files.
-	  First, you will need to download a &os;/&arch; loader for
-	  &man.tftpd.8; to serve to your &arch; client.  The loader
-	  will use either TFTP or NFS to retrieve the &os; kernel from
-	  the netboot server.  There is a separate loader for each of
-	  these methods (i.e. a loader for TFTP and a loader for NFS).
-	  You should download one of the following files, as
-	  appropriate:</para>
-
-	  <itemizedlist>
-	    <listitem><para><ulink url="&release.url;loader-tftp.gz"></ulink></para></listitem>
-	    <listitem><para><ulink url="&release.url;loader-nfs.gz"></ulink></para></listitem>
-	  </itemizedlist>
-
-	<para>A network installation also requires a kernel to be
-	  served to the netboot client.  A suitable kernel can be
-	  found at
-	  <ulink url="&release.url;"></ulink>.</para>
-
-<!-- XXX kernel filename?-->
-
-	<para>Finally, you will need a &man.tar.1; archive which
-	  contains the binaries and configuration files from the base
-	  system.  This file is available from <ulink
-	  url="&release.url;distrib.tar.gz"></ulink>.</para>
-      </sect4>
-   </sect3>
-   <sect3 id="getting-to-prom-prompt">
+   <sect2 id="getting-to-prom-prompt">
      <title>Getting to the PROM Prompt</title>
      <para>Most &arch; systems are set up to boot automatically from
        disk.  To install &os;, you need to boot over the network or
@@ -162,11 +108,19 @@
 	  </callout>
         </calloutlist>
       </screenco>
-    </sect3>
   </sect2>
-    
-  <sect2>
-    <title>Installing from CDROM</title>
+
+  <sect2 id="prepare-cd">
+    <title>Preparing for a CDROM Installation</title>
+
+	<para>If you want to do a CDROM installation, an ISO
+	  image with a snapshot of &os;/&arch; can be found at
+	  <ulink url="&release.url;"></ulink>.  This file can be used
+	  to create a bootable CDROM which contains everything
+	  necessary to boot and load at least a minimal &os;
+	  installation.</para>
+
+<!-- XXX ISO location?-->
     <para>Place the CDROM into your drive, and break into the PROM as
       described above. On the PROM prompt, type <command>boot
       cdrom</command>.  The system should boot into single-user mode
@@ -175,10 +129,9 @@
       linkend="creating-disk-label"> and <xref
       linkend="creating-root-filesystem">.</para>
   </sect2>
-  <sect2>
-    <title>Installing over the Network</title>
-    <sect3>
-      <title>Configuring the Netboot Server</title>
+
+  <sect2 id="prepare-network">
+    <title>Preparing for a Network Installation</title>
 
       <para>A &os;/&arch; kernel is booted by having the firmware
 	retrieve and execute a <application>loader</application>,
@@ -189,7 +142,38 @@
 	system.  The loader can fetch a kernel using TFTP or NFS. All
 	of this is covered in detail below.</para> 
 
-      <sect4>
+     <sect3 id="downloading">
+       <title>Getting the Required Files</title>
+
+	<para>For a network installation, you will need several files.
+	  First, you will need to download a &os;/&arch; loader for
+	  &man.tftpd.8; to serve to your &arch; client.  The loader
+	  will use either TFTP or NFS to retrieve the &os; kernel from
+	  the netboot server.  There is a separate loader for each of
+	  these methods (i.e. a loader for TFTP and a loader for NFS).
+	  You should download one of the following files, as
+	  appropriate:</para>
+
+	  <itemizedlist>
+	    <listitem><para><ulink url="&release.url;loader-tftp.gz"></ulink></para></listitem>
+	    <listitem><para><ulink url="&release.url;loader-nfs.gz"></ulink></para></listitem>
+	  </itemizedlist>
+
+	<para>A network installation also requires a kernel to be
+	  served to the netboot client.  A suitable kernel can be
+	  found at
+	  <ulink url="&release.url;"></ulink>.</para>
+
+<!-- XXX kernel filename?-->
+
+	<para>Finally, you will need a &man.tar.1; archive which
+	  contains the binaries and configuration files from the base
+	  system.  This file is available from <ulink
+	  url="&release.url;distrib.tar.gz"></ulink>.</para>
+      </sect3>
+
+<!-- put the words "netboot server" in here -->
+      <sect3>
 	<title>rarpd</title>
 
 	<para>You need to add the Ethernet address of your &os;/&arch;
@@ -207,9 +191,10 @@
 	  interface that is on the same subnet as the &os;/&arch;
 	  system.</para>
 
-      </sect4>
+      </sect3>
 
-      <sect4>
+<!-- put the words "netboot server" in here -->
+      <sect3>
 	<title>tftpd</title>
 
 	<para>Activate &man.tftpd.8; in your &man.inetd.8;
@@ -234,9 +219,10 @@
            allow you to see the file name you need to use for the
            loader. Error replies by the TFTP server are most often due
            to incorrect file permissions.</para>
-      </sect4>
+      </sect3>
 
-      <sect4>
+<!-- put the words "netboot server" in here -->
+      <sect3>
         <title>Setting up bootpd/dhcpd</title>
 
 	<para>You can use either BOOTP or DHCP (both not both) to
@@ -305,7 +291,6 @@
            a DNS entry or is associated with an address in
            <filename>/etc/hosts</filename>, the
            <literal>fixed-address</literal> specification can be omitted.</para>
-      </sect4>
     </sect3>
 
     <sect3>

--HuXIgs6JvY9hJs5C--

To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020409045627.GO51146>