Date: Sun, 16 Jul 2000 08:00:05 -0700 (PDT) From: Sheldon Hearn <sheldonh@uunet.co.za> To: freebsd-doc@freebsd.org Subject: Re: docs/19894: confusingly-named punctuation in style(9) Message-ID: <200007161500.IAA39299@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/19894; it has been noted by GNATS. From: Sheldon Hearn <sheldonh@uunet.co.za> To: Ben Smithurst <ben@FreeBSD.org> Cc: Tony Finch <dot@dotat.at>, FreeBSD-gnats-submit@FreeBSD.ORG Subject: Re: docs/19894: confusingly-named punctuation in style(9) Date: Sun, 16 Jul 2000 16:52:42 +0200 On Sat, 15 Jul 2000 17:55:51 +0100, Ben Smithurst wrote: > .Pp > -Usage statements should look like the manual pages synopsis. Options w/o > +Usage statements should look like the manual pages synopsis. Options without Break that sentence off onto its own new line. :-) Usage statements should look like the manual pages synopsis. Options without > operands come first, in alphabetical order inside a single set of > -braces, followed by options with operands, in alphabetical order, > -each in braces, followed by required arguments in the order they > -are specified, followed by optional arguments in the order they > -are specified. A bar > +brackets, followed by options with operands, in alphabetical order, > +each in brackets, followed by required arguments in the order they > +are specified, not in brackets, followed by optional arguments in the order they > +are specified, in brackets. A bar There's another too-long line in here, again the symptom of poor line breaking. Each sentence should begin on its own line, and sentences which don't fit on a single line (<72 chars) should be broken on sentence fragments if possible: Options without operands come first, in alphabetical order inside a single set of brackets, followed by options with operands, in alphabetical order, each in brackets, followed by required arguments in the order they are specified, not in brackets, followed by optional arguments in the order they are specified, in brackets. A bar [...] This is awful English. I think it might be better to do this as a bullet list. But now we're moving further from the original problem. It often happens like this, especially with manual pages that receive lots of piecemeal updates. ;-) Ciao, Sheldon. 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?200007161500.IAA39299>