diff options
Diffstat (limited to 'tmac/groff_man.7.man.in')
| -rw-r--r-- | tmac/groff_man.7.man.in | 4287 |
1 files changed, 4287 insertions, 0 deletions
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in new file mode 100644 index 0000000..f98bee6 --- /dev/null +++ b/tmac/groff_man.7.man.in @@ -0,0 +1,4287 @@ +divert(-1) +Note to maintainers of this document: while it is desirable to bracket +material that differs between groff_man(7) and groff_man_style(7) as +tightly as possible to honor the Don't Repeat Yourself principle, in +GBR's opinion this maxim has limits. + +Consider this ghastly example: + +If no scaling unit is given, +the +.I man +package assumes \(lqn\(rq\c +_ifstyle()dnl +; that is, +approximately the width of the letter \(lqn\(rq in the font current when +the macro is called +(see section \(lqMeasurements\(rq in +.MR groff @MAN7EXT@ )\c +_endif()dnl +\&. + +These man pages serve multiple goals, one of which is to serve as a +model for good man page writing by people who examine their sources. + +After processing by m4, both child pages in the above case will carry \c +escape sequences followed by text lines starting with punctuation one +normally does not find in that position (and in the case of the period, +which has to be protected from interpretation as a control line). + +This is ugly, fragile, and unnecessary; all of these traits are +offensive to good pedagogy. + +Consequently, it is better to repeat a small amount of material than +write a man page that looks like the output of docbook-to-man. + +define(`_ifstyle',`ifdef(`_groff_man_style',,`divert(-1)')') +define(`_ifnotstyle',`ifdef(`_groff_man_style',`divert(-1)')') +define(`_endif',`divert`'') +divert`'dnl +'\" t +.\" This page is generated by m4 from tmac/groff_man.7.man.in. +_ifnotstyle()dnl +.TH groff_man @MAN7EXT@ "@MDATE@" "groff @VERSION@" +_endif()dnl +_ifstyle()dnl +.TH groff_man_style @MAN7EXT@ "@MDATE@" "groff @VERSION@" +_endif()dnl +.SH Name +_ifnotstyle()dnl +groff_man \- compose manual pages with GNU +.I roff +_endif()dnl +_ifstyle()dnl +groff_man_style \- GNU +.I roff +man page tutorial and style guide +_endif()dnl +. +. +.\" ==================================================================== +.\" 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. +. +. +_ifnotstyle()dnl +.P +Man page authors and maintainers who are not already experienced +.I groff +users should consult +.MR groff_man_style @MAN7EXT@ , +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. +. +. +_endif()dnl +.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. +_ifstyle()dnl +. +. +.\" ==================================================================== +.\" .SS "Input file format" +.\" ==================================================================== +.P +Man pages should be encoded using Unicode basic Latin code points +exclusively, +and employ the Unix line-ending convention +(U+000A only). +.\" What about rare English words that require diacritics, and +.\" proper names that require more than basic Latin? +.\" +.\" sentence (including end-of-sentence detection) +.\" The above distinction works well with filling. +.\" Don't fill your input text yourself; let groff do the work. +.\" Also good for diffs. +.\" escape sequences--pretty much just "see Portability" +. +.\" ==================================================================== +.SS "Fundamental concepts" +.\" ==================================================================== +.\" font (family, style [elsewhere known as face]) +.\" type size +.\" typesetter (troff device, PostScript, PDF) +.\" terminal (nroff device, emulator, typewriter, TTY) +.I groff +is a programming system for typesetting: +we thus often use the verb \(lqto set\(rq in the sense +\(lqto typeset\(rq. +. +The formatter +.MR @g@troff @MAN1EXT@ +collects words from the input and +.I fills +output lines with as many as will fit. +. +.I Words +are separated by spaces and newlines. +.\" Also tabs and leaders, but let's not discuss those in man(7). +. +A transition to a new output line is called a +.I break. +. +When formatted, +a word may be broken at hyphens, +at +.B \e% +or +.B \e: +escape sequences +(see subsection \(lqPortability\(rq below), +or at predetermined locations +if automatic hyphenation is enabled +(see the +.B \-rHY +option in section \(lqOptions\(rq below). +. +An output line may be supplemented with +.I inter-sentence space, +and then optionally +.I adjusted +with more space to a consistent line length +(see the +.B \-dAD +option). +. +.MR roff @MAN7EXT@ +details these processes. +. +. +.P +An input line that starts with a dot (.\&) +or neutral apostrophe (\(aq) +is a +.I control line. +. +To call a macro, +put its name after a dot on a control line. +.\" You never need to indent macro calls in man(7), or call them with +.\" the no-break control character. +. +We refer to macros in this document using this leading dot. +. +Some macros interpret +.I arguments, +words that follow the macro name. +. +A newline, +unless escaped +(see subsection \(lqPortability\(rq below), +marks the end of the macro call. +. +An input line consisting of a dot followed by a newline +is called the +.I empty request; +it does nothing. +. +.I Text lines +are input lines that are not control lines. +. +. +.P +We describe below several +.I man +macros that plant one-line +.I input traps: +the next input line that directly produces formatted output is treated +specially. +. +For +.I man +documents that follow the advice in section +\[lq]Portability\[rq] below, +this means that control lines using the empty request +and uncommented input lines ending with an escaped newline +do not spring the trap; +anything else does +(but see the +.B .TP +macro description). +. +. +.\" ==================================================================== +.\" .SS "Why have a tutorial and style guide?" +.\" ==================================================================== +.\" the processing pipeline in brief +.\" preprocessors, roff itself, various output devices +.\" Things that aren't groff--why you want the man page language to be +.\" small (mandoc, Kerrisk's man7.org, manpages.debian.org, non-expert +.\" humans). +.\" possibly exhibit a horrorshow docbook-to-man example +_endif()dnl +. +. +.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 +_ifstyle()dnl +Optional macro arguments are indicated by surrounding them with square +brackets. +. +If a macro accepts multiple arguments, +those containing space \" or tab (in Plan 9 troff [only?]) +characters must be double-quoted to be interpreted correctly. +. +_endif()dnl +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. +_ifstyle()dnl +. +See section \(lqNotes\(rq below for examples of cases where better +alternatives to empty arguments in macro calls are available. +_endif()dnl +. +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. +_ifstyle()dnl +. +.I roff +systems refer to these collectively as \(lqtitles\(rq. +_endif()dnl +. +The subject of the man page is +.I topic +and the section of the manual to which it belongs is +.I section. +_ifstyle()dnl +. +This use of \(lqsection\(rq has nothing to do with the section headings +otherwise discussed in this page; +it arises from the organizational scheme of printed and bound Unix +manuals. +_endif()dnl +. +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 +_ifstyle()dnl +.RB ( .\|.\|.\& ) +_endif()dnl +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. +_ifstyle()dnl +. +. +.IP +By convention, +.I footer-middle +is the date of the most recent modification to the man page source +document, +and +.I footer-inside +is the name and version or release of the project providing it. +_endif()dnl +. +. +.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 +_ifnotstyle()dnl +.MR groff_man_style @MAN7EXT@ +for suggestions and +_endif()dnl +.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. +. +. +_ifstyle()dnl +.IP +Example regions are useful for formatting code, +shell sessions, +and text file contents. +. +An example region is not +a \(lqliteral mode\(rq +of any sort: +special character escape sequences must still be used to produce correct +glyphs for +.BR \(aq , +.BR \- , +.BR \(rs , +.BR \(ha , +.BR \(ga , +and +.BR \(ti , +and sentence endings are still detected and additional inter-sentence +space applied. +. +If the amount of additional inter-sentence spacing is altered, +the rendering of, +for instance, +regular expressions using +.B .\& +or +.B ?\& +followed by multiple spaces can change. +. +Use the dummy character escape sequence +.B \(rs& +before the spaces. +. +. +_endif()dnl +.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 ) +_ifstyle()dnl +like this one +_endif()dnl +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. +_ifstyle()dnl +. +. +.IP +The line containing the tag can `include' a macro call, +for instance to set the tag in bold with +.BR .B . +. +.B .TP +was used to write the first paragraph of this description of +.BR .TP , +and +.B .IP +the subsequent one. +_endif()dnl +. +. +.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. +_ifstyle()dnl +. +. +.IP +The descriptions of +.BR .P , +.BR .LP , +and +.B .PP +above were written using +.B .TP +and +.BR .TQ . +_endif()dnl +. +. +.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. +. +. +_ifstyle()dnl +.IP +Two convenient uses for +.B .IP +are +. +. +.RS \" Invisibly move left margin to current .IP indentation. +.RS 4n \" Now indent further, visibly. +.IP (1) 4n +to start a new paragraph with the same indentation as an immediately +preceding +.B .IP +or +.B .TP +paragraph, +if no +.I indentation +argument is given; +and +. +. +.IP (2) +to set a paragraph with a short +.I tag +that is not semantically important, +such as a bullet (\(bu)\(emobtained with the +.B \e(bu +special character escape sequence\(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. +. +. +_endif()dnl +.\" ==================================================================== +.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 +_ifstyle()dnl +(as with +.BR .P ) +_endif()dnl +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. +_ifstyle()dnl +. +. +.P +Multiple +.BR .SY / .YS +blocks can be specified, +for instance to distinguish differing modes of operation of a complex +command like +.MR tar 1 ; +each will be vertically separated as paragraphs are. +. +. +.P +.B .SY +can be repeated before +.B .YS +to indicate synonymous ways of invoking a particular mode of operation. +. +. +.br +.ne 2v +.P +.IR groff 's +own command-line interface serves to illustrate most of the specimens +of synopsis syntax one is likely to encounter. +. +. +.IP +.\" from src/roff/groff/groff.1.man +.EX +\&.SY groff +\&.RB [ \e-abcCeEgGijklNpRsStUVXzZ ] +\&.RB [ \e-d\e\(ti\ec +\&.IR cs ] +\&.RB [ \e-d\e\(ti\ec +\&.IB name =\ec +\&.IR string ] +\&.RB [ \e-D\e\(ti\ec +\&.IR enc ] +.EE +. +.I (and so on similarly) +. +.EX +\&.RI [ file\e\(ti .\e|.\e|.] +\&.YS +\&. +\&. +\&.SY groff +\&.B \e-h +\&. +\&.SY groff +\&.B \e-\e-help +\&.YS +\&. +\&. +\&.SY groff +\&.B \e-v +\&.RI [ option\e\(ti .\e|.\e|.\e&] +\&.RI [ file\e\(ti .\e|.\e|.] +\&. +\&.SY groff +\&.B \e-\e-version +\&.RI [ option\e\(ti .\e|.\e|.\e&] +\&.RI [ file\e\(ti .\e|.\e|.] +\&.YS +.EE +. +. +.P +produces the following output. +. +. +.RS +.SY groff +.RB [ \-abcCeEgGijklNpRsStUVXzZ ] +.RB [ \-d\~\c +.IR cs ] +.RB [ \-d\~\c +.IB name =\c +.IR string ] +.RB [ \-D\~\c +.IR enc ] +.RB [ \-f\~\c +.IR fam ] +.RB [ \-F\~\c +.IR dir ] +.RB [ \-I\~\c +.IR dir ] +.RB [ \-K\~\c +.IR enc ] +.RB [ \-L\~\c +.IR arg ] +.RB [ \-m\~\c +.IR name ] +.RB [ \-M\~\c +.IR dir ] +.RB [ \-n\~\c +.IR num ] +.RB [ \-o\~\c +.IR list ] +.RB [ \-P\~\c +.IR arg ] +.RB [ \-r\~\c +.IR cn ] +.RB [ \-r\~\c +.IB reg =\c +.IR expr ] +.RB [ \-T\~\c +.IR dev ] +.RB [ \-w\~\c +.IR name ] +.RB [ \-W\~\c +.IR name ] +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY groff +.B \-h +. +.SY groff +.B \-\-help +.YS +. +. +.SY groff +.B \-v +.RI [ option\~ .\|.\|.\&] +.RI [ file\~ .\|.\|.] +. +.SY groff +.B \-\-version +.RI [ option\~ .\|.\|.\&] +.RI [ file\~ .\|.\|.] +.YS +.RE +. +. +.P +Several features of the above example are of note. +. +. +.IP \(bu 2n +The empty request (.), +which does nothing, +is used to vertically space the input file for readability by the +document maintainer. +. +Do not put blank (empty) lines in a man page source document. +. +. +.IP \(bu +Command and option names are presented in +.B bold +to cue the user that they should be input literally. +. +. +.IP \(bu +Option dashes are specified with the +.B \e\- +escape sequence; +this is an important practice to make them clearly visible and to +facilitate copy-and-paste from the rendered man page to a shell prompt +or text file. +. +. +.IP \(bu +Option arguments and command operands are presented in +.I italics +(but see subsection \(lqFont style macros\(rq below regarding terminals) +to cue the user that they must be replaced with appropriate text. +. +. +.IP \(bu +Symbols that are neither to be typed literally nor replaced at the +user's discretion appear in the roman style; +brackets surround optional arguments, +and an ellipsis indicates that the previous syntactical element may be +repeated arbitrarily. +. +. +.IP \(bu +The non-breaking adjustable space escape sequence +.B \e\(ti +is used to prevent the output line from being broken within the option +brackets; +see subsection \(lqPortability\(rq below. +. +. +.IP \(bu +The output line continuation escape sequence +.B \ec +is used with font style alternation macros to allow all three font +styles to be set without (breakable) space among them; +see subsection \(lqPortability\(rq below. +. +. +.IP \(bu +The dummy character escape sequence +.B \e& +follows the ellipsis when further text will follow after space on the +output line, +keeping its last period from being interpreted as the end of a +sentence +.\" ...because it is followed by characters that are transparent to +.\" end-of-sentence detection, and a newline... +and causing additional inter-sentence space to be placed after it. +. +See subsection \(lqPortability\(rq below. +_endif()dnl +. +. +.\" ==================================================================== +.SS "Hyperlink macros" +.\" ==================================================================== +. +Man page cross references +_ifstyle()dnl +like +.MR ls 1 +_endif()dnl +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 @MAN1EXT@ ). +. +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. +_ifstyle()dnl +. +(See section \[lq]Portability\[rq] below.) +. +URIs can be lengthy; +rendering them can result in jarring adjustment or variations in line +length, +or +.I @g@troff +warnings when a hyperlink is longer than an output line. +. +The application of non-printing break point escape sequences +.B \e: +after each slash +(or series thereof), +and before each dot +(or series thereof) +is recommended as a rule of thumb. +. +The former practice avoids forcing a trailing slash in a URI onto a +separate output line, +and the latter helps the reader to avoid mistakenly interpreting a dot +at the end of a line as a period +(or multiple dots as an ellipsis). +. +Thus, +.RS +.EX +\&.UR http://\e:example\e:.com/\e:fb8afcfbaebc74e\e:.cc +.EE +.RE +has several potential break points in the URI shown. +. +Consider adding break points before or after at signs in email +addresses, +and question marks, +ampersands, +and number signs in HTTP(S) URIs. +. +_endif()dnl +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]. +_ifstyle()dnl +. +. +.RS +.IP +.EX +The output driver +\&.MR grops @MAN1EXT@ +produces PostScript from +\&.I troff +output. +\&. +The Ghostscript program (\[rs]c +\&.MR gs 1 ) +interprets PostScript and PDF. +.EE +.RE +_endif()dnl +. +. +.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. +_ifstyle()dnl +. +. +.br +.ne 6v +.IP +When rendered by +.I groff +to a PostScript device, +.RS +.IP +.EX +Contact +\&.MT fred\e:.foonly@\e:fubar\e:.net +Fred Foonly +\&.ME +for more information. +.EE +.RE +. +. +.IP +displays as \(lqContact Fred Foonly \(lafred\:.foonly@\:fubar\:.net\(ra +for more information.\(rq. +_endif()dnl +. +. +.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. +_ifstyle()dnl +. +. +.IP +When rendered by +.I groff +to a PostScript device, +.RS +.IP +.EX +The GNU Project of the Free Software Foundation +hosts the +\&.UR https://\e:www\e:.gnu\e:.org/\e:software/\e:groff/ +\&.I groff +home page +\&.UE . +.EE +.RE +. +. +.IP +displays as \(lqThe GNU Project of the Free Software Foundation hosts +the +.I groff +home page +\(lahttps://\:www\:.gnu\:.org/\:software/\:groff/\(ra.\(rq. +_endif()dnl +. +. +.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. +_ifstyle()dnl +. +. +.P +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, +and inlined literals. +_endif()dnl +. +. +.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. +. +. +_ifstyle()dnl +.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, +string, +and register names. +. +In an +.BR .EX / .EE +example of interactive I/O +(such as a shell session), +set only user input in bold. +. +. +. +_endif()dnl +.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. +. +. +_ifstyle()dnl +.IP +Use italics +for file and path names, +for environment variables, +for C data types, +for enumeration or preprocessor constants in C, +for variant (user-replaceable) portions of syntax synopses, +for the first occurrence (only) of a technical concept being introduced, +for names of journals and of literary works longer than an article, +and anywhere a parameter requiring replacement by the user is +encountered. +. +An exception involves variant text in a context already typeset in +italics, +such as file or path names with replaceable components; +in such cases, +follow the convention of mathematical typography: +set the file or path name in italics as usual +but use roman for the variant part +(see +.B .IR +and +.B .RI +below), +and italics again in running roman text when referring to the variant +material. +. +. +_endif()dnl +.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. +. +. +_ifstyle()dnl +.IP +.I Note: +terminals will render +.I text +at normal size instead. +. +Do not rely upon +.B .SM +to communicate semantic information distinct from using roman style at +normal size; +it will be hidden from readers using such devices. +. +. +_endif()dnl +.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. +. +. +_ifstyle()dnl +.IP +.I Note: +terminals will render +.I text +in bold at the normal size instead. +. +Do not rely upon +.B .SB +to communicate semantic information distinct from using bold style at +normal size; +it will be hidden from readers using such devices. +. +. +.P +Observe 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 major works of literature; +identifiers for standards documents or technical reports such as +CSTR\~#54, +RFC\~1918, +Unicode\~13.0, +or +POSIX.1-2017; +acronyms; +and occurrences after the first of a technical term. +. +. +.P +Be frugal with italics for emphasis, +and particularly with bold. +. +Article titles and brief runs of literal text, +such as references to individual characters or short strings, +including section and subsection headings of man pages, +are suitable objects for quotation; +see the +.BR \e(lq , +.BR \e(rq , +.BR \e(oq , +and +.B \e(cq +escape sequences in subsection \(lqPortability\(rq below. +. +. +_endif()dnl +.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. +. +_ifstyle()dnl +If a space is required within an argument, +first consider whether the same result could be achieved with as much +clarity by using single-style macros on separate input lines. +. +When it cannot, +double-quote an argument containing embedded space characters. +. +Setting all three different styles within a word +presents challenges; +it is possible with the +.B \ec +and/or +.B \ef +escape sequences. +. +See subsection \(lqPortability\(rq +below for approaches. +_endif()dnl +. +. +.TP +.BI .BI " bold-text italic-text "\c +\&.\|.\|.\& +Set each argument in bold and italics, +alternately. +. +. +_ifstyle()dnl +.RS +.IP +.\" from src/roff/troff/troff.1.man +.EX +\&.BI \-r\~ register = numeric-expression +.EE +.RE +. +. +_endif()dnl +.TP +.BI .BR " bold-text roman-text "\c +\&.\|.\|.\& +Set each argument in bold and roman, +alternately. +. +. +_ifstyle()dnl +.RS +.IP +.\" from tmac/groff_ms.7.man +.EX +After +\&.B .NH +is called, +.EE +.RE +. +. +_endif()dnl +.TP +.BI .IB " italic-text bold-text "\c +\&.\|.\|.\& +Set each argument in italics and bold, +alternately. +. +. +_ifstyle()dnl +.RS +.IP +.\" from src/preproc/pic/pic.1.man +.EX +In places where +\&.IB n th +is allowed, +.EE +.RE +. +. +_endif()dnl +.TP +.BI .IR " italic-text roman-text "\c +\&.\|.\|.\& +Set each argument in italics and roman, +alternately. +. +. +_ifstyle()dnl +.RS +.IP +.\" from src/preproc/pic/pic.1.man +.EX +Use GNU +\&.IR pic \[aq]s +\&.B figname +command to change the name of the vbox. +.EE +.RE +. +. +_endif()dnl +.TP +.BI .RB " roman-text bold-text "\c +\&.\|.\|.\& +Set each argument in roman and bold, +alternately. +. +. +_ifstyle()dnl +.RS +.IP +.\" from src/preproc/pic/pic.1.man +.EX +if +\&.I file +is +\&.RB \[rs][lq] \[rs]\- \[rs][rq], +the standard input stream is read. +.RE +.EE +. +. +_endif()dnl +.TP +.BI .RI " roman-text italic-text "\c +\&.\|.\|.\& +Set each argument in roman and italics, +alternately. +. +. +_ifstyle()dnl +.RS +.IP +.\" from src/preproc/pic/pic.1.man +.EX +\&.RI ( tpic +was a fork of AT&T +\&.I pic \" AT&T +by Tim Morgan of the University of California at Irvine +.EE +.RE +. +. +_endif()dnl +.\" ==================================================================== +.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 +_ifstyle()dnl +package assumes \(lqn\(rq; +that is, +the width of a letter \(lqn\(rq in the font current when the macro is +called +(see section \(lqMeasurements\(rq in +.MR groff @MAN7EXT@ ). +_endif()dnl +_ifnotstyle()dnl +package assumes \(lqn\(rq. +_endif()dnl +. +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 @MAN7EXT@ ) +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. +_ifstyle()dnl +. +. +.P +It may be helpful to think of the left margin and indentation as related +but distinct concepts; +.IR groff 's +implementation of the +.I man +macro package tracks them separately. +. +The left margin is manipulated by +.B .RS +and +.B .RE +(and by +.\".BR .TH ,\" True but not to be encouraged within a document. +.B .SH +and +.BR .SS , +which reset it to the default). +. +Indentation is controlled by the paragraphing macros +(though, +again, +.\".BR .TH , +.B .SH +and +.B .SS +reset it); +it is imposed by the +.BR .TP , +.BR .IP , +and deprecated +.B .HP +macros, +and cancelled by +.B .P +and its synonyms. +. +An extensive example follows. +. +. +.P +This ordinary +.RB ( .P ) +paragraph is not in a relative inset nor does it possess an indentation. +. +. +.RS +.P +Now we have created a relative inset +(in other words, +moved the left margin) +with +.B .RS +and started another ordinary paragraph with +.BR .P . +. +. +.TP +.B tag +This tagged paragraph, +set with +.BR .TP , +is still within the +.B .RS +region, +but lines after the first have a supplementary indentation that the +tag lacks. +. +. +.IP +A paragraph like this one, +set with +.BR .IP , +will appear to the reader as also associated with the tag above, +because +.B .IP +re-uses the previous paragraph's indentation unless given an argument +to change it. +. +This paragraph is affected both by the moved left margin +.RB ( .RS ) +and indentation +.RB ( .IP ). +. +.TS +box; +l. +This table is affected both by +the left margin and indentation. +.TE +. +. +.IP \(bu +This indented paragraph has a bullet for a tag, +making it more obvious that the left margin and indentation are +distinct; +only the former affects the tag, +but both affect the text of the paragraph. +. +. +.br +.ne 3v +.P +This ordinary +.RB ( .P ) +paragraph resets the indentation, +but the left margin is still inset. +. +.TS +box; +l. +This table is affected only +by the left margin. +.TE +.RE +. +. +.P +Finally, +we have ended the relative inset by using +.BR .RE , +which +(because we used only one +.BR .RS / .RE +pair) +has reset the left margin to the default. +. +This is an ordinary +.B .P +paragraph. +. +. +.P +Resist the temptation to mock up tabular or multi-column output with +tab characters or the indentation arguments to +.BR .IP , +.BR .TP , +.BR .RS , +or the deprecated +.BR .HP ; +the result may not render comprehensibly on an output device you fail to +check, +or which is developed in the future. +. +The table preprocessor +.MR @g@tbl @MAN1EXT@ +can likely meet your needs. +_endif()dnl +. +. +.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 +_ifstyle()dnl +and 0.4v for typesetting devices +(\(lqv\(rq is a unit of vertical distance, +where 1v is the distance between adjacent text baselines in a +single-spaced document). +_endif()dnl +_ifnotstyle()dnl +and 0.4v for typesetting devices. +_endif()dnl +. +(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. +. +_ifnotstyle()dnl +None of these is necessary in a contemporary man page; +see +.MR groff_man_style @MAN7EXT@ . +_endif()dnl +. +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. +_ifstyle()dnl +. +. +.P +None of the above is necessary in a contemporary man page. +. +.B \e*S +is superfluous, +since type size changes are invisible on terminal devices and macros +that change it restore its original value afterward. +. +Better alternatives exist for the rest; +simply use the +.BR \(rs(rg , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9, Solaris +.BR \(rs(lq , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9 +.BR \(rs(rq , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9 +and +.B \(rs(tm \" Heirloom Doctools, mandoc, neatmkfn, Plan 9 +special character escape sequences directly. +. +Unless a man page author is aiming for a pathological level of +portability, +such as the composition of pages for consumption on simulators of 1980s +Unix systems +(or Solaris +.IR troff , +though even it supports +.BR \(rs(rg ), +the above strings should be avoided. +. +. +.\" ==================================================================== +.SS Portability +.\" ==================================================================== +. +It is wise to quote multi-word section and subsection headings; +the +.B .SH +and +.B .SS +macros of +.MR man 7 +implementations descended from Seventh Edition Unix supported six +arguments at most. +. +A similar restriction applied to the +.BR .B , +.BR .I , +.BR .SM , +and font style alternation macros. +. +. +.P +The two major syntactical categories for formatting control in the +.I roff +language are requests and escape sequences. +. +Since the +.I man +macros are implemented in terms of +.I groff +requests and escape sequences, +one can, +in principle, +supplement the functionality of +.I man +with these lower-level elements where necessary. +. +. +.br +.ne 2v +.P +However, +using raw +.I groff +requests +(apart from the empty request +.RB \(lq . \(rq)\& +is likely to make your page render poorly when processed by other tools; +many of these attempt to interpret page sources directly for conversion +to HTML. +. +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 omitted +or presented incomprehensibly. +. +. +.P +For portability to modern viewers, +it is best to write your page solely with the macros described in this +page +(except for the ones identified as deprecated, +which should be avoided). +. +The macros we have described as extensions +.RB ( .EX / .EE , +.BR .SY / .YS , +.BR .TQ , +.BR .UR / .UE , +.BR .MT / .ME , +.BR .MR , +and +.BR .SB ) +should be used with caution, +as they may not be built in to some viewer that is important to your +audience. +. +See +.I \%an\-ext.tmac +in section \(lqFiles\(rq below. +. +. +.P +Similar caveats apply to escape sequences. +. +Some escape sequences are however required for correct typesetting +even in man pages and usually do not cause portability problems. +. +Several of these render glyphs corresponding to punctuation code points +in the Unicode basic Latin range +(U+0000\(enU+007F) +that are handled specially in +.I roff +input; +the escape sequences below must be used to render them correctly and +portably when documenting material that uses them +syntactically\(emnamely, +any of the set +.B \(aq \- \(rs \(ha \(ga \(ti +(apostrophe, +dash or minus, +backslash, +caret, +grave accent, +tilde). +. +. +.br +.ne 2v +.TP +.B \e\(dq +Comment. +. +Everything after the double-quote to the end of the input line is +ignored. +. +Whole-line comments should be placed immediately after the empty request +.RB (\(lq . \(rq). +. +. +.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 appears to +.I groff +as a single input line. +. +Use this escape sequence to split excessively long input lines for +document maintenance. +. +. +.TP +.B \e% +Control hyphenation. +. +The location of this escape sequence within a word marks a hyphenation +point, +supplementing +.IR groff 's +automatic hyphenation patterns. +. +At the beginning of a word, +it suppresses any hyphenation breaks within +.I except +those specified with +.BR \e% . +. +. +.TP +.B \e: +Insert a non-printing break point. +. +A word can break at such a point, +but a hyphen glyph is not written to the output if it does. +. +This escape sequence is an input word boundary, +so the remainder of the word is subject to hyphenation as normal. +. +You can use +.B \e: +and +.B \e% +in combination to control breaking of a file name or URI or to permit +hyphenation only after certain explicit hyphens within a word. +. +See subsection \[lq]Hyperlink macros\[rq] above for an example. +. +. +.IP +This escape sequence is a +.I groff +extension also supported by Heirloom Doctools +.I troff \" Heirloom +050915 (September 2005), +.I mandoc +1.14.5 (2019-03-10), +and +.I neatroff +(commit 399a4936, +2014-02-17), +but not by Plan\~9, +Solaris, +or Documenter's Workbench +.IR troff s. \" Plan 9, Solaris, DWB +.\" as of this writing, 2022-08-13 +. +. +.TP +.B \e\(ti +Adjustable non-breaking space. +. +Use this escape sequence to prevent a break inside a short phrase or +between a numerical quantity and its corresponding unit(s). +. +. +.RS +.IP +.EX +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\e\(tilanguage. +.EE +.RE +. +. +.\" BEGIN Keep in sync with groff.texi node "Other Differences" and +.\" groff_diff(7). +.IP +This escape sequence is a +.I groff +extension also supported by Heirloom Doctools +.I troff \" Heirloom +050915 (September 2005), +.I mandoc +1.9.5 (2009-09-21), +.I neatroff +(commit 1c6ab0f6e, +2016-09-13), +and +Plan\~9 from User Space +.I troff \" Plan 9 +(commit 93f8143600, +2022-08-12), +but not by Solaris +or Documenter's Workbench +.IR troff s. \" Solaris, DWB +.\" as of this writing, 2022-08-13 +.\" END Keep in sync with groff.texi node "Other Differences" and +.\" groff_diff(7). +. +. +.TP +.B \e& +Dummy character. +. +Insert at the beginning of an input line to prevent a dot or apostrophe +from being interpreted as beginning a +.I roff +control line. +. +Append to an end-of-sentence punctuation sequence to keep it from being +recognized as such. +. +. +.TP +.B \e| +Thin space +(one-sixth em on typesetters, +zero-width on terminals); +a non-breaking space. +. +Used primarily in ellipses +(\(lq.\e|.\e|.\(rq) +to space the dots more pleasantly on typesetting devices like +.BR dvi , +.BR pdf , +and +.BR ps . +. +. +.TP +.B \ec +End a text line without inserting space or attempting a break. +. +.\" TODO: When we explain what a "sentence" is, move this parenthetical +.\" there. +Normally, +if filling is enabled, +the end of a text line is treated like a space; +.\" end-of-sentence detection is performed, and... +an output line +.I may +be broken there +(if not, +an adjustable space is inserted); +if filling is disabled, +the line +.I will +be broken there, +as in +.BR .EX / .EE +examples. +. +The next line is interpreted as usual and can `include' a macro call +(contrast with +.BI \e newline\/\c +). +. +.B \(rsc +is useful when three font styles are +needed in a single word, +as in a command synopsis. +. +. +.RS +.IP +.\" from contrib/pdfmark/pdfroff.1.man +.EX +\&.RB [ \e\-\e\-stylesheet=\ec +\&.IR name ] +.EE +.RE +. +. +.IP +It also helps when changing font styles in +.BR .EX / .EE +examples, +since they are not filled. +. +. +.RS +.IP +.\" from src/devices/grotty/grotty.1.man +.EX +\&.EX +$ \ec +\&.B groff \e\-T utf8 \e\-Z \ec +\&.I file \ec +\&.B | grotty \e\-i +\&.EE +.EE +.RE +. +. +.IP +Alternatively, +and perhaps with better portability, +the +.B \ef +font selection escape sequence can be used; +see below. +. +Using +.B \ec +to continue a +.B .TP +paragraph tag across multiple input lines will render incorrectly with +.I groff +1.22.3, +.I mandoc +1.14.1, +older versions of these programs, +and perhaps with some other formatters. +. +. +.TP +.B \ee +Format the current escape character on the output; +widely used in man pages to render a backslash glyph. +. +.\" Don't bold the .ec request in this discussion; it's not a major +.\" topic of _this_ page as it would be in groff(7). Also, we don't +.\" want to encourage people to mess with this old kludge by drawing +.\" attention to it. +It works reliably as long as the \[lq].ec\[rq] request is not used, +which should never happen in man pages, +and it is slightly more portable than the more explicit +.B \e(rs +(\(lqreverse solidus\(rq) special character escape sequence. +. +. +.TP +.BR \efB ,\~ \efI ,\~ \efR ,\~ \efP +Switch to bold, +italic, +roman, +or back to the previous style, +respectively. +. +Either +.B \ef +or +.B \ec +is needed when three different font styles are required in a word. +. +. +.RS +.IP +.\" second example from contrib/pdfmark/pdfroff.1.man +.EX +\&.RB [ \e\-\e\-reference\e\-dictionary=\efI\e,name\e/\efP ] +.IP +\&.RB [ \e\-\e\-reference\e\-dictionary=\ec +\&.IR name ] +.EE +.RE +. +. +.IP +Style escape sequences may be more portable than +.BR \ec . +. +As shown above, +it is up to you to account for italic corrections with +.\" Normally we don't quote escape sequences, but these use +.\" potentially-confusing prose punctuation. +.RB \(lq \^\e\|/\^ \(rq +and +.RB \(lq \^\e\^, \(rq, +which are themselves GNU extensions, +if desired and if supported by your implementation. +. +. +.IP +.B \efP +reliably returns to the style in use immediately preceding the +previous +.B \ef +escape sequence only if no +sectioning, +paragraph, +or style macro calls have intervened. +. +. +.IP +As long as at most two styles are needed in a word, +style macros like +.B .B +and +.B .BI +usually result in more readable +.I roff +source than +.B \ef +escape sequences do. +. +. +.P +Several special characters are also widely portable. +.\" meaning: groff, Heirloom Doctools troff, neatroff, mandoc +. +Except for +.BR \[rs]\- , +.BR \[rs](em , +and +.BR \[rs](ga , +AT&T +.I troff +did not consistently `define' the characters listed below, +.\" Only \-, \(em, and \(ga were documented in CSTR #54 (1976). CSTR +.\" #54 (1992) offers no _comprehensive_ list but shows \(en in its +.\" PostScript DESC file example. In DWB 3.3, \(aq was supported by the +.\" "post" device, and \(dq by "pcl" and "Latin1". +but its descendants, +like Plan\~9 or Solaris +.IR troff , \" Plan 9, Solaris +can be made to support them by defining them in font description files, +making them aliases of existing glyphs if necessary; +see +.MR groff_font @MAN5EXT@ . +. +. +.TP +.B \e\- +Minus sign or basic Latin hyphen-minus. +. +This escape sequence produces the Unix command-line option dash in the +output. +. +.RB \(lq \- \(rq +is a hyphen in the +.I roff +language; +some output devices replace it with U+2010 +(hyphen) +or similar. +. +. +.TP +.B \e(aq +Basic Latin neutral apostrophe. +. +Some output devices format +.RB \(lq\| \(aq \|\(rq +as a right single quotation mark. +. +. +.br +.ne 3v +.TP +.B \e(oq +.TQ +.B \e(cq +Opening (left) and closing (right) single quotation marks. +. +Use these for paired directional single quotes, +\(oqlike this\(cq. +. +. +.TP +.B \e(dq +Basic Latin quotation mark +(double quote). +. +Use in macro calls to prevent +.\" This page prefers double quotes, but not here because they are more +.\" confusing to the eye when another double quote is what is quoted! +.RB \(oq\| \(dq \|\(rq +.\" AT&T: .RB ` """' +from being interpreted as beginning a quoted argument, +or simply for readability. +. +. +.RS +.IP +.\" from src/preproc/eqn/eqn.1.man +.EX +\&.TP +\&.BI \(dqsplit \e(dq\(dq text \e(dq +.EE +.RE +. +. +.br +.\" XXX: We need only 2v, but 2v more are necessary due to bad +.\" interaction with TP's own use of the ne request. +.ne 4v +.TP +.B \e(lq +.TQ +.B \e(rq +Left and right double quotation marks. +. +Use these for paired directional double quotes, +\(lqlike this\(rq. +. +. +.TP +.B \e(em +Em-dash. +. +Use for an interruption\(emsuch as this one\(emin a sentence. +. +. +.TP +.B \e(en +En-dash. +. +Use to separate the ends of a range, +particularly between numbers; +for example, +\(lqthe digits 1\(en9\(rq. +. +. +.TP +.B \e(ga +Basic Latin grave accent. +. +Some output devices format +.RB \(lq\| \(ga \|\(rq +as a left single quotation mark. +. +. +.TP +.B \e(ha +Basic Latin circumflex accent +(\(lqhat\(rq). +. +Some output devices format +.RB \(lq \(ha \(rq +as U+02C6 +(modifier letter circumflex accent) +or similar. +. +. +.TP +.B \e(rs +Reverse solidus +(backslash). +. +The backslash is the default escape character in the +.I roff +language, +so it does not represent itself in output. +. +Also see +.B \ee +above. +. +. +.TP +.B \e(ti +Basic Latin tilde. +. +Some output devices format +.RB \(lq \(ti \(rq +as U+02DC +(small tilde) +or similar. +. +. +.P +For maximum portability, +escape sequences and special characters not listed above are better +avoided in man pages. +_endif()dnl +. +. +.\" ==================================================================== +.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 +_ifnotstyle()dnl +(every 0.5i). +_endif()dnl +_ifstyle()dnl +(every 0.5i [inches]). +_endif()dnl +. +.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 @g@tbl @MAN1EXT@ +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 @MAN7EXT@ +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 @MAN7EXT@ . +. +. +.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 @MAN7EXT@ . +. +. +.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. +_ifstyle()dnl +. +(\(lqTitles\(rq is the +.I roff +term for headers and footers.) +_endif()dnl +. +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 @MAN7EXT@ ). +. +_ifstyle()dnl +For example, +the option +.B \-rX2 +produces the following page +numbers: 1, +2, +2a, +2b, +\&.\|.\|.\|, +2aa, +2ab, +and so on. +_endif()dnl +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I @MACRODIR@/\:an\:.tmac +Most +.I man +macros are defined in this file. +. +It also loads extensions from +.I \%an\-ext.tmac +(see below). +. +. +.TP +.I @MACRODIR@/\:\%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 @MACRODIR@/\:\%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 @MACRODIR@/\:man\:.tmac +This is a wrapper that loads +.IR an.tmac . +. +. +.TP +.I @MACRODIR@/\:\%mandoc\:.tmac +This is a wrapper that loads +.IR \%andoc.tmac . +. +. +.TP +.I @LOCALMACRODIR@/\:\%man\:\%.local +Put site-local changes and customizations into this file. +_ifstyle()dnl +. +. +.RS +.RS +.P +.EX +\&.\e" Use narrower indentation on terminals and similar. +\&.if n .nr IN 4n +\&.\e" Put only one space after the end of a sentence. +\&.ss 12 0 \e" See groff(@MAN7EXT@). +\&.\e" Keep pages narrow even on wide terminals. +\&.if n .if \(rsn[LL]>78n .nr LL 78n +\&.\e" Ensure hyperlinks are enabled for terminals. +\&.nr U 1 +.EE +.RE +.RE +. +. +.IP +On multi-user systems, +it is more considerate to users whose preferences may differ from the +administrator's to be less aggressive with such settings, +or to permit their override with a user-specific +.I man.local +file. +. +Place the requests below at the end of the site-local file to +manifest courtesy. +. +.br +.ne 3v +.RS +.RS +.EX +\&.soquiet \eV[XDG_CONFIG_HOME]/man.local +\&.soquiet \eV[HOME]/.man.local +.EE +.RE +. +However, +a security-sandboxed +.MR man 1 \" such as man-db 2.8.5 +program may lack permission to open such files. +.RE +. +. +.\" ==================================================================== +.SH Notes +.\" ==================================================================== +. +Some tips on troubleshooting your man pages follow. +. +. +.TP +\(bu Some ASCII characters look funny or copy and paste wrong. +. +On devices with large glyph repertoires, +like UTF-8-capable terminals and PDF, +several keyboard glyphs are mapped to code points outside the Unicode +basic Latin range because that usually results in better typography in +the general case. +. +When documenting GNU/Linux command or C language syntax, +however, +this translation is sometimes not desirable. +. +. +.IP +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +c c +rfCB lfCB. +To get a \(lqliteral\(rq.\|.\|. .\|.\|.should be input. +_ +\(aq \(rs(aq +\- \(rs\- +\(rs \(rs(rs +\(ha \(rs(ha +\(ga \(rs(ga +\(ti \(rs(ti +_ +.TE +. +. +.IP +Additionally, +if a neutral double quote (") is needed in a macro argument, +you can use +.B \(rs(dq +to get it. +. +You should +.I not +use +.B \(rs(aq +for an ordinary apostrophe +(as in \(lqcan't\(rq) +or +.B \(rs\- +for an ordinary hyphen +(as in \(lqword-aligned\(rq). +. +Review subsection \(lqPortability\(rq above. +. +. +.TP +\(bu Do I ever need to use an empty macro argument ("")? +. +Probably not. +. +When this seems necessary, +often a shorter or clearer alternative is available. +. +. +.IP +.if t .ne 10v +.if n .ne 16v \" account for horizontal rules +.TS +c c +lfCB lfCB. +Instead of.\|.\|. .\|.\|.should be considered. +_ +\&.TP \(dq\(dq .TP +_ +\&.BI \(dq\(dq \fIitalic-text bold-text .IB \fIitalic-text bold-text +_ +\&.TH foo 1 \(dq\(dq \(dqfoo 1.2.3\(dq .TH foo 1 \ +\f(CIyyyy\fP-\f(CImm\fP-\f(CIdd\fP \(dqfoo 1.2.3\(dq +_ +\&.IP \(dq\(dq 4n .IP +_ +\&.IP \(dq\(dq 4n .RS 4n +\fIparagraph .P +\fR.\|.\|. \fIparagraph +\fR.\|.\|. .RE +_ +\&.B one two \(dq\(dq three .B one two three +.TE +. +. +.IP +In the title heading +.RB ( .TH ), +the date of the page's last revision is more important than packaging +information; +it should not be omitted. +. +Ideally, +a page maintainer will keep both up to date. +. +. +.IP +.B .IP +is sometimes ill-understood and misused, +especially when no marker argument is supplied\(eman indentation +argument is not required. +. +By setting an explicit indentation, +you may be overriding the reader's preference as set with the +.B \-rIN +option. +. +If your page renders adequately without one, +use the simpler form. +. +If you need to indent multiple (unmarked) paragraphs, +consider setting an inset region with +.B .RS +and +.B .RE +instead. +. +. +.IP +In the last example, +the empty argument does have a subtly different effect than its +suggested replacement: +the empty argument causes an additional space character to be +interpolated between the arguments \(lqtwo\(rq and \(lqthree\(rq\(embut +it is a regular breaking space, +so it can be discarded at the end of an output line. +. +It is better not to be subtle, +particularly with space, +which can be overlooked in source and rendered forms. +. +. +.TP +.RB \(bu " .RS" " doesn't indent relative to my indented paragraph." +. +The +.B .RS +macro sets the left margin; +that is, +the position at which an +.I ordinary +paragraph +.RB ( .P +and its synonyms) +will be set. +. +.BR .IP , +.BR .TP , +and the deprecated +.B .HP +use the same default indentation. +. +If not given an argument, +.B .RS +moves the left margin by this same amount. +. +To create an inset relative to an indented paragraph, +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 +.B .P +paragraph. +. +See subsection \(lqHorizontal and vertical spacing\(rq above for the +values. +. +. +.IP +Another approach you can use with tagged paragraphs is to place an +.B .RS +call immediately after the paragraph tag; +this will also force a break regardless of the width of the tag, +which some authors prefer. +. +Follow-up paragraphs under the tag can then be set with +.B .P +instead of +.BR .IP . +. +Remember to use +.B .RE +to end the indented region before starting the next tagged paragraph +(at the appropriate nesting level). +. +. +.TP +.RB \(bu " .RE" " doesn't move the inset back to the expected level." +.TQ +\(bu warning: scaling unit invalid in context +.TQ +\(bu warning: register \(aqan\-saved\-margin\c +.IR n "\(aq not defined" +.TQ +\(bu warning: register \(aqan\-saved\-prevailing\-indent\c +.IR n "\(aq not defined" +. +The +.B .RS +macro takes an +.I indentation amount +as an argument; +the +.B .RE +macro's argument is a specific +.I inset level. +. +.B .RE\~1 +goes to the level before any +.B .RS +macros were called, +.B .RE\~2 +goes to the level of the first +.B .RS +call you made, +and so forth. +. +If you desire symmetry in your macro calls, +simply issue one +.B .RE +without an argument +for each +.B .RS +that precedes it. +. +. +.IP +After calls to the +.B .SH +and +.B .SS +sectioning macros, +all relative insets are cleared and calls to +.B .RE +have no effect until +.B .RS +is used again. +. +. +.TP +\(bu Do I need to keep typing the indentation in a series of \c +.BR .IP " calls?" +. +Not if you don't want to change it. +. +Review subsection \(lqHorizontal and vertical spacing\(rq above. +. +. +.IP +.if t .ne 5v +.if n .ne 7v \" account for horizontal rules +.TS +c c +lfCB lfCB. +Instead of.\|.\|. .\|.\|.should be considered. +_ +\&.IP \(rs(bu 4n .IP \(rs(bu 4n +\fIparagraph \fIparagraph +\&.IP \(rs(bu 4n .IP \(rs(bu +\fIanother-paragraph \fIanother-paragraph +_ +.TE +. +. +.TP +\(bu Why doesn't the package provide a string to insert an ellipsis? +. +Examples of ellipsis usage are shown above, +in subsection \[lq]Command synopsis macros\[rq]. +. +The idiomatic +.I roff +ellipsis is three dots (periods) +with thin space escape sequences +.B \[rs]| +internally separating them. +. +Since dots both begin control lines and are candidate end-of-sentence +characters, +however, +it is sometimes necessary to prefix and/or suffix an ellipsis with the +dummy character escape sequence +.BR \[rs]& . +. +That fact stands even if a string is defined to contain the sequence; +further, +if the string ends with +.BR \[rs]& , +end-of-sentence detection is defeated when you use the string at the end +of an actual sentence. +. +(Ending a sentence with an ellipsis is often poor style, +but not always.) +. +A hypothetical string +.B EL +that contained an ellipsis, +but not the trailing dummy character +.BR \[rs]& , +would then need to be suffixed with the latter +when not ending a sentence. +. +. +.IP +.if t .ne 5v +.if n .ne 7v \" account for horizontal rules +.TS +C C +LfCB LfCB. +Instead of.\|.\|. .\|.\|.do this. +_ +\&.ds EL \[rs]&.\[rs]|.\[rs]|. Arguments are +Arguments are .IR src-file\[rs]\[ti] .\[rs]|.\[rs]|.\[rs]& +\&.IR src-file\[rs]\[ti] \[rs]*(EL\[rs]& .IR dest-dir . +\&.IR dest-dir . +_ +.TE +. +. +.IP +The first column practices a false economy; +the savings in typing is offset by the cost of obscuring even the +suggestion of an ellipsis to a casual reader of the source document, +and reduced portability to +.RI non- roff +man page formatters that cannot handle string definitions. +. +. +.IP +There is an ellipsis code point in Unicode, +and some fonts have an ellipsis glyph, +which some man pages have accessed in a non-portable way with the +font-dependent +.B \[rs]N +escape sequence. +. +We discourage the use of these; +on terminals, +they may crowd the dots into a half-width character cell, +and will not render at all if the output device doesn't have the glyph. +. +In syntax synopses, +missing ellipses can cause great confusion. +. +Dots and space are universally supported. +.\" XXX: Does an unconditional _preceding_ dummy character cause +.\" problems? +_endif()dnl +. +. +.\" ==================================================================== +.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. +_ifstyle()dnl +Raymond also originated the portability section, +to which +.MT schwarze@\:usta\:.de +Ingo Schwarze +.ME +contributed most of the material on escape sequences. +_endif()dnl +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.MR @g@tbl @MAN1EXT@ , +.MR @g@eqn @MAN1EXT@ , +and +.MR @g@refer @MAN1EXT@ +are preprocessors used with man pages. +. +.MR man 1 +describes the man page librarian on your system. +. +.MR groff_mdoc @MAN7EXT@ +details the +.I groff +version of the BSD-originated alternative macro package for man pages. +. +. +.P +_ifstyle()dnl +.MR groff_man @MAN7EXT@ , +_endif()dnl +_ifnotstyle()dnl +.MR groff_man_style @MAN7EXT@ , +_endif()dnl +.MR groff @MAN7EXT@ , +.MR groff_char @MAN7EXT@ , +.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: |