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 Fix: Change documentation: - mention that the attributes are set using -a, not -f How-To-Repeat: man gparm, read the 'set' command section
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
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
For bugs matching the following criteria: Status: In Progress Changed: (is less than) 2014-06-01 Reset to default assignee and clear in-progress tags. Mail being skipped