Bug 19894
| Summary: | confusingly-named punctuation in style(9) | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Tony Finch <dot> | ||||
| Component: | Books & Articles | Assignee: | freebsd-doc (Nobody) <doc> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | ||||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
|
Description
Tony Finch
2000-07-13 17:40:01 UTC
On Thu, 13 Jul 2000 15:40:19 GMT, Tony Finch wrote:
> In the section about usage() and manual page synopsys lines, the
> text refers to what I call "square brackets" as "braces". I think
> this is confusing and should be changed according to the diff below.
> This also makes it consistent with the Jargon File.
I agree that the text as is, is wrong. However, I think the correct
names for these things should be used:
parentheses ( )
braces { }
brackets [ ]
Ciao,
Sheldon.
Sheldon Hearn wrote: > I agree that the text as is, is wrong. However, I think the correct > names for these things should be used: > > parentheses ( ) > braces { } > brackets [ ] Probably. I think saying "square brackets" would make it clearer (I suspect a lot of people think of "(" and ")" as "brackets"), but since an example is given anyway I suppose just "brackets" is adequate. How about this then? I found one other thing which I think should be fixed while I'm there... --- style.9 2000/03/19 16:52:59 1.33 +++ style.9 2000/07/15 16:51:19 @@ -56,7 +56,7 @@ OR <sys/param.h>, but not both! <sys/types.h> includes <sys/cdefs.h>, and it's okay to depend on that. .Bd -literal -offset 0i -#include <sys/types.h> /* Non-local includes in brackets. */ +#include <sys/types.h> /* Non-local includes in angle brackets. */ .Ed .Pp If it's a network program, put the network include files next. @@ -470,16 +470,16 @@ not fputs/puts/putchar/whatever; it's faster and usually cleaner, not to mention avoiding stupid bugs. .Pp -Usage statements should look like the manual pages synopsis. Options w/o +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 .Pq Sq \&| separates either-or options/arguments, and multiple options/arguments which are specified together are -placed in a single set of braces. +placed in a single set of brackets. .Pp .Bd -ragged -offset 0.3i "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en" -- Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D FreeBSD Documentation Project / 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. Sheldon Hearn wrote: >> -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. :-) Doh! <excuse quality=weak> I was trying to change as few lines as possible to make the diff easier to read... </excuse> > 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. That's one long sentence. :-( > I think it might be better to do this as a bullet list. I guess that's an excuse for me to learn how to do bullet lists in mdoc. :-) mdoc.samples should explain all, I hope... -- Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D FreeBSD Documentation Project / Sheldon Hearn wrote: > I think it might be better to do this as a bullet list. ok, my first diff for that: Index: style.9 =================================================================== RCS file: /usr/cvs/src/share/man/man9/style.9,v retrieving revision 1.33 diff -u -r1.33 style.9 --- style.9 2000/03/19 16:52:59 1.33 +++ style.9 2000/07/16 17:54:00 @@ -56,7 +56,7 @@ OR <sys/param.h>, but not both! <sys/types.h> includes <sys/cdefs.h>, and it's okay to depend on that. .Bd -literal -offset 0i -#include <sys/types.h> /* Non-local includes in brackets. */ +#include <sys/types.h> /* Non-local includes in angle brackets. */ .Ed .Pp If it's a network program, put the network include files next. @@ -470,16 +470,35 @@ not fputs/puts/putchar/whatever; it's faster and usually cleaner, not to mention avoiding stupid bugs. .Pp -Usage statements should look like the manual pages synopsis. Options w/o -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 +Usage statements should look like the manual pages synopsis. +The usage statement should be structured in the following order: +.Bl -enum -compat +.It +Options without operands come first, +in alphabetical order, +inside a single set of brackets. +.It +Options with operands come next, +also in alphabetical order, +with each option and its argument inside its own pair of brackets. +.It +Required arguments +.Pq if any +are next, +listed in the order they should be specified in the command line. +Any required arguments should not be within brackets. +.It +Finally, +any optional arguments should be listed, +listed in the order they should be specified, +and all inside brackets. +.El +.Pp +A bar .Pq Sq \&| separates either-or options/arguments, and multiple options/arguments which are specified together are -placed in a single set of braces. +placed in a single set of brackets. .Pp .Bd -ragged -offset 0.3i "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en" -- Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D FreeBSD Documentation Project / On Sun, 16 Jul 2000 19:01:47 +0100, Ben Smithurst wrote: > > I think it might be better to do this as a bullet list. > > ok, my first diff for that: Your patch is good. I would consider placeing a paragraph marker (Pp) before the -compact list. Also, I'd leave out this one line: > +Any required arguments should not be within brackets. I don't think it adds anything. I don't feel very strongly about this. Good job. Ciao, Sheldon. State Changed From-To: open->closed Committed in -current, thanks! |
