From nobody@FreeBSD.org  Tue Jun 23 21:53:28 2009
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 4D1B71065675
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 23 Jun 2009 21:53:28 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21])
	by mx1.freebsd.org (Postfix) with ESMTP id 3A1048FC1E
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 23 Jun 2009 21:53:28 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.3/8.14.3) with ESMTP id n5NLrS5e050974
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 23 Jun 2009 21:53:28 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.3/8.14.3/Submit) id n5NLrR0W050973;
	Tue, 23 Jun 2009 21:53:27 GMT
	(envelope-from nobody)
Message-Id: <200906232153.n5NLrR0W050973@www.freebsd.org>
Date: Tue, 23 Jun 2009 21:53:27 GMT
From: Dan Naumov <dan.naumov@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: "The Z File System" - title is misleading and causes search issue
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         135983
>Category:       docs
>Synopsis:       "The Z File System" - title is misleading and causes search issue
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Jun 23 22:00:13 UTC 2009
>Closed-Date:    Tue Aug 11 07:11:05 UTC 2009
>Last-Modified:  Tue Aug 11 07:20:02 UTC 2009
>Originator:     Dan Naumov
>Release:        7.2-RELEASE
>Organization:
>Environment:
FreeBSD atom.localdomain 7.2-RELEASE-p1 FreeBSD 7.2-RELEASE-p1 #0: Tue Jun  9 18:02:21 UTC 2009     root@amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC  amd64
>Description:
People looking for information regarding ZFS support in FreeBSD are very likely to start by opening the handbook table of contents in their web browser, initiate their browser search function and search for "ZFS". This will result in 0 matches and the user will be left confused, thinking the handbook has no articles on the subject.

Proposal: edit the following files:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/filesystems-zfs.html

and change any instances of "The Z File System" (a name which has no basis on reality) to "ZFS - Zettabyte File System". This will make the term searchable using web browser (or any other viewer) search functions allowing easier access for the user. Additionally this would decipher the ZFS acronym in a proper way with actual basis on the origin of the name.
>How-To-Repeat:
Open the Handbook table of contents at http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook and use your web browser's search function to search for "ZFS".
>Fix:


>Release-Note:
>Audit-Trail:

From: Tom Rhodes <trhodes@FreeBSD.org>
To: Dan Naumov <dan.naumov@gmail.com>
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/135983: "The Z File System" - title is misleading and
 causes search issue
Date: Wed, 24 Jun 2009 02:58:47 -0400

 On Tue, 23 Jun 2009 21:53:27 GMT
 Dan Naumov <dan.naumov@gmail.com> wrote:
 
 > 
 > >Number:         135983
 > >Category:       docs
 > >Synopsis:       "The Z File System" - title is misleading and causes search issue
 > >Confidential:   no
 > >Severity:       non-critical
 > >Priority:       medium
 > >Responsible:    freebsd-doc
 > >State:          open
 > >Quarter:        
 > >Keywords:       
 > >Date-Required:
 > >Class:          doc-bug
 > >Submitter-Id:   current-users
 > >Arrival-Date:   Tue Jun 23 22:00:13 UTC 2009
 > >Closed-Date:
 > >Last-Modified:
 > >Originator:     Dan Naumov
 > >Release:        7.2-RELEASE
 > >Organization:
 > >Environment:
 > FreeBSD atom.localdomain 7.2-RELEASE-p1 FreeBSD 7.2-RELEASE-p1 #0: Tue Jun  9 18:02:21 UTC 2009     root@amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC  amd64
 > >Description:
 > People looking for information regarding ZFS support in FreeBSD are very likely to start by opening the handbook table of contents in their web browser, initiate their browser search function and search for "ZFS". This will result in 0 matches and the user will be left confused, thinking the handbook has no articles on the subject.
 > 
 > Proposal: edit the following files:
 > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
 > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/filesystems-zfs.html
 > 
 > and change any instances of "The Z File System" (a name which has no basis on reality) to "ZFS - Zettabyte File System". This will make the term searchable using web browser (or any other viewer) search functions allowing easier access for the user. Additionally this would decipher the ZFS acronym in a proper way with actual basis on the origin of the name.
 
 Actually, the term "Zettabyte" is out dated too.  As for the "Z
 file system" - I read that somewhere.  I just can't remember,
 perhaps it was the source code or a link on Sun's site or a
 developer blog; trust me, I wouldn't have used it otherwise.
 Searching around it appears that it's an orphan acronym
 (according to:
 http://opensolaris.org/os/community/zfs/faq/#whatstandfor)
 
 I have no issue with the changes, and may even make them
 myself if I find the time; however, I just wanted to
 explain where the "basis of reality" part.  Thanks,
 
 --- 
 Tom Rhodes

From: Manolis Kiagias <sonic2000gr@gmail.com>
To: Tom Rhodes <trhodes@FreeBSD.org>
Cc: freebsd-doc@FreeBSD.org, bug-followup@FreeBSD.org
Subject: Re: docs/135983: "The Z File System" - title is misleading and causes
 search issue
Date: Wed, 24 Jun 2009 10:37:29 +0300

 Tom Rhodes wrote:
 > The following reply was made to PR docs/135983; it has been noted by GNATS.
 >
 > From: Tom Rhodes <trhodes@FreeBSD.org>
 > To: Dan Naumov <dan.naumov@gmail.com>
 > Cc: bug-followup@FreeBSD.org
 > Subject: Re: docs/135983: "The Z File System" - title is misleading and
 >  causes search issue
 > Date: Wed, 24 Jun 2009 02:58:47 -0400
 >
 >  On Tue, 23 Jun 2009 21:53:27 GMT
 >  Dan Naumov <dan.naumov@gmail.com> wrote:
 >  
 >  > 
 >  > >Number:         135983
 >  > >Category:       docs
 >  > >Synopsis:       "The Z File System" - title is misleading and causes search issue
 >  > >Confidential:   no
 >  > >Severity:       non-critical
 >  > >Priority:       medium
 >  > >Responsible:    freebsd-doc
 >  > >State:          open
 >  > >Quarter:        
 >  > >Keywords:       
 >  > >Date-Required:
 >  > >Class:          doc-bug
 >  > >Submitter-Id:   current-users
 >  > >Arrival-Date:   Tue Jun 23 22:00:13 UTC 2009
 >  > >Closed-Date:
 >  > >Last-Modified:
 >  > >Originator:     Dan Naumov
 >  > >Release:        7.2-RELEASE
 >  > >Organization:
 >  > >Environment:
 >  > FreeBSD atom.localdomain 7.2-RELEASE-p1 FreeBSD 7.2-RELEASE-p1 #0: Tue Jun  9 18:02:21 UTC 2009     root@amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC  amd64
 >  > >Description:
 >  > People looking for information regarding ZFS support in FreeBSD are very likely to start by opening the handbook table of contents in their web browser, initiate their browser search function and search for "ZFS". This will result in 0 matches and the user will be left confused, thinking the handbook has no articles on the subject.
 >  > 
 >  > Proposal: edit the following files:
 >  > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
 >  > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/filesystems-zfs.html
 >  > 
 >  > and change any instances of "The Z File System" (a name which has no basis on reality) to "ZFS - Zettabyte File System". This will make the term searchable using web browser (or any other viewer) search functions allowing easier access for the user. Additionally this would decipher the ZFS acronym in a proper way with actual basis on the origin of the name.
 >  
 >  Actually, the term "Zettabyte" is out dated too.  As for the "Z
 >  file system" - I read that somewhere.  I just can't remember,
 >  perhaps it was the source code or a link on Sun's site or a
 >  developer blog; trust me, I wouldn't have used it otherwise.
 >  Searching around it appears that it's an orphan acronym
 >  (according to:
 >  http://opensolaris.org/os/community/zfs/faq/#whatstandfor)
 >  
 >  I have no issue with the changes, and may even make them
 >  myself if I find the time; however, I just wanted to
 >  explain where the "basis of reality" part.  Thanks,
 >  
 >  --- 
 >  Tom Rhodes
 >   
 
 The chapter still appears when using the "search the Handbook" link, so
 I feel this is not much of an issue.
 As a compromise though, we could probably change the title to:
 
 "The Z File System (ZFS)"

From: Dan Naumov <dan.naumov@gmail.com>
To: bug-followup@FreeBSD.org, dan.naumov@gmail.com
Cc:  
Subject: Re: docs/135983: "The Z File System" - title is misleading and causes 
	search issue
Date: Wed, 24 Jun 2009 11:14:12 +0300

 Hopefully you didn't take an offense to my initial PR, the Handbook
 guide was what actually had me started on getting into ZFS with
 FreeBSD :)
 
 Either way, I had some other changes in mind as well, for example the
 RAID-Z example uses a pool made of 2 disks. While it will obviously
 work, all SUN documentation indicates that the suggested amount of
 vdevs for a RAIDZ or RAIDZ2 pool is between 3 and 9 devices and that
 bigger pools should be broken up to be made of smaller groups of vdevs
 (for example 2 x 7disk RAIDZ for a single pool 14 disk setup).. Using
 RAIDZ with just 2 disks will result in slower performance than simply
 using a ZFS mirror and using more than 9 disks is likely to cause
 problems with parity computations (I have already heard stories of
 people running into Bad Things (tm) while using a 24-disk RAIDZ-2 and
 a 14-disk RAIDZ configurations during resilvering and scrubs). Things
 like this definitely deserve a mention.
 
 If you don't have much time, I could see if I could find a few moments
 over the next week or 2 to make a few changes. What's the proposed
 format of change submissions? Are edited files ok or does one need to
 submit patches and if it's the latter, whats the syntax for making
 properly suited diffs?
 
 
 - Sincerely,
 Dan Naumov

From: Dan Naumov <dan.naumov@gmail.com>
To: bug-followup@FreeBSD.org, dan.naumov@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&nbsp;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"' &gt;&gt;
 /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

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

 In case I managed to screw up formatting using gmail, here is a direct
 link to the patch file:
 http://jago.pp.fi/temp/filesystems.chapter.sgml.patch.txt For future
 reference, when submitting patches, am I supposed to include them into
 the email body of replying to the PR or am I supposed to include the
 patch file(s) as an attachment?
 
 - Sincerely,
 Dan Naumov

From: Dan Naumov <dan.naumov@gmail.com>
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/135983: "The Z File System" - title is misleading and causes 
	search issue
Date: Wed, 5 Aug 2009 00:14:49 +0300

 Hello
 
 Considering the amount of time during which nothing has happened, am I
 to assume that my patch submission has been deemed unnecessary and the
 PR itself unimportant? Would be nice to get some kind of closure,
 either a commit of the patch I have submitted or a decline of the
 patch and closure of the PR with a brief explanation for the decline.
 
 Sincerely,
 Dan Naumov
State-Changed-From-To: open->closed 
State-Changed-By: remko 
State-Changed-When: Tue Aug 11 07:11:03 UTC 2009 
State-Changed-Why:  
Committed, thanks for the reminder! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=135983 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/135983: commit references a PR
Date: Tue, 11 Aug 2009 07:10:32 +0000 (UTC)

 remko       2009-08-11 07:10:14 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en_US.ISO8859-1/books/handbook/filesystems chapter.sgml 
   Log:
   Tidy up the ZFS section a bit, adjust the RAID-Z example from two to three
   drives and add a warning that the suggested configuration is between three
   to nine disks.
   
   PR:             135983
   
   Revision  Changes    Path
   1.6       +27 -14    doc/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
>Unformatted:
