From owner-freebsd-doc Fri Feb 1 18: 1:58 2002 Delivered-To: freebsd-doc@freebsd.org Received: from lists.blarg.net (lists.blarg.net [206.124.128.17]) by hub.freebsd.org (Postfix) with ESMTP id DF92C37B428 for ; Fri, 1 Feb 2002 18:01:40 -0800 (PST) Received: from thig.blarg.net (thig.blarg.net [206.124.128.18]) by lists.blarg.net (Postfix) with ESMTP id 662BEBDB1; Fri, 1 Feb 2002 18:01:40 -0800 (PST) Received: from localhost.localdomain ([206.124.139.115]) by thig.blarg.net (8.9.3/8.9.3) with ESMTP id SAA07317; Fri, 1 Feb 2002 18:01:33 -0800 Received: (from jojo@localhost) by localhost.localdomain (8.11.6/8.11.3) id g12225Z04041; Fri, 1 Feb 2002 18:02:05 -0800 (PST) (envelope-from swear@blarg.net) To: Giorgos Keramidas Cc: freebsd-doc@FreeBSD.ORG Subject: Re: docs/34529: [patch] Grammar nits in usbd.conf(5) and usbd(8) References: <200202011930.g11JU4Y67232@freefall.freebsd.org> From: swear@blarg.net (Gary W. Swearingen) Date: 01 Feb 2002 18:02:05 -0800 In-Reply-To: <200202011930.g11JU4Y67232@freefall.freebsd.org> Message-ID: Lines: 55 User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.1 (Cuyahoga Valley) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org Giorgos Keramidas writes: > Hum, capitalization is prime time flamefest/bikeshed material. > I can't comment on this. Someone with more 'english style' expertize > will probably know better. My dictionary from early 70s says I.D., but I'll bet that's obsolete. > > .Sh AUTHORS > > -The man page for the usbd configuration file was written by > > +The manual page for the usbd configuration file was written by > > .An Nick Hibma Aq n_hibma@FreeBSD.org . > > Is this even necessary? I haven't searched the sources for -all- the > manpages to see which have an 'AUTHORS' section. Others do have a > section like that (ipfw.8 for instance). What do others think? It's not necessary, but is low cost and may tend to broaden the pool of man page writer to include more GOOD man page writers. The compromise position is to keep it only in the man page "source code". I do think it should be careful to call (after the can't-change section title) the author the "initial author" or "creator" or it was first authored by so-and-so, so that that person can't be blamed for things that creep in during maintenance. Without a better place for it, this section (in every man page) should probably also say what group(s) or person(s) maintain the man page. > > @@ -80,7 +80,7 @@ > > Whenever a device is attached or > > detached the list of actions read from > > .Pa /etc/usbd.conf > > -are searched for a matching entry. > > +is searched for a matching entry. > > If found, the corresponding action is > > executed. > > `The list .. is searched.' This is correct as it is IMHO. > I'm not a native speaker, and I might be wrong here, but this would > probably look OK, if written as the following: > > =09Whenever a device is attached or detached, > =09the list of actions (which is read from > =09.Pa /etc/usbd.conf ) > =09is searched for a matching entry. > > or something similar. What do you think? Either is acceptable (though the parens might better be commas), but I like his patch as it is. I might have removed "read from /etc/usbd.conf" as it should be obvious (but I don't have the context in front of me). Generally, I'd prefer man pages referred to the thing they are documenting as "this file" or "this command" instead of "/etc/usbd.conf" or "the usbd command", but that's just an opinion. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message