From owner-freebsd-doc@FreeBSD.ORG Wed Jan 18 05:10:16 2012 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id AA12B1065674 for ; Wed, 18 Jan 2012 05:10:16 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 94D658FC23 for ; Wed, 18 Jan 2012 05:10:16 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.5/8.14.5) with ESMTP id q0I5AG4Y031986 for ; Wed, 18 Jan 2012 05:10:16 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.5/8.14.5/Submit) id q0I5AGXB031985; Wed, 18 Jan 2012 05:10:16 GMT (envelope-from gnats) Date: Wed, 18 Jan 2012 05:10:16 GMT Message-Id: <201201180510.q0I5AGXB031985@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: Ariane van der Steldt Cc: Subject: Re: docs/164099: man page for gparm set is incorrect and incomplete X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Ariane van der Steldt List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 18 Jan 2012 05:10:16 -0000 The following reply was made to PR docs/164099; it has been noted by GNATS. From: Ariane van der Steldt To: Benjamin Kaduk 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