{
    "mode": "man",
    "parameter": "groff_man",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/groff_man/7/json",
    "generated": "2026-06-15T13:12:50Z",
    "synopsis": "groff -man [option ...] [input-file ...]\ngroff -m man [option ...] [input-file ...]",
    "sections": {
        "NAME": {
            "content": "groffman - GNU roff macro package for formatting man pages\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "groff -man [option ...] [input-file ...]\ngroff -m man [option ...] [input-file ...]\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The  man  macro  package for groff is used to produce manual pages (“man pages”) like the one\nyou are reading.  GNU roff's implementation was written by James Clark.\n\nThis document presents the macros thematically to aid learners;  for  those  needing  only  a\nquick  reference, the following table lists them alphabetically, with cross-references to ap‐\npropriate subsections below.\n\nMacro   Meaning                         Subsection\n───────────────────────────────────────────────────────────────────\n.B      Bold                            Font style macros\n.BI     Bold, italic alternating        Font style macros\n.BR     Bold, roman alternating         Font style macros\n.EE     Example end                     Document structure macros\n.EX     Example begin                   Document structure macros\n.I      Italic                          Font style macros\n.IB     Italic, bold alternating        Font style macros\n.IP     Indented paragraph              Paragraph macros\n.IR     Italic, roman alternating       Font style macros\n.LP     (Left) paragraph                Paragraph macros\n.ME     Mail-to end                     Hyperlink and email macros\n.MT     Mail-to start                   Hyperlink and email macros\n.OP     (Command-line) option           Command synopsis macros\n.P      Paragraph                       Paragraph macros\n.PP     Paragraph                       Paragraph macros\n.RB     Roman, bold alternating         Font style macros\n.RE     Relative-indent end             Document structure macros\n.RI     Roman, italic alternating       Font style macros\n.RS     Relative-indent start           Document structure macros\n.SB     Small bold                      Font style macros\n.SH     Section heading                 Document structure macros\n.SM     Small                           Font style macros\n.SS     Subection heading               Document structure macros\n.SY     Synopsis start                  Command synopsis macros\n.TH     Title heading                   Document structure macros\n.TP     Tagged paragraph                Paragraph macros\n.TQ     Tagged paragraph continuation   Paragraph macros\n.UE     URL end                         Hyperlink and email macros\n.UR     URL start                       Hyperlink and email macros\n.YS     Synopsis end                    Command synopsis macros\n\nMacros whose use we discourage (.AT, .BT, .DT, .HP, .PD, .PT, and .UC) are described in  sub‐\nsection “Deprecated features”, below.\n",
            "subsections": [
                {
                    "name": "Macro reference preliminaries",
                    "content": "Each  macro is described in a tagged paragraph.  Closely related macros, such as .EX and .EE,\nare grouped together.\n\nOptional macro arguments are indicated by surrounding them with square brackets.  If a  macro\naccepts  multiple  arguments,  arguments  containing  whitespace  must be double-quoted (\"one\ntwo\"), to be interpreted correctly.  Most macro arguments are strings that will be output  as\ntext; exceptions are noted.\n\nBear in mind that groff is fundamentally a programming system for typesetting.  Consequently,\nthe verb “to set” is frequently used below in the sense “to typeset”.\n"
                },
                {
                    "name": "Document structure macros",
                    "content": "The highest level of organization of a man page is determined by this group of  macros.   .TH\n(title  heading)  identifies  the document as a man page and defines information enabling its\nindexing by mandb(8) or a similar tool.  Sections (.SH), one of which is mandatory  and  many\nof  which  are standardized, facilitate quick location of relevant material by the reader and\naid the man page writer to discuss all essential aspects of the topic.  Subsections (.SS) are\noptional  and  permit sections that grow long to develop in a controlled way.  Many technical\ndiscussions require examples; lengthy ones, especially those reflecting multiple lines of in‐\nput  to  or  output from the system, are usefully bracketed by .EX and .EE.  When none of the\nforegoing meets a structural demand, a section of the discussion  can  be  manually  indented\nwithin .RS and .RE macros.\n\n.TH title section [footer-middle] [footer-outside] [header-middle]\nDefine  the title of the man page as title and the section as section.  See man(1) for\ndetails on the section numbers and suffixes applicable to your system.  title and sec‐\ntion are positioned together at the left and right in the header line (with section in\nparentheses immediately appended to title).  footer-middle is centered in  the  footer\nline.   footer-outside is positioned at the left in the footer line (or at the left on\neven pages and at the right on odd pages if double-sided printing is active).  header-\nmiddle is centered in the header line.  If section is a simple integer between 1 and 9\n(inclusive), or is exactly “3p”, there is no need to specify header-middle; the  macro\npackage will supply text for it.\n\nFor HTML output, headers and footers are completely suppressed.\n\nAdditionally,  this macro starts a new page; the page number is reset to 1 (unless the\n-rC1 option is given on the command line).  This feature is intended only for  format‐\nting multiple man pages.\n\nA  man  page should contain exactly one .TH call at or near the beginning of the file,\nprior to any other macro calls.\n\nBy convention, footer-middle is the most recent modification  date  of  the  man  page\nsource  document, and footer-outside is the name and version or release of the project\nproviding it.\n\n.SH [heading-text]\nSet heading-text as a section heading flush left.  The text following .SH  up  to  the\nend  of  the line, or the text on the next input line if .SH is given no arguments, is\nset in bold (or the font specified by the string register HF) slightly larger than the\nbase  font  size.   Additionally, the left margin and indentation affecting subsequent\ntext are reset to their default values.  Text on input lines after heading-text is set\nas a normal paragraph (.PP).\n\nThe  content  of heading-text and ordering of sections has been standardized by common\npractice, as has much of the layout of material within sections.  For example, a  sec‐\ntion called “Name” or “NAME” must exist, must be the first section after the .TH call,\nand must contain only a line of the form\npage-topic[, ...] \\- summary-description\nfor a man page to be properly indexed.  See man(7) for the conventions  prevailing  on\nyour system.\n\n.SS [subheading-text]\nSet  subheading-text  as  a subsection heading indented (by default) partway between a\nsection heading and a normally-indented paragraph (.PP).  The text following .SS up to\nthe  end of the line, or the text on the next input line if .SS is given no arguments,\nis set in bold (or the font specified by the string register  HF)  at  the  base  font\nsize.  Additionally, the left margin and indentation affecting subsequent text are re‐\nset to their default values.  Text on input lines after subheading-text is  set  as  a\nnormal paragraph (.PP).\n"
                },
                {
                    "name": ".EX",
                    "content": ".EE    Begin  and  end  example.   After .EX, filling and hyphenation are disabled and a con‐\nstant-width (monospaced) font is selected.  Calling .EE enables filling  and  restores\nthe previous hyphenation setting and font.\n\nExample  regions  are  useful  for formatting code, shell sessions, and text file con‐\ntents.\n\nThese macros are defined on many (but not all) legacy  Unix  systems  running  classic\ntroff.   To be certain your page will be portable to those systems, copy their defini‐\ntions from the an-ext.tmac file of a groff installation.\n\n.RS [indent]\nMove the left margin to the right by the value indent, if specified, and by a  default\namount  otherwise;  see  subsection “Horizontal and vertical spacing” below.  Calls to\n.RS can be nested; each call increments by 1 the indentation level used by  .RE.   The\nindentation level prior to any .RS calls is 1.\n\n.RE [level]\nMove the left margin back to that corresponding to indentation level level.  If no ar‐\ngument is given, move the left margin one level back.\n"
                },
                {
                    "name": "Paragraph macros",
                    "content": "A typical paragraph (.PP) is set at the current left margin, which  by  default  is  indented\nfrom the left margin of the output device.  In man pages and other technical literature, def‐\ninition lists are frequently encountered; these can be set as “tagged  paragraphs”  (.TP  and\n.TQ), which have one or more leading tags followed by a paragraph that has an additional left\nindent.  The indented paragraph (.IP) macro is useful to continue the indented content  of  a\nnarrative started with .TP, or to present an itemized or ordered list.\n"
                },
                {
                    "name": ".LP",
                    "content": ""
                },
                {
                    "name": ".PP",
                    "content": ".P     Begin a new paragraph; these macros are synonymous.  They break the output line at the\ncurrent position, followed by a vertical space downward by a default amount (which can\nbe  changed  by  the  deprecated .PD macro).  The font size and style are reset to de‐\nfaults; see subsection “Font style macros” below.  Finally, the left margin and inden‐\ntation are reset to default values.\n\n.TP [indent]\nSet  a  tagged, indented paragraph.  The input line following this macro, known as the\ntag, is printed at the current left margin.  Subsequent text is indented by indent, if\nspecified,  and by a default amount otherwise; see subsection “Horizontal and vertical\nspacing” below.\n\nIf the tag is not as wide as the indentation, the paragraph starts on the same line as\nthe  tag, at the applicable indentation, and continues on the following lines.  Other‐\nwise, the descriptive part of the paragraph begins on the line following the tag,  en‐\ntirely  indented.   The line containing the tag can include a macro call, for instance\nto set the tag in bold with .B.\n\n.TP was used to write the first paragraph of this description of .TP, and .IP the sub‐\nsequent ones.\n\n.TQ    Set  an  additional  tag  for a paragraph tagged with .TP.  The pending output line is\nbroken.  The tag on the input line following this macro and subsequent lines are  han‐\ndled as with .TP.\n\nThis macro is not defined on legacy Unix systems running classic troff.  To be certain\nyour page will be portable to those systems, copy its definition from the  an-ext.tmac\nfile of a groff installation.\n\nThe descriptions of .LP, .PP, and .P above were written using .TP and .TQ.\n\n.IP [tag] [indent]\nSet  an  indented  paragraph  with  an optional tag.  The tag and indent arguments, if\npresent, are handled as with .TP, with the exception that the tag argument to .IP can‐\nnot include a macro call.\n\nTwo convenient use cases for .IP are\n\n(1) to  start  a new paragraph with the same indentation as the previous .IP or\n.TP paragraph, if no indent argument is given; and\n\n(2) to set a paragraph with a short tag that  is  not  semantically  important,\nsuch as a bullet (•)—obtained with the ‘\\(bu’ character escape—or list enu‐\nmerator, as seen in this very paragraph.\n"
                },
                {
                    "name": "Command synopsis macros",
                    "content": "Command synopses are a staple of section 1 and 8 man pages.  These macros  aid  you  to  con‐\nstruct  one  that has the classical Unix appearance.  Furthermore, some tools are able to in‐\nterpret these macros semantically and treat them appropriately for localization  and/or  pre‐\nsentation.  A command synopsis is wrapped in .SY/.YS calls, with command-line options of some\nformats indicated by .OP.\n\nThese macros are not defined on legacy Unix systems running classic  troff.   To  be  certain\nyour page will be portable to those systems, copy their definitions from the an-ext.tmac file\nof a groff installation.\n\n.SY command\nBegin synopsis.  Hyphenation is turned off.  The command argument is set in bold.  The\noutput  line  is filled as normal, but if a break is required, subsequent output lines\nare indented by the width of command plus a space.\n\n.OP option-name [option-argument]\nIndicate an optional command parameter called option-name, which is set in  bold.   If\nthe  option  takes an argument, specify option-argument using a noun, abbreviation, or\nhyphenated noun phrase.  If present, option-argument is preceded by a space and set in\nitalics.  Square brackets (in roman) surround both arguments.\n\n.YS    End synopsis.  Restore indentation and hyphenation to previous values.\n\nMultiple  .SY/.YS blocks can be specified, for instance to distinguish differing modes of op‐\neration of a complex command like tar(1); each will be separated by a paragraph space.\n\n.SY can also be repeated multiple times before a closing .YS, which  is  useful  to  indicate\nsynonymous ways of invoking a particular mode of operation.\n\nFor example,\n\n.SY groff\n.OP \\-abcegiklpstzCEGNRSUVXZ\n.OP \\-d cs\n.OP \\-f fam\n.OP \\-F dir\n.OP \\-I dir\n.OP \\-K arg\n.OP \\-L arg\n.OP \\-m name\n.OP \\-M dir\n.OP \\-n num\n.OP \\-o list\n.OP \\-P arg\n.OP \\-r cn\n.OP \\-T dev\n.OP \\-w name\n.OP \\-W name\n.RI [ file\n\\&.\\|.\\|.\\&]\n.YS\n.\n.SY groff\n.B \\-h\n.SY groff\n.B \\-\\-help\n.YS\n\nproduces the following output.\n\ngroff [-abcegiklpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir] [-I dir] [-K arg] [-L arg]\n[-m name] [-M dir] [-n num] [-o list] [-P arg] [-r cn] [-T dev] [-w name]\n[-W name] [file ...]\n\ngroff -h\ngroff --help\n\nSeveral features of the above example are of note.\n\n•      The  empty  request (.), which does nothing, is used for vertical spacing in the input\nfile for readability by the document maintainer.  Do not put empty  lines  in  a  roff\nsource document.\n\n•      The command and option names are presented in bold to cue the user that they should be\ninput literally.\n\n•      Option dashes are specified with the ‘\\-’ escape sequence; this is an important  prac‐\ntice  to  make  them clearly visible and to facilitate cut-and-paste from the rendered\nman page to a shell prompt or text file.\n\n•      Option arguments and command operands are presented in  italics  (underlined  on  some\noutput  devices,  such  as terminals and emulators), to cue the user that they must be\nreplaced with appropriate text.\n\n•      Symbols that are neither to be typed literally nor simply replaced appear in the roman\nstyle; brackets surround optional arguments, and an ellipsis indicates that the previ‐\nous syntactical element may be repeated arbitrarily.\n\nSome man pages use a brace-and-pipe notation such as “{--diff|--compare}” to  indicate\nthat  one and only one of the ‘|’-separated items within the braces must be input.  If\nthis braced construct is furthermore surrounded by square brackets, it means  that  at\nmost one of the items is accepted.\n\nAuthors  of man pages should note the use of the zero-width space escape sequence ‘\\&’\non both sides of the ellipsis; this is a good practice to avoid surprises in the event\nthe  ellipsis  gets refilled in your text editor.  See “Portability”, below.  The mor‐\nbidly curious may consult groff(7) regarding the narrow-space escape sequence ‘\\|’.\n"
                },
                {
                    "name": "Hyperlink and email macros",
                    "content": "Email addresses are bracketed with .MT/.ME and URL hyperlinks with .UR/.UE.\n\nThese macros are not defined on legacy Unix systems running classic  troff.   To  be  certain\nyour page will be portable to those systems, copy their definitions from the an-ext.tmac file\nof a groff installation.\n\n.MT address\n.ME [punctuation]\nIdentify address as an RFC 6068 addr-spec for a “mailto:” URI with  the  text  between\nthe  two macro calls as the link text.  A punctuation argument to .ME is placed at the\nend of the link text without intervening space.  Note that address may not be  visible\nin the output text, particularly if the man page is being viewed as HTML.  On a device\nthat is not a browser, address is set in angle brackets after the link text and before\npunctuation.\n\nWhen rendered by groff to a TTY or PostScript output device,\n\nContact\n.MT fred.foonly@\\:fubar.net\nFred Foonly\n.ME\nfor more information.\n\ndisplays as: “Contact Fred Foonly ⟨fred.foonly@fubar.net⟩ for more information.”.\n\nThe use of ‘\\:’ to insert hyphenless discretionary breaks is a groff extension and can\nbe omitted.\n\n.UR URL\n.UE [punctuation]\nIdentify URL as an RFC 3986 URI hyperlink with the text between the two macro calls as\nthe  link  text.   A punctuation argument to .UE is placed at the end of the link text\nwithout intervening space.  Note that URL may not be visible in the output text,  par‐\nticularly if the man page is being viewed as HTML.  On a device that is not a browser,\nURL is set in angle brackets after the link text and before punctuation.\n\nWhen rendered by groff to a TTY or PostScript output device,\n\nThe GNU Project of the Free Software Foundation hosts the\n.UR https://\\:www.gnu.org/\\:software/\\:groff/\nGroff home page\n.UE .\n\ndisplays as: “The GNU Project of the Free Software Foundation  hosts  the  Groff  home\npage ⟨https://www.gnu.org/software/groff/⟩.”.\n\nThe use of ‘\\:’ to insert hyphenless discretionary breaks is a groff extension and can\nbe omitted.\n"
                },
                {
                    "name": "Font style macros",
                    "content": "The man macro package is limited in its  font  styling  options,  offering  only  bold  (.B),\nitalic (.I), and roman (the default).  Italic text is usually set underscored instead on ter‐\nminals and other classical nroff-style output devices.  The .SM and .SB macros  set  text  in\nroman  or  bold,  respectively,  at a smaller point size; these differ visually from regular-\nsized roman or bold text only on troff-style output devices.  The foregoing macros cause word\nbreaks  before  and after their arguments, but it is often necessary to set text in different\nstyles without intervening whitespace.  The macros .BI, .BR, .IB, .IR, .RB,  and  .RI,  where\n‘B’,  ‘I’,  and  ‘R’ indicate bold, italic, and roman, respectively, set their odd- and even-\nnumbered arguments in alternating styles, with no whitespace separating them.\n\nBecause font styles are presentational rather  than  semantic,  conflicting  traditions  have\narisen  regarding  which  font  styles should be used to mark file or path names, environment\nvariables, in-line literals, and even man page cross-references.\n\nThe default font size and family (for troff output devices) is 10-point Times.   The  default\nstyle is roman.\n\n.B [text]\nSet text in bold.  If the macro is given no arguments, the text of the next input line\nis set in bold.\n\nUse bold for literal portions of syntax synopses, for command-line options in  running\ntext,  and for literals that are major topics of the subject under discussion; for ex‐\nample, this page uses bold for macro and register names.  In .EX/.EE examples  of  in‐\nteractive I/O (such as a shell session), set only the user-typed input in bold.\n\n.I [text]\nSet  text  in italics.  If the macro is given no arguments, the text of the next input\nline is set in italics.\n\nUse italics for file and path names, for environment  variables,  for  enumeration  or\npreprocessor  constants  in  C, for variable (user-determined) portions of syntax syn‐\nopses, for the first occurrence only of a  technical  concept  being  introduced,  for\nnames  of  works of software (including commands and functions, but excluding names of\noperating systems or their kernels), and anywhere a parameter requiring replacement by\nthe user is encountered.  An exception involves variable text in a context that is al‐\nready marked up in italics, such as file or path names with  variable  components;  in\nsuch  cases,  follow  the  convention of mathematical typography: set the file or path\nname in italics as usual (see .IR below), but use roman for  the  variable  part,  and\nitalics again in running roman text when referring to the variable material.\n\n.SM [text]\nSet text one point size smaller than the default size.  If the macro is given no argu‐\nments, the text of the next input line is set smaller.\n\nNote: nroff-style output devices, such as terminals, will render text  at  the  normal\nfont  size instead.  Do not rely upon .SM to communicate semantic information distinct\nfrom using roman style at the normal size; it will be hidden from readers  using  such\ndevices.\n\n.SB [text]\nSet text in bold, one point size smaller than the default size.  If the macro is given\nno arguments, the text of the next input line is set smaller and in bold.\n\nNote: nroff-style output devices, such as terminals, will render text in bold  at  the\nnormal  font  size  instead.  Do not rely upon .SB to communicate semantic information\ndistinct from using bold style at the normal size; it will be hidden from readers  us‐\ning such devices.\n\nNote  what is not prescribed for setting in bold or italics above: elements of “synopsis lan‐\nguage” such as ellipses and brackets around options; proper names and adjectives;  titles  of\nanything  other  than works of literature or software; identifiers for standards documents or\ntechnical reports such as CSTR #54, RFC 1918, Unicode 11.0, or  POSIX.1-2017;  acronyms;  and\noccurrences  after the first of a technical term or piece of jargon.  Again, the names of op‐\nerating systems and their kernels are, by practically universal convention, set in roman.\n\nBe frugal with the use of italics for emphasis, and particularly with the use of bold.  Brief\nruns of literal text, such as references to individual characters or short strings, including\nsection and subsection headings of man pages, are suitable objects  for  quotation;  see  the\n‘\\(lq’, ‘\\(rq’, ‘\\(oq’, and ‘\\(cq’ escapes in subsection “Portability” below.\n\nUnlike  the  above font style macros, the font alternation macros below accept only arguments\non the same line as the macro call.  If whitespace is required within one of  the  arguments,\nfirst  consider  whether  the same result could be achieved with as much clarity by using the\nsingle-style macros on separate input lines.  When it cannot, double-quote an  argument  with\none  or more embedded space characters.  Setting all three different styles within one white‐\nspace-delimited word presents challenges; it is possible with the ‘\\c’ and/or  ‘\\f’  escapes,\nbut see subsection “Portability” below for caveats.\n\n.BI bold-text italic-text ...\nSet each argument in bold and italics, alternately.\n\n.BI \\-r name = n\n\n.BR bold-text roman-text ...\nSet each argument in bold and roman, alternately.\n\nAny such change becomes effective with the first use of\n.BR .NH ,\n.I after\nthe new alias is defined.\n\n.IB italic-text bold-text ...\nSet each argument in italics and bold, alternately.\n\nAll macro package files must be named\n.IB name .tmac\nto fully use the\n.I tmac\nmechanism.\n\n.IR italic-text roman-text ...\nSet each argument in italics and roman, alternately.\n\nThis is the first command of the\n.IR prologue .\n\n.RB roman-text bold-text ...\nSet each argument in roman and bold, alternately.\n\nAlso, the statement\n.RB \\(oq \"delim on\" \\(cq\nis not handled specially.\n\n.RI roman-text italic-text ...\nSet each argument in roman and italics, alternately.\n\n.RI [ file\n\\&.\\|.\\|.\\&]\n"
                },
                {
                    "name": "Horizontal and vertical spacing",
                    "content": "The indent argument accepted by .RS, .IP, .TP, and the deprecated .HP is a number plus an op‐\ntional scaling indicator.  If no scaling indicator is given, the  man  package  assumes  ‘n’;\nthat is, the width of a letter “n” in the font current when the macro is called.  See section\n“Numerical Expressions” in groff(7) for further details.  An indent specified in  a  call  to\n.IP,  .TP, or the deprecated .HP persists until (1) another of these macros is called with an\nexplicit indent argument, or (2) .SH, .SS, or .PP or its synonyms is called; these clear  the\nindent entirely.\n\nIndents  set  by  .RS move the left margin and persist until .RS, .RE, .SH, or .SS is called.\nThe default indentation, exhibited by ordinary .PP paragraphs not within an .RS/.RE  relative\nindent,  is 7.2n in troff mode and 7n in nroff mode.  The HTML output device is an exception;\nit ignores indentation completely.  This same indentation is used again (additively) for  the\ndefaults of .IP, .TP, .RS, and the deprecated .HP.  Section headings (.SH) are set flush with\nthe left margin of the output device, and subsection headings (.SS) are indented 3n.\n\nResist the temptation to mock up tabular or multi-column output with ASCII tab characters  or\nthe  indentation arguments to .IP, .TP, .RS, or the deprecated .HP; the result may not render\ncomprehensibly on an output device you fail to check, or which is developed  in  the  future.\nThe table preprocessor tbl(1) can likely meet your needs.\n\nThe  following macros cause a line break with the insertion of vertical space: .SH, .SS, .TP,\n.TQ, .PP (and its synonyms), .IP, and the deprecated .HP.  The default inter-section and  in‐\nter-paragraph spacing is 1 line in nroff mode, and 0.4v in troff mode.  (The deprecated macro\n.PD can change this vertical spacing, but its use is discouraged.)  The macros .RS, .RE, .EX,\nand .EE also cause a break but no insertion of vertical space.\n"
                },
                {
                    "name": "Number registers",
                    "content": "Number registers are described in section “Options” below.\n"
                },
                {
                    "name": "String registers",
                    "content": "The following strings are defined.\n\n\\*R    expands to the character escape for the “registered sign” glyph, ‘\\(rg’, if available,\nand “(Reg.)” otherwise.\n\n\\*S    expands to an escape setting the font size to the document default.\n\n\\*(HF  expands to the font identifier used to print headings and subheadings.  The default is\n‘B’.\n\n\\*(lq\n\\*(rq  expand  to the character escapes for left and right double-quotation marks, ‘\\(lq’ and\n‘\\(rq’, respectively.\n\n\\*(Tm  expands to the character escape for the “trade mark sign” glyph, ‘\\(tm’, if available,\nand “(TM)” otherwise.\n"
                },
                {
                    "name": "Interaction with preprocessors",
                    "content": "When  a preprocessor like tbl or eqn is needed, a hint can be given to the man page formatter\nby making the first line of a man page look like this:\n\n'\\\" word\n\nNote that the line starts with an apostrophe ('), not a dot, and that a single space  charac‐\nter  follows the double quote.  The word consists of one letter for each needed preprocessor:\n‘e’ for eqn, ‘r’ for refer, and ‘t’ for tbl.  Modern implementations of the man  program  in‐\nterpret this first line and automatically call the right preprocessor(s).\n\nThe  usual  tbl and eqn macros for table and equation inclusion, .TS, .T&, .TE, .EQ, and .EN,\nmay be used freely.  Note that nroff output devices are extremely limited in presentation  of\nmathematical equations.\n"
                },
                {
                    "name": "Portability",
                    "content": "The  two  major syntactical categories of roff languages are requests and escapes.  Since the\nman macros are implemented in terms of groff requests and escapes,  one  can,  in  principle,\nsupplement the functionality of man with these lower-level elements where necessary.\n\nNote, however, that using raw groff requests is likely to make your page render poorly on the\nclass of viewers that transform it to HTML.  Some requests make  implicit  assumptions  about\nthings  like character and page sizes that may not hold in an HTML environment; also, many of\nthese viewers don't interpret the full groff vocabulary, a problem that can lead to  portions\nof your text being silently dropped.\n\nFor portability to modern viewers, it is best to write your page entirely with the macros de‐\nscribed in this page (except for the ones identified as deprecated, which should be avoided).\nThe  macros  we  have  described  as  extensions (.EX/.EE, .SY/.OP/.YS, .UR/.UE, and .MT/.ME)\nshould be used with caution, as they may not yet be built in to some viewer that is important\nto your audience.  If in doubt, copy the implementation into your page—after the .TH call and\nthe “Name” section, to accommodate timid mandb implementations.\n\nSimilar caveats apply to escapes.  Some escape sequences are  however  required  for  correct\ntypesetting even in man pages and usually do not cause portability problems:\n\n\\\"     Comment.   Everything  after the double-quote to the end of the input line is ignored.\nWhole-line comments are frequently placed immediately after the empty request ‘.’.\n\n\\newline\nJoin the next input line to the current one.  Except for the update of the input  line\ncounter  (used for diagnostic messages and related purposes), a series of lines ending\nin backslash-newline is transparent to groff.  Use this escape  to  break  excessively\ninput long lines for document maintenance.\n\n\\~     Adjustable, non-breaking space character.  Use this escape to prevent a break inside a\nshort phrase or between a numerical quantity and its corresponding unit(s).\n\nBefore starting the motor, set the output speed to\\~1.\nThere are 1,024\\~bytes in 1\\~kiB.\nCSTR\\~#8 documents the B language.\n\n\\&     Zero-width space.  Append to an input line to prevent an  end-of-sentence  punctuation\nsequence from being recognized as such, or insert at the beginning of an input line to\nprevent a dot or apostrophe from being interpreted as the beginning of a roff request.\n\n\\(aq   ASCII apostrophe.  Use for syntax elements of programming languages because some  out‐\nput devices might replace unescaped apostrophes with right single quotation marks.\n\n\\(oq   Opening single quotation mark.\n\\(cq   Closing single quotation mark.\n\nUse these for paired directional single quotes, ‘like this’.\n\n\\(dq   ASCII  double-quote.  Sometimes needed after macro calls to prevent the interpretation\nof the ASCII quotation mark character ‘\"’ as the beginning or end of a macro argument.\n\n\\(lq   Left double quotation mark.\n\\(rq   Right double quotation mark.\n\nUse these for paired directional double quotes, “like this”.\n\n\\(em   Em-dash.  Use for an interruption in a sentence—such as this one.\n\n\\(en   En-dash.  Use to separate the two ends of a range, in particular between numbers,  for\nexample: the digits 1–9.\n\n\\(ga   ASCII  grave  accent.   Use  for syntax elements of programming languages, for example\nshell command substitutions, because some output devices might replace unescaped grave\naccents with left single quotation marks.\n\n\\(ha   ASCII  circumflex  accent.   Use  for syntax elements of programming languages because\nsome output devices might replace unescaped circumflex accents with  non-ASCII  glyphs\nlike the Unicode U+02C6 modifier letter circumflex.\n\n\\(ti   ASCII tilde.  Use for syntax elements of programming languages because some output de‐\nvices might replace unescaped tildes with non-ASCII glyphs  like  the  Unicode  U+02DC\nsmall tilde.\n\n\\-     Minus  sign.   Also use this to display syntax elements that require the ASCII hyphen-\nminus character, for example command-line options and C language operators.   The  un‐\nescaped  ‘-’  input character is not appropriate for these cases because it may render\nas a hyphen on some output devices.\n\n\\c     If this escape sequence occurs at the end of an input line, no white space is inserted\nbetween  the  last glyph on it and the first glyph resulting from the next input line.\nThis is occasionally useful when three different fonts are needed in a single word.\n\nNormally, the final output file should be named\n.IB file .pdf\\c\n\\&.\n\nNote that when using this trick with the .BI or .RI macros, you will need to  manually\nadd  an  italic  correction escape ‘\\/’ before the ‘\\c’ due to way macros expand their\narguments.\n\nFiles processed with\n.B groff \\-mom\n(or\n.BI \"\\-m \" mom\\/\\c\n) produce PostScript output by default.\n\nAlternatively, and perhaps with better portability, the ‘\\f’ font escape sequence  can\nbe  used;  see  below.  Using ‘\\c’ to include the output from more than one input line\ninto the next-line argument of a .TP macro will render incorrectly with groff  1.22.3,\nmandoc  1.14.1,  older versions of these programs, and perhaps with some other format‐\nters.\n\n\\e     Widely used in man pages to represent a backslash output glyph.  It works reliably  as\nlong as the .ec request is not used, which should never happen in man pages, and it is\nslightly more portable than the more exact ‘\\(rs’ (“reverse solidus”) escape sequence.\n\n\\fB, \\fI, \\fR, \\fP\nSwitch to bold, italic, roman, or back to the  previous  font,  respectively.   Either\nthese  or  ‘\\c’  is  needed when three different fonts are required in a single white‐\nspace-delimited word.\n\n.RB [ \\-\\-reference\\-dictionary=\\fI\\,name\\/\\fP ]\n\n.RB [ \\-\\-reference\\-dictionary=\\c\n.IR name ]\n\nFont escapes may be more portable than ‘\\c’.  As shown above, it is up to you  to  ac‐\ncount  for  italic  corrections  with ‘\\/’ and ‘\\,’, which are themselves groff exten‐\nsions, if desired and if supported by your implementation.\n\nNote that ‘\\fP’ reliably returns to the style in use immediately preceding the  previ‐\nous ‘\\f’ escape only if no sectioning, paragraph, or font face macro calls have inter‐\nvened.\n\nAs long as only two fonts are needed in any single whitespace-delimited word, font al‐\nternation  macros  like  .BI usually result in more readable source code than ‘\\f’ es‐\ncapes do.\n\nFor maximum portability, escape sequences and special characters not listed above are  better\navoided in man pages.\n"
                },
                {
                    "name": "Deprecated features",
                    "content": "Use of the following is discouraged.\n\n.AT [system [release]]\nAlter the footer for use with AT&T man pages, overriding any definition of the footer-\noutside argument to .TH.  This macro exists only for compatibility; don't use it.\n\nThe first argument system can be:\n\n3      7th edition (default)\n\n4      System III\n\n5      System V\n\nThe optional second argument release specifies the release number, such as in  “System\nV Release 3”.\n\n.BT    Set the page footer.  Redefine this macro to get control of the footer.\n\n.DT    Set  tabs  every 0.5 inches.  Since this macro is always called during a .TH macro, it\nmakes sense to call it only if the tab positions have been changed.\n\nUse of this presentation-level macro is deprecated.  It translates poorly to HTML, un‐\nder  which  exact whitespace control and tabbing are not readily available.  Thus, in‐\nformation or distinctions that you use .DT to express are likely to be lost.   If  you\nfeel  tempted  to use it, you should probably be composing a table using tbl(1) markup\ninstead.\n\n.HP [indent]\nSet up a paragraph with a hanging left indentation.  The indent argument, if  present,\nis handled as with .TP.\n\nUse  of this presentation-level macro is deprecated.  While it is universally portable\nto legacy Unix systems, a hanging indentation  cannot  be  expressed  naturally  under\nHTML, and many HTML-based manual viewers simply interpret it as a starter for a normal\nparagraph.  Thus, any information or distinction you tried to express with the  inden‐\ntation may be lost.\n\n.PD [vertical-space]\nDefine  the vertical space between paragraphs or (sub)sections.  The optional argument\nvertical-space specifies the amount of space; the default scaling is ‘v’).  Without an\nargument,  the  spacing  is  reset  to its default value; see “Horizontal and vertical\nspacing” above.\n\nUse of this presentation-level macro is deprecated.  It translates poorly to HTML, un‐\nder  which  exact  control of inter-paragraph spacing is not readily available.  Thus,\ninformation or distinctions that you use .PD to express are likely to be lost.\n\n.PT    Set the page header.  Redefine this macro to get control of the header.\n\n.UC [version]\nAlter the footer for use with BSD man pages, overriding any definition of the  footer-\noutside argument to .TH.  This macro exists only for compatibility; don't use it.\n\nThe argument version can be:\n\n3      3rd Berkeley Distribution (default)\n\n4      4th Berkeley Distribution\n\n5      4.2 Berkeley Distribution\n\n6      4.3 Berkeley Distribution\n\n7      4.4 Berkeley Distribution\n"
                },
                {
                    "name": "History",
                    "content": "According to its own man(7) page, Version 7 Unix (1979) supported all of the macros described\nin this page not listed as GNU extensions, except .P, .SB, .SS, and the deprecated .AT,  .BT,\n.PT, and .UC.  The only string registers defined were R and S; no number registers were docu‐\nmented.\n"
                }
            ]
        },
        "OPTIONS": {
            "content": "The following groff options set number registers recognized and used by the man  macro  pack‐\nage.\n",
            "subsections": [
                {
                    "name": "-rcR=1",
                    "content": "This is the default in nroff mode.  Use -rcR=0 to disable it.\n"
                },
                {
                    "name": "-rC1",
                    "content": "number the pages continuously, rather than starting each at 1.\n"
                },
                {
                    "name": "-rD1",
                    "content": "ently; see the description of .TH in “Document structure macros”, above.\n"
                },
                {
                    "name": "-rFT=",
                    "content": "Set distance of the footer, relative to the bottom of the page if negative or relative\nto the top if positive, to footer-distance.  The default is -0.5i.\n"
                },
                {
                    "name": "-rHY=",
                    "content": "Set hyphenation flags.  Permissible values of flags are documented in section “Hyphen‐\nation” of groff(7).  The default is 4  if  continuous  rendering  is  enabled  (-rcR=1\nabove), and 6 otherwise.\n"
                },
                {
                    "name": "-rIN=",
                    "content": "Set  the body text indentation (for normal paragraphs) to indent.  See “Horizontal and\nvertical spacing” above for the default indentation value.  For nroff,  indent  should\nalways be an integer multiple of unit ‘n’ to get consistent indentation.\n"
                },
                {
                    "name": "-rLL=",
                    "content": "Set  line  length.  If this option is not given, the line length is set to respect any\nvalue set by a prior “.ll” request (which must be in effect when the .TH macro is  in‐\nvoked),  if this differs from the built-in default for the formatter; otherwise it de‐\nfaults to 78n in nroff mode and 6.5i in troff mode.\n\nNote that the use of a “.ll” request to initialize the line length  is  supported  for\nbackward compatibility with some versions of the man program; direct initialization of\nthe LL register should always be preferred to the use of such a request.  In  particu‐\nlar,  note  that  a  “.ll 65n” request does not preserve the normal nroff default line\nlength (the man default initialization to 78n prevails), whereas the -rLL=65n  option,\nor  an  equivalent “.nr LL 65n” request preceding the use of the .TH macro, does set a\nline length of 65n.\n"
                },
                {
                    "name": "-rLT=",
                    "content": "Set title length.  If this option is not given, the title length defaults to the  line\nlength.\n"
                },
                {
                    "name": "-rP",
                    "content": ""
                },
                {
                    "name": "-rS",
                    "content": "Use  point-size  as the base document font size.  Acceptable values are 10, 11, or 12.\nSee subsection “Font style macros” above for the default.\n"
                },
                {
                    "name": "-rSN=",
                    "content": "Set subsection indentation to subsection-indent.  See “Horizontal and  vertical  spac‐\ning” above for the default indentation value.\n"
                },
                {
                    "name": "-rX -rX2",
                    "content": "produces the following page numbers: 1, 2, 2a, 2b, 2c, and so on.\n"
                }
            ]
        },
        "FILES": {
            "content": "/usr/share/groff/1.22.4/tmac/man.tmac\n/usr/share/groff/1.22.4/tmac/an.tmac\nThese are wrapper files to call andoc.tmac.\n\n/usr/share/groff/1.22.4/tmac/andoc.tmac\nThis brief groff program detects whether the man or mdoc macro package is  being  used\nby  a  document  and loads the correct macro definitions, taking advantage of the fact\nthat pages using them must call .TH or .Dd, respectively, as their first  macro.   Be‐\ncause  the  wrappers  above load this file, a man program or user typing, for example,\n“groff -man page.1”, need not know which package the file page.1 uses.   Multiple  man\npages, in either format, can be handled.\n\n/usr/share/groff/1.22.4/tmac/an-old.tmac\nMost  man  macros  are  contained in this file.  It also loads the GNU extensions from\nan-ext.tmac (see below).\n\n/usr/share/groff/1.22.4/tmac/an-ext.tmac\nThe extension macro definitions for .SY, .OP, .YS, .TQ, .EX/.EE, .UR/.UE, and  .MT/.ME\nare  contained  in  this  file, which is written in classic troff and permissively li‐\ncensed—not copylefted.  Man page authors concerned about portability  to  legacy  Unix\nsystems  are encouraged to copy these definitions into their pages, and maintainers of\ntroff implementations or work-alike systems that format man pages  are  encouraged  to\nre-use them.\n\nNote  that  the  definitions  for these macros are read after the call of .TH, so they\nwill replace any macros of the same names preceding it in your file.  If you use  your\nown  implementations  of  these macros, they must be defined after calling .TH to have\nany effect.\n\n/usr/share/groff/site-tmac/man.local\nLocal changes and customizations should be put into this file.\n",
            "subsections": []
        },
        "NOTES": {
            "content": "Some tips on troubleshooting your man pages follow.\n\n• .RS doesn't indent relative to my indented paragraph\nThe .RS macro sets the indentation relative to the amount of a normal  paragraph  (.PP\nand its synonyms).  The same default indentation amount is used for .RS, .IP, .TP, and\nthe deprecated .HP.  If you need to start an indent relative to an indented paragraph,\ncall .RS repeatedly until an acceptable indentation is achieved, or give .RS an inden‐\ntation argument that is at least as much as the paragraph's indentation  amount  rela‐\ntive  to  an  adjacent .PP paragraph.  See “Horizontal and vertical spacing” above for\nthe values.\n\n• .RE doesn't reset the indent to the expected level\n• warning: scale indicator invalid in this context\n• warning: number register 'an-saved-marginn' not defined\n• warning: number register 'an-saved-prevailing-indentn' not defined\nThe .RS macro takes an indentation amount as an argument; the .RE macro's argument  is\na  specific  indentation  level.   .RE  1 goes to the level before any .RS macros were\ncalled, .RE 2 goes to the level of the first .RS call you made, and so forth.  If  you\ndesire symmetry in your macro calls, simply issue one .RE without an argument for each\n.RS that precedes it.\n\nAfter calls to the .SH and .SS sectioning macros, all relative indents are cleared and\ncalls to .RE have no effect.\n",
            "subsections": []
        },
        "AUTHORS": {
            "content": "The  GNU  version  of the man macro package was written by James Clark and contributors.  The\nextension macros were written by Werner  Lemberg  ⟨wl@gnu.org⟩  and  Eric  S.  Raymond  ⟨esr@\nthyrsus.com⟩.\n\nThis  document  was  originally written for the Debian GNU/Linux system by Susan G. Kleinmann\n⟨sgk@debian.org⟩.  It was corrected and updated by Werner Lemberg and  G.  Branden  Robinson.\nThe  extension  macros were documented by Eric S. Raymond; he also originated the portability\nsection, to which Ingo Schwarze contributed most of the material on escape sequences.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg,  is  the  main\ngroff documentation.  You can browse it interactively with “info groff”.\n\ntbl(1), eqn(1), and refer(1) are preprocessors used with man pages.\n\nman(1) describes the man page formatter on your system.\n\ngroffmdoc(7) describes the groff version of the BSD-originated alternative macro package for\nman pages.\n\ngroff(7), groffchar(7), man(7)\n\n\n\ngroff 1.22.4                                23 March 2022                               GROFFMAN(7)",
            "subsections": []
        }
    },
    "summary": "groffman - GNU roff macro package for formatting man pages",
    "flags": [
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "This is the default in nroff mode. Use -rcR=0 to disable it."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "number the pages continuously, rather than starting each at 1."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "ently; see the description of .TH in “Document structure macros”, above."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Set distance of the footer, relative to the bottom of the page if negative or relative to the top if positive, to footer-distance. The default is -0.5i."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Set hyphenation flags. Permissible values of flags are documented in section “Hyphen‐ ation” of groff(7). The default is 4 if continuous rendering is enabled (-rcR=1 above), and 6 otherwise."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Set the body text indentation (for normal paragraphs) to indent. See “Horizontal and vertical spacing” above for the default indentation value. For nroff, indent should always be an integer multiple of unit ‘n’ to get consistent indentation."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Set line length. If this option is not given, the line length is set to respect any value set by a prior “.ll” request (which must be in effect when the .TH macro is in‐ voked), if this differs from the built-in default for the formatter; otherwise it de‐ faults to 78n in nroff mode and 6.5i in troff mode. Note that the use of a “.ll” request to initialize the line length is supported for backward compatibility with some versions of the man program; direct initialization of the LL register should always be preferred to the use of such a request. In particu‐ lar, note that a “.ll 65n” request does not preserve the normal nroff default line length (the man default initialization to 78n prevails), whereas the -rLL=65n option, or an equivalent “.nr LL 65n” request preceding the use of the .TH macro, does set a line length of 65n."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Set title length. If this option is not given, the title length defaults to the line length."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": ""
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Use point-size as the base document font size. Acceptable values are 10, 11, or 12. See subsection “Font style macros” above for the default."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Set subsection indentation to subsection-indent. See “Horizontal and vertical spac‐ ing” above for the default indentation value."
        },
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "produces the following page numbers: 1, 2, 2a, 2b, 2c, and so on."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "tbl",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/tbl/1/json"
        },
        {
            "name": "eqn",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/eqn/1/json"
        },
        {
            "name": "refer",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/refer/1/json"
        },
        {
            "name": "man",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/man/1/json"
        },
        {
            "name": "groffmdoc",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/groffmdoc/7/json"
        },
        {
            "name": "groff",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/groff/7/json"
        },
        {
            "name": "groffchar",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/groffchar/7/json"
        },
        {
            "name": "man",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/man/7/json"
        }
    ]
}