Date: 01 Feb 2002 18:02:05 -0800 From: swear@blarg.net (Gary W. Swearingen) To: Giorgos Keramidas <keramida@ceid.upatras.gr> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: docs/34529: [patch] Grammar nits in usbd.conf(5) and usbd(8) Message-ID: <pw7kpwk5eq.kpw@localhost.localdomain> In-Reply-To: <200202011930.g11JU4Y67232@freefall.freebsd.org> References: <200202011930.g11JU4Y67232@freefall.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Giorgos Keramidas <keramida@ceid.upatras.gr> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?pw7kpwk5eq.kpw>