docs/164099: man page for gparm set is incorrect and incomplete
kaduk at MIT.EDU
Mon Jan 16 03:50:13 UTC 2012
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
Date: Sun, 15 Jan 2012 22:45:49 -0500 (EST)
On Fri, 13 Jan 2012, Ariane van der Steldt wrote:
> 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
> - the -f option apparently has no relation to ATTRIBUTES
> - the -a option is used for the ATTRIBUTES
> man gparm, read the 'set' command section
> 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.]
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
'gpart set' looks to be mentioned in a few places (hopefully my formatting
is not destroyed somewhere in the mail path):
% Usage of the gpart utility:
% gpart set -a attrib -i index [-f flags] geom
% set Set the named attribute on the partition entry. See the sec-
% tion entitled ATTRIBUTES below for a list of available
% Additional options include:
% -f flags Additional operational flags. See the section
% entitled OPERATIONAL FLAGS below for a discussion
% about its use.
% The scheme-specific attributes for EBR:
% 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.
More information about the freebsd-doc