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

[Ariane van der Steldt]

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

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