Date: Wed, 18 Jan 2012 05:10:16 GMT From: Ariane van der Steldt <ariane@stack.nl> To: freebsd-doc@FreeBSD.org Subject: Re: docs/164099: man page for gparm set is incorrect and incomplete Message-ID: <201201180510.q0I5AGXB031985@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: 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201201180510.q0I5AGXB031985>