Date: Mon, 16 Jan 2012 03:50:12 GMT From: Benjamin Kaduk <kaduk@MIT.EDU> To: freebsd-doc@FreeBSD.org Subject: Re: docs/164099: man page for gparm set is incorrect and incomplete Message-ID: <201201160350.q0G3oCbx019469@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/164099; it has been noted by GNATS. 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201201160350.q0G3oCbx019469>