docs/135983: "The Z File System" - title is misleading and causes search issue

[Dan Naumov]

The following reply was made to PR docs/135983; it has been noted by GNATS.

From: Dan Naumov <dan.naumov at gmail.com>
To: bug-followup at FreeBSD.org, dan.naumov at gmail.com
Cc:  
Subject: Re: docs/135983: "The Z File System" - title is misleading and causes 
	search issue
Date: Tue, 30 Jun 2009 02:53:02 +0300

 Patch below, please comment if you disagree or commit if you don't :)
 
 ==============================================================
 diff -ru /DATA/bsdwork/docs/doc/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml
 /DATA/bsdwork/docs/doc-mine/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml
 --- /DATA/bsdwork/docs/doc/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml	2008-11-26
 06:54:41.000000000 +0200
 +++ /DATA/bsdwork/docs/doc-mine/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml	2009-06-30
 02:33:10.786630005 +0300
 @@ -108,7 +108,7 @@
    </sect1>
 
    <sect1 id="filesystems-zfs">
 -    <title>The Z File System</title>
 +    <title>The Z File System (ZFS)</title>
 
      <para>The Z file system, developed by &sun;, is a new
        technology designed to use a pooled storage method.  This means
 @@ -198,19 +198,20 @@
  	<screen>&prompt.root; <userinput>echo 'zfs_enable="YES"' >>
 /etc/rc.conf</userinput>
  &prompt.root; <userinput>/etc/rc.d/zfs start</userinput></screen>
 
 -	<para>The remainder of this document assumes two
 +	<para>The remainder of this document assumes 3
  	  <acronym>SCSI</acronym> disks are available, and their device names
 -	  are <devicename><replaceable>da0</replaceable></devicename>
 -	  and <devicename><replaceable>da1</replaceable></devicename>
 -	  respectively.  Users of <acronym>IDE</acronym> hardware may
 -	  use the <devicename><replaceable>ad</replaceable></devicename>
 +	  are <devicename><replaceable>da0</replaceable></devicename>,
 +          <devicename><replaceable>da1</replaceable></devicename>
 +	  and <devicename><replaceable>da2</replaceable></devicename>.
 +	  Users of <acronym>IDE</acronym> hardware may use the
 +	  <devicename><replaceable>ad</replaceable></devicename>
  	  devices in place of <acronym>SCSI</acronym> hardware.</para>
 
        <sect3>
  	<title>Single Disk Pool</title>
 
 -	<para>To create a <acronym>ZFS</acronym> over a single disk
 -	  device, use the <command>zpool</command> command:</para>
 +	<para>To create a simple, non-redundant <acronym>ZFS</acronym> pool using a
 +	  single disk device, use the <command>zpool</command> command:</para>
 
  	<screen>&prompt.root; <userinput>zpool create example
 /dev/da0</userinput></screen>
 
 @@ -340,13 +341,19 @@
  	<title><acronym>ZFS</acronym> RAID-Z</title>
 
  	<para>As previously noted, this section will assume that
 -	  two <acronym>SCSI</acronym> exists as devices
 -	  <devicename>da0</devicename> and
 -	  <devicename>da1</devicename>.  To create a
 +	  3 <acronym>SCSI</acronym> discs exist as devices
 +	  <devicename>da0</devicename>, <devicename>da1</devicename>
 +	  and <devicename>da2</devicename>. To create a
  	  <acronym>RAID</acronym>-Z pool, issue the following
  	  command:</para>
 
 -	<screen>&prompt.root; <userinput>zpool create storage raidz da0
 da1</userinput></screen>
 +	<screen>&prompt.root; <userinput>zpool create storage raidz da0 da1
 da2</userinput></screen>
 +
 +	<warning><para>The recommended amount of devices to be used in a
 <acronym>RAID</acronym>-Z
 +	  configuration is 3-9. If your needs call for a single pool to
 consist of 10 disks or more,
 +	  consider breaking it up into groups of smaller
 <acronym>RAID</acronym>-Z. If you only
 +	  have 2 disks and require redundancy, consider using a
 <acronym>ZFS</acronym> mirror
 +	  configuration. See the &man.zpool.8; manual page for more
 details.</para></warning>
 
  	<para>The <literal>storage</literal> zpool should have been
  	  created.  This may be verified by using the &man.mount.8; and
 @@ -432,8 +439,8 @@
  /dev/ad0s1a    2026030  235240  1628708    13%    /
  devfs                1       1        0   100%    /dev
  /dev/ad0s1d   54098308 1032826 48737618     2%    /usr
 -storage       17547008       0 17547008     0%    /storage
 -storage/home  17547008       0 17547008     0%    /home</screen>
 +storage       26320512       0 26320512     0%    /storage
 +storage/home  26320512       0 26320512     0%    /home</screen>
 
  	<para>This completes the <acronym>RAID</acronym>-Z
  	  configuration.  To get status updates about the file systems
 @@ -477,6 +484,7 @@
  	  raidz1    DEGRADED     0     0     0
  	    da0     ONLINE       0     0     0
  	    da1     OFFLINE      0     0     0
 +	    da2     ONLINE       0     0     0
 
  errors: No known data errors</screen>
 
 @@ -509,6 +517,7 @@
  	  raidz1    ONLINE       0     0     0
  	    da0     ONLINE       0     0     0
  	    da1     ONLINE       0     0     0
 +	    da2     ONLINE       0     0     0
 
  errors: No known data errors</screen>
 
 @@ -556,6 +565,7 @@
  	  raidz1    ONLINE       0     0     0
  	    da0     ONLINE       0     0     0
  	    da1     ONLINE       0     0     0
 +	    da2     ONLINE       0     0     0
 
  errors: No known data errors</screen>
 ==============================================================
 
 - Sincerely,
 Dan Naumov