At 2018-11-04T02:25:37+0100, Bertrand Garrigues wrote: > Apologies for my long silence; due to personal problems I wasn't able to > work on groff these last months.
Hi Bertrand, I hope things are getting better for you! > Version 1.22.4.rc2 no longer build on my environment (Archlinux) because > of glibc 2.28 (fixed by 1c8c0210bded9e78c2748753c17fc9d9b07b0089) so > I've just made a 1.22.4.rc3 version. I need to check the issue on > 'contrib/hdtbl' pointed out by Branden before pushing an official > release. I'd like to propose resolving the following 4 issues before going final. 1. Resolve this compiler warning: ../src/roff/troff/input.cpp: In function ‘void macro_source()’: ../src/roff/troff/input.cpp:7716:11: warning: ‘char* strncat(char*, const char*, size_t)’ specified bound depends on the length of the source argument [-Wstringop-overflow=] strncat(s, fn, strlen(fn) - sizeof(MACRO_POSTFIX) + 1); ~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ../src/roff/troff/input.cpp:7716:25: note: length computed here strncat(s, fn, strlen(fn) - sizeof(MACRO_POSTFIX) + 1); ~~~~~~^~~~ 2. Revert the 3 changes Ingo made to hdtbl in August; unfortunately they had bad side-effects, producing warnings and causing some documents to not generate correctly. (It may be better to think of contrib/hdtbl/examples as contrib/hdtbl/test-suite.) 3. Resolve Savannah #40967. I told Dave K. I'd work on this back on February but I let it drop. It is not a big patch, and only affects the "me" macro package documentation. Maybe we can even get a French translation before 1.22.4 final (it's only a few words). https://savannah.gnu.org/bugs/?40967 I'll work on this first as it requires no research. 4. Apply the final pass of my groff_man.7 overhaul. IIRC I sent this privately to you and Ingo a few months ago; I have tweaked it very little sense, so I reckon I'm happy with it. All it needs now is a commit message and ChangeLog entry. Please find it attached. -- Regards, Branden
diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man index 1ce14033..12c655fc 100644 --- a/tmac/groff_man.7.man +++ b/tmac/groff_man.7.man @@ -53,7 +53,7 @@ groff_man \- GNU roff macro package for formatting man pages .\" ==================================================================== . The -.B man +.I man macro package for .I groff is used to produce manual pages @@ -81,28 +81,28 @@ Macro Meaning Subsection .T& lB l l. _ -\&.B Boldface Font face macros -\&.BI Boldface, italic alternating Font face macros -\&.BR Boldface, roman alternating Font face macros +\&.B Bold Font style macros +\&.BI Bold, italic alternating Font style macros +\&.BR Bold, roman alternating Font style macros \&.EE Example end Document structure macros \&.EX Example begin Document structure macros -\&.I Italic Font face macros -\&.IB Italic, boldface alternating Font face macros +\&.I Italic Font style macros +\&.IB Italic, bold alternating Font style macros \&.IP Indented paragraph Paragraph macros -\&.IR Italic, roman alternating Font face macros +\&.IR Italic, roman alternating Font style macros \&.LP (Left) paragraph Paragraph macros \&.ME Mail-to end Hyperlink and email macros \&.MT Mail-to start Hyperlink and email macros \&.OP (Command-line) option Command synopsis macros \&.P Paragraph Paragraph macros \&.PP Paragraph Paragraph macros -\&.RB Roman, boldface alternating Font face macros +\&.RB Roman, bold alternating Font style macros \&.RE Relative-indent end Document structure macros -\&.RI Roman, italic alternating Font face macros +\&.RI Roman, italic alternating Font style macros \&.RS Relative-indent start Document structure macros -\&.SB Small boldface Font face macros +\&.SB Small bold Font style macros \&.SH Section heading Document structure macros -\&.SM Small Font face macros +\&.SM Small Font style macros \&.SS Subection heading Document structure macros \&.SY Synopsis start Command synopsis macros \&.TH Title heading Document structure macros @@ -156,10 +156,10 @@ exceptions are noted. .PP Bear in mind that .I groff -is fundamentally a programming language for typesetting. +is fundamentally a programming system for typesetting. . Consequently, -the verb \(lqset\(rq is frequently used below in the sense of \(lqto +the verb \(lqto set\(rq is frequently used below in the sense \(lqto typeset\(rq. . . @@ -172,15 +172,16 @@ group of macros. . .B .TH (title heading) identifies the document as a man page and defines -fundamental information enabling its indexing by -.BR mandb (8). +information enabling its indexing by +.IR mandb (8) +or a similar tool. +. . Sections .RB ( .SH ), one of which is mandatory and many of which are standardized, -facilitate quick location of relevant information by the reader and aid -the man page writer to comprehensively discuss all essential aspects of -the topic. +facilitate quick location of relevant material by the reader and aid +the man page writer to discuss all essential aspects of the topic. . Subsections .RB ( .SS ) @@ -205,154 +206,227 @@ macros. . . .TP -.BI .TH " title section \fR[\fPextra1\fR]\fP \fR[\fPextra2\fR]\fP \fR[\fPextra3\fR]" -Set the title of the man page to +.BI .TH " title section"\c +.RI " [" footer-middle ]\c +.RI " [" footer-outside ]\c +.RI " [" header-middle ] +Define the title of the man page as .I title -and the section to -.IR section , -which must take on a value between 1 and\~8. +and the section as +.IR section . . -The value -.I section -may also have a string appended, e.g.\& \[oq]pm\[cq], to indicate a -specific subsection of the man pages. +See +.IR man (1) +for details on the section numbers and suffixes applicable to your +system. . -Both .I title and .I section -are positioned at the left and right in the header line (with +are positioned together at the left and right in the header line +(with .I section in parentheses immediately appended to -.IR title . +.IR title ). . -.I extra1 -is positioned in the middle of the footer line. +.I footer-middle +is centered in the footer line. . -.I extra2 +.I footer-outside is positioned at the left in the footer line (or at the left on even pages and at the right on odd pages if double-sided printing is active). . -.I extra3 +.I header-middle is centered in the header line. . +If +.I section +is a simple integer between 1 and\~9 (inclusive), +or is exactly \(lq3p\(rq, +there is no need to specify +.IR header-middle ; +the macro package will supply text for it. +. . .IP For HTML output, headers and footers are completely suppressed. . . .IP -Additionally, this macro starts a new page; the new line number is\~1 -again (except if the \[oq]\-rC1\[cq] option is given on the command -line). +Additionally, this macro starts a new page; the page number is reset +to\~1 +(unless the \(lq\-rC1\(rq option is given on the command line). +. +This feature is intended only for formatting multiple man pages. +. +. +.IP +A man page should contain exactly one +.B .TH +call at or near the beginning of the file, +prior to any other macro calls. . -This feature is intended only for formatting multiple man pages; -a single man page should contain exactly one -.B TH -macro at the beginning of the file. +. +.IP +By convention, +.I footer-middle +is the most recent modification date of the man page source document, +and +.I footer-outside +is the name and version or release of the project providing it. . . .TP -.BI .SH " \fR[\fPtext for a heading\fR]\fP" -Set up an unnumbered section heading sticking out to the left. +.BR .SH " ["\c +.IR heading-text ] +Set +.I heading-text +as a section heading flush left. . -Prints out all the text following +The text following +.B .SH +up to the end of the line, +or the text on the next input line if .B .SH -up to the end of the line (or the text in the next input line if there -is no argument to -.BR .SH ) -in bold face -(or the font specified by the string -.BR HF ), -one size larger than the base document size. +is given no arguments, +is set in bold +(or the font specified by the string register +.BR HF ) +slightly larger than the base font size. . -Additionally, the left margin and the indentation for the following -text is reset to the default values. +Additionally, +the left margin and indentation affecting subsequent text are reset to +their default values. . +Text on input lines after +.I heading-text +is set as a normal paragraph +.RB ( .PP ). . -.TP -.BI .SS " \fR[\fPtext for a heading\fR]\fP" -Set up a secondary, unnumbered section heading. . -Prints out all the text following +.IP +The content of +.I heading-text +and ordering of sections has been standardized by common practice, +as has much of the layout of material within sections. +. +For example, +a section called \(lqName\(rq or \(lqNAME\(rq must exist, +must be the first section after the +.B .TH +call, +and must contain only a line of the form +.RS \" Invisibly move left margin to current .IP indent. +.RS \" Now indent further, visibly. +.IR page-topic [\c +.BR , " \&.\|.\|.\&]" +.B \e\-\ \c +.I summary-description +.RE \" Move left margin back to .IP indentation. +for a man page to be properly indexed. +. +See +.IR man (7) +for the conventions prevailing on your system. +.RE \" Move left margin back to standard position. +. +. +.TP +.BR .SS " ["\c +.IR subheading-text ] +Set +.I subheading-text +as a subsection heading indented (by default) partway between a section +heading and a normally-indented paragraph +.RB ( .PP ). +. +The text following +.B .SS +up to the end of the line, +or the text on the next input line if .B .SS -up to the end of the line (or the text in the next input line if there -is no argument to -.BR .SS ) -in bold face -(or the font specified by the string -.BR HF ), -at the same size as the base document size. +is given no arguments, +is set in bold +(or the font specified by the string register +.BR HF ) +at the base font size. +. +Additionally, +the left margin and indentation affecting subsequent text are reset to +their default values. . -Additionally, the left margin and the indentation for the following -text is reset to the default values. +Text on input lines after +.I subheading-text +is set as a normal paragraph +.RB ( .PP ). . . .TP .B .EX .TQ .B .EE -Example/End Example. +Begin and end example. . After .BR .EX , -filling is disabled and the font is set to constant-width. +filling and hyphenation are disabled and a constant-width (monospaced) +font is selected. . -This is useful for formatting code, command, and configuration-file -examples. +Calling +.B .EE +enables filling and restores the previous hyphenation setting and font. . -The -.B EE -macro restores filling and restores the previous font. +. +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) +.IP +Example regions are useful for formatting code, +shell sessions, +and text file contents. . . +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) .IP These macros are defined on many (but not all) legacy Unix systems -running classic troff. +running classic +.IR troff . . To be certain your page will be portable to those systems, copy their definitions from the .I \%an\-ext.tmac file of a -.BR groff +.I groff installation. . . .TP -.BI .RS " \fR[\fPnnn\fR]\fP" -This macro moves the left margin to the right by the value -.I nnn -if specified (default unit is \[oq]n\[cq]); otherwise it is set to the -previous indentation value specified with -.BR .TP , -.BR .IP , -or -.B .HP -(or to the default value if none of them have been used yet). -. -The indentation value is then set to the default. +.BR .RS " ["\c +.IR indent ] +Move the left margin to the right by the value +.IR indent , +if specified, +and by a default amount otherwise; +see subsection \(lqHorizontal and vertical spacing\(rq, +below. . +Calls to +.B .RS +can be nested; +each call increments by\~1 the indentation level used by +.BR .RE . . -.IP -Calls to the -.B RS -macro can be nested. +The indentation level prior to any +.B .RS +calls is\~1. . . .TP -.BI .RE " \fR[\fPnnn\fR]\fP" -This macro moves the left margin back to level -.IR nnn , -restoring the previous left margin. +.BR .RE " ["\c +.IR level ] +Move the left margin back to that corresponding to indentation level +.IR level . . -If no argument is given, it moves one level back. -. -The first level (i.e., no call to -.B .RS -yet) has number\~1, and each call to -.B .RS -increases the level by\~1. +If no argument is given, move the left margin one level back. . . .\" ==================================================================== @@ -361,7 +435,8 @@ increases the level by\~1. . A typical paragraph .RB ( .PP ) -is set at the current left margin. +is set at the current left margin, +which by default is indented from the left margin of the output device. . In man pages and other technical literature, definition lists are frequently encountered; @@ -386,52 +461,54 @@ or to present an itemized or ordered list. .B .PP .TQ .B .P -These macros are mutual aliases. +Begin a new paragraph; +these macros are synonymous. . -Any of them causes a line break at the current position, followed by a -vertical space downwards by the amount specified by the +They break the output line at the current position, +followed by a vertical space downward by a default amount +(which can be changed by the deprecated .B PD -macro. +macro). . -The font size and shape are reset to the default value (normally 10pt -Roman). +The font size and style are reset to defaults; +see subsection \(lqFont style macros\(rq, +below. . -Finally, the current left margin and the indentation is reset to the -default values. +Finally, the left margin and indentation are reset to default values. . . .TP -.BI .TP " \fR[\fPnnn\fR]\fP" -Set up an indented paragraph with label. +.BR .TP " ["\c +.IR indent ] +Set a tagged, indented paragraph. . -The indentation is set to -.I nnn -if that argument is supplied (the default unit is \[oq]n\[cq] if omitted), -otherwise it is set to the previous indentation value specified with -.BR .TP , -.BR .IP , -or -.B .HP -(or to the default value if none of them have been used yet). +The input line following this macro, +known as the +.IR tag , +is printed at the current left margin. . +Subsequent text is indented by +.IR indent , +if specified, +and by a default amount otherwise; +see subsection \(lqHorizontal and vertical spacing\(rq, +below. . -.IP -The first input line of text following this macro is interpreted as a -string to be printed flush-left, as it is appropriate for a label. -. -It is not interpreted as part of a paragraph, so there is no attempt -to fill the first line with text from the following input lines. . -Nevertheless, if the label is not as wide as the indentation the -paragraph starts at the same line (but indented), continuing on the -following lines. +.IP +If the tag is not as wide as the indentation, +the paragraph starts on the same line as the tag, +at the applicable indentation, +and continues on the following lines. . -If the label is wider than the indentation the descriptive part of the -paragraph begins on the line following the label, entirely indented. +Otherwise, +the descriptive part of the paragraph begins on the line following the +tag, +entirely indented. . -Note that neither font shape nor font size of the label is set to a -default value; on the other hand, the rest of the text has default -font settings. +The line containing the tag can include a macro call, +for instance to set the tag in bold with +.BR .B . . . .IP @@ -445,161 +522,193 @@ the subsequent ones. . .TP .B .TQ -The -.B TQ -macro sets up header continuation for a -.B TP -macro. +Set an additional tag for a paragraph tagged with +.BR .TP . . -With it, you can stack up any number of labels (such as in a -glossary, or list of commands) before beginning the indented -paragraph. +The pending output line is broken. . -For an example, look up the documentation of the -.BR LP , -.BR PP , -and -.BR P -macros. +The tag on the input line following this macro and subsequent lines are +handled as with +.BR .TP . . . .IP This macro is not defined on legacy Unix systems running classic -troff. +.IR troff . . To be certain your page will be portable to those systems, copy its definition from the .I \%an\-ext.tmac file of a -.BR groff +.I groff installation. . . +.IP +The descriptions of +.BR .LP , +.BR .PP , +and +.BR .P +above were written using +.B .TP +and +.BR .TQ . +. +. .TP -.BI .IP " \fR[\fPdesignator\fR]\fP \fR[\fPnnn\fR]\fP" -Set up an indented paragraph, using -.I designator -as a tag to mark its beginning. +.BR .IP " ["\c +.IR tag "] "\c +.RI [ indent ] +Set an indented paragraph with an optional tag. . -The indentation is set to -.I nnn -if that argument is supplied (the default unit is \[oq]n\[cq] if -omitted), otherwise it is set to the previous indentation value -specified with +The +.I tag +and +.I indent +arguments, +if present, +are handled as with .BR .TP , -.BR .IP , -or -.B .HP -(or to the default value if none of them have been used yet). -. -Font size and face of the paragraph (but not the designator) are reset -to its default values. +with the exception that the +.I tag +argument to +.B .IP +cannot include a macro call. . . +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) .IP -To start an indented paragraph with a particular indentation but -without a designator, use \[oq]""\[cq] (two doublequotes) as the -first argument. -. +Two convenient use cases for +.B .IP +are . -.IP -For example, the following paragraphs were all set up with bullets as -the designator, using \[oq].IP\ \e(bu\ 4\[cq]. . -The whole block has been enclosed with -.B .RS +.RS \" Invisibly move left margin to current .IP indent. +.RS \" Now indent further, visibly. +.IP (1) 4n +to start a new paragraph with the same indentation as the previous +.B .IP +or +.B .TP +paragraph, +if no +.I indent +argument is given; and -.B .RE -to set the left margin temporarily to the current indentation value. . . -.RS -.IP \(bu 4 -.B IP -is one of the three macros used in the -.B man -package to format lists. +.IP (2) +to set a paragraph with a short +.I tag +that is not semantically important, +such as a bullet (\(bu)\(emobtained with the \(oq\e(bu\(cq character +escape\(emor list enumerator, +as seen in this very paragraph. +.RE \" Move left margin back to .IP indentation. +.RE \" Move left margin back to standard position. . . -.IP \(bu 4 -.B HP -is another. +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) +.\" ==================================================================== +.SS "Command synopsis macros" +.\" ==================================================================== . -This macro produces a paragraph with a left hanging indentation. +Command synopses are a staple of section\~1 and\~8 man pages. . +These macros aid you to construct one that has the classical Unix +appearance. . -.IP \(bu 4 -.B TP -is another. +Furthermore, +some tools are able to interpret these macros semantically and treat +them appropriately for localization and/or presentation. . -This macro produces an unindented label followed by an indented -paragraph. -.RE +A command synopsis is wrapped in +.BR .SY / .YS +calls, +with command-line options of some formats indicated by +.BR .OP . . . -.\" ==================================================================== -.SS "Command synopsis macros" -.\" ==================================================================== -. -The following macros are not defined on legacy Unix systems -running classic troff. +.PP +These macros are not defined on legacy Unix systems running classic +.IR troff . . -To be certain your page will be portable to those systems, copy their -definitions from the +To be certain your page will be portable to those systems, copy +their definitions from the .I \%an\-ext.tmac file of a -.BR groff +.I groff 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 .SY " command" Begin synopsis. . -Takes a single argument, the name of a command. +Hyphenation is turned off. . -Text following, until closed by -.BR .YS , -is set with a hanging indentation of the width of +The .I command -plus a space. +argument is set in bold. . -Hyphenation is turned off. +The output line is filled as normal, +but if a break is required, +subsequent output lines are indented by the width of +.I command +plus a space. . . .TP .BI .OP " option-name"\/\c .RI " [" option-argument ] Indicate an optional command parameter called -.IR option-name . +.IR option-name , +which is set in bold. . If the option takes an argument, specify .I option-argument using a noun, abbreviation, or hyphenated noun phrase. . +If present, +.I option-argument +is preceded by a space and set in italics. +. +Square brackets (in roman) surround both arguments. +. . .TP .B .YS End synopsis. . -Restores indentation and hyphenation to previous values. +Restore indentation and hyphenation to previous values. +. +. +.PP +Multiple +.B .SY/.YS +blocks can be specified, +for instance to distinguish differing modes of operation of a complex +command like +.IR tar (1); +each will be separated by a paragraph space. +. +. +.PP +.B .SY +can also be repeated multiple times before a closing +.BR .YS , +which is useful to indicate synonymous ways of invoking a particular +mode of operation. . . +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) .PP For example, . . .IP +.\" from src/roff/groff/groff.1.man .EX \&.SY groff \&.OP \e\-abcegiklpstzCEGNRSUVXZ @@ -621,6 +730,16 @@ For example, \&.RI [ file \e&.\e|.\e|.\e&] \&.YS +\&. +\&.SY groff +\&.B \e\-h +\&.SY groff +\&.B \e\-\e\-help +\&.YS +. +. +.IP + .EE . . @@ -650,35 +769,40 @@ produces the following output. .RI [ file \&.\|.\|.\&] .YS +. +.SY groff +.B \-h +.SY groff +.B \-\-help +.YS .RE . . .PP -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. +Several features of the above example are of note. +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) +.\" TODO: Some of the normative discussion below can go there, too. . -If necessary, you can use a -.B br -request to insert a mandatory line break. . +.IP \(bu +The empty request (.), +which does nothing, +is used for vertical spacing in the input file for readability by the +document maintainer. . -.PP -Several features of the above example are of note. +Do not put empty lines in a +.I roff +source document. . . .IP \(bu The command and option names are presented in -.B boldface +.B bold to cue the user that they should be input literally. . . .IP \(bu -Option dashes are specified with the \(lq\e\-\(rq escape sequence; +Option dashes are specified with the \(oq\e\-\(cq 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. @@ -693,7 +817,7 @@ 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; +appear in the roman style; brackets surround optional arguments, and an ellipsis indicates that the previous syntactical element may be repeated arbitrarily. @@ -702,7 +826,7 @@ 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 +to indicate that one and only one of the \(oq|\(cq-separated items within the braces must be input. . If this braced construct is furthermore surrounded by square brackets, @@ -711,229 +835,511 @@ it means that at most one of the items is 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; +escape sequence \(oq\e&\(cq 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. +gets refilled in your text editor. . See \(lqPortability\(rq, below. . The morbidly curious may consult -.BR groff (7) -regarding the narrow-space escape sequence \(lq\e|\(rq. +.IR groff (7) +regarding the narrow-space escape sequence \(oq\e|\(cq. . . .\" ==================================================================== .SS "Hyperlink and email macros" .\" ==================================================================== . -The following macros are not defined on legacy Unix systems -running classic troff. +Email addresses are bracketed with +.BR .MT / .ME +and URL hyperlinks with +.BR .UR / .UE . +. +. +.PP +These macros are not defined on legacy Unix systems running classic +.IR troff . . To be certain your page will be portable to those systems, copy their definitions from the .I \%an\-ext.tmac file of a -.B groff +.I groff installation. . . -.PP -Using these macros helps ensure that you get hyperlinks when your -manual page is rendered in a browser or other program that is -Web-enabled. -. -. .TP .BI .MT " address" .TQ -.BI .ME " \fR[\fPpunctuation\fR]\fP" -Wrap an email address. -. -The argument of -.B .MT -is the address; text following, until -.BR .ME , -is a name to be associated with the address. +.BR .ME " ["\c +.IR punctuation ] +Identify +.I address +as an RFC 6068 +.I addr-spec +for a \(lqmailto:\(rq URI with the text between the two macro +calls as the link text. +. +A +.I punctuation +argument to +.B .ME +is placed at the end of the link text without intervening space. . -Any argument to the -.B ME -macro is pasted to the end of the link text. +Note that +.I address +may not be visible in the output text, +particularly if the man page is being viewed as HTML. . On a device that is not a browser, +.I address +is set in angle brackets after the link text and before +.IR punctuation . . . +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) +.IP +When rendered by +.I groff +to a TTY or PostScript output device, .RS .IP .EX -contact +Contact \&.MT fred.foonly@\e:fubar.net Fred Foonly \&.ME -for more information +for more information. .EE .RE . . .IP -usually displays like this: \[lq]contact Fred Foonly -<fred.foonly@\:fubar.net> for more information\[rq]. +displays as: \(lqContact Fred Foonly +\(lafred.foonly@\:fubar.net\(ra for more information.\(rq. . . .IP -The use of -.B \e: -to insert hyphenless breakpoints is a groff extension and can -be omitted. +The use of \(oq\e:\(cq to insert hyphenless discretionary breaks is a +.I groff +extension and can be omitted. . . +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) .TP .BI .UR " URL" .TQ -.BI .UE " \fR[\fPpunctuation\fR]\fP" -Wrap a World Wide Web hyperlink. -. -The argument to -.B .UR -is the URL; thereafter, lines until +.BR .UE " ["\c +.IR punctuation ] +Identify +.I URL +as an RFC 3986 URI hyperlink with the text between the two macro calls +as the link text. +. +A +.I punctuation +argument to .B .UE -are collected and used as the link text. +is placed at the end of the link text without intervening space. . -Any argument to the -.B UE -macro is pasted to the end of the text. +Note that +.I URL +may not be visible in the output text, +particularly if the man page is being viewed as HTML. . On a device that is not a browser, +.I URL +is set in angle brackets after the link text and before +.IR punctuation . . . +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) +.IP +When rendered by +.I groff +to a TTY or PostScript output device, .RS .IP .EX -this is a link to -\&.UR http://\e:randomsite.org/\e:fubar -some random site -\&.UE , -given as an example +The GNU Project of the Free Software Foundation hosts the +\&.UR https://\e:www.gnu.org/\e:software/\e:groff/ +Groff home page +\&.UE . .EE .RE . . .IP -usually displays like this: \[lq]this is a link to some random -site \[la]http://\:randomsite.org/\:fubar\[ra], given as an -example\[rq]. +displays as: \(lqThe GNU Project of the Free Software Foundation hosts +the Groff home page +\(lahttps://\:www.gnu.org/\:software/\:groff/\(ra.\(rq. . . .IP -The use of -.B \e: -to insert hyphenless breakpoints is a groff extension and can be -omitted. +The use of \(oq\e:\(cq to insert hyphenless discretionary breaks is a +.I groff +extension and can be omitted. . . +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) .\" ==================================================================== -.SS "Font face macros" +.SS "Font style macros" .\" ==================================================================== . +The +.I man +macro package is limited in its font styling options, +offering only +.BR bold \~( .B ), +.I italic\c +.RB \~( .I ), +and roman (the default). +. +Italic text is usually set underscored instead on terminals and other +classical +.IR nroff -style +output devices. +. +The +.B .SM +and +.B .SB +macros set text in roman or bold, respectively, at a smaller point size; +these differ visually from regular-sized roman or bold text only on +.IR troff -style +output devices. +. +The foregoing macros cause word breaks before and after their arguments, +but it is often necessary to set text in different styles without +intervening whitespace. +. +The macros +.BR .BI , +.BR .BR , +.BR .IB , +.BR .IR , +.BR .RB , +and +.BR .RI , +where \(oqB\(cq, \(oqI\(cq, and \(oqR\(cq indicate bold, italic, and +roman, respectively, +set their odd- and even-numbered arguments in alternating styles, +with no whitespace separating them. +. +. +.PP +Because font styles are presentational rather than semantic, +conflicting traditions have arisen regarding which font styles should be +used to mark file or path names, +environment variables, +in-line literals, +and even man page cross-references. +. +. +.PP The default font size and family (for .I troff output devices) is 10-point Times. . -The default face is roman. +The default style is roman. . . .TP -.BI .B " \fR[\fPtext\fR]\fP" -Causes +.BR .B \~[\c +.IR text ] +Set .I text -to appear in bold face. +in bold. +. +If the macro is given no arguments, +the text of the next input line is set in bold. +. +. +.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it) +.IP +Use bold +for literal portions of syntax synopses, +for command-line options in running text, +and for literals that are major topics of the subject under discussion; +for example, +this page uses bold for macro and register names. +. +In +.BR .EX / .EE +examples of interactive I/O (such as a shell session), +set only the user-typed input in bold. . -If no text is present on the line where the macro is called the text -of the next input line appears in bold face. . . +.\" END USAGE (TODO: move to tutorial/style guide when we have it) .TP -.BI .I " \fR[\fPtext\fR]\fP" -Causes +.BR .I \~[\c +.IR text ] +Set .I text -to appear in italic. +in italics. . -If no text is present on the line where the macro is called the text -of the next input line appears in italic. +If the macro is given no arguments, +the text of the next input line is set in italics. . . -.TP -.BI .SM " \fR[\fPtext\fR]\fP" -Causes the text on the same line or the text on the next input line to -appear in a font that is one point size smaller than the default font. +.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it) +.IP +Use italics +for file and path names, +for environment variables, +for enumeration or preprocessor constants in C, +for variable (user-determined) portions of syntax synopses, +for the first occurrence only of a technical concept being introduced, +for names of works of software +(including commands and functions, +.\" The following is an interesting exception that seems to have arisen +.\" organically and nearly universally. +but excluding names of operating systems or their kernels), +and anywhere a parameter requiring replacement by the user is +encountered. +. +An exception involves file or path names with variable components; +in such cases, +follow the convention of mathematical typography: +set the file or path name in italics as usual +(see +.B .IR +below), +but use roman for the variable part, +and italics again in running roman text when referring to the variable. +. +. +.\" END USAGE (TODO: move to tutorial/style guide when we have it) +.TP +.BR .SM \~[\c +.IR text ] +Set +.I text +one point size smaller that the default size. . +If the macro is given no arguments, +the text of the next input line is set smaller. . -.TP -.BI .SB " \fR[\fPtext\fR]\fP" -Causes the text on the same line or the text on the next input line to -appear in boldface font, one point size smaller than the default font. . +.IP +.IR Note : +.IR nroff -style +output devices, +such as terminals, +will render +.I text +at the normal font size instead. +. +Do not rely upon +.B .SM +to communicate semantic information distinct from using roman style at +the normal size; +it will be hidden from readers using such devices. . -.TP -.BI ".BI " text -Causes text on the same line to appear alternately in bold face and -italic. . -The text must be on the same line as the macro call. +.TP +.BR .SB \~[\c +.IR text ] +Set +.I text +in bold, +one point size smaller that the default size. . -Thus +If the macro is given no arguments, +the text of the next input line is set smaller and in bold. . . -.RS .IP -\&.BI this "word and" that +.IR Note : +.IR nroff -style +output devices, +such as terminals, +will render +.I text +in bold at the normal font size instead. +. +Do not rely upon +.B .SB +to communicate semantic information distinct from using bold style at +the normal size; +it will be hidden from readers using such devices. +. +. +.\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it) +.PP +Note what is +.I not +prescribed for setting in bold or italics above: +elements of \(lqsynopsis language\(rq such as ellipses and brackets +around options; +proper names and adjectives; +titles of anything other than works of literature or software; +identifiers for standards documents or technical reports such as +CSTR\~#54, +RFC\~1918, +Unicode\~11.0, +or +POSIX.1-2017; +acronyms; +and occurrences after the first of a technical term or piece of jargon. +. +Again, +the names of operating systems and their kernels are, +by practically universal convention, +set in roman. . . .PP -would cause \[oq]this\[cq] and \[oq]that\[cq] to appear in bold face, -while \[oq]word and\[cq] appears in italics. +Be frugal with the use of italics for emphasis, +and particularly with the use of bold. +. +Brief runs of literal text, +such as references to individual characters or short strings, +are suitable objects for quotation; +see the +\(oq\e(lq\(cq, +\(oq\e(rq\(cq, +\(oq\e(oq\(cq, +and +\(oq\e(cq\(cq +escapes in the subsection \(lqPortability\(rq, +below. +. +. +.\" END USAGE (TODO: move to tutorial/style guide when we have it) +.PP +Unlike the above font style macros, +the font alternation macros below accept only arguments on the same +line as the macro call. +. +If whitespace is required within one of the arguments, +first consider whether the same result could be achieved with as much +clarity by using the single-style macros on separate input lines. +. +When it cannot, +double-quote an argument with one or more embedded space characters. +. +Setting all three different styles within one whitespace-delimited word +presents challenges; +it is possible with the \(oq\ec\(cq and/or \(oq\ef\(cq escapes, +but see subsection \(lqPortability\(rq below for caveats. +. +. +.TP +.BI .BI " bold-text italic-text"\c +\~\&.\|.\|.\& +Set each argument in bold and italics, alternately. +. +. +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) +.RS +.IP +.\" from src/roff/troff/troff.1.man +.EX +\&.BI \e\-r name = n +.EE .RE . . +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) .TP -.BI ".BR " text -Causes text on the same line to appear alternately in bold face and -roman. +.BI .BR " bold-text roman-text"\c +\~\&.\|.\|.\& +Set each argument in bold and roman, alternately. . -The text must be on the same line as the macro call. +. +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) +.RS +.IP +.\" from tmac/groff_ms.7.man +.EX +Any such change becomes effective with the first use of +\&.BR .NH , +\&.I after +the new alias is defined. +.EE +.RE . . +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) .TP -.BI ".IB " text -Causes text to appear alternately in italic and bold face. +.BI .IB " italic-text bold-text"\c +\~\&.\|.\|.\& +Set each argument in italics and bold, alternately. . -The text must be on the same line as the macro call. +. +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) +.RS +.IP +.\" from man/groff_tmac.5.man +.EX +All macro package files must be named +\&.IB name .tmac +to fully use the +\&.I tmac +mechanism. +.EE +.RE . . +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) .TP -.BI ".IR " text -Causes text on the same line to appear alternately in italic and -roman. +.BI .IR " italic-text roman-text"\c +\~\&.\|.\|.\& +Set each argument in italics and roman, alternately. +. . -The text must be on the same line as the macro call. +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) +.RS +.IP +.\" from man/groff_out.5.man +.EX +This is the first command of the +\&.IR prologue . +.EE +.RE . . +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) .TP -.BI ".RB " text -Causes text on the same line to appear alternately in roman and bold -face. +.BI .RB " roman-text bold-text"\c +\~\&.\|.\|.\& +Set each argument in roman and bold, alternately. . -The text must be on the same line as the macro call. +. +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) +.RS +.IP +.\" from src/preproc/eqn/eqn.1.man +.EX +Also, the statement +\&.RB \e(oq "delim on" \e(cq +is not handled specially. +.RE +.EE . . +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) .TP -.BI ".RI " text -Causes text on the same line to appear alternately in roman and -italic. +.BI .RI " roman-text italic-text"\c +\~\&.\|.\|.\& +Set each argument in roman and italics, alternately. +. . -The text must be on the same line as the macro call. +.\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it) +.RS +.IP +.\" from contrib/mm/groff_mm.7.man +.EX +\&.RI [ file +\e&.\e|.\e|.\e&] +.EE +.RE . . +.\" END EXAMPLE (TODO: move to tutorial/style guide when we have it) .\" ==================================================================== .SS "Horizontal and vertical spacing" .\" ==================================================================== @@ -973,7 +1379,7 @@ or (2) .BR .SS , or .B .PP -or its synonyms is made; +or its synonyms is called; these clear the indent entirely. . . @@ -999,10 +1405,10 @@ is 7.2n in .I troff mode and 7n in .I nroff -mode, -except for -.BR grohtml , -which ignores indentation. +mode. +. +The HTML output device is an exception; +it ignores indentation completely. . This same indentation is used again (additively) for the defaults of .BR .IP , @@ -1032,23 +1438,29 @@ check, or which is developed in the future. . The table preprocessor -.BR tbl (1) +.IR @g@tbl (@MAN1EXT@) can likely meet your needs. . . .PP The following macros cause a line break with the insertion of vertical space: -.BR SH , -.BR SS , -.BR TP , -.BR TQ , -.B LP -.RB ( PP , -.BR P ), -.BR IP , +.BR .SH , +.BR .SS , +.BR .TP , +.BR .TQ , +.B .PP +(and its synonyms), +.BR .IP , and the deprecated -.BR HP . +.BR .HP . +. +The default inter-section and inter-paragraph spacing is 1\~line in +.I nroff +mode, +and 0.4v in +.I troff +mode. . (The deprecated macro .B .PD @@ -1056,50 +1468,64 @@ can change this vertical spacing, but its use is discouraged.) . The macros -.BR RS , -.BR RE , -.BR EX , +.BR .RS , +.BR .RE , +.BR .EX , and -.B EE +.B .EE also cause a break but no insertion of vertical space. . . .\" ==================================================================== +.SS "Number registers" +.\" ==================================================================== +. +Number registers are described in section \(lqOPTIONS\(rq, below. +. +. +.\" ==================================================================== .SS "String registers" .\" ==================================================================== . -The following strings are defined: +The following strings are defined. . . .TP .B \e*R -The \[oq]registered\[cq] sign. +expands to the character escape for the \(lqregistered sign\(rq glyph, +\(oq\e(rg\(cq, +if available, +and \(lq(Reg.)\(rq otherwise. +. . . .TP .B \e*S -Switch back to the default font size. +expands to an escape setting the font size to the document default. . . .TP -.B \e*(lq -.TQ -.B \e*(rq -Left and right quote. +.B \e*(HF +expands to the font identifier used to print headings and subheadings. . -This is equal to \[oq]\e(lq\[cq] and \[oq]\e(rq\[cq], respectively. +The default is \(oqB\(cq. . . .TP -.B \e*(HF -The typeface used to print headings and subheadings. -. -The default is \[oq]B\[cq]. +.B \e*(lq +.TQ +.B \e*(rq +expand to the character escapes for left and right double-quotation +marks, +\(oq\e(lq\(cq and \(oq\e(rq\(cq, respectively. . . .TP .B \e*(Tm -The \[oq]trademark\[cq] sign. +expands to the character escape for the \(lqtrade mark sign\(rq glyph, +\(oq\e(tm\(cq, +if available, +and \(lq(TM)\(rq otherwise. . . .\" ==================================================================== @@ -1117,7 +1543,7 @@ of a man page look like this: . .PP .RS -.BI \(aq\e"\ word +.BI "\(aq\e\(dq " word .RE . . @@ -1128,13 +1554,13 @@ and that a single space character follows the double quote. The .I word consists of one letter for each needed preprocessor: -\[oq]e\[cq] for -.BR @g@eqn , -\[oq]r\[cq] for -.BR @g@refer , +\(oqe\(cq for +.IR @g@eqn , +\(oqr\(cq for +.IR @g@refer , and -\[oq]t\[cq] for -.BR @g@tbl . +\(oqt\(cq for +.IR @g@tbl . . Modern implementations of the .I man @@ -1162,49 +1588,51 @@ output devices are extremely limited in presentation of mathematical equations. . . +.\" TODO BEGIN: move subsection to tutorial/style guide when we have it .\" ==================================================================== .SS Portability .\" ==================================================================== . -Since the -.B man -macros consist of groups of -.I groff -requests, one can, in principle, supplement the functionality of the -.B man -macros with individual -.I groff -requests where necessary. +The two major syntactical categories of +.I roff +languages are requests and escapes. . -See the +Since the +.I man +macros are implemented in terms of .I groff -info pages for a complete reference of all requests. +requests and escapes, +one can, +in principle, +supplement the functionality of +.I man +with these lower-level elements where necessary. . . .PP -Note, however, that using raw troff requests is likely to make your -page render poorly on the class of viewers that transform it to HTML. +Note, +however, +that using raw +.I groff +requests is likely to make your page render poorly on the class of +viewers that transform it to HTML. . -Troff requests make implicit assumptions about things like character -and page sizes that may break in an HTML environment; also, many of -these viewers don't interpret the full troff vocabulary, a problem -that can lead to portions of your text being silently dropped. +Some requests make implicit assumptions about things like character +and page sizes that may not hold in an HTML environment; +also, +many of these viewers don't interpret the full +.I groff +vocabulary, +a problem that can lead to portions of your text being silently dropped. . . .PP -For portability to modern viewers, it is best to write your page -entirely in the requests described on this page. -. -Further, it is best to completely avoid those we have described as -\[oq]presentation-level\[cq] -.RB ( .HP , -.BR .PD , -and -.BR .DT ) -in \(lqDeprecated features\(rq, below. -. +For portability to modern viewers, +it is best to write your page entirely with the macros described in this +page +(except for the ones identified as deprecated, +which should be avoided entirely). . -.PP The macros we have described as extensions .RB ( .EX / .EE , .BR .SY / .OP / .YS , @@ -1214,43 +1642,63 @@ and should be used with caution, as they may not yet be built in to some viewer that is important to your audience. . -If in doubt, copy the implementation onto your page. +If in doubt, copy the implementation into your page\(emafter the +.B .TH +call and the \(lqName\(rq section, +to accommodate timid +.I mandb +implementations. . . .PP -In a way similar to using -.I groff -requests, it is possible to use the facilities documented in the -ESCAPE SEQUENCES section of the -.BR groff (7) -manual page and in the -.BR groff_char (7) -manual page. -. -Regarding portability, similar caveats apply as with respect to -.I groff -requests. +Similar caveats apply to escapes. . Some escape sequences are however required for correct typesetting -even in manual pages and usually do not cause portability problems: +even in man pages and usually do not cause portability problems: +. . .TP -.RB \(dq \e\ \(dq -Unpaddable non-breaking space character. +.B \e\(dq +Comment. +. +Everything after the double-quote to the end of the input line is +ignored. . -(The double-quotes are to make the presence of the space character -clear in this document, and are not necessary in the input file.) +Whole-line comments are frequently placed immediately after the empty +request \(oq.\(cq. +. +. +.TP +.BI \e newline +Join the next input line to the current one. +. +Except for the update of the input line counter (used for diagnostic +messages and related purposes), +a series of lines ending in backslash-newline is transparent to +.IR groff . +. +Use this escape to break excessively input long lines for document +maintenance. +. +. +.TP +.B \e\(ti +Adjustable, non-breaking space character. +. +Use this escape to prevent a break inside a short phrase or between a +numerical quantity and its corresponding unit(s). . -Useful for preventing breaking between a numerical quantity and its -corresponding unit(s), for instance: . .RS .IP .EX -There are 2.54\e\ cm in an inch, and 1,024\e\ bytes in 1\e\ kiB. +Before starting the motor, set the output speed to\e\(ti1. +There are 1,024\e\(tibytes in 1\e\(tikiB. +CSTR\e\(ti#8 documents the B language. .EE .RE . +. .TP .B \e& Zero-width space. @@ -1262,14 +1710,16 @@ beginning of a .I roff request. . +. .TP .B \e(aq ASCII apostrophe. . -Useful for syntax elements of programming languages because some +Use for syntax elements of programming languages because some output devices might replace unescaped apostrophes with right single quotation marks. . +. .TP .B \e(oq Opening single quotation mark. @@ -1278,17 +1728,20 @@ Opening single quotation mark. .B \e(cq Closing single quotation mark. . +. .IP Use these for paired directional single quotes, \(oqlike this\(cq. . +. .TP .B \e(dq ASCII double-quote. . -Sometimes needed on macro lines to prevent the interpretation of the +Sometimes needed after macro calls to prevent the interpretation of the ASCII quotation mark character \(oq\(dq\(cq as the beginning or end of a macro argument. . +. .TP .B \e(lq Left double quotation mark. @@ -1297,58 +1750,67 @@ Left double quotation mark. .B \e(rq Right double quotation mark. . +. .IP Use these for paired directional double quotes, \(lqlike this\(rq. . +. .TP .B \e(em Em-dash. . -Used as a punctuation mark for an interruption in a sentence\(emlike -in this one. +Use for an interruption in a sentence\(emsuch as this one. +. . .TP .B \e(en En-dash. . -Used to separate the two ends of a range, in particular between -numbers, for example: the digits 1\(en9. +Use to separate the two ends of a range, +in particular between numbers, +for example: the digits 1\(en9. +. . .TP .B \e(ga ASCII grave accent. . -Useful for syntax elements of programming languages, for example -shell command substitutions, because some output devices might -replace unescaped grave accents with left single quotation marks. +Use for syntax elements of programming languages, +for example shell command substitutions, +because some output devices might replace unescaped grave accents with +left single quotation marks. +. . .TP .B \e(ha ASCII circumflex accent. . -Useful for syntax elements of programming languages because some -output devices might replace unescaped circumflex accents with -non-ASCII glyphs like the Unicode U+02C6 modifier letter circumflex. +Use for syntax elements of programming languages because some output +devices might replace unescaped circumflex accents with non-ASCII glyphs +like the Unicode U+02C6 modifier letter circumflex. +. . .TP .B \e(ti ASCII tilde. . -Useful for syntax elements of programming languages because some -output devices might replace unescaped tildes with non-ASCII glyphs -like the Unicode U+02DC small tilde. +Use for syntax elements of programming languages because some output +devices might replace unescaped tildes with non-ASCII glyphs like the +Unicode U+02DC small tilde. +. . .TP -.B \e- +.B \e\- Minus sign. . Also use this to display syntax elements that require the ASCII -hyphen-minus character, for example command-line options and C -language operators. +hyphen-minus character, +for example command-line options and C language operators. . The unescaped \(oq\-\(cq input character is not appropriate for these cases because it may render as a hyphen on some output devices. . +. .TP .B \ec . @@ -1357,30 +1819,33 @@ space is inserted between the last glyph on it and the first glyph resulting from the next input line. . This is occasionally useful when three different fonts are needed -in a single word, for example: +in a single word. +. . .RS .IP +.\" contrib/pdfmark/pdfroff.1.man .EX -\&.BR "dd if" =\ec -\&.I file +Normally, the final output file should be named +\&.IB file .pdf\ec +\e&. .EE .RE . +. .IP Note that when using this trick with the .B .BI or .B .RI macros, you will need to manually add an italic correction escape -.B \e/ -before the -.B \ec -due to way macros expand their arguments. +\(oq\e/\(cq before the \(oq\ec\(cq due to way macros expand their +arguments. . . .RS .IP +.\" from contrib/mom/groff_mom.7.man .EX Files processed with \&.B groff \e\-mom @@ -1392,16 +1857,15 @@ Files processed with . . .IP -Alternatively, and perhaps with better portability, the -.B \ef -font escape sequence can be used; see below. +Alternatively, +and perhaps with better portability, +the \(oq\ef\(cq font escape sequence can be used; +see below. . -Attempting to use -.B \ec -to include the output from more than one macro line into the next-line -argument of a +Using \(oq\ec\(cq to include the output from more than one input line +into the next-line argument of a .B .TP -macro will misrender with +macro will render incorrectly with .I groff 1.22.3, .I mandoc @@ -1409,45 +1873,46 @@ macro will misrender with older versions of these programs, and perhaps with some other formatters. . +. .TP .B \ee -Widely used in manual pages to represent a backslash output glyph. +Widely used in man pages to represent a backslash output glyph. . It works reliably as long as the .B .ec -request is not used, which should never happen in manual pages, and -it is slightly more portable than the more exact -.B \e(rs -(\[lq]reverse solidus\[rq]) -escape sequence. +request is not used, +which should never happen in man pages, +and it is slightly more portable than the more exact \(oq\e(rs\(cq +(\(lqreverse solidus\(rq) escape sequence. +. . .TP .BR \efB ,\ \efI ,\ \efR ,\ \efP Switch to bold, italic, roman, or back to the previous font, respectively. . -This is needed when three different fonts are required on a single -input line, for example: +Either these or \(oq\ec\(cq is needed when three different fonts are +required in a single whitespace-delimited word. +. . .RS .IP +.\" second example from contrib/pdfmark/pdfroff.1.man .EX -\&.TP -\efBif\efP=\efIfile\efP +\&.RB [ \e\-\e\-reference\e\-dictionary=\efI\e,name\e/\efP ] +.IP +\&.RB [ \e\-\e\-reference\e\-dictionary=\ec +\&.IR name ] .EE .RE . +. .IP -It can also be used if three different fonts are needed in a -single word. -It may be more portable than -.BR \ec . +Font escapes may be more portable than \(oq\ec\(cq. . -It is up to you to account for italic corrections with -.B \e/ -and -.BR \e, , -which are themselves +As shown above, +it is up to you to account for italic corrections with \(oq\e/\(cq and +\(oq\e,\(cq, which are themselves .I groff extensions, if desired and if supported by your implementation. @@ -1456,16 +1921,17 @@ if desired and if supported by your implementation. .IP As long as at most two fonts are needed in any one whitespace-delimited word, -using font alternation macros like +font alternation macros like .B .BR -usually results in more readable source code. +usually result in more readable source code than \(oq\ef\(cq escapes. . . .PP For maximum portability, escape sequences and special characters -not listed above are better avoided in manual pages. +not listed above are better avoided in man pages. . . +.\" TODO END: move subsection to tutorial/style guide when we have it .\" ==================================================================== .SS "Deprecated features" .\" ==================================================================== @@ -1474,19 +1940,53 @@ Use of the following is discouraged. . . .TP -.BI .AT " \fR[\fPsystem \fR[\fPrelease\fR]]\fP" -Alter the footer for use with AT&T man pages. +.BR .AT " ["\c +.IR system "] [" release ] +Alter the footer for use with AT&T man pages, +overriding any definition of the +.I footer-outside +argument to +.BR .TH . . This macro exists only for compatibility; don't use it. . -See the -.I groff -info manual for more. +. +.IP +The first argument +.I system +can be: +. +. +.RS \" Invisibly move left margin to current .IP indent. +.RS \" Now indent further, visibly. +.TP +3 +7th edition +.I (default) +. +. +.TP +4 +System III +. +. +.TP +5 +System V +.RE \" Move left margin back to .IP indentation. +.RE \" Move left margin back to standard position. +. +. +.IP +The optional second argument +.I release +specifies the release number, +such as in \(lqSystem V Release 3\(rq. . . .TP .B .BT -Print the footer string. +Set the page footer. . Redefine this macro to get control of the footer. . @@ -1496,7 +1996,7 @@ Redefine this macro to get control of the footer. Set tabs every 0.5\~inches. . Since this macro is always called during a -.B TH +.B .TH macro, it makes sense to call it only if the tab positions have been changed. . @@ -1513,44 +2013,21 @@ to express are likely to be lost. . If you feel tempted to use it, you should probably be composing a table using -.BR @g@tbl (@MAN1EXT@) +.IR @g@tbl (@MAN1EXT@) markup instead. . . .TP -.BI .HP " \fR[\fPnnn\fR]\fP" -Set up a paragraph with hanging left indentation. +.BR .HP " ["\c +.IR indent ] +Set up a paragraph with a hanging left indentation. . -The indentation is set to -.I nnn -if that argument is supplied (the default unit is \[oq]n\[cq] if -omitted), otherwise it is set to the previous indentation value -specified with -.BR .TP , -.BR .IP , -or -.B .HP -(or to the default value if none of them have been used yet). -. -Font size and face are reset to its default values. -. -The following paragraph illustrates the effect of this macro with -hanging indentation set to\~4 (enclosed by -.B .RS -and -.B .RE -to set the left margin temporarily to the current indentation): -. -. -.RS -.HP 4 -This is a paragraph following an invocation of the -.B HP -macro. -. -As you can see, it produces a paragraph where all lines but the first -are indented. -.RE +The +.I indent +argument, +if present, +is handled as with +.BR .TP . . . .IP @@ -1566,25 +2043,18 @@ indentation may be lost. . . .TP -.BI .PD " \fR[\fPnnn\fR]\fP" -Adjust the empty space before a new paragraph or section. +.BR .PD " ["\c +.IR vertical-space ] +Define the vertical space between paragraphs or (sub)sections. . -The optional argument gives the amount of space (default unit is -\[oq]v\[cq]); without parameter, the value is reset to its default -value (1\~line in nroff mode, 0.4v\~otherwise). +The optional argument +.I vertical-space +specifies the amount of space; +the default scaling is \(oqv\(cq). . -This affects the macros -.BR SH , -.BR SS , -.BR TP , -.B LP -(resp.\& -.B PP -and -.BR P ), -.BR IP , -and -.BR HP . +Without an argument, +the spacing is reset to its default value; +see \(lqHorizontal and vertical spacing\(rq above. . . .IP @@ -1600,61 +2070,135 @@ to express are likely to be lost. . .TP .B .PT -Print the header string. +Set the page header. . Redefine this macro to get control of the header. . . .TP -.BI .UC " \fR[\fPversion\fR]\fP" -Alter the footer for use with BSD man pages. +.BR .UC " ["\c +.IR version ] +Alter the footer for use with BSD man pages, +overriding any definition of the +.I footer-outside +argument to +.BR .TH . . This macro exists only for compatibility; don't use it. . -See the -.I groff -info manual for more. +. +.IP +The argument +.I version +can be: . . +.RS \" Invisibly move left margin to current .IP indent. +.RS \" Now indent further, visibly. +.TP +3 +3rd Berkeley Distribution +.I (default) +. +. +.TP +4 +4th Berkeley Distribution +. +. +.TP +5 +4.2 Berkeley Distribution +. +. +.TP +6 +4.3 Berkeley Distribution +. +. +.TP +7 +4.4 Berkeley Distribution +.RE \" Move left margin back to .IP indentation. +.RE \" Move left margin back to standard position. +. +. +.\" ==================================================================== +.SS "History" +.\" ==================================================================== +. +According to its own +.IR man (7) +page, +Version 7 Unix (1979) supported all of the macros described in this page +not listed as GNU extensions, +except +.BR .P , +.BR .SB , +.BR .SS , +and the deprecated +.BR .AT , +.BR .BT , +.BR .PT , +and +.BR .UC . +. +The only string registers defined were +.B R +and +.BR S; +no number registers were documented. . . .\" ==================================================================== .SH OPTIONS .\" ==================================================================== . -The -.B man -macros understand the following command-line options (which define -various registers). +The following +.I groff +options set number registers recognized and used by the +.I man +macro package. . . .TP .B \-rcR=1 -This option (the default if in nroff mode) creates a single, very -long page instead of multiple pages. +Continuous rendering. +. +Create a single, +very long page instead of multiple pages. +. +This is the default in +.I nroff +mode. . -Say +Use .B \-rcR=0 to disable it. . . .TP .B \-rC1 -If more than one manual page is given on the command line, number the +Number pages continuously. +. +If more than one man page is given on the command line, number the pages continuously, rather than starting each at\~1. . . .TP .B \-rD1 -Double-sided printing. +Enable double-sided printing. . Footers for even and odd pages are formatted differently. . . .TP -.BI \-rFT= dist -Set distance of the footer relative to the bottom of the page if -negative or relative to the top if positive. +.BI \-rFT= footer-distance +Set distance of the footer, +relative to the bottom of the page if negative or relative to the top if +positive, +to +.IR footer-distance . . The default is \-0.5i. . @@ -1663,14 +2207,18 @@ The default is \-0.5i. .BI \-rHY= flags Set hyphenation flags. . -Possible values are 1\~to not hyphenate the first and last character -of a word, 2\~to not hyphenate the last word on a page, 4\~to not -hyphenate the last two characters of a word, 8\~to not hyphenate the -first two characters of a word, 16\~to enable hyphenation before the -last character of a word, and 32 to enable hyphenation after the -first character of a word. +Possible values of +.I flags +are 1\~to not hyphenate the first and last character of a word, +2\~to not hyphenate the last word on a page, +4\~to not hyphenate the last two characters of a word, +8\~to not hyphenate the first two characters of a word, +16\~to enable hyphenation before the last character of a word, +and +32\~to enable hyphenation after the first character of a word. . -These values are additive; the default is\~6. +These values are additive; +the default is\~6. . Values 4 and\~16 can't be used together since they contradict each other; @@ -1678,19 +2226,18 @@ the same holds for values 8 and\~32. . . .TP -.BI \-rIN= width -Set body text indentation to -.IR width . +.BI \-rIN= indent +Set the body text indentation (for normal paragraphs) to +.IR indent . . -The default is 7n for -.IR nroff , -7.2n for -.IR troff . +See \(lqHorizontal and vertical spacing\(rq above for the default +indentation value. . For .IR nroff , -this value should always be an integer multiple of unit \[oq]n\[cq] to -get consistent indentation. +.I indent +should always be an integer multiple of unit \(oqn\(cq to get consistent +indentation. . . .TP @@ -1698,10 +2245,12 @@ get consistent indentation. Set line length. . If this option is not given, the line length is set to respect any -value set by a prior \[oq].ll\[cq] request (which +value set by a prior \(lq.ll\(rq request (which .I must -be in effect when the \[oq].TH\[cq] macro is invoked), -if this differs from the built\-in default for the formatter; +be in effect when the +.B .TH +macro is invoked), +if this differs from the built-in default for the formatter; otherwise it defaults to 78n in .I nroff mode and 6.5i in @@ -1710,25 +2259,29 @@ mode. . . .IP -Note that the use of a \[oq].ll\[cq] request to initialize the line +Note that the use of a \(lq.ll\(rq request to initialize the line length is supported for backward compatibility with some versions of the -.B man +.I man program; -direct initialization of the \[oq]LL\[cq] register should +direct initialization of the +.B LL +register should .I always be preferred to the use of such a request. . -In particular, note that a \[oq].ll\ 65n\[cq] request does +In particular, note that a \(lq.ll\~65n\(rq request does .I not preserve the normal .I nroff default line length, (the -.B man -default initialization to 78n prevails), whereas, the -\[oq]\-rLL=65n\[cq] option, or an equivalent \[oq].nr\ LL\ 65n\[cq] -request preceding the use of the \[oq]TH\[cq] macro, +.I man +default initialization to 78n prevails), +whereas the \(lq\-rLL=65n\(rq option, +or an equivalent \(lq.nr\~LL\~65n\(rq request preceding the use of the +.B .TH +macro, .I does set a line length of 65n. . @@ -1742,40 +2295,44 @@ length. . . .TP -.BI \-rP nnn -Enumeration of pages start with -.I nnn -rather than with\~1. +.BI \-rP n +Start enumeration of pages at +.I n +rather than\~1. . . .TP -.BI \-rS xx -Base document font size is -.I xx -points -.RI ( xx -can be 10, 11, or\~12) rather than 10\~points. +.BI \-rS point-size +Use +.I point-size +as the base document font size. +. +Acceptable values are 10, 11, or 12. +. +See subsection \(lqFont style macros\(rq above for the default. . . .TP -.BI \-rSN= width -Set sub-subheading indentation to -.IR width . -The default is 3n. +.BI \-rSN= subsection-indent +Set subsection indentation to +.IR subsection-indent . +. +See \(lqHorizontal and vertical spacing\(rq above for the default +indentation value. . . .TP -.BI \-rX nnn -After page\~\c -.IR nnn , +.BI \-rX p +After +.RI page " p" , number pages as -.IR nnn a, -.IR nnn b, -.IR nnn c, -etc. +.IR p a, +.IR p b, +.IR p c, +and so forth. . -For example, the option \[oq]\-rX2\[cq] produces the following page -numbers: 1, 2, 2a, 2b, 2c, etc. +For example, the option \(lq\-rX2\(rq produces the following page +numbers: 1, 2, 2a, 2b, 2c, and so on. . . .\" ==================================================================== @@ -1897,7 +2454,10 @@ and the deprecated .BR .HP . . If you need to start an indent relative to an indented paragraph, -give +call +.B .RS +repeatedly until an acceptable indentation is achieved, +or give .B .RS an indentation argument that is at least as much as the paragraph's indentation amount relative to an adjacent @@ -1959,6 +2519,7 @@ have no effect. .\" ==================================================================== .SH AUTHORS .\" ==================================================================== +. The GNU version of the .I man macro package was written by James Clark and contributors. @@ -1979,21 +2540,52 @@ This document was originally written for the Debian GNU/Linux system by Susan G.\& Kleinmann .ME . . -It was corrected and updated by Werner Lemberg. +It was corrected and updated by Werner Lemberg and G.\& Branden +Robinson. . The extension macros were documented by Eric S.\& Raymond; -he also originated the portability advice. +he also originated the portability section, +to which Ingo Schwarze contributed most of the material on escape +sequences. . . .\" ==================================================================== .SH "SEE ALSO" .\" ==================================================================== -.BR @g@tbl (@MAN1EXT@), -.BR @g@eqn (@MAN1EXT@), -.BR @g@refer (@MAN1EXT@), -.BR man (1), -.BR man (7), -.BR groff_mdoc (7) +. +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the main +.I groff +documentation. +. +You can browse it interactively with \(lqinfo groff\(rq. +. +. +.PP +.IR @g@tbl (@MAN1EXT@), +.IR @g@eqn (@MAN1EXT@), +and +.IR @g@refer (@MAN1EXT@) +are preprocessors used with man pages. +. +. +.PP +.IR man (1) +describes the man page formatter on your system. +. +. +.PP +.IR groff_mdoc (@MAN7EXT@) +describes the +.I groff +version of the BSD-originated alternative macro package for man pages. +. +. +.PP +.IR groff (@MAN7EXT@), +.IR groff_char (@MAN7EXT@), +.IR man (7) . . .\" Restore compatibility mode (for, e.g., Solaris 10/11). @@ -2004,5 +2596,6 @@ he also originated the portability advice. .\" ### Emacs settings: .\" Local Variables: .\" mode: nroff +.\" fill-column: 72 .\" End: -.\" vim: set filetype=groff: +.\" vim: set filetype=groff textwidth=72:
signature.asc
Description: PGP signature