On Mon, Aug 22, 2011 at 22:38, Benno Schulenberg <bensberg@xxxxxxxxxxxxx> wrote: > On Sat, 20 Aug 2011 21:08 +0200, "Sami Kerola" <kerolasa@xxxxxx> wrote: >> To me it does not sound a big deal if --help and --version >> description begins from different indent than rest of lines. I >> wrote example output that way, so that you can judge how that >> will look. > > When --help and --version are always the last two options of the > usage help text, a differing indentation is acceptable. But if --help > is ordered alphabetically, it will look broken. True, and that's why I wrote they should be last entries. >> \fB\-o\fR, \fB\-\-optional\fR[=<\fIarg\fR>] >> This option uses optional argument. > > As Karel said, the majority convention now is to not use pointy brackets > for arguments in man pages. The italics/underlining is enough to make > them stand out. I guess you did not read from git the section. .SH OPTIONS .TP \fB\-n\fR, \fB\-\-no\-argument\fR This option does not use argument. .TP \fB\-o\fR, \fB\-\-optional\fR [\fIarg\fR] Tell in description an .I arg is optional, and what happens when is or is not given. .TP \fB\-r\fR, \fB\-\-required\fR \fIarg\fR Tell in description option .I arg is required. As you can see no diamond brackets there. > I would also suggest to not use "arg" but the full word "argument", so as > to encourage writers to not unnecessarily abbreviate the argument name, > to use for example "seconds" and not "secs", use "number" and not "num". Good point. I will fix that when I'm at home again. > A thing about the formatting: why us \fB and \fR and \fB and \fR? > Why not use the macro .BR at the start of the line instead? No matter how I tried to use various .B, .BR > (I do not understand your comment about some macros not being > visually different from plain .B or .I.) Either my term, groff or pager is/are broken, or I have wooden eyes or the different highlights do not stand out, see yourself: http://ut3.org/~kerolasa/groff-highlight.png What I tried to say; Do not get fooled that different macros will look different so that you can refer visually in between different text elements. For example in the screen shot on top the required argument has same appearance when it is next to switch & in text. I think that sort of consistency in style makes things more understandable. > Another thing: the man page formatter itself puts a double space after a > period when in the man page source the next sentence begins on a new > line. So when in the source a new sentence begins somewhere midline, > it should use a double space before its initial letter. Are you sure it does that? See the screenshot notes section third paragraph line two, words `macros. See' has only single space in between them. Even there would be two spaces I do not agree that groff input writer should imitate output. It should be enough that words and sentences are white space separated, groff will take care the rest. > From your usage howto: >> -n, --no-argument option requires no_argument >> -o, --optional[=<arg>] option has optional_argument >> -r, --required <arg> option requires required_argument > > Why the underscores? I would suggest the following: > > -n, --no-argument option takes no argument > -o, --optional[=<arg>] option takes optional argument > -r, --required <arg> option requires an argument > > (As in a usage text space is limited, abbreviations are okay.) The weird underscores are used in option structure. Now when you mention that I think having such unexplained reference is not good. I'll write the description using ordinary text. -- Sami Kerola http://www.iki.fi/kerolasa/ -- To unsubscribe from this list: send the line "unsubscribe util-linux" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
