diff --git a/tmac/an-ext.tmac b/tmac/an-ext.tmac index 5a2ede65c..2fb4190bb 100644 --- a/tmac/an-ext.tmac +++ b/tmac/an-ext.tmac @@ -1,6 +1,6 @@ .\" groff extension macros for man(7) package .\" -.\" Copyright (C) 2007-2023 Free Software Foundation, Inc. +.\" Copyright (C) 2007-2024 Free Software Foundation, Inc. .\" .\" Written by Eric S. Raymond .\" Werner Lemberg @@ -62,17 +62,31 @@ .de SY . nr mA \\n(.j . ad l . nr mI \\n(.i -. sp . \} -. el \{\ +. el \ . br -. ns -. \} . -. nr mT \w'\fB\\$1\fP\ ' -. HP \\n(mTu +. nr mT \\n(.k+\w'\fB\\$1\fP' +. if \\n(.$=1 \ +. nr mT +\w'\ ' +. if \\n(.$>1 \ +. nr mT +\w'\fB\\$2\fP' +. \" Ensure that a partially collected line exists so that the `in` +. \" request affects only _subsequent_ output lines. (CSTR #54 §6) +\&\c +' in +\\n(mTu +. if \\n(.$=1 \{\ +. do nr .X +0 \" Ensure this Heirloom register exists for testing. +. \" If the formatter is not groff, work around DWB/Heirloom/ +. \" Solaris 10 glitch. Something in their man(7) defeats the rules +. \" set forth in CSTR #54 §6. +. if \\n(.g=0:\\n(.X \ +' ti -\\n(mTu +. B \\$1\ \c +. \} +. if \\n(.$>1 \ +. B \\$1\\$2\c . rr mT -. B "\\$1" .. . . diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in index f8488c6b0..d8f65334f 100644 --- a/tmac/groff_man.7.man.in +++ b/tmac/groff_man.7.man.in @@ -61,7 +61,7 @@ .SH Name .\" Legal Terms .\" ==================================================================== .\" -.\" Copyright (C) 1999-2023 Free Software Foundation, Inc. +.\" Copyright (C) 1999-2024 Free Software Foundation, Inc. .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are @@ -106,6 +106,7 @@ .SH Synopsis .SY "groff \-man" .RI [ option\~ .\|.\|.\&] .RI [ file\~ .\|.\|.] +.YS . .SY "groff \-m man" .RI [ option\~ .\|.\|.\&] @@ -181,13 +182,13 @@ .SH Description \&.SH Section heading Document structure macros \&.SM Small Font style macros \&.SS Subsection heading Document structure macros -\&.SY Synopsis start Command synopsis macros +\&.SY Synopsis start Synopsis macros \&.TH Title heading Document structure macros \&.TP Tagged paragraph Paragraphing macros \&.TQ Supplemental paragraph tag Paragraphing macros \&.UE URI end Hyperlink macros \&.UR URI start Hyperlink macros -\&.YS Synopsis end Command synopsis macros +\&.YS Synopsis end Synopsis macros .TE . . @@ -994,7 +995,7 @@ .SS "Paragraphing macros" . _endif()dnl .\" ==================================================================== -.SS "Command synopsis macros" +.SS "Synopsis macros" .\" ==================================================================== . Use @@ -1003,8 +1004,6 @@ .SS "Command synopsis macros" .B .YS to summarize syntax using familiar Unix conventions. . -These macros break the output line. -. .\" TODO: Determine whether this (is still? was ever?) true. .\" Furthermore, .\" some tools are able to interpret these macros semantically and treat @@ -1034,54 +1033,61 @@ .SS "Command synopsis macros" . . .TP -.BI .SY\~ keyword +.BI .SY\~ keyword\~\c +.RI [ suffix ] Begin synopsis. . -A new paragraph begins as with -.BR .P , -unless +Adjustment and automatic hyphenation are disabled. +. +If .B .SY has already been called without a corresponding .BR .YS , -in which case only a break is performed. -. -Adjustment and automatic hyphenation are disabled. +a break is performed. . .I keyword -is set in bold. +and +.I suffix +(if any) +are set in bold. +. +If a break is required in subsequent text +(up to another paragraphing +sectioning, +or synopsis macro call), +lines after the first are indented. . -If a break is required, -lines after the first are indented by the width of +The indentation amount is the width of .I keyword -plus a space. +plus a space, +if that is the only argument, +and by the sum of the widths of +.I keyword +and +.I suffix +otherwise. . . .TP .B .YS -End synopsis. -. -Indentation, +End synopsis, +breaking the line and restoring +indentation, adjustment, and hyphenation -are restored to their previous states. +to their previous states. _ifstyle()dnl . . .P -Multiple +Interleave multiple .BR .SY / .YS -blocks can be specified, -for instance to distinguish differing modes of operation of a complex -command like -.MR tar 1 ; -each will be vertically separated as paragraphs are. +blocks with paragraphing macros to distinguish differing modes of +operation of a complex command like +.MR tar 1 . . -. -.P -.B .SY -can be repeated before -.B .YS -to indicate synonymous ways of invoking a particular mode of operation. +Omit the paragraphing macro to indicate synonymous ways of invoking a +particular mode of operation. . . .P @@ -1110,6 +1116,7 @@ .SS "Command synopsis macros" \&.YS \&. \&. +\&.P \&.SY groff \&.B \e\-h \&.YS @@ -1119,10 +1126,12 @@ .SS "Command synopsis macros" \&.YS \&. \&. +\&.P \&.SY groff \&.B \e\-v \&.RI [ option\e\(ti .\e|.\e|.\e&] \&.RI [ file\e\(ti .\e|.\e|.] +\&.YS \&. \&.SY groff \&.B \e\-\e\-version @@ -1136,6 +1145,7 @@ .SS "Command synopsis macros" produces the following output. . . +.P .RS .SY groff .RB [ \-abcCeEgGijklNpRsStUVXzZ ] @@ -1181,18 +1191,22 @@ .SS "Command synopsis macros" .YS . . +.P .SY groff .B \-h +.YS . .SY groff .B \-\-help .YS . . +.P .SY groff .B \-v .RI [ option\~ .\|.\|.\&] .RI [ file\~ .\|.\|.] +.YS . .SY groff .B \%\-\-version @@ -1275,6 +1289,44 @@ .SS "Command synopsis macros" and causing additional inter-sentence space to be placed after it. . See subsection \(lqPortability\(rq below. +. +. +.P +We might synopsize the standard C library function +.MR snprintf 3 +as follows. +. +. +.P +.RS +.EX +\&.P +\&.B int +\&.SY snprintf ( +\&.BI \(dqchar *\(dq str , +\&.BI size_t\(rs\(ti size , +\&.BI \(dqconst char *\(dq format , +\&.RB .\(rs|.\(rs|. ); +\&.YS +.EE +.RE +. +. +.P +.I man +produces the following result. +. +. +.RS +.P +.B int +.SY snprintf ( +.BI "char\~*" str , +.BI size_t\~ size , +.BI "const\~char\~*" format , +.RB .\|.\|. ); +.YS +.RE _endif()dnl . . @@ -4290,7 +4342,7 @@ .SH Notes . .IP Examples of ellipsis usage are shown above, -in subsection \[lq]Command synopsis macros\[rq]. +in subsection \[lq]Synopsis macros\[rq]. . The idiomatic .I roff