svn commit: r40946 - head/en_US.ISO8859-1/books/handbook/geom

[Warren Block]

On Mon, 11 Feb 2013, Dru Lavigne wrote:

> Author: dru
> Date: Mon Feb 11 14:50:33 2013
> New Revision: 40946
> URL: http://svnweb.freebsd.org/changeset/doc/40946
>
> Log:
>  This patch addresses the following:
>
>  - fixes xref tags
>
>  - some tightening and removing of redundancy
>
>  - fixed some confusion in glabel section
>
>  Approved by	gjb (mentor)
>
> Modified:
>  head/en_US.ISO8859-1/books/handbook/geom/chapter.xml

... Uh oh.  Heading for the mirror section, which I and HRS revised 
recently and is still seared into my memory.  Comments inline.

> &prompt.root; <userinput>echo "/dev/stripe/st0a /stripe ufs rw 2 2" \</userinput>
> @@ -249,8 +248,8 @@ Done.</screen>
>       replace the failed drive without user interruption.</para>
>
>     <para>Two common situations are illustrated in these examples.
> -      The first is creating a mirror out of two new drives and using
> -      it as a replacement for an existing single drive.  The second
> +      The first creates a mirror out of two new drives and uses it
> +      as a replacement for an existing single drive.  The second
>       example creates a mirror on a single new drive, copies the old
>       drive's data to it, then inserts the old drive into the
>       mirror.  While this procedure is slightly more complicated, it
> @@ -317,28 +316,28 @@ Done.</screen>
> 	used to replace the old single disk.</para>
>
>       <para>&man.gmirror.8; requires a kernel module,
> -	<filename>geom_mirror.ko</filename>, either built into the
> -	kernel or loaded at boot- or run-time.  Manually load the
> -	kernel module now:</para>
> +	<filename>geom_mirror.ko</filename>, either compiled into a
> +	custom kernel or loaded at boot- or run-time.  To manually
> +	load the kernel module now:</para>

That last sentence was right the previous way.  It's not "how to do it", 
it's "do this because the following instructions require it."

>       <screen>&prompt.root; <userinput>gmirror load</userinput></screen>
>
> -      <para>Create the mirror with the two new drives.</para>
> +      <para>To create the mirror with the two new drives.</para>

As above, this is (was) an imperative.  "Do this, or feel the sting of 
utter failure!"

>       <screen>&prompt.root; <userinput>gmirror label -v gm0 /dev/ada1 /dev/ada2</userinput></screen>
>
>       <para><devicename>gm0</devicename> is a user-chosen device name
> 	assigned to the new mirror.  After the mirror has been
> -	started, this device name will appear in the
> -	<filename>/dev/mirror/</filename> directory.</para>
> +	started, this device name will appear in
> +	<filename>/dev/mirror/</filename>.</para>

>       <para>MBR and bsdlabel partition tables can now be created on
> 	the mirror with &man.gpart.8;.  Here we show a traditional
> 	split-filesystem layout, with partitions for
> 	<filename>/</filename>, swap, <filename>/var</filename>,
> 	<filename>/tmp</filename>, and <filename>/usr</filename>.  A
> -	single <filename>/</filename> filesystem and a swap partition
> -	will also work.</para>
> +	single <filename>/</filename> and a swap partition will also
> +	work.</para>

Without the "filesystem" word, it is not as clear what the / refers to; 
it could be read as a literal slash, or a directory, or a file.

>       <para>Partitions on the mirror do not have to be the same size
> 	as those on the existing disk, but they must be large enough
> @@ -384,8 +383,8 @@ Done.</screen>
> &prompt.root; <userinput>newfs -U /dev/mirror/gm0s1e</userinput>
> &prompt.root; <userinput>newfs -U /dev/mirror/gm0s1f</userinput></screen>
>
> -      <para>Filesystems from the original disk
> -	(<devicename>ada0</devicename>) can now be copied onto the
> +      <para>Filesystems from the original
> +	<devicename>ada0</devicename> disk can now be copied onto the
> 	mirror with &man.dump.8; and &man.restore.8;.</para>
>
>       <screen>&prompt.root; <userinput>mount /dev/mirror/gm0s1a /mnt</userinput>
> @@ -419,8 +418,8 @@ Done.</screen>
> 	are identical, it does not matter which is selected to
> 	boot.</para>
>
> -      <para>See the
> -	<link linkend="gmirror-troubleshooting">Troubleshooting</link>
> +      <para>See the <link
> +	  linkend="gmirror-troubleshooting">Troubleshooting</link>
> 	section if there are problems booting.  Powering down and
> 	disconnecting the original <devicename>ada0</devicename> disk
> 	will allow it to be kept as an offline backup.</para>
> @@ -432,23 +431,23 @@ Done.</screen>
>     <sect2>
>       <title>Creating a Mirror with an Existing Drive</title>
>
> -      <para>In this example, &os; has already been installed on a
> -	single disk, <devicename>ada0</devicename>.  A new disk,
> +      <para>In this example, &os; has been installed on a single
> +	disk, <devicename>ada0</devicename>.  A new disk,

Why remove the "already"?  That's part of what this example is trying to 
explain, how to create a mirror when FreeBSD is already on one of two 
drives.

> 	<devicename>ada1</devicename>, has been connected to the
> 	system.  A one-disk mirror will be created on the new disk,
> -	the existing system copied onto it, and then the old disk will be
> -	inserted into the mirror.  This slightly complex procedure is
> -	required because &man.gmirror.8; needs to put a 512-byte block
> -	of metadata at the end of each disk, and the existing
> -	<devicename>ada0</devicename> has usually had all of its space
> +	the existing system copied onto it, and then the old disk will
> +	be inserted into the mirror.  This slightly complex procedure
> +	is required because &man.gmirror.8; needs to put a 512-byte
> +	block of metadata at the end of each disk, and the existing
> +	<devicename>ada0</devicename> usually has all of its space
> 	already allocated.</para>

I think "has usually had all of of its space already allocated" is the 
correct tense.

> -      <para>Load the &man.gmirror.8; kernel module.</para>
> +      <para>Load the &man.gmirror.8; kernel module:</para>

It's not required that everything that is about to show an example lead 
up to it with a colon.  It makes for staccato reading, but people seem 
to like that, so okay.

>       <screen>&prompt.root; <userinput>gmirror load</userinput></screen>
>
>       <para>Check the media size of the original disk with
> -	&man.diskinfo.8;.</para>
> +	&man.diskinfo.8;:</para>
>
>       <screen>&prompt.root; <userinput>diskinfo -v ada0 | head -n3</userinput>
> /dev/ada0
> @@ -461,11 +460,11 @@ Done.</screen>
> 	size.  This drive does not store any data, but is used only to
> 	limit the size of the mirror.  When &man.gmirror.8; creates
> 	the mirror, it will restrict the capacity to the size of
> -	<devicename>gzero.nop</devicename> even if the new drive
> +	<devicename>gzero.nop</devicename>, even if the new drive
> 	(<devicename>ada1</devicename>) has more space.  Note that the
> 	<replaceable>1000204821504</replaceable> in the second line
> -	should be equal to <devicename>ada0</devicename>'s media size
> -	as shown by &man.diskinfo.8; above.</para>
> +	should be equal to the size of <devicename>ada0</devicename>
> +	as shown by &man.diskinfo.8;.</para>

"media size" is (was) mentioned to help the user find the right value in 
diskinfo(8) output.

>       <screen>&prompt.root; <userinput>geom zero load</userinput>
> &prompt.root; <userinput>gnop create -s 1000204821504 gzero</userinput>
> @@ -502,7 +501,7 @@ Done.</screen>
> 	be explained later.</para>
>
>       <para>In either case, partition tables on the primary disk
> -	should be copied first.  It can be done by using &man.gpart.8;
> +	should be copied first using the &man.gpart.8;
> 	<command>backup</command> and <command>restore</command>
> 	subcommands.</para>

Okay.  But I suggest s/using/with/.

> @@ -527,8 +526,8 @@ BSD 8
> 6  freebsd-ufs  130023424  838860800
> 7  freebsd-ufs  968884224  984640881</screen>
>
> -      <para>If the whole disk was used in the output of &man.gpart.8;
> -	<command>show</command>, the capacity in these partition
> +      <para>If the whole disk shows as used in the output of
> +	<command>gpart show</command>, the capacity in these partition
> 	tables must be reduced by one sector.  Edit the two files,
> 	reducing the size of both the slice and last partition by one.
> 	These are the last numbers in each listing.</para>
> @@ -550,13 +549,13 @@ BSD 8
> 	disk, these two files can be used without modification.</para>

Suggestion for specifics: "If the output of <command>gpart 
show</command> shows no free space at the end of the disk, the size of 
both the slice and the last partition must be reduced by one sector."

>       <para>Now restore the partition table into
> -	<devicename>mirror/gm0</devicename>.</para>
> +	<devicename>mirror/gm0</devicename>:</para>
>
>       <screen>&prompt.root; <userinput>gpart restore mirror/gm0 < table.ada0</userinput>
> &prompt.root; <userinput>gpart restore mirror/gm0s1 < table.ada0s1</userinput></screen>
>
> -      <para>Check the partition table with the &man.gpart.8;
> -	<command>show</command>.  This example has
> +      <para>Check the partition table with
> +	<command>gpart show</command>.  This example has
> 	<devicename>gm0s1a</devicename> for <filename>/</filename>,
> 	<devicename>gm0s1d</devicename> for <filename>/var</filename>,
> 	<devicename>gm0s1e</devicename> for <filename>/usr</filename>,
> @@ -707,8 +706,7 @@ mirror/gm0  COMPLETE  ada1 (ACTIVE)
>
> 	  <para>BIOS settings may have to be changed to boot from one
> 	    of the new mirrored drives.  Either mirror drive can be
> -	    used for booting.  As components of a mirror, they contain
> -	    identical data.</para>
> +	    used for booting as they contain identical data.</para>
> 	</sect4>

Needs a comma after "booting", I think.

> 	<sect4>
> @@ -742,10 +740,10 @@ mountroot></screen>
> 	  <para>Forgetting to load the
> 	    <filename>geom_mirror</filename> module in
> 	    <filename>/boot/loader.conf</filename> can cause this
> -	    problem.  To fix it, boot from a &os;-9 or later CD or USB
> -	    stick and choose <literal>Shell</literal> at the first
> -	    prompt.  Then load the mirror module and mount the mirror
> -	    device:</para>
> +	    problem.  To fix it, boot from a &os; 9.0 or later
> +	    installation media and choose <literal>Shell</literal> at
> +	    the first prompt.  Then load the mirror module and mount
> +	    the mirror device:</para>
>
> 	  <screen>&prompt.root; <userinput>gmirror load</userinput>
> &prompt.root; <userinput>mount /dev/mirror/gm0s1a /mnt</userinput></screen>
> @@ -759,14 +757,14 @@ mountroot></screen>
>
> 	  <para>Other problems that cause <literal>error 19</literal>
> 	    require more effort to fix.  Enter
> -	    <literal>ufs:/dev/ada0s1a</literal> at the prompt.
> -	    Although the system should boot from
> +	    <literal>ufs:/dev/ada0s1a</literal> at the boot loader
> +	    prompt.  Although the system should boot from
> 	    <devicename>ada0</devicename>, another prompt to select a
> 	    shell appears because <filename>/etc/fstab</filename> is
> 	    incorrect.  Press the Enter key at the prompt.  Undo the
> 	    modifications so far by reverting
> 	    <filename>/etc/fstab</filename>, mounting filesystems from
> -	    the original disk (<devicename>ada0</devicename>) instead
> +	    the original <devicename>ada0</devicename> instead
> 	    of the mirror.  Reboot the system and try the procedure
> 	    again.</para>

ada0 is (was) mentioned parenthetically because it was the example, not 
necessarily what the user will have.