Date: Fri, 19 Aug 2005 08:20:22 -0700 From: garys@opusnet.com (Gary W. Swearingen) To: Giorgos Keramidas <keramida@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: docs/85097: [patch] devd.conf.5 lacks a lot of vital information. Message-ID: <oad5oarm15.5oa@mail.opusnet.com> In-Reply-To: <200508191310.j7JDANAm099431@freefall.freebsd.org> (Giorgos Keramidas's message of "Fri, 19 Aug 2005 13:10:23 GMT") References: <200508191310.j7JDANAm099431@freefall.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Giorgos Keramidas <keramida@FreeBSD.org> writes: > Literal quote characters shouldn't be present in mdoc manuals. Apparently excepting those used as apostrophes. > Colon instead of a fullstop before the beginning of a list, please. When using colon for a list, it's usually best to avoid using "the following" as that should be obvious from the colon. > % +.Sh EXAMPLES > % +The file > % +.Pa /etc/devd.conf > % +contains numerous of different examples. > > It's probably better to write: > > The "foo" file contains... > > I'm not sure about this one, though. It's just a vague feeling that > placing the "file" after the filename reads more natural. The FreeBSD commiter Giorgos said that. The Giorgos FreeBSD commiter said that. ??? :) But "file name" and "name file" both sound fine to me. Of course, if we didn't have the need for Capitalization, we'd just write "/etc/devd.conf contains...". And there's a increasing trend towards using the French order of "noun, adjective" as in "Zoo Atlanta" instead of the usual "The Atlanta Zoo", so this would be OK too: "File /etc/devd.conf contains...". > As above, .Ql is not good for quoting multicharacter strings. It's Try this: find $(manpath|sed s/:/\ /g) | xargs zgrep '.Ql'
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?oad5oarm15.5oa>