diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man7/groff_man.7')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man7/groff_man.7 | 2146 |
1 files changed, 2146 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man7/groff_man.7 b/upstream/opensuse-tumbleweed/man7/groff_man.7 new file mode 100644 index 00000000..2c31d289 --- /dev/null +++ b/upstream/opensuse-tumbleweed/man7/groff_man.7 @@ -0,0 +1,2146 @@ +'\" t +.\" This page is generated by m4 from tmac/groff_man.7.man.in. +.TH groff_man 7 "4 October 2023" "groff 1.23.0" +.SH Name +groff_man \- compose manual pages with GNU +.I roff +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1999-2018, 2020-2021 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 +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_man_7_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY "groff \-man" +.RI [ option\~ .\|.\|.\&] +.RI [ file\~ .\|.\|.] +. +.SY "groff \-m man" +.RI [ option\~ .\|.\|.\&] +.RI [ file\~ .\|.\|.] +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The GNU implementation of the +.I man +macro package is part of the +.I groff +document formatting system. +. +It is used to produce manual pages +.\" We use an unbreakable space \~ here to keep the phrase intact for +.\" its introduction; in subsequent discussion, that is not important. +(\(lqman\~pages\(rq) +like the one you are reading. +. +. +.P +This document presents the macros thematically; +for those needing only a quick reference, +the following table lists them alphabetically, +with cross references to appropriate subsections below. +. +. +.P +Man page authors and maintainers who are not already experienced +.I groff +users should consult +.MR groff_man_style 7 , +an expanded version of this document, +for additional explanations and advice. +. +It covers only those concepts required for man page document +maintenance, +and not the full breadth of the +.I groff +typesetting system. +. +. +.P +.TS +l l l. +Macro Meaning Subsection +.T& +lB l l. +_ +\&.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 style macros +\&.IB Italic, bold alternating Font style macros +\&.IP Indented paragraph Paragraphing macros +\&.IR Italic, roman alternating Font style macros +\&.LP Begin paragraph Paragraphing macros +\&.ME Mail-to end Hyperlink macros +\&.MR Man page cross reference Hyperlink macros +\&.MT Mail-to start Hyperlink macros +\&.P Begin paragraph Paragraphing macros +\&.PP Begin paragraph Paragraphing macros +\&.RB Roman, bold alternating Font style macros +\&.RE Relative inset end Document structure macros +\&.RI Roman, italic alternating Font style macros +\&.RS Relative inset start Document structure macros +\&.SB Small bold Font style macros +\&.SH Section heading Document structure macros +\&.SM Small Font style macros +\&.SS Subsection heading Document structure macros +\&.SY Synopsis start Command 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 +.TE +. +. +.P +We discuss other macros +.RB ( .AT , +.BR .DT , +.BR .HP , +.BR .OP , +.BR .PD , +and +.BR .UC ) +in subsection \(lqDeprecated features\(rq below. +. +. +.P +Throughout Unix documentation, +a manual entry is referred to simply as a \(lqman page\(rq, +regardless of its length, +without gendered implication, +and irrespective of the macro package selected for its composition. +. +. +.br +.ne 6v +.\" ==================================================================== +.SS "Macro reference preliminaries" +.\" ==================================================================== +. +A tagged paragraph describes each macro. +. +We present coupled pairs together, +as with +.B .EX +and +.BR .EE . +. +. +.br +.ne 2v +.P +An empty macro argument can be specified with a pair of double-quotes +(""), +but the +.I man +package is designed such that this should seldom be necessary. +. +Most macro arguments will be formatted as text in the output; +exceptions are noted. +. +. +.\" ==================================================================== +.SS "Document structure macros" +.\" ==================================================================== +. +Document structure macros organize a man page's content. +. +All of them break the output line. +. +.B .TH +(title heading) +identifies the document as a man page and configures the page headers +and footers. +. +Section headings +.RB ( .SH ), +one of which is mandatory and many of which are conventionally expected, +facilitate location of material by the reader and aid the man page +writer to discuss all essential aspects of the topic. +. +Subsection headings +.RB ( .SS ) +are optional and permit sections that grow long to develop in a +controlled way. +. +Many technical discussions benefit from examples; +lengthy ones, +especially those reflecting multiple lines of input to or output from +the system, +are usefully bracketed by +.B .EX +and +.BR .EE . +. +When none of the foregoing meets a structural demand, +use +.BR .RS / .RE +to inset a region within a (sub)section. +. +. +.TP +.BI .TH " topic section"\c +.RI " [" footer-middle ]\c +.RI " [" footer-inside ]\c +.RI " [" header-middle ] +Determine the contents of the page header and footer. +. +The subject of the man page is +.I topic +and the section of the manual to which it belongs is +.I section. +. +See +.MR man 1 +or +.MR intro 1 +for the manual sectioning applicable to your system. +. +.I topic +and +.I section +are positioned together at the left and right in the header +(with +.I section +in parentheses immediately appended to +.IR topic ). +. +.I footer-middle +is centered in the footer. +. +The arrangement of the rest of the footer depends on whether +double-sided layout is enabled with the option +.BR \-rD1 . +. +When disabled (the default), +.I footer-inside +is positioned at the bottom left. +. +Otherwise, +.I footer-inside +appears at the bottom left on recto (odd-numbered) pages, +and at the bottom right on verso (even-numbered) pages. +. +The outside footer is the page number, +except in the continuous-rendering mode enabled by the option +.BR \-rcR=1 , +in which case it is the +.I topic +and +.I section, +as in the header. +. +.I header-middle +is centered in the header. +. +If +.I section +is an integer between 1 and\~9 (inclusive), +there is no need to specify +.I header-middle; +.I an.tmac +will supply text for it. +. +The macro package may also abbreviate +.I topic +and +.I footer-inside +with ellipses +if they would overrun the space available in the header and footer, +respectively. +. +For HTML output, +headers and footers are suppressed. +. +. +.IP +Additionally, +this macro breaks the page, +resetting the number to\~1 +(unless the +.B \-rC1 +option is given). +. +This feature is intended only for formatting multiple +.I man +documents in sequence. +. +. +.IP +A valid +.I man +document calls +.B .TH +once, +early in the file, +prior to any other macro calls. +. +. +.TP +.BR .SH " ["\c +.IR heading-text ] +Set +.I heading-text +as a section heading. +. +If no argument is given, +a one-line input trap is planted; +text on the next line +.\", which can be formatted with a macro, \" true but discouraged +becomes +.I heading-text. +. +The left margin is reset to zero to set the heading text in bold +(or the font specified by the string +.BR HF ), +and, +on typesetting devices, +slightly larger than the base type size. +. +If the heading font +.B \[rs]*[HF] +is bold, +use of an italic style in +.I heading-text +is mapped to the bold-italic style if available in the font family. +. +The inset level is reset to 1, +setting the left margin to the value of the +.B IN \" TODO: future: BP or BI register ("base paragraph indentation") +register. +. +Text after +.I heading-text +is set as an ordinary paragraph +.RB ( .P ). +. +. +.IP +The content of +.I heading-text +and ordering of sections follows a set of common practices, +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 text of the form +.RS \" Invisibly move left margin to current .IP indentation. +.RS \" Now indent further, visibly. +.IR topic [\c +.BI , " another-topic"\c +.RB "].\|.\|.\& \e\- "\c +.I summary-description +.RE \" Move left margin back to .IP indentation. +for a man page to be properly indexed. +. +See +.MR groff_man_style 7 +for suggestions and +.MR 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 between a section heading and an +ordinary paragraph +.RB ( .P ). +. +If no argument is given, +a one-line input trap is planted; +text on the next line +.\", which can be formatted with a macro, \" true but discouraged +becomes +.I subheading-text. +. +The left margin is reset to the value of the +.B SN +register to set the heading text in bold +(or the font specified by the string +.BR HF ). +. +If the heading font +.B \[rs]*[HF] +is bold, +use of an italic style in +.I subheading-text +is mapped to the bold-italic style if available in the font family. +. +The inset level is reset to 1, +setting the left margin to the value of the +.B IN \" TODO: future: BP or BI register ("base paragraph indentation") +register. +. +Text after +.I subheading-text +is set as an ordinary paragraph +.RB ( .P ). +. +. +.TP +.B .EX +.TQ +.B .EE +Begin and end example. +. +After +.BR .EX , +filling is disabled and a constant-width (monospaced) font is selected. +. +Calling +.B .EE +enables filling and restores the previous font. +. +. +.IP +.\" Also see subsection "History" below... +These macros are extensions introduced in Ninth Edition Research Unix. +. +Systems running that +.IR troff , \" AT&T Research Unix +or those from +Documenter's Workbench, +Heirloom Doctools, +or Plan\~9 +.I troff +support them. +.\" Solaris 10 troff does not support .EX/.EE. Neatroff doesn't ship +.\" (m)an macros. +. +To be certain your page will be portable to systems that do not, +copy their definitions from the +.I \%an\-ext.tmac +file of a +.I groff +installation. +. +. +.TP +.BR .RS " ["\c +.IR inset-amount ] +Start a new relative inset level. +. +The position of the left margin is saved, +then moved right by +.I inset-amount, +if specified, +and by the amount of the +.B IN +register otherwise. +. +Calls to +.B .RS +can be nested; +each increments by\~1 +the inset level used by +.BR .RE . +. +The level prior to any +.B .RS +calls is\~1. +. +. +.TP +.BR .RE " ["\c +.IR level ] +End a relative inset. +. +The left margin corresponding to inset level +.I level +is restored. +. +If no argument is given, +the inset level is reduced by\~1. +. +. +.\" ==================================================================== +.SS "Paragraphing macros" +.\" ==================================================================== +. +An ordinary paragraph +.RB ( .P ) +is set without a first-line indentation at the current left margin. +. +In man pages and other technical literature, +definition lists are frequently encountered; +these can be set as \(lqtagged paragraphs\(rq, +which have one +.RB ( .TP ) +or more +.RB ( .TQ ) +leading tags followed by a paragraph that has an additional indentation. +. +The indented paragraph +.RB ( .IP ) +macro is useful to continue the indented content of a narrative started +with +.BR .TP , +or to present an itemized or ordered list. +. +All of these macros break the output line. +. +If another paragraph macro has occurred since the previous +.B .SH +or +.BR .SS , +they +(except for +.BR .TQ ) +follow the break with a default amount of vertical space, +which can be changed by the deprecated +.B .PD +macro; +see subsection \(lqHorizontal and vertical spacing\(rq below. +. +They also reset the type size and font style to defaults +.RB ( .TQ +again excepted); +see subsection \(lqFont style macros\(rq below. +. +. +.br +.ne 4v +.TP +.B .P +.TQ +.B .LP +.TQ +.B .PP +Begin a new paragraph; +these macros are synonymous. +. +The indentation is reset to the default value; +the left margin, +as affected by +.B .RS +and +.BR .RE , +is not. +. +. +.TP +.BR .TP " ["\c +.IR indentation ] +Set a paragraph with a leading tag, +and the remainder of the paragraph indented. +. +A one-line input trap is planted; +text on the next line, +which can be formatted with a macro, +becomes the tag, +which is placed at the current left margin. +. +The tag can be extended with the +.B \(rsc +escape sequence. +. +Subsequent text is indented by +.I indentation, +if specified, +and by the amount of the +.B IN +register otherwise. +. +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. +. +Otherwise, +the descriptive part of the paragraph begins on the line following the +tag. +. +. +.TP +.B .TQ +Set an additional tag for a paragraph tagged with +.BR .TP . +. +An input trap is planted as with +.BR .TP . +. +. +.IP +This macro is a GNU extension not defined on systems running +AT&T, +Plan\~9, +or +Solaris +.IR troff ; +see +.I \%an\-ext.tmac +in section \(lqFiles\(rq below. +. +. +.TP +.BR .IP " ["\c +.IR tag "] "\c +.RI [ indentation ] +Set an indented paragraph with an optional tag. +. +The +.I tag +and +.I indentation +arguments, +if present, +are handled as with +.BR .TP , +with the exception that the +.I tag +argument to +.B .IP +cannot include a macro call. +. +. +.\" ==================================================================== +.SS "Command synopsis macros" +.\" ==================================================================== +. +.B .SY +and +.B .YS +aid you to construct a command synopsis that has the classical Unix +appearance. +. +They 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 +.\" them appropriately for localization and/or presentation. +. +. +.P +These macros are GNU extensions not defined on systems running +AT&T, +Plan\~9, +or +Solaris +.IR troff ; +see +.I \%an\-ext.tmac +in section \(lqFiles\(rq below. +. +. +.TP +.BI .SY " command" +Begin synopsis. +. +A new paragraph begins at the left margin +unless +.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. +. +.I command +is set in bold. +. +If a break is required, +lines after the first are indented by the width of +.I command +plus a space. +. +. +.TP +.B .YS +End synopsis. +. +Indentation, +adjustment, +and hyphenation +are restored to their previous states. +. +. +.\" ==================================================================== +.SS "Hyperlink macros" +.\" ==================================================================== +. +Man page cross references +are best presented with +.BR .MR . +. +Text may be hyperlinked to email addresses with +.BR .MT / .ME +or other URIs with +.BR .UR / .UE . +. +Hyperlinked text is supported on HTML +.\", PDF, +and terminal output devices; +terminals and pager programs must support ECMA-48 OSC\~8 escape +sequences +(see +.MR grotty 1 ). +. +When device support is unavailable or disabled with the +.B U +register +(see section \[lq]Options\[rq] below), +.B .MT +and +.B .UR +URIs are rendered between angle brackets after the linked text. +. +. +.P +.BR .MT , +.BR .ME , +.BR .UR , +and +.B .UE +are GNU extensions not defined on systems running +AT&T, +Plan\~9, +or +Solaris +.IR troff ; \" Solaris +see +.I \%an\-ext.tmac +in section \(lqFiles\(rq below. +. +Plan\~9 from User Space's +.I troff \" plan9port +implements +.BR .MR . +. +. +.P +The arguments to +.BR .MR , +.BR .MT , +and +.B .UR +should be prepared for typesetting since they can appear in the +output. +. +Use special character escape sequences to encode Unicode basic Latin +characters where necessary, +particularly the hyphen-minus. +The formatter removes +.B \e: +escape sequences from hyperlinks when supplying device control commands +to output drivers. +. +. +.TP +.BI .MR "\~topic manual-section"\c +.RI \~[ trailing-text ] +.IR (since\~ groff \~1.23) \" TODO: remove note once novelty dies down +Set a man page cross reference as +\[lq]\c +.IB topic ( manual-section )\c +\[rq]. +. +If +.I trailing-text +(typically punctuation) +is specified, +it follows the closing parenthesis without intervening space. +. +Hyphenation is disabled while the cross reference is set. +. +.I topic +is set in the font specified by the +.B MF +string. +. +The cross reference hyperlinks to a URI of the form +.RB \[lq] man:\c +.IR topic ( manual-section )\[rq]. +. +. +.TP +.BI .MT " address" +.TQ +.BR .ME " ["\c +.IR trailing-text ] +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. +. +An argument to +.B .ME +is placed after the link text without intervening space. +. +.I address +may not be visible in the rendered document if hyperlinks are enabled +and supported by the output driver. +. +If they are not, +.I address +is set in angle brackets after the link text and before +.I trailing-text. +. +If hyperlinking is enabled but there is no link text, +.I address +is formatted and hyperlinked +.I without +angle brackets. +. +. +.TP +.BI .UR " uri" +.TQ +.BR .UE " ["\c +.IR trailing-text ] +Identify +.I uri +as an RFC 3986 URI hyperlink with the text between the two macro calls +as the link text. +. +An argument to +.B .UE +is placed after the link text without intervening space. +. +.I uri +may not be visible in the rendered document if hyperlinks are enabled +and supported by the output driver. +. +If they are not, +.I uri +is set in angle brackets after the link text and before +.I trailing-text. +. +If hyperlinking is enabled but there is no link text, +.I uri +is formatted and hyperlinked +.I without +angle brackets. +. +. +.P +The hyperlinking of +.B .TP +paragraph tags with +.BR .UR / .UE +and +.BR .MT / .ME +is not yet supported; +if attempted, +the hyperlink will be typeset at the beginning of the indented paragraph +even on hyperlink-supporting devices. +. +. +.\" ==================================================================== +.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. +. +Italic text is usually set underscored instead on terminal devices. +. +The +.B .SM +and +.B .SB +macros set text in roman or bold, +respectively, +at a smaller type size; +these differ visually from regular-sized roman or bold text only on +typesetting devices. +. +It is often necessary to set text in different styles without +intervening space. +. +The macros +.BR .BI , +.BR .BR , +.BR .IB , +.BR .IR , +.BR .RB , +and +.BR .RI , +where \(lqB\(rq, +\(lqI\(rq, +and \(lqR\(rq indicate bold, +italic, +and roman, +respectively, +set their odd- and even-numbered arguments in alternating styles, +with no space separating them. +. +. +.br +.ne 2v +.P +The default type size and family for typesetting devices is 10-point +Times, +except on the +.B \%X75\-12 +and +.B \%X100\-12 +devices where the type size is 12 points. +. +The default style is roman. +. +. +.TP +.BR .B \~[\c +.IR text ] +Set +.I text +in bold. +. +If no argument is given, +a one-line input trap is planted; +text on the next line, +which can be further formatted with a macro, +is set in bold. +. +. +.TP +.BR .I \~[\c +.IR text ] +Set +.I text +in an italic or oblique face. +. +If no argument is given, +a one-line input trap is planted; +text on the next line, +which can be further formatted with a macro, +is set in an italic or oblique face. +. +. +.TP +.BR .SM \~[\c +.IR text ] +Set +.I text +one point smaller than the default type size on typesetting devices. +. +If no argument is given, +a one-line input trap is planted; +text on the next line, +which can be further formatted with a macro, +is set smaller. +. +. +.TP +.BR .SB \~[\c +.IR text ] +Set +.I text +in bold and +(on typesetting devices) +one point smaller than the default type size. +. +If no argument is given, +a one-line input trap is planted; +text on the next line, +which can be further formatted with a macro, +is set smaller and in bold. +. +This macro is an extension introduced in SunOS\~4.0. +. +. +.P +Unlike the above font style macros, +the font style alternation macros below set no input traps; +they must be given arguments to have effect. +. +Italic corrections are applied as appropriate. +. +. +. +.TP +.BI .BI " bold-text italic-text "\c +\&.\|.\|.\& +Set each argument in bold and italics, +alternately. +. +. +.TP +.BI .BR " bold-text roman-text "\c +\&.\|.\|.\& +Set each argument in bold and roman, +alternately. +. +. +.TP +.BI .IB " italic-text bold-text "\c +\&.\|.\|.\& +Set each argument in italics and bold, +alternately. +. +. +.TP +.BI .IR " italic-text roman-text "\c +\&.\|.\|.\& +Set each argument in italics and roman, +alternately. +. +. +.TP +.BI .RB " roman-text bold-text "\c +\&.\|.\|.\& +Set each argument in roman and bold, +alternately. +. +. +.TP +.BI .RI " roman-text italic-text "\c +\&.\|.\|.\& +Set each argument in roman and italics, +alternately. +. +. +.\" ==================================================================== +.SS "Horizontal and vertical spacing" +.\" ==================================================================== +. +The +.I indentation +argument accepted by +.BR .IP , +.BR .TP , +and the deprecated +.B .HP +is a number plus an optional scaling unit, +as is +.BR .RS 's +.IR inset-amount . +. +If no scaling unit is given, +the +.I man +package assumes \(lqn\(rq. +. +An indentation specified in a call to +.BR .IP , +.BR .TP , +or the deprecated +.B .HP +persists until +(1) another of these macros is called with an +.I indentation +argument, +or +(2) +.BR .SH , +.BR .SS , +or +.B .P +or its synonyms is called; +these clear the indentation entirely. +. +. +.P +The left margin used by ordinary paragraphs set with +.B .P +(and its synonyms) +not within an +.BR .RS / .RE +relative inset +.\" TODO: future: BP or BI register ("base paragraph indentation") +is 7.2n for typesetting devices +and 7n for terminal devices +(but see the +.B \-rIN +option). +. +Headers, +footers +(both set with +.BR .TH ), +and section headings +.RB ( .SH ) +are set at the page offset +(see +.MR groff 7 ) +and subsection headings +.RB ( .SS ) +indented from it by 3n +(but see the +.B \-rSN +option). +. +.\" XXX: This is not true, but they do handle it badly. +.\" HTML output devices ignore indentation. +. +. +.P +Several macros insert vertical space: +.BR .SH , +.BR .SS , +.BR .TP , +.B .P +(and its synonyms), +.BR .IP , +and the deprecated +.BR .HP . +. +The default inter-section and inter-paragraph spacing is +is 1v for terminal devices +and 0.4v for typesetting devices. +. +(The deprecated macro +.B .PD +can change this vertical spacing, +but its use is discouraged.) +. +Between +.B .EX +and +.B .EE +calls, +the inter-paragraph spacing is 1v regardless of output +device. +. +. +.\" ==================================================================== +.SS Registers +.\" ==================================================================== +. +Registers are described in section \(lqOptions\(rq below. +. +They can be set not only on the command line but in the site +.I man.local +file as well; +see section \(lqFiles\(rq below. +. +. +.br +.ne 7v +.\" ==================================================================== +.SS Strings +.\" ==================================================================== +. +The following strings are defined for use in man pages. +. +None of these is necessary in a contemporary man page; +see +.MR groff_man_style 7 . +. +Others are supported for configuration of rendering parameters; +see section \(lqOptions\(rq below. +. +. +.TP +.B \e*R +interpolates a special character escape sequence for the \(lqregistered +sign\(rq glyph, +.BR \e(rg , +if available, +and \(lq(Reg.)\(rq otherwise. +. +. +. +.TP +.B \e*S +interpolates an escape sequence setting the type size to the document +default. +. +. +.TP +.B \e*(lq +.TQ +.B \e*(rq +interpolate special character escape sequences for left and right +double-quotation marks, +.B \e(lq +and +.BR \e(rq , +respectively. +. +. +.TP +.B \e*(Tm +interpolates a special character escape sequence for the \(lqtrade mark +sign\(rq glyph, +.BR \e(tm , +if available, +and \(lq(TM)\(rq otherwise. +. +. +.\" ==================================================================== +.SS Hooks +.\" ==================================================================== +. +Two macros, +both GNU extensions,\" from groff 1.19 +are called internally by the +.I groff man +package to format page headers and footers and can be redefined by the +administrator in a site's +.I man.local +file +(see section \(lqFiles\(rq below). +. +The presentation of +.B .TH +above describes the default headers and footers. +. +Because these macros are hooks for +.I groff man +internals, +man pages have no reason to call them. +. +Such hook definitions will likely consist of \[lq].sp\[rq] and +\[lq].tl\[rq] requests. +. +They must also increase the page length with \[lq].pl\[rq] requests in +continuous rendering mode; +.B .PT +furthermore has the responsibility of emitting a PDF bookmark after +writing the first page header in a document. +. +Consult the existing implementations in +.I an.tmac +when drafting replacements. +. +. +.TP +.B .BT +Set the page footer text +(\(lqbottom trap\(rq). +. +. +.TP +.B .PT +Set the page header text +(\(lqpage trap\(rq). +. +. +.P +To remove a page header or footer entirely, +define the appropriate macro as empty rather than deleting it. +. +. +.\" ==================================================================== +.SS "Deprecated features" +.\" ==================================================================== +. +Use of the following in man pages for public distribution is +discouraged. +. +. +.TP +.BR .AT " ["\c +.IR system " [" release ]] +Alter the footer for use with legacy AT&T man pages, +overriding any definition of the +.I footer-inside +argument to +.BR .TH . +. +This macro exists only to render man pages from historical systems. +. +. +.IP +.I system +can be any of the following. +. +. +.RS \" Invisibly move left margin to current .IP indentation. +.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 +.I release +argument specifies the release number, +as in \(lqSystem\~V Release\~3\(rq. +. +. +.TP +.B .DT +Reset tab stops to the default +(every 0.5i). +. +.IP +Use of this presentation-oriented macro is deprecated. +. +It translates poorly to HTML, +under which exact space control and tabulation are not readily +available. +. +Thus, +information or distinctions that you use tab stops to express are likely +to be lost. +. +If you feel tempted to change the tab stops such that calling this macro +later is desirable to restore them, +you should probably be composing a table using +.MR \%tbl 1 +instead. +. +. +.TP +.BR .HP " ["\c +.IR indentation ] +Set up a paragraph with a hanging left indentation. +. +The +.I indentation +argument, +if present, +is handled as with +.BR .TP . +. +. +.IP +Use of this presentation-oriented macro is deprecated. +. +A hanging indentation cannot be expressed naturally under HTML, +and +.RI non- roff -based +man page interpreters may treat +.B .HP +as an ordinary paragraph. +. +Thus, +information or distinctions you mean to express with indentation may be +lost. +. +. +.TP +.BI .OP " option-name"\/\c +.RI " [" option-argument ] +Indicate an optional command parameter called +.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. +. +. +.IP +Use of this quasi-semantic macro, +.\" https://github.com/n-t-roff/DWB3.3/blob/master/macros/man/an.sr#L37 +an extension originating in Documenter's Workbench +.IR troff ,\" DWB +is deprecated. +. +It cannot easily be used to annotate options that take optional +arguments or options whose arguments have internal structure +(such as a mixture of literal and variable components). +. +One could work around these limitations with font selection escape +sequences, +but it is preferable to use font style alternation macros, +which afford greater flexibility. +. +. +.TP +.BR .PD " ["\c +.IR vertical-space ] +Define the vertical space between paragraphs or (sub)sections. +. +The optional argument +.I vertical-space +specifies the amount; +the default scaling unit is \(lqv\(rq. +. +Without an argument, +the spacing is reset to its default value; +see subsection \(lqHorizontal and vertical spacing\(rq above. +. +. +.IP +Use of this presentation-oriented macro is deprecated. +. +It translates poorly to HTML, +under which exact control of inter-paragraph spacing is not readily +available. +. +Thus, +information or distinctions that you use +.B .PD +to express are likely to be lost. +. +. +.TP +.BR .UC " ["\c +.IR version ] +Alter the footer for use with legacy BSD man pages, +overriding any definition of the +.I footer-inside +argument to +.BR .TH . +. +This macro exists only to render man pages from historical systems. +. +. +.IP +.I version +can be any of the following. +. +. +.RS \" Invisibly move left margin to current .IP indentation. +.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 +.\" ==================================================================== +. +.MT m.douglas.mcilroy@dartmouth.edu +M.\& Douglas McIlroy +.ME +designed, +implemented, +and documented the AT&T +.I man +macros +for +Unix Version\~7 (1979) and employed them +to edit the first volume of its +.IR "Programmer's Manual" , +a compilation of all man pages supplied by the system. +. +That +.I man +supported the macros listed in this page not described as extensions, +except +.B .P +.\" .SS was implemented in tmac.an but not documented in man(7). +and the deprecated +.B .AT +and +.BR .UC . +. +The only strings defined were +.B R +and +.BR S ; +no registers were documented. +. +. +.P +.B .UC +appeared in 3BSD (1980). +. +.\" per https://archive.org/details/\ +.\" bitsavers_attunixSysalRelease3Jun80_33886798 +Unix System\~III (1980) introduced +.B .P +.\" ...and de-documented .LP... +and exposed the registers +.B IN +and +.BR LL , +.\" ...as well as \n[PD], which we implement but don't expose. +which had been internal to Seventh Edition Unix +.IR man . +. +.\" This inference is based on RCS idents of "PWB Manual Entry Macros" +.\" from various forms of "an.src" distributed with System III (an.src +.\" 1.35, dated 5/6/80, lacks the Tm string), Research Unix Version 10 +.\" (1.36, dated 11/11/80, has it), Ultrix 3.1 (1.37, dated 12/19/80, +.\" retains it) and "pdp11v" (also 1.37). One source (S. S. Pirzada) +.\" says PWB 2.0 was released in June 1979. I found no record of later +.\" releases and cannot account for the discrepancy (field updates?). +.\" -- GBR +PWB/UNIX 2.0 (1980) added the +.B Tm +string. +. +4BSD (1980) added +.\" undocumented .VS and .VE macros to mark regions with 12-point box +.\" rules (\[br]) as margin characters, as well as... +.B lq +and +.B rq +strings. +. +.\" The SunOS inferences here and below are based on inspection of SunOS +.\" 2.0 (May 1985), 3.2 (September 1986), 3.5 (January 1988), and 4.0 +.\" (December 1988) tape archives (only). +SunOS\~2.0 (1985) recognized +.BR C , +.BR D , +.BR P , +and +.B X +registers. +. +4.3BSD (1986) added +.\" undocumented .DS and .DE macros for "displays", which are .RS/.RE +.\" wrappers with filling disabled and vertical space of 1v before and +.\" .5v after, as well as... +.B .AT +and +.BR .P . +. +.\" Per Doug McIlroy in +.\" <https://lists.gnu.org/archive/html/groff/2019-07/msg00038.html>... +Ninth Edition Research Unix (1986) introduced +.B .EX +and +.BR .EE . +. +SunOS\~4.0 (1988) added +.BR .SB . +. +. +.P +The foregoing features were what James Clark implemented in early +versions of +.IR groff . +. +. +Later, +.I groff +1.20 (2009) originated +.BR .SY / .YS , +.BR .TQ , +.BR .MT / .ME , +and +.BR .UR / .UE . +.\" ...along with implementations of OP, EX, and EE. +. +Plan\~9 from User Space's +.I troff \" plan9port +introduced +.B .MR +in 2020. +.\" https://github.com/9fans/plan9port/commit/\ +.\" 977b25a76ae8263e53fb4eb1abfc395769f23e3d +.\" d32deab17bfffa5bffc5fab3e6577558e40888c5 +.\" 36cd4c58c1346375b98f517fb8568be5bb47618d +. +. +.br +.ne 4v +.\" ==================================================================== +.SH Options +.\" ==================================================================== +. +The following +.I groff +options set registers +(with +.BR \-r ) +and strings +(with +.BR \-d ) +recognized and used by the +.I man +macro package. +. +To ensure rendering consistent with output device capabilities and +reader preferences, +man pages should never manipulate them. +. +. +.TP +.BI \-dAD= adjustment-mode +Set line adjustment to +.I adjustment-mode, +which is typically +.RB \[lq] b \[rq] +for adjustment to both margins +(the default), +or +.RB \[lq] l \[rq] +for left alignment +(ragged right margin). +. +Any valid argument to +.IR groff 's +\[lq].ad\[rq] request may be used. +. +See +.MR groff 7 +for less-common choices. +. +. +.TP +.B \-rcR=1 +Enable continuous rendering. +. +Output is not paginated; +instead, +one +(potentially very long) +page is produced. +. +This is the default for terminal and HTML devices. +. +Use +.B \-rcR=0 +to disable it on terminal devices; +on HTML devices, +it cannot be disabled. +. +. +.TP +.B \-rC1 +Number output pages consecutively, +in strictly increasing sequence, +rather than resetting the page number to\~1 +(or the value of register +.BR P ) +with each new +.I man +document. +. +. +.TP +.B \-rCS=1 +Set section headings +(the argument(s) to +.BR .SH ) +in full capitals. +. +This transformation is off by default because it discards case +distinction information. +. +. +.TP +.B \-rCT=1 +Set the man page topic +(the first argument to +.BR .TH ) +in full capitals in headers and footers. +. +This transformation is off by default because it discards case +distinction information. +. +. +.TP +.B \-rD1 +Enable double-sided layout, +formatting footers for even and odd pages differently; +see the description of +.B .TH +in subsection \(lqDocument structure macros\(rq above. +. +. +.TP +.BI \-rFT= footer-distance +Set distance of the footer relative to the bottom of the page to +.I footer-distance; +this amount is always negative. +. +At one half-inch above this location, +the page text is broken before writing the footer. +. +Ignored if continuous rendering is enabled. +. +The default is \-0.5i. +. +. +.TP +.BI \-dHF= heading-font +Set the font used for section and subsection headings; +the default is +.RB \(lq B \(rq +(bold style of the default family). +. +Any valid argument to +.IR groff 's +\[lq].ft\[rq] request may be used. +. +See +.MR groff 7 . +. +. +.TP +.B \-rHY=0 +Disable automatic hyphenation. +. +Normally, +it is enabled\~(1). +. +The hyphenation mode is determined by the +.I groff +locale; +see section \[lq]Localization\[lq] of +.MR groff 7 . +. +. +.TP +.BI \-rIN= standard-indentation +Set the amount of indentation used for ordinary paragraphs +.RB ( .P +and its synonyms) +and the default indentation amount used by +.BR .IP , +.BR .RS , +.BR .TP , +.\" .TQ inherits its indentation from the preceding .TP. +and the deprecated +.BR .HP . +. +See subsection \(lqHorizontal and vertical spacing\(rq above for the +default. +. +For +terminal devices, +.I standard-indentation +should always be an integer multiple of unit \(lqn\(rq to get consistent +indentation. +. +. +.TP +.BI \-rLL= line-length +Set line length; +the default is 78n for terminal devices +and 6.5i for typesetting devices. +. +. +.TP +.BI \-rLT= title-length +Set the line length for titles. +. +By default, +it is set to the line length +(see +.B \-rLL +above). +. +. +.TP +.BI \-dMF= man-page-topic-font +Set the font used for man page topics named in +.B .TH +and +.B .MR +calls; +the default is +.RB \(lq I \(rq +(italic style of the default family). +. +Any valid argument to +.IR groff 's +\[lq].ft\[rq] request may be used. +. +If the +.B MF +string ends in \[lq]I\[rq], +it is assumed to be an oblique typeface, +and italic corrections are applied before and after man page topics. +. +. +.TP +.BI \-rP n +Start enumeration of pages at +.IR n . +. +The default is\~1. +. +. +.TP +.BI \-rS type-size +Use +.I type-size +for the document's body text; +acceptable values are 10, +11, +or 12 points. +. +See subsection \(lqFont style macros\(rq above for the default. +. +. +.TP +.BI \-rSN= subsection-indentation +Set indentation of subsection headings to +.I subsection-indentation. +. +See subsection \(lqHorizontal and vertical spacing\(rq above for the +default. +. +. +.br +.ne 4v +.TP +.B \-rU1 +Enable generation of URI hyperlinks in the +.I grohtml +and +.I grotty +output drivers. +. +.I grohtml +enables them by default; +.I grotty +does not, +pending more widespread pager support for OSC\~8 escape sequences. +. +Use +.B \-rU0 +to disable hyperlinks; +this will make the arguments to +.B MT +and +.B UR +calls visible in the document text produced by link-capable drivers. +. +. +.TP +.BI \-rX p +Number successors of +.RI page\~ p +as +.IR p a, +.IR p b, +.IR p c, +and so forth. +. +The register tracking the suffixed page letter uses format \(lqa\(rq +(see the \(lq.af\(rq request in +.MR groff 7 ). +. +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:an\:.tmac +Most +.I man +macros are defined in this file. +. +It also loads extensions from +.I \%an\-ext.tmac +(see below). +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%andoc\:.tmac +This brief +.I groff +program detects whether the +.I man +or +.I mdoc +macro package is being used by a document and loads the correct macro +definitions, +taking advantage of the fact that pages using them must call +.B .TH +or +.BR .Dd , +respectively, +before any other macros. +. +A +.I man +program or user typing, +for example, +.RB \[lq] "groff \-mandoc page.1" \[rq], +need not know which package the file +.I page.1 +uses. +. +Multiple man pages, +in either format, +can be handled; +.I \%andoc +reloads each macro package as necessary. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%an\-ext\:.tmac +Except for +.BR .SB , +definitions of macros described above as extensions +are contained in this file; +in some cases, +they are simpler versions of definitions appearing in +.IR an.tmac , +and are ignored if the formatter is GNU +.IR troff .\" GNU +. +They are written to be compatible with AT&T +.I troff \" AT&T +and permissively licensed\(emnot copylefted. +. +To reduce the risk of name space collisions, +string and register names begin only with +.RB \[lq] m \[rq] . +. +We encourage man page authors +who are concerned about portability to legacy Unix systems +to copy these definitions into their pages, +and maintainers of +.I troff \" generic +implementations or work-alike systems that format man pages +to re-use them. +. +. +.IP +The definitions for these macros are read after a page calls +.BR .TH , +so they will replace any macros of the same names preceding it in your +file. +. +If you use your own implementations of these macros, +they must be defined after +.B .TH +is called to have any effect. +. +Furthermore, +it is wise to define such page-local macros +(if at all) +after the \(lqName\(rq section to accommodate timid +.I makewhatis +or +.I mandb +implementations that may give up their scan for indexing material early. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:man\:.tmac +This is a wrapper that loads +.IR an.tmac . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%mandoc\:.tmac +This is a wrapper that loads +.IR \%andoc.tmac . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%site\-tmac/\:\%man\:\%.local +Put site-local changes and customizations into this file. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +The initial GNU implementation of the +.I man +macro package was written by James Clark. \" by 1.01 +. +Later, +.MT wl@\:gnu\:.org +Werner Lemberg +.ME +supplied the +.BR S , \" 1.16 +.BR LT , \" 1.18 +and +.B cR \" 1.17 +registers, +the last a 4.3BSD-Reno +.IR mdoc (7) +feature. +.\" "Assume nroff on crt's [sic] only if cR==1" +.\" https://minnie.tuhs.org/cgi-bin/utree.pl +.\" ?file=4.3BSD-Reno/share/tmac/tmac.doc +. +.MT kollar@\:alltel\:.net +Larry Kollar +.ME +added the +.BR FT , +.BR HY , +and +.B SN +registers; +the +.B HF +string; +and the +.B PT +and +.B BT +macros. +. +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME +implemented the +.B AD +and +.B MF +strings; +.BR CS , +.BR CT , +and +.B U +registers; +and the +.B MR +macro. \" all 1.23 +. +. +Except for +.BR .SB , \" Clark, as noted above +the extension macros were written by +Lemberg, +.MT esr@\:thyrsus\:.com +Eric S.\& Raymond +.ME , +and +Robinson. \" 1.23: MR +. +. +.br +.ne 3v +.P +This document was originally written for the Debian GNU/Linux system by +.MT sgk@\:debian\:.org +Susan G.\& Kleinmann +.ME . +. +It was corrected and updated by Lemberg and Robinson. +. +The extension macros were documented by Raymond and Robinson. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.MR \%tbl 1 , +.MR \%eqn 1 , +and +.MR \%refer 1 +are preprocessors used with man pages. +. +.MR man 1 +describes the man page librarian on your system. +. +.MR groff_mdoc 7 +details the +.I groff +version of the BSD-originated alternative macro package for man pages. +. +. +.P +.MR groff_man_style 7 , +.MR groff 7 , +.MR groff_char 7 , +.MR man 7 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_man_7_man_C] +.do rr *groff_groff_man_7_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: |