gbranden pushed a commit to branch master in repository groff. commit 5599c6decdc82d146b216b7111adfd55fa958294 Author: G. Branden Robinson <g.branden.robin...@gmail.com> Date: Sun Apr 22 01:51:43 2018 -0400
groff_man(7): Expand command synopsis section. This section now explains in detail how to write (and read) a command synopsis. Also fix some style/markup issues: * Mark the second argument to the .OP macro as optional. * Escape the hyphens in the command synopsis input example. * Guard ellipsis boundaries with zero-width spaces. Signed-off-by: G. Branden Robinson <g.branden.robin...@gmail.com> --- ChangeLog | 7 +++ tmac/groff_man.7.man | 131 ++++++++++++++++++++++++++++++++++++++------------- 2 files changed, 104 insertions(+), 34 deletions(-) diff --git a/ChangeLog b/ChangeLog index 5ea92e1..3b7cbed 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2018-04-22 G. Branden Robinson <g.branden.robin...@gmail.com> + + groff_man(7): Expand command synopsis section. + + This section now explains in detail how to write (and read) a + command synopsis. + 2018-04-12 Deri James <d...@chuzzlewit.myzen.co.uk> Make PDFPIC behave the same whether -Tps or -Tpdf used. diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man index f786898..e9e64a9 100644 --- a/tmac/groff_man.7.man +++ b/tmac/groff_man.7.man @@ -843,18 +843,22 @@ installation. .PP These macros are a convenience for authors. . +Together, they produce the traditional look of a Unix command synopsis. +. They also assist automated translation tools and help browsers in recognizing command synopses and treating them differently from running text. . . .TP -.BI .OP " key value" -Describe an optional command argument. +.BI .OP " option-name"\c +.RI " [" option-argument ] +Indicate an optional command parameter called +.IR option-name . . -The arguments of this macro are set surrounded by option braces -in the default Roman font; the first argument is printed with -a bold face, while the second argument is typeset as italic. +If the option takes an argument, specify +.I option-argument +using a noun, abbreviation, or hyphenated noun phrase. . . .TP @@ -865,50 +869,49 @@ Takes a single argument, the name of a command. . Text following, until closed by .BR .YS , -is set with a hanging indentation with the width of +is set with a hanging indentation of the width of .I command plus a space. . -This produces the traditional look of a Unix command synopsis. -. . .TP .B .YS -This macro restores normal indentation at the end of a command -synopsis. +End synopsis. +. +Restore normal indentation. . . .PP -Here is a real example: +For example, . . .IP .EX \&.SY groff -\&.OP \e-abcegiklpstzCEGNRSUVXZ -\&.OP \e-d cs -\&.OP \e-f fam -\&.OP \e-F dir -\&.OP \e-I dir -\&.OP \e-K arg -\&.OP \e-L arg -\&.OP \e-m name -\&.OP \e-M dir -\&.OP \e-n num -\&.OP \e-o list -\&.OP \e-P arg -\&.OP \e-r cn -\&.OP \e-T dev -\&.OP \e-w name -\&.OP \e-W name +\&.OP \e\-abcegiklpstzCEGNRSUVXZ +\&.OP \e\-d cs +\&.OP \e\-f fam +\&.OP \e\-F dir +\&.OP \e\-I dir +\&.OP \e\-K arg +\&.OP \e\-L arg +\&.OP \e\-m name +\&.OP \e\-M dir +\&.OP \e\-n num +\&.OP \e\-o list +\&.OP \e\-P arg +\&.OP \e\-r cn +\&.OP \e\-T dev +\&.OP \e\-w name +\&.OP \e\-W name \&.RI [ file -\&.IR .\e|.\e|. ] +\e&.\e|.\e|.\e&] \&.YS .EE . . .PP -produces the following output: +produces the following output. . . .RS @@ -931,18 +934,78 @@ produces the following output: .OP \-w name .OP \-W name .RI [ file -.IR .\|.\|. ] +\&.\|.\|.\&] .YS .RE . . .PP -If necessary, you might use +Multiple +.B .SY/.YS +blocks can be specified, +for instance to distinguish differing modes of operation of a complex +command like +.BR tar (1); +each will be separated by a paragraph space. +. +If necessary, you can use a .B br -requests to control line breaking. +request to insert a mandatory line break. +. +. +.PP +Several features of the above example are of note. +. +. +.IP \(bu +The command and option names are presented in +.B boldface +to cue the user that they should be input literally. +. +. +.IP \(bu +Option dashes are specified with the \(lq\e\-\(rq escape sequence; +this is an important practice to make them clearly visible and to +facilitate cut-and-paste from the rendered man page to a shell prompt or +text file. +. . -You can insert plain text as well; this looks like the traditional -(unornamented) syntax for a required command argument or filename. +.IP \(bu +Option arguments and command operands are presented in +.I italics +(underlined on some output devices, such as terminals and emulators), +to cue the user that they must be replaced with appropriate text. +. +. +.IP \(bu +Symbols that are neither to be typed literally nor simply replaced +appear in plain (roman) style; +brackets surround optional arguments, +and an ellipsis indicates that the previous syntactical element may be +repeated arbitrarily. +. +. +.IP +Some man pages use a brace-and-pipe notation such as +.RB \(lq{ \-\-diff | \-\-compare }\(rq +to indicate that one and only one of the \(lq|\(rq-separated items +within the braces must be input. +. +If this braced construct were furthermore surrounded by brackets, +then the meaning is that at most one of the items would be accepted. +. +. +.IP +Authors of man pages should note the use of the zero-width space +escape sequence \(lq\e&\(rq on both sides of the ellipsis; +this is a good practice to avoid surprises in the event the ellipsis +gets reflowed in your text editor. +. +See \(lqPORTABILITY AND TROFF REQUESTS\(rq, below. +. +The morbidly curious may consult +.BR groff (7) +regarding the narrow-space escape sequence \(lq\e|\(rq. . . .\" ==================================================================== _______________________________________________ Groff-commit mailing list Groff-commit@gnu.org https://lists.gnu.org/mailman/listinfo/groff-commit