docs/164099: man page for gparm set is incorrect and incomplete

[Benjamin Kaduk]

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

From: Benjamin Kaduk <kaduk at MIT.EDU>
To: Ariane van der Steldt <ariane at stack.nl>
Cc: freebsd-gnats-submit at 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