From nobody@FreeBSD.org  Fri Jan 13 20:53:16 2012
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 AA8CB1065672
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 13 Jan 2012 20:53:16 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id 969E98FC1A
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 13 Jan 2012 20:53:16 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.4/8.14.4) with ESMTP id q0DKrGfS030458
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 13 Jan 2012 20:53:16 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.4/8.14.4/Submit) id q0DKrGmK030453;
	Fri, 13 Jan 2012 20:53:16 GMT
	(envelope-from nobody)
Message-Id: <201201132053.q0DKrGmK030453@red.freebsd.org>
Date: Fri, 13 Jan 2012 20:53:16 GMT
From: Ariane van der Steldt <ariane@stack.nl>
To: freebsd-gnats-submit@FreeBSD.org
Subject: man page for gparm set is incorrect and incomplete
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         164099
>Category:       docs
>Synopsis:       gparm(8): man page for gparm set is incorrect and incomplete
>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:   Fri Jan 13 21:00:24 UTC 2012
>Closed-Date:    
>Last-Modified:  Wed Jan 18 05:10:12 UTC 2012
>Originator:     Ariane van der Steldt
>Release:        FreeBSD 9.0 RELEASE
>Organization:
>Environment:
FreeBSD 9.0 RELEASE - amd64
>Description:
man gparm: set command describes -f as the only specific option to gparm
set and mentions that for further info, the section ATTRIBUTES must be consulted.

However:
- the -f option apparently has no relation to ATTRIBUTES
- the -a option is used for the ATTRIBUTES
>How-To-Repeat:
man gparm, read the 'set' command section
>Fix:
Change documentation:
- mention that the attributes are set using -a, not -f

>Release-Note:
>Audit-Trail:

From: Benjamin Kaduk <kaduk@MIT.EDU>
To: Ariane van der Steldt <ariane@stack.nl>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/164099: man page for gparm set is incorrect and
 incomplete
Date: Sun, 15 Jan 2012 22:45:49 -0500 (EST)

 On Fri, 13 Jan 2012, Ariane van der Steldt wrote:
 
 >> Description:
 > man gparm: set command describes -f as the only specific option to gparm 
 > set and mentions that for further info, the section ATTRIBUTES must be 
 > consulted.
 >
 > However:
 > - the -f option apparently has no relation to ATTRIBUTES
 > - the -a option is used for the ATTRIBUTES
 >> How-To-Repeat:
 > man gparm, read the 'set' command section
 >> Fix:
 > Change documentation:
 > - mention that the attributes are set using -a, not -f
 
 [I am assuming that this is actually referring to gpart(8), not a "gparm" 
 that I don't seem to find anywhere.]
 
 Hi Ariane,
 
 I must confess I'm not entirely sure what parts of the man page are giving 
 you difficulty here, so I'll go through and explain how I'm interpreting 
 things, and you can tell me which parts of my interpretation you aren't 
 getting from the current text.  Then we can come up with a patch to make 
 it better.
 
 'gpart set' looks to be mentioned in a few places (hopefully my formatting 
 is not destroyed somewhere in the mail path):
 
 % SYNOPSIS
 % [...]
 %      Usage of the gpart utility:
 % [...]
 %      gpart set -a attrib -i index [-f flags] geom
 % [...]
 % DESCRIPTION
 % [...]
 %     set       Set the named attribute on the partition entry.  See the sec-
 %                tion entitled ATTRIBUTES below for a list of available
 %                attributes.
 % 
 %                Additional options include:
 % 
 %                -f flags    Additional operational flags.  See the section
 %                            entitled OPERATIONAL FLAGS below for a discussion
 %                            about its use.
 % [...]
 % ATTRIBUTES
 %      The scheme-specific attributes for EBR:
 % 
 %      active
 % 
 %      The scheme-specific attributes for GPT:
 % [..., including MBR and PC98]
 % OPERATIONAL FLAGS
 %      Actions other than the commit and undo actions take an optional -f flags
 %      option.  This option is used to specify action-specific operational
 %      flags.  By default, the gpart utility defines the `C' flag so that the
 %      action is immediately committed.  The user can specify ``-f x'' to have
 %      the action result in a pending change that can later, with other pending
 %      changes, be committed as a single compound change with the commit action
 %      or reverted with the undo action.
 
 The synopsis tells me that the 'gpart set' subcommand takes a mandatory 
 '-a attrib'[utes] argument and a mandatory '-i index' argument, and can 
 take an optional flags argument.  It, of course, must also operate on a 
 particular geom device.
 
 Looking at the more detailed entry for the 'set' subcommand, I get 
 confirmation that this subcommand must deal with attributes (i.e. has a 
 mandatory argument), and can get the list of choices from the ATTRIBUTES 
 section later on.  (Hmm, there is no mention of the 'index' argument here, 
 though, which is probably a separate bug.  The text from the 'add' 
 subcommand could be used, but it might be more consistent with the rest of 
 the manual page to just mention it inline.)  The 'additional options' then 
 are just the "optional" (i.e. non-mandatory) options, and OPERATIONAL 
 FLAGS tells me what in particular I can use.
 
 Which parts of my interpretation do not come through to you from the 
 current text of the man page?  I'll put together a patch that includes 
 those changes and also adds mention of the 'index' argument.
 
 Thanks,
 
 Ben Kaduk

From: Ariane van der Steldt <ariane@stack.nl>
To: Benjamin Kaduk <kaduk@MIT.EDU>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/164099: man page for gparm set is incorrect and incomplete
Date: Wed, 18 Jan 2012 06:05:11 +0100

 On Sun, Jan 15, 2012 at 10:45:49PM -0500, Benjamin Kaduk wrote:
 > On Fri, 13 Jan 2012, Ariane van der Steldt wrote:
 > >> Description:
 > > man gparm: set command describes -f as the only specific option to gparm 
 > > set and mentions that for further info, the section ATTRIBUTES must be 
 > > consulted.
 > >
 > > However:
 > > - the -f option apparently has no relation to ATTRIBUTES
 > > - the -a option is used for the ATTRIBUTES
 > >> How-To-Repeat:
 > > man gparm, read the 'set' command section
 > >> Fix:
 > > Change documentation:
 > > - mention that the attributes are set using -a, not -f
 > 
 > [I am assuming that this is actually referring to gpart(8), not a "gparm" 
 > that I don't seem to find anywhere.]
 
 gpart indeed, my apologies.
 
 > I must confess I'm not entirely sure what parts of the man page are giving 
 > you difficulty here, so I'll go through and explain how I'm interpreting 
 > things, and you can tell me which parts of my interpretation you aren't 
 > getting from the current text.  Then we can come up with a patch to make 
 > it better.
 > 
 > 'gpart set' looks to be mentioned in a few places (hopefully my formatting 
 > is not destroyed somewhere in the mail path):
 > 
 > % SYNOPSIS
 > % [...]
 > %      Usage of the gpart utility:
 > % [...]
 > %      gpart set -a attrib -i index [-f flags] geom
 > % [...]
 > % DESCRIPTION
 > % [...]
 > %     set       Set the named attribute on the partition entry.  See the sec-
 > %                tion entitled ATTRIBUTES below for a list of available
 > %                attributes.
 > % 
 > %                Additional options include:
 > % 
 > %                -f flags    Additional operational flags.  See the section
 > %                            entitled OPERATIONAL FLAGS below for a discussion
 > %                            about its use.
 
 The above is where it went wrong. I double checked and the error is all
 mine. I think what happened was I read the -f as only option, went up
 again (the kernel options left me wondering if I really had this
 enabled, which invoking 'gpart show' confirmed) and then scrolled back
 to the set subcommand. Where I proceeded to find the uppercase wording
 and probably selected the wrong term.
 At least, that's what I think happened. :/
 
 > % [...]
 > % ATTRIBUTES
 > %      The scheme-specific attributes for EBR:
 > % 
 > %      active
 > % 
 > %      The scheme-specific attributes for GPT:
 > % [..., including MBR and PC98]
 > % OPERATIONAL FLAGS
 > %      Actions other than the commit and undo actions take an optional -f flags
 > %      option.  This option is used to specify action-specific operational
 > %      flags.  By default, the gpart utility defines the `C' flag so that the
 > %      action is immediately committed.  The user can specify ``-f x'' to have
 > %      the action result in a pending change that can later, with other pending
 > %      changes, be committed as a single compound change with the commit action
 > %      or reverted with the undo action.
 > 
 > The synopsis tells me that the 'gpart set' subcommand takes a mandatory 
 > '-a attrib'[utes] argument and a mandatory '-i index' argument, and can 
 > take an optional flags argument.  It, of course, must also operate on a 
 > particular geom device.
 > 
 > Looking at the more detailed entry for the 'set' subcommand, I get 
 > confirmation that this subcommand must deal with attributes (i.e. has a 
 > mandatory argument), and can get the list of choices from the ATTRIBUTES 
 > section later on.  (Hmm, there is no mention of the 'index' argument here, 
 > though, which is probably a separate bug.  The text from the 'add' 
 > subcommand could be used, but it might be more consistent with the rest of 
 > the manual page to just mention it inline.)  The 'additional options' then 
 > are just the "optional" (i.e. non-mandatory) options, and OPERATIONAL 
 > FLAGS tells me what in particular I can use.
 
 It seems a bit strange to me to mention the -f option for each entry,
 while it seems to be universal to each modifying subcommand.
 Alternatively, the -a, -i and -f could be described at the top of the
 DESCRIPTION, followed by each ofthe subcommands.
 
 > Which parts of my interpretation do not come through to you from the 
 > current text of the man page?  I'll put together a patch that includes 
 > those changes and also adds mention of the 'index' argument.
 
 I think it's best to describe the -a, -i, -f etc options at the top of
 the description, after:
 'The gpart utility is used to partition GEOM providers, normally disks.'
 It'll mean less duplication of text (by reducing the -f description to
 only one occurence) and places the options closer to the synopsis,
 improving readability.
 
 None the less, the error was obviously mine, my apologies.
 -- 
 Ariane
>Unformatted:
