{
    "mode": "man",
    "parameter": "groff_mdoc",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/groff_mdoc/7/json",
    "generated": "2026-10-06T03:29:13Z",
    "sections": {
        "Name": {
            "content": "groffmdoc — compose BSD-style manual (man) pages with GNU roff\n",
            "subsections": []
        },
        "Synopsis": {
            "content": "groff -mdoc file ...\n",
            "subsections": []
        },
        "Description": {
            "content": "The  GNU implementation of the mdoc macro package is part of the groff(1) document formatting\nsystem.  mdoc is a structurally- and semantically-oriented package for  writing  Unix  manual\npages  with  troff(1).   Its predecessor, the man(7) package, primarily addressed page layout\nand presentational concerns, leaving the selection of fonts and other typesetting details  to\nthe  individual author.  This discretion has led to divergent styling practices among authors\nusing it.\n\nmdoc organizes its macros into domains.  The page structure domain lays out the page and com‐\nprises titles, section headings, displays, and  lists.   The  general  text  domain  supplies\nmacros  to quote or style text, or to interpolate common noun phrases.  The manual domain of‐\nfers semantic macros corresponding to the terminology used by practitioners in discussion  of\nUnix  commands, routines, and files.  Manual domain macros distinguish command-line arguments\nand options, function names, function parameters, pathnames, variables, cross  references  to\nother manual pages, and so on.  These terms are meaningful both to the author and the readers\nof  a manual page.  It is hoped that the resulting increased consistency of the man page cor‐\npus will enable easier translation to future documentation tools.\n\nThroughout Unix documentation, a manual entry is referred to simply as a “man page”,  regard‐\nless  of  its length, without gendered implication, and irrespective of the macro package se‐\nlected for its composition.\n",
            "subsections": []
        },
        "Getting started": {
            "content": "The mdoc package attempts to simplify man page authorship and maintenance  without  requiring\nmastery  of  the  roff language.  This document presents only essential facts about roff. For\nfurther background, including a discussion of basic typographical concepts  like  “breaking”,\n“filling”,  and  “adjustment”,  see  roff(7).   Specialized  units of measurement also arise,\nnamely ens, vees, inches, and points, abbreviated “n”, “v”, “i”, and “p”,  respectively;  see\nsection “Measurements” of groff(7).\n\nFor brief examples, we employ an arrow notation illustrating a transformation of input on the\nleft  to rendered output on the right.  Consider the .Dq macro, which double-quotes its argu‐\nments.\n.Dq man page  → “man page”\n",
            "subsections": [
                {
                    "name": "Usage",
                    "content": "An mdoc macro is called by placing the roff control character, ‘.’ (dot) at the beginning  of\na line followed by its name.  In this document, we often discuss a macro name with this lead‐\ning dot to identify it clearly, but the dot is not part of its name.  Space or tab characters\ncan  separate  the  dot  from the macro name.  Arguments may follow, separated from the macro\nname and each other by spaces, but not tabs.  The dot at the beginning of the  line  prepares\nthe  formatter  to  expect a macro name.  A dot followed immediately by a newline is ignored;\nthis is called the empty request.  To begin an input line with a dot (or a neutral apostrophe\n‘'’) in some context other than a macro call, precede it with the ‘\\&’ escape sequence;  this\nis  a dummy character, not formatted for output.  The backslash is the roff escape character;\nit can appear anywhere and it always followed by at least one more character.  If followed by\na newline, the backslash escapes the input line break; you can thus keep  input  lines  to  a\nreasonable length without affecting their interpretation.\n\nMacros in GNU troff accept an unlimited number of arguments, in contrast to other troffs that\noften  can't handle more than nine.  In limited cases, arguments may be continued or extended\non the next input line without resort to  the  ‘\\newline’  escape  sequence;  see  subsection\n“Extended arguments” below.  Neutral double quotes \" can be used to group multiple words into\nan argument; see subsection “Passing space characters in an argument” below.\n\nMost  of mdoc's general text and manual domain macros parse their argument lists for callable\nmacro names.  This means that an argument in the list matching a general text or  manual  do‐\nmain macro name (and defined to be callable) will be called with the remaining arguments when\nit  is  encountered.   In such cases, the argument, although the name of a macro, is not pre‐\nceded by a dot.  Macro calls can thus be nested.  This approach to macro argument  processing\nis a unique characteristic of the mdoc package, not a general feature of roff syntax.\n\nFor  example,  the  option macro, .Op, may call the flag and argument macros, .Fl and .Ar, to\nspecify an optional flag with an argument.\n.Op Fl s Ar bytes      → [-s bytes]\nTo prevent a word from being interpreted as a macro name, precede it with the  dummy  charac‐\nter.\n.Op \\&Fl s \\&Ar bytes  → [Fl s Ar bytes]\n\nIn  this document, macros whose argument lists are parsed for callable arguments are referred\nto as parsed, and those that may be called from an argument list are referred to as callable.\nThis usage is a technical faux pas, since all mdoc macros are  in  fact  interpreted  (unless\nprevented with ‘\\&’), but as it is cumbersome to constantly refer to macros as “being able to\ncall other macros”, we employ the term “parsed” instead.  Except where explicitly stated, all\nmdoc macros are parsed and callable.\n\nIn  the following, we term an mdoc macro that starts a line (with a leading dot) a command if\na distinction from those appearing as arguments of other macros is necessary.\n"
                },
                {
                    "name": "Passing space characters in an argument",
                    "content": "Sometimes it is desirable to give a macro an argument containing one or  more  space  charac‐\nters,  for  instance  to specify a particular arrangement of arguments demanded by the macro.\nAdditionally, quoting multi-word arguments that are to be treated the same  makes  mdoc  work\nfaster; macros that parse arguments do so once (at most) for each.  For example, the function\ncommand  .Fn  expects its first argument to be the name of a function and any remaining argu‐\nments to be function parameters.  Because C language standards mandate the inclusion of types\nand identifiers in the parameter lists of function definitions, each ‘Fn’ parameter after the\nfirst will be at least two words in length, as in “int foo”.\n\nThere are a few ways to embed a space in a macro argument.  One is to  use  the  unadjustable\nspace  escape  sequence  \\space.  The formatter treats this escape sequence as if it were any\nother printable character, and will not break a line there as it would a word space when  the\noutput  line  is  full.   This  method is useful for macro arguments that are not expected to\nstraddle an output line boundary, but has a drawback: this space does not adjust as others do\nwhen the output line is formatted.  An alternative is to use the unbreakable space escape se‐\nquence, ‘\\~’, which cannot break but does adjust.  This groff extension  is  widely  but  not\nperfectly portable.  Another method is to enclose the string in double quotes.\n.Fn fetch char\\ *str   → fetch(char *str)\n.Fn fetch char\\~*str   → fetch(char *str)\n.Fn fetch \"char *str\"  → fetch(char *str)\nIf  the  ‘\\’  before the space in the first example or the double quotes in the third example\nwere omitted, ‘.Fn’ would see three arguments, and the  result  would  contain  an  undesired\ncomma.\n.Fn fetch char *str    → fetch(char, *str)\n"
                },
                {
                    "name": "Trailing space characters",
                    "content": "It  is wise to remove trailing spaces from the ends of input lines.  Should the need arise to\nput a formattable space at the end of a line, do so  with  the  unadjustable  or  unbreakable\nspace escape sequences.\n"
                },
                {
                    "name": "Formatting the backslash glyph",
                    "content": "When  you  need the roff escape character ‘\\’ to appear in the output, use ‘\\e’ or ‘\\(rs’ in‐\nstead.  Technically, ‘\\e’ formats the current escape character; it works reliably as long  as\nno  roff  request  is used to change it, which should never happen in man pages.  ‘\\(rs’ is a\ngroff special character escape sequence that explicitly formats the “reverse solidus”  (back‐\nslash) glyph.\n"
                },
                {
                    "name": "Other possible pitfalls",
                    "content": "groff mdoc warns when an empty input line is found outside of a display, a topic presented in\nsubsection  “Examples  and  displays” below.  Use empty requests to space the source document\nfor maintenance.\n\nLeading spaces cause a break and are formatted.  Avoid this  behaviour  if  possible.   Simi‐\nlarly,  do  not  put more than one space between words in an ordinary text line; they are not\n“normalized” to a single space as other text formatters might do.\n\nDon't try to use the neutral double quote character ‘\"’ to represent itself in  an  argument.\nUse  the  special  character escape sequence ‘\\(dq’ to format it.  Further, this glyph should\nnot be used for conventional quotation; mdoc offers several quotation macros.  See subsection\n“Enclosure and quoting macros” below.\n\nThe formatter attempts to detect the ends of sentences and by default puts the equivalent  of\ntwo  spaces between sentences on the same output line; see roff(7).  To defeat this detection\nin a parsed list of macro arguments, put ‘\\&’ before the punctuation mark.  Thus,\nThe\n.Ql .\ncharacter.\n.Pp\nThe\n.Ql \\&.\ncharacter.\n.Pp\n.No test .\ntest\n.Pp\n.No test.\ntest\ngives\nThe ‘’.  character\n\nThe ‘.’ character.\n\ntest.  test\n\ntest. test\nas output.  As can be seen in the first and third  output  lines,  mdoc  handles  punctuation\ncharacters  specially in macro arguments.  This will be explained in section “General syntax”\nbelow.\n\nA comment in the source file of a man page can begin with ‘.\\\"’ at  the  start  of  an  input\nline, ‘\\\"’ after other input, or ‘\\#’ anywhere (the last is a groff extension); the remainder\nof any such line is ignored.\n\nA man page template\nUse mdoc to construct a man page from the following template.\n\n.\\\" The following three macro calls are required.\n.Dd date\n.Dt topic [section-identifier [section-keyword-or-title]]\n.Os [package-or-operating system [version-or-release]]\n.Sh Name\n.Nm topic\n.Nd summary-description\n.\\\" The next heading is used in sections 2 and 3.\n.\\\" .Sh Library\n.\\\" The next heading is used in sections 1-4, 6, 8, and 9.\n.Sh Synopsis\n.Sh Description\n.\\\" Uncomment and populate the following sections as needed.\n.\\\" .Sh \"Implementation notes\"\n.\\\" The next heading is used in sections 2, 3, and 9.\n.\\\" .Sh \"Return values\"\n.\\\" The next heading is used in sections 1, 3, 6, and 8.\n.\\\" .Sh Environment\n.\\\" .Sh Files\n.\\\" The next heading is used in sections 1, 6, and 8.\n.\\\" .Sh \"Exit status\"\n.\\\" .Sh Examples\n.\\\" The next heading is used in sections 1, 4, 6, 8, and 9.\n.\\\" .Sh Diagnostics\n.\\\" .Sh Compatibility\n.\\\" The next heading is used in sections 2, 3, 4, and 9.\n.\\\" .Sh Errors\n.\\\" .Sh \"See also\"\n.\\\" .Sh Standards\n.\\\" .Sh History\n.\\\" .Sh Authors\n.\\\" .Sh Caveats\n.\\\" .Sh Bugs\n\nThe  first  items in the template are the commands .Dd, .Dt, and .Os.  They identify the page\nand are discussed below in section “Title macros”.\n\nThe remaining items in  the  template  are  section  headings  (.Sh);  of  which  “Name”  and\n“Description”  are  mandatory.   These  headings  are  discussed  in  section “Page structure\ndomain”, which follows section “Manual domain”.   Familiarize  yourself  with  manual  domain\nmacros first; we use them to illustrate the use of page structure domain macros.\n"
                }
            ]
        },
        "Conventions": {
            "content": "In  the descriptions of macros below, square brackets surround optional arguments.  An ellip‐\nsis (‘...’) represents repetition of the preceding argument zero or more times.   Alternative\nvalues  of a parameter are separated with ‘|’.  If a mandatory parameter can take one of sev‐\neral alternative values, use braces to enclose the set, with spaces and  ‘|’  separating  the\nitems.\nztar {c | x} [-w [-y | -z]] [-f archive] member ...\nAn  alternative to using braces is to separately synopsize distinct operation modes, particu‐\nlarly if the list of valid optional arguments is dependent on the user's choice of  a  manda‐\ntory parameter.\nztar c [-w [-y | -z]] [-f archive] member ...\nztar x [-w [-y | -z]] [-f archive] member ...\n\nMost macros affect subsequent arguments until another macro or a newline is encountered.  For\nexample,  ‘.Li  ls Bq Ar file’ doesn't produce ‘ls [file]’, but ‘ls [file]’.  Consequently, a\nwarning message is emitted for many commands if the first argument is itself a  macro,  since\nit  cancels  the  effect of the preceding one.  On rare occasions, you might want to format a\nword along with surrounding brackets as a literal.\n.Li \"ls [file]\"  → ls [file] # list any files named e, f, i, or l\n\nMany macros possess an implicit width, used when they are contained in  lists  and  displays.\nIf you avoid relying on these default measurements, you escape potential conflicts with site-\nlocal  modifications  of  the mdoc package.  Explicit -width and -offset arguments to the .Bl\nand .Bd macros are preferable.\n",
            "subsections": []
        },
        "Title macros": {
            "content": "We present the mandatory title macros first due to their importance even though they formally\nbelong to the page structure domain macros.  They designate the topic, date of last revision,\nand the operating system or software project associated with the page.  Call each once at the\nbeginning of the document.  They populate the page headers and footers,  which  are  in  roff\nparlance termed “titles”.\n\n.Dd date\nThis  first  macro of any mdoc manual records the last modification date of the docu‐\nment source.  Arguments are concatenated and separated with space characters.\n\nHistorically, date was written in U.S. traditional format, “Month day ,  year”  where\nMonth  is  the full month name in English, day an integer without a leading zero, and\nyear the four-digit year.  This localism is not enforced, however.   You  may  prefer\nISO 8601 format, YYYY-MM-DD. A date of the form ‘$Mdocdate: Month day year $’ is also\nrecognized.   It  is used in OpenBSD manuals to automatically insert the current date\nwhen committing.\n\nThis macro is neither callable nor parsed.\n\n.Dt topic [section-identifier [section-keyword-or-title]]\ntopic is the subject of the man page.  A section-identifier that begins with an inte‐\nger in the range 1–9 or is one of the words ‘unass’, ‘draft’, or  ‘paper’  selects  a\npredefined  section  title.  This use of “section” has nothing to do with the section\nheadings otherwise discussed in this page; it arises from the  organizational  scheme\nof printed and bound Unix manuals.\n\nIn  this  implementation,  the following titles are defined for integral section num‐\nbers.\n\n1   General Commands Manual\n2   System Calls Manual\n3   Library Functions Manual\n4   Kernel Interfaces Manual\n5   File Formats Manual\n6   Games Manual\n7   Miscellaneous Information Manual\n8   System Manager's Manual\n9   Kernel Developer's Manual\n\nA section title may be arbitrary or one of the following abbreviations.\n\nUSD     User's Supplementary Documents\nPS1     Programmer's Supplementary Documents\nAMD     Ancestral Manual Documents\nSMM     System Manager's Manual\nURM     User's Reference Manual\nPRM     Programmer's Manual\nKM      Kernel Manual\nIND     Manual Master Index\nLOCAL   Local Manual\nCON     Contributed Software Manual\n\nFor compatibility, ‘MMI’ can be used for ‘IND’, and ‘LOC’ for ‘LOCAL’.   Values  from\nthe  previous  table  will  specify a new section title.  If section-keyword-or-title\ndesignates a computer architecture recognized by groff mdoc, its value  is  prepended\nto  the  default section title as specified by the second parameter.  By default, the\nfollowing architecture keywords are defined.\n\nacorn26, acorn32, algor, alpha, amd64, amiga, amigappc, arc, arm, arm26, arm32,\narmish, atari, aviion, beagle, bebox, cats, cesfic, cobalt, dreamcast, emips,\nevbarm, evbmips, evbppc, evbsh3, ews4800mips, hp300, hp700, hpcarm, hpcmips,\nhpcsh, hppa, hppa64, i386, ia64, ibmnws, iyonix, landisk, loongson, luna68k,\nluna88k, m68k, mac68k, macppc, mips, mips64, mipsco, mmeye, mvme68k, mvme88k,\nmvmeppc, netwinder, news68k, newsmips, next68k, ofppc, palm, pc532, playstation2,\npmax, pmppc, powerpc, prep, rs6000, sandpoint, sbmips, sgi, sgimips, sh3, shark,\nsocppc, solbourne, sparc, sparc64, sun2, sun3, tahoe, vax, x68k, x8664, xen,\nzaurus\n\nIf a section title is not determined after the above  matches  have  been  attempted,\nsection-keyword-or-title is used.\n\nThe  effects  of  varying ‘.Dt’ arguments on the page header content are shown below.\nObserve how ‘\\&’ prevents the numeral 2 from being used to look up a predefined  sec‐\ntion title.\n\n.Dt foo 2       →  foo(2)     System Calls Manual      foo(2)\n.Dt foo 2 m68k  →  foo(2)   m68k System Calls Manual   foo(2)\n.Dt foo 2 baz   →  foo(2)     System Calls Manual      foo(2)\n.Dt foo \\&2 baz →  foo(2)             baz              foo(2)\n.Dt foo \"\" baz  →  foo                baz                 foo\n.Dt foo M Z80   →  foo(M)             Z80              foo(M)\n\nroff strings define section titles and architecture identifiers.  Site-specific addi‐\ntions might be found in the file mdoc.local; see section “Files” below.\n\nThis macro is neither callable nor parsed.\n\n.Os [operating-system-or-package-name [version-or-release]]\nThis  macro  associates  the document with a software distribution.  When composing a\nman page to be included in the base installation of an operating system, do not  pro‐\nvide  an  argument;  mdoc  will  supply  it.  In this implementation, that default is\n“Debian”.  It may be overridden in the site configuration file, mdoc.local; see  sec‐\ntion  “Files”  below.   A portable software package maintaining its own man pages can\nsupply its name and version number or release identifier as  optional  arguments.   A\nversion-or-release  argument  should  use  the standard nomenclature for the software\nspecified.  In the following table, recognized version-or-release arguments for  some\npredefined  operating  systems  are listed.  As with .Dt, site additions might be de‐\nfined in mdoc.local.\n\nATT        7th, 7, III, 3, V, V.2, V.3, V.4\n\nBSD        3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4\n\nNetBSD     0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a, 1.2b, 1.2c, 1.2d,\n1.2e, 1.3, 1.3a, 1.4, 1.4.1, 1.4.2, 1.4.3, 1.5, 1.5.1, 1.5.2, 1.5.3,\n1.6, 1.6.1, 1.6.2, 1.6.3, 2.0, 2.0.1, 2.0.2, 2.0.3, 2.1, 3.0, 3.0.1,\n3.0.2, 3.0.3, 3.1, 3.1.1, 4.0, 4.0.1, 5.0, 5.0.1, 5.0.2, 5.1, 5.1.2,\n5.1.3, 5.1.4, 5.2, 5.2.1, 5.2.2, 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4,\n6.0.5, 6.0.6, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 7.0, 7.0.1,\n7.0.2, 7.1, 7.1.1, 7.1.2, 7.2, 8.0, 8.1\n\nFreeBSD    1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5, 2.1.6, 2.1.7, 2.2,\n2.2.1, 2.2.2, 2.2.5, 2.2.6, 2.2.7, 2.2.8, 2.2.9, 3.0, 3.1, 3.2, 3.3,\n3.4, 3.5, 4.0, 4.1, 4.1.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.6.2, 4.7, 4.8,\n4.9, 4.10, 4.11, 5.0, 5.1, 5.2, 5.2.1, 5.3, 5.4, 5.5, 6.0, 6.1, 6.2,\n6.3, 6.4, 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 9.0,\n9.1, 9.2, 9.3, 10.0, 10.1, 10.2, 10.3, 10.4, 11.0, 11.1, 11.2, 11.3,\n12.0, 12.1\n\nOpenBSD    2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 3.0, 3.1, 3.2,\n3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 4.0, 4.1, 4.2, 4.3, 4.4, 4.5,\n4.6, 4.7, 4.8, 4.9, 5.0, 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8,\n5.9, 6.0, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6\n\nDragonFly  1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.8.1, 1.9, 1.10, 1.11,\n1.12, 1.12.2, 1.13, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8,\n2.9, 2.9.1, 2.10, 2.10.1, 2.11, 2.12, 2.13, 3.0, 3.0.1, 3.0.2, 3.1,\n3.2, 3.2.1, 3.2.2, 3.3, 3.4, 3.4.1, 3.4.2, 3.4.3, 3.5, 3.6, 3.6.1,\n3.6.2, 3.7, 3.8, 3.8.1, 3.8.2, 4.0, 4.0.1, 4.0.2, 4.0.3, 4.0.4,\n4.0.5, 4.0.6, 4.1, 4.2, 4.2.1, 4.2.2, 4.2.3, 4.2.4, 4.3, 4.4, 4.4.1,\n4.4.2, 4.4.3, 4.5, 4.6, 4.6.1, 4.6.2, 4.7, 4.8, 4.8.1, 4.9, 5.0,\n5.0.1, 5.0.2, 5.1, 5.2, 5.2.1, 5.2.2, 5.3, 5.4, 5.4.1, 5.4.2, 5.4.3,\n5.5, 5.6, 5.6.1, 5.6.2\n\nDarwin     8.0.0, 8.1.0, 8.2.0, 8.3.0, 8.4.0, 8.5.0, 8.6.0, 8.7.0, 8.8.0,\n8.9.0, 8.10.0, 8.11.0, 9.0.0, 9.1.0, 9.2.0, 9.3.0, 9.4.0, 9.5.0,\n9.6.0, 9.7.0, 9.8.0, 10.0.0, 10.1.0, 10.2.0, 10.3.0, 10.4.0, 10.5.0,\n10.6.0, 10.7.0, 10.8.0, 11.0.0, 11.1.0, 11.2.0, 11.3.0, 11.4.0,\n11.5.0, 12.0.0, 12.1.0, 12.2.0, 13.0.0, 13.1.0, 13.2.0, 13.3.0,\n13.4.0, 14.0.0, 14.1.0, 14.2.0, 14.3.0, 14.4.0, 14.5.0, 15.0.0,\n15.1.0, 15.2.0, 15.3.0, 15.4.0, 15.5.0, 15.6.0, 16.0.0, 16.1.0,\n16.2.0, 16.3.0, 16.4.0, 16.5.0, 16.6.0, 17.0.0, 17.1.0, 17.2.0,\n17.3.0, 17.4.0, 17.5.0, 17.6.0, 17.7.0, 18.0.0, 18.1.0, 18.2.0,\n18.3.0, 18.4.0, 18.5.0, 18.6.0, 18.7.0, 19.0.0, 19.1.0, 19.2.0\n\nHistorically, the first argument used with .Dt was BSD or ATT.  An unrecognized  ver‐\nsion  argument after ATT is replaced with “Unix”; for other predefined abbreviations,\nit is ignored and a warning diagnostic emitted.   Otherwise,  unrecognized  arguments\nare  displayed  verbatim in the page footer.  For instance, this page uses “.Os groff\n1.23.0” whereas a locally produced page might  employ  “.Os  \"UXYZ  CS  Department\"”,\nomitting versioning.\n\nThis macro is neither callable nor parsed.\n",
            "subsections": []
        },
        "Introduction to manual and general text domains": {
            "content": "What's in a Name...\nThe  manual  domain macro names are derived from the day to day informal language used to de‐\nscribe commands, subroutines and related files.  Slightly different variations of  this  lan‐\nguage  are  used to describe the three different aspects of writing a man page.  First, there\nis the description of mdoc macro command usage.  Second is the description of a Unix  command\nwith mdoc macros, and third, the description of a command to a user in the verbal sense; that\nis, discussion of a command in the text of a man page.\n\nIn  the  first  case, troff macros are themselves a type of command; the general syntax for a\ntroff command is:\n\n.Xx argument1 argument2 ...\n\n‘.Xx’ is a macro command, and anything following it are arguments to be  processed.   In  the\nsecond  case,  the description of a Unix command using the manual domain macros is a bit more\ninvolved; a typical “Synopsis” command line might be displayed as:\n\nfilter [-flag] ⟨infile⟩ ⟨outfile⟩\n\nHere, filter is the command name and the bracketed string -flag is a flag argument designated\nas optional by the option brackets.  In mdoc terms, ⟨infile⟩ and ⟨outfile⟩  are  called  meta\narguments;  in  this  example,  the  user  has to replace the meta expressions given in angle\nbrackets with real file names.  Note that in this document meta arguments  are  used  to  de‐\nscribe mdoc commands; in most man pages, meta variables are not specifically written with an‐\ngle brackets.  The macros that formatted the above example:\n\n.Nm filter\n.Op Fl flag\n.Ao Ar infile Ac Ao Ar outfile Ac\n\nIn  the  third  case, discussion of commands and command syntax includes both examples above,\nbut may add more detail.  The arguments ⟨infile⟩ and ⟨outfile⟩ from the example  above  might\nbe  referred  to  as  operands or file arguments.  Some command-line argument lists are quite\nlong:\n\nmake  [-eiknqrstv] [-D variable] [-d flags] [-f makefile] [-I directory] [-j maxjobs]\n[variable=value] [target ...]\n\nHere one might talk about the command make and qualify the argument, makefile, as an argument\nto the flag, -f, or discuss the optional file operand target.  In the  verbal  context,  such\ndetail  can prevent confusion, however the mdoc package does not have a macro for an argument\nto a flag.  Instead the ‘Ar’ argument macro is used for an  operand  or  file  argument  like\ntarget  as  well  as an argument to a flag like variable.  The make command line was produced\nfrom:\n\n.Nm make\n.Op Fl eiknqrstv\n.Op Fl D Ar variable\n.Op Fl d Ar flags\n.Op Fl f Ar makefile\n.Op Fl I Ar directory\n.Op Fl j Ar maxjobs\n.Op Ar variable Ns = Ns Ar value\n.Bk\n.Op Ar target ...\n.Ek\n\nThe ‘.Bk’ and ‘.Ek’ macros are explained in “Keeps”.\n",
            "subsections": [
                {
                    "name": "General Syntax",
                    "content": "The manual domain and general text domain macros share a similar syntax with a few minor  de‐\nviations;  most notably, ‘.Ar’, ‘.Fl’, ‘.Nm’, and ‘.Pa’ differ only when called without argu‐\nments; and ‘.Fn’ and ‘.Xr’ impose an order on their argument lists.  All manual domain macros\nare capable of recognizing and properly handling punctuation, provided each punctuation char‐\nacter is separated by a leading space.  If a command is given:\n\n.Ar sptr, ptr),\n\nThe result is:\n\nsptr, ptr),\n\nThe punctuation is not recognized and all is output in the font used by ‘.Ar’.  If the  punc‐\ntuation is separated by a leading white space:\n\n.Ar sptr , ptr ) ,\n\nThe result is:\n\nsptr, ptr),\n\nThe  punctuation  is now recognized and output in the default font distinguishing it from the\nargument strings.  To remove the special meaning from a punctuation character, escape it with\n‘\\&’.\n\nThe following punctuation characters are recognized by mdoc:\n\n.         ,         :         ;         (\n)         [         ]         ?         !\n\ntroff is limited as a macro language, and has difficulty when presented with  a  string  con‐\ntaining certain mathematical, logical, or quotation character sequences:\n\n{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',\"}\n\nThe  problem  is  that  troff  may assume it is supposed to actually perform the operation or\nevaluation suggested by the characters.  To prevent the accidental evaluation of these  char‐\nacters, escape them with ‘\\&’.  Typical syntax is shown in the first manual domain macro dis‐\nplayed below, ‘.Ad’.\n"
                }
            ]
        },
        "Manual domain": {
            "content": "",
            "subsections": [
                {
                    "name": "Addresses",
                    "content": "The address macro identifies an address construct.\n\nUsage: .Ad ⟨address⟩ ...\n\n.Ad addr1           addr1\n.Ad addr1 .         addr1.\n.Ad addr1 , file2   addr1, file2\n.Ad f1 , f2 , f3 :  f1, f2, f3:\n.Ad addr ) ) ,      addr)),\n\nThe default width is 12n.\n"
                },
                {
                    "name": "Author Name",
                    "content": "The  ‘.An’  macro  is used to specify the name of the author of the item being documented, or\nthe name of the author of the actual manual page.\n\nUsage: .An ⟨author name⟩ ...\n\n.An \"Joe Author\"        Joe Author\n\n.An \"Joe Author\" ,      Joe Author,\n\n.An \"Joe Author\" Aq nobody@FreeBSD.org\nJoe Author <nobody@FreeBSD.org>\n\n.An \"Joe Author\" ) ) ,  Joe Author)),\n\nThe default width is 12n.\n\nIn a section titled “Authors”, ‘An’ causes a break, allowing each new name to appear  on  its\nown line.  If this is not desirable,\n\n.An -nosplit\n\ncall will turn this off.  To turn splitting back on, write\n\n.An -split\n"
                },
                {
                    "name": "Arguments",
                    "content": "The .Ar argument macro may be used whenever an argument is referenced.  If called without ar‐\nguments, ‘file ...’ is output.  This places the ellipsis in italics, which is ugly and incor‐\nrect,  and will be noticed on terminals that underline text instead of using an oblique type‐\nface.  We recommend using ‘.Ar file No ...’ instead.\n\nUsage: .Ar [⟨argument⟩] ...\n\n.Ar              file ...\n.Ar file No ...  file ...\n.Ar file1        file1\n.Ar file1 .      file1.\n.Ar file1 file2  file1 file2\n.Ar f1 f2 f3 :   f1 f2 f3:\n.Ar file ) ) ,   file)),\n\nThe default width is 12n.\n"
                },
                {
                    "name": "Configuration Declaration (Section Four Only)",
                    "content": "The ‘.Cd’ macro is used to demonstrate a config(8) declaration for a device  interface  in  a\nsection four manual.\n\nUsage: .Cd ⟨argument⟩ ...\n\n.Cd \"device le0 at scode?\"  device le0 at scode?\n\nIn a section titled “Synopsis”, ‘Cd’ causes a break before and after its arguments.\n\nThe default width is 12n.\n"
                },
                {
                    "name": "Command Modifiers",
                    "content": "The  command  modifier  is  identical to the ‘.Fl’ (flag) command with the exception that the\n‘.Cm’ macro does not assert a dash in front  of  every  argument.   Traditionally  flags  are\nmarked  by the preceding dash, however, some commands or subsets of commands do not use them.\nCommand modifiers may also be specified in conjunction with interactive commands such as edi‐\ntor commands.  See “Flags”.\n\nThe default width is 10n.\n"
                },
                {
                    "name": "Defined Variables",
                    "content": "A variable (or constant) that is defined in an include file is specified by the macro ‘.Dv’.\n\nUsage: .Dv ⟨defined-variable⟩ ...\n\n.Dv MAXHOSTNAMELEN  MAXHOSTNAMELEN\n.Dv TIOCGPGRP )     TIOCGPGRP)\n\nThe default width is 12n.\n"
                },
                {
                    "name": "Errnos",
                    "content": "The ‘.Er’ errno macro specifies the error return value for section 2, 3, and 9  library  rou‐\ntines.   The  second example below shows ‘.Er’ used with the ‘.Bq’ general text domain macro,\nas it would be used in a section two manual page.\n\nUsage: .Er ⟨errno type⟩ ...\n\n.Er ENOENT      ENOENT\n.Er ENOENT ) ;  ENOENT);\n.Bq Er ENOTDIR  [ENOTDIR]\n\nThe default width is 17n.\n"
                },
                {
                    "name": "Environment Variables",
                    "content": "The ‘.Ev’ macro specifies an environment variable.\n\nUsage: .Ev ⟨argument⟩ ...\n\n.Ev DISPLAY        DISPLAY\n.Ev PATH .         PATH.\n.Ev PRINTER ) ) ,  PRINTER)),\n\nThe default width is 15n.\n"
                },
                {
                    "name": "Flags",
                    "content": "The ‘.Fl’ macro handles command-line flags.  It prepends a dash, ‘-’, to the flag.   For  in‐\nteractive  command  flags  that  are  not prepended with a dash, the ‘.Cm’ (command modifier)\nmacro is identical, but without the dash.\n\nUsage: .Fl ⟨argument⟩ ...\n\n.Fl          -\n.Fl cfv      -cfv\n.Fl cfv .    -cfv.\n.Cm cfv .    cfv.\n.Fl s v t    -s -v -t\n.Fl - ,      --,\n.Fl xyz ) ,  -xyz),\n.Fl |        - |\n\nThe ‘.Fl’ macro without any arguments results in a dash representing stdin/stdout.  Note that\ngiving ‘.Fl’ a single dash will result in two dashes.\n\nThe default width is 12n.\n"
                },
                {
                    "name": "Function Declarations",
                    "content": "The ‘.Fd’ macro is used in the “Synopsis” section with section two or three functions.  It is\nneither callable nor parsed.\n\nUsage: .Fd ⟨argument⟩ ...\n\n.Fd \"#include <sys/types.h>\"  #include <sys/types.h>\n\nIn a section titled “Synopsis”, ‘Fd’ causes a break if a function has already been  presented\nand a break has not occurred, leaving vertical space between one function declaration and the\nnext.\n\nIn  a section titled “Synopsis”, the ‘In’ macro represents the #include statement, and is the\nshort form of the above example.  It specifies the C header  file  as  being  included  in  a\nC program.  It also causes a break.\n\nWhile  not  in the “Synopsis” section, it represents the header file enclosed in angle brack‐\nets.\n\nUsage: .In ⟨header file⟩\n\n.In stdio.h  <stdio.h>\n.In stdio.h  <stdio.h>\n"
                },
                {
                    "name": "Function Types",
                    "content": "This macro is intended for the “Synopsis” section.  It may be used anywhere else in  the  man\npage  without  problems,  but its main purpose is to present the function type (in BSD kernel\nnormal form) for the “Synopsis” of sections two and three.  (It causes a break, allowing  the\nfunction name to appear on the next line.)\n\nUsage: .Ft ⟨type⟩ ...\n\n.Ft struct stat  struct stat\n"
                },
                {
                    "name": "Functions (Library Routines)",
                    "content": "The ‘.Fn’ macro is modeled on ANSI C conventions.\n\nUsage: .Fn ⟨function⟩ [⟨parameter⟩] ...\n\n.Fn getchar              getchar()\n.Fn strlen ) ,           strlen()),\n.Fn align \"char *ptr\" ,  align(char *ptr),\n\nNote that any call to another macro signals the end of the ‘.Fn’ call (it will insert a clos‐\ning parenthesis at that point).\n\nFor  functions  with  many  parameters  (which is rare), the macros ‘.Fo’ (function open) and\n‘.Fc’ (function close) may be used with ‘.Fa’ (function argument).\n\nExample:\n\n.Ft int\n.Fo resmkquery\n.Fa \"int op\"\n.Fa \"char *dname\"\n.Fa \"int class\"\n.Fa \"int type\"\n.Fa \"char *data\"\n.Fa \"int datalen\"\n.Fa \"struct rrec *newrr\"\n.Fa \"char *buf\"\n.Fa \"int buflen\"\n.Fc\n\nProduces:\n\nint resmkquery(int op, char *dname, int class, int type, char *data, int datalen,\nstruct rrec *newrr, char *buf, int buflen)\n\nTypically, in a “Synopsis” section, the function delcaration will begin the  line.   If  more\nthan  one  function  is  presented in the “Synopsis” section and a function type has not been\ngiven, a break will occur, leaving vertical space between  the  current  and  prior  function\nnames.\n\nThe default width values of ‘.Fn’ and ‘.Fo’ are 12n and 16n, respectively.\n"
                },
                {
                    "name": "Function Arguments",
                    "content": "The ‘.Fa’ macro is used to refer to function arguments (parameters) outside of the “Synopsis”\nsection  of  the  manual  or  inside the “Synopsis” section if the enclosure macros ‘.Fo’ and\n‘.Fc’ instead of ‘.Fn’ are used.  ‘.Fa’ may also be used to refer to structure members.\n\nUsage: .Fa ⟨function argument⟩ ...\n\n.Fa dnamlen ) ) ,  dnamlen)),\n.Fa iovlen         iovlen\n\nThe default width is 12n.\n"
                },
                {
                    "name": "Return Values",
                    "content": "The ‘.Rv’ macro generates text for use in the “Return values” section.\n\nUsage: .Rv [-std] [⟨function⟩ ...]\n\nFor example, ‘.Rv -std atexit’ produces:\n\nThe atexit() function returns the value 0 if successful; otherwise the value -1 is re‐\nturned and the global variable errno is set to indicate the error.\n\nThe -std option is valid only for manual page sections 2 and 3.  Currently, this  macro  does\nnothing if used without the -std flag.\n"
                },
                {
                    "name": "Exit Status",
                    "content": "The ‘.Ex’ macro generates text for use in the “Diagnostics” section.\n\nUsage: .Ex [-std] [⟨utility⟩ ...]\n\nFor example, ‘.Ex -std cat’ produces:\n\nThe cat utility exits 0 on success, and >0 if an error occurs.\n\nThe  -std  option  is  valid only for manual page sections 1, 6 and 8.  Currently, this macro\ndoes nothing if used without the -std flag.\n"
                },
                {
                    "name": "Interactive Commands",
                    "content": "The ‘.Ic’ macro designates an interactive or internal command.\n\nUsage: .Ic ⟨argument⟩ ...\n\n.Ic :wq                :wq\n.Ic \"do while {...}\"   do while {...}\n.Ic setenv , unsetenv  setenv, unsetenv\n\nThe default width is 12n.\n"
                },
                {
                    "name": "Library Names",
                    "content": "The ‘.Lb’ macro is used to specify the library where a particular function is compiled in.\n\nUsage: .Lb ⟨argument⟩ ...\n\nAvailable arguments to ‘.Lb’ and their results are:\n\nlibarchive     Reading and Writing Streaming Archives Library (libarchive, -larchive)\nlibarm         ARM Architecture Library (libarm, -larm)\nlibarm32       ARM32 Architecture Library (libarm32, -larm32)\nlibbluetooth   Bluetooth Library (libbluetooth, -lbluetooth)\nlibbsm         Basic Security Module Library (libbsm, -lbsm)\nlibc           Standard C Library (libc, -lc)\nlibcr         Reentrant C Library (libcr, -lcr)\nlibcalendar    Calendar Arithmetic Library (libcalendar, -lcalendar)\nlibcam         Common Access Method User Library (libcam, -lcam)\nlibcdk         Curses Development Kit Library (libcdk, -lcdk)\nlibcipher      FreeSec Crypt Library (libcipher, -lcipher)\nlibcompat      Compatibility Library (libcompat, -lcompat)\nlibcrypt       Crypt Library (libcrypt, -lcrypt)\nlibcurses      Curses Library (libcurses, -lcurses)\nlibdevinfo     Device and Resource Information Utility Library (libdevinfo, -ldevinfo)\nlibdevstat     Device Statistics Library (libdevstat, -ldevstat)\nlibdisk        Interface to Slice and Partition Labels Library (libdisk, -ldisk)\nlibdwarf       DWARF Access Library (libdwarf, -ldwarf)\nlibedit        Command Line Editor Library (libedit, -ledit)\nlibelf         ELF Access Library (libelf, -lelf)\nlibevent       Event Notification Library (libevent, -levent)\nlibfetch       File Transfer Library for URLs (libfetch, -lfetch)\nlibform        Curses Form Library (libform, -lform)\nlibgeom        Userland API Library for kernel GEOM subsystem (libgeom, -lgeom)\nlibgpib        General-Purpose Instrument Bus (GPIB) library (libgpib, -lgpib)\nlibi386        i386 Architecture Library (libi386, -li386)\nlibintl        Internationalized Message Handling Library (libintl, -lintl)\nlibipsec       IPsec Policy Control Library (libipsec, -lipsec)\nlibipx         IPX Address Conversion Support Library (libipx, -lipx)\nlibiscsi       iSCSI protocol library (libiscsi, -liscsi)\nlibjail        Jail Library (libjail, -ljail)\nlibkiconv      Kernel side iconv library (libkiconv, -lkiconv)\nlibkse         N:M Threading Library (libkse, -lkse)\nlibkvm         Kernel Data Access Library (libkvm, -lkvm)\nlibm           Math Library (libm, -lm)\nlibm68k        m68k Architecture Library (libm68k, -lm68k)\nlibmagic       Magic Number Recognition Library (libmagic, -lmagic)\nlibmd          Message Digest (MD4, MD5, etc.) Support Library (libmd, -lmd)\nlibmemstat     Kernel Memory Allocator Statistics Library (libmemstat, -lmemstat)\nlibmenu        Curses Menu Library (libmenu, -lmenu)\nlibnetgraph    Netgraph User Library (libnetgraph, -lnetgraph)\nlibnetpgp      Netpgp signing,  verification,  encryption  and  decryption  (libnetpgp,\n-lnetpgp)\nlibossaudio    OSS Audio Emulation Library (libossaudio, -lossaudio)\nlibpam         Pluggable Authentication Module Library (libpam, -lpam)\nlibpcap        Packet Capture Library (libpcap, -lpcap)\nlibpci         PCI Bus Access Library (libpci, -lpci)\nlibpmc         Performance Counters Library (libpmc, -lpmc)\nlibposix       POSIX Compatibility Library (libposix, -lposix)\nlibprop        Property Container Object Library (libprop, -lprop)\nlibpthread     POSIX Threads Library (libpthread, -lpthread)\nlibpuffs       puffs Convenience Library (libpuffs, -lpuffs)\nlibrefuse      File System in Userspace Convenience Library (librefuse, -lrefuse)\nlibresolv      DNS Resolver Library (libresolv, -lresolv)\nlibrpcsecgss  RPC GSS-API Authentication Library (librpcsecgss, -lrpcsecgss)\nlibrpcsvc      RPC Service Library (librpcsvc, -lrpcsvc)\nlibrt          POSIX Real-time Library (librt, -lrt)\nlibsdp         Bluetooth Service Discovery Protocol User Library (libsdp, -lsdp)\nlibssp         Buffer Overflow Protection Library (libssp, -lssp)\nlibSystem      System Library (libSystem, -lSystem)\nlibtermcap     Termcap Access Library (libtermcap, -ltermcap)\nlibterminfo    Terminal Information Library (libterminfo, -lterminfo)\nlibthr         1:1 Threading Library (libthr, -lthr)\nlibufs         UFS File System Access Library (libufs, -lufs)\nlibugidfw      File System Firewall Interface Library (libugidfw, -lugidfw)\nlibulog        User Login Record Library (libulog, -lulog)\nlibusbhid      USB Human Interface Devices Library (libusbhid, -lusbhid)\nlibutil        System Utilities Library (libutil, -lutil)\nlibvgl         Video Graphics Library (libvgl, -lvgl)\nlibx8664      x8664 Architecture Library (libx8664, -lx8664)\nlibz           Compression Library (libz, -lz)\n\nSite-specific additions might be found in the file mdoc.local; see section “Files” below.\n\nIn a section titled “Library”, ‘Lb’ causes a break before and after its arguments.\n"
                },
                {
                    "name": "Literals",
                    "content": "The ‘Li’ literal macro may be used for special characters, symbolic constants, and other syn‐\ntactical items that should be typed exactly as displayed.\n\nUsage: .Li ⟨argument⟩ ...\n\n.Li \\en          \\n\n.Li M1 M2 M3 ;   M1 M2 M3;\n.Li cntrl-D ) ,  cntrl-D),\n.Li 1024 ...     1024 ...\n\nThe default width is 16n.\n"
                },
                {
                    "name": "Names",
                    "content": "The ‘Nm’ macro is used for the document title or page topic.  Upon its first call, it has the\npeculiarity  of  remembering  its argument, which should always be the topic of the man page.\nWhen subsequently called without arguments, ‘Nm’ regurgitates this initial name for the  sole\npurpose  of making less work for the author.  Use of ‘Nm’ is also appropriate when presenting\na command synopsis for the topic of a man page in section 1, 6, or 8.  Its  behavior  changes\nwhen presented with arguments of various forms.\n\n.Nm groffmdoc  groffmdoc\n.Nm             groffmdoc\n.Nm \\-mdoc      -mdoc\n.Nm foo ) ) ,   foo)),\n.Nm :           groffmdoc:\n\nBy  default,  the topic is set in boldface to reflect its prime importance in the discussion.\nCross references to other man page topics should use ‘Xr’; including a  second  argument  for\nthe  section  number enables them to be hyperlinked.  By default, cross-referenced topics are\nset in italics to avoid cluttering the page with boldface.\n\nThe default width is 10n.\n"
                },
                {
                    "name": "Options",
                    "content": "The ‘.Op’ macro places option brackets around any remaining arguments on  the  command  line,\nand  places any trailing punctuation outside the brackets.  The macros ‘.Oo’ and ‘.Oc’ (which\nproduce an opening and a closing option bracket, respectively) may be used across one or more\nlines or to specify the exact position of the closing parenthesis.\n\nUsage: .Op [⟨option⟩] ...\n\n.Op                                []\n.Op Fl k                           [-k]\n.Op Fl k ) .                       [-k]).\n.Op Fl k Ar kookfile               [-k kookfile]\n.Op Fl k Ar kookfile ,             [-k kookfile],\n.Op Ar objfil Op Ar corfil         [objfil [corfil]]\n.Op Fl c Ar objfil Op Ar corfil ,  [-c objfil [corfil]],\n.Op word1 word2                    [word1 word2]\n.Li .Op Oo Ao option Ac Oc ...     .Op [⟨option⟩] ...\n\nHere a typical example of the ‘.Oo’ and ‘.Oc’ macros:\n\n.Oo\n.Op Fl k Ar kilobytes\n.Op Fl i Ar interval\n.Op Fl c Ar count\n.Oc\n\nProduces:\n\n[[-k kilobytes] [-i interval] [-c count]]\n\nThe default width values of ‘.Op’ and ‘.Oo’ are 14n and 10n, respectively.\n"
                },
                {
                    "name": "Pathnames",
                    "content": "The ‘.Pa’ macro formats file specifications.  If called without arguments, ‘~’ (recognized by\nmany shells) is output, representing the user's home directory.\n\nUsage: .Pa [⟨pathname⟩] ...\n\n.Pa                    ~\n.Pa /usr/share         /usr/share\n.Pa /tmp/fooXXXXX ) .  /tmp/fooXXXXX).\n\nThe default width is 32n.\n"
                },
                {
                    "name": "Standards",
                    "content": "The ‘.St’ macro replaces standard abbreviations with their formal names.\n\nUsage: .St ⟨abbreviation⟩ ...\n\nAvailable pairs for “Abbreviation/Formal Name” are:\n\nANSI/ISO C\n\n-ansiC          ANSI X3.159-1989 (“ANSI C89”)\n-ansiC-89       ANSI X3.159-1989 (“ANSI C89”)\n-isoC           ISO/IEC 9899:1990 (“ISO C90”)\n-isoC-90        ISO/IEC 9899:1990 (“ISO C90”)\n-isoC-99        ISO/IEC 9899:1999 (“ISO C99”)\n-isoC-2011      ISO/IEC 9899:2011 (“ISO C11”)\n\nPOSIX Part 1: System API\n\n-iso9945-1-90   ISO/IEC 9945-1:1990 (“POSIX.1”)\n-iso9945-1-96   ISO/IEC 9945-1:1996 (“POSIX.1”)\n-p1003.1        IEEE Std 1003.1 (“POSIX.1”)\n-p1003.1-88     IEEE Std 1003.1-1988 (“POSIX.1”)\n-p1003.1-90     ISO/IEC 9945-1:1990 (“POSIX.1”)\n-p1003.1-96     ISO/IEC 9945-1:1996 (“POSIX.1”)\n-p1003.1b-93    IEEE Std 1003.1b-1993 (“POSIX.1”)\n-p1003.1c-95    IEEE Std 1003.1c-1995 (“POSIX.1”)\n-p1003.1g-2000  IEEE Std 1003.1g-2000 (“POSIX.1”)\n-p1003.1i-95    IEEE Std 1003.1i-1995 (“POSIX.1”)\n-p1003.1-2001   IEEE Std 1003.1-2001 (“POSIX.1”)\n-p1003.1-2004   IEEE Std 1003.1-2004 (“POSIX.1”)\n-p1003.1-2008   IEEE Std 1003.1-2008 (“POSIX.1”)\n\nPOSIX Part 2: Shell and Utilities\n\n-iso9945-2-93   ISO/IEC 9945-2:1993 (“POSIX.2”)\n-p1003.2        IEEE Std 1003.2 (“POSIX.2”)\n-p1003.2-92     IEEE Std 1003.2-1992 (“POSIX.2”)\n-p1003.2a-92    IEEE Std 1003.2a-1992 (“POSIX.2”)\n\nX/Open\n\n-susv1          Version 1 of the Single UNIX Specification (“SUSv1”)\n-susv2          Version 2 of the Single UNIX Specification (“SUSv2”)\n-susv3          Version 3 of the Single UNIX Specification (“SUSv3”)\n-susv4          Version 4 of the Single UNIX Specification (“SUSv4”)\n-svid4          System V Interface Definition, Fourth Edition (“SVID4”)\n-xbd5           X/Open Base Definitions Issue 5 (“XBD5”)\n-xcu5           X/Open Commands and Utilities Issue 5 (“XCU5”)\n-xcurses4.2     X/Open Curses Issue 4, Version 2 (“XCURSES4.2”)\n-xns5           X/Open Networking Services Issue 5 (“XNS5”)\n-xns5.2         X/Open Networking Services Issue 5.2 (“XNS5.2”)\n-xpg3           X/Open Portability Guide Issue 3 (“XPG3”)\n-xpg4           X/Open Portability Guide Issue 4 (“XPG4”)\n-xpg4.2         X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”)\n-xsh5           X/Open System Interfaces and Headers Issue 5 (“XSH5”)\n\nMiscellaneous\n\n-ieee754        IEEE Std 754-1985\n-iso8601        ISO 8601\n-iso8802-3      ISO/IEC 8802-3:1989\n"
                },
                {
                    "name": "Variable Types",
                    "content": "The ‘.Vt’ macro may be used whenever a type is referenced.  In a section  titled  “Synopsis”,\n‘Vt’ causes a break (useful for old-style C variable declarations).\n\nUsage: .Vt ⟨type⟩ ...\n\n.Vt extern char *optarg ;  extern char *optarg;\n.Vt FILE *                 FILE *\n"
                },
                {
                    "name": "Variables",
                    "content": "Generic variable reference.\n\nUsage: .Va ⟨variable⟩ ...\n\n.Va count             count\n.Va settimer ,        settimer,\n.Va \"int *prt\" ) :    int *prt):\n.Va \"char s\" ] ) ) ,  char s])),\n\nThe default width is 12n.\n"
                },
                {
                    "name": "Manual Page Cross References",
                    "content": "The ‘.Xr’ macro expects the first argument to be a manual page name.  The optional second ar‐\ngument, if a string (defining the manual section), is put into parentheses.\n\nUsage: .Xr ⟨man page name⟩ [⟨section⟩] ...\n\n.Xr mdoc        mdoc\n.Xr mdoc ,      mdoc,\n.Xr mdoc 7      mdoc(7)\n.Xr xinit 1x ;  xinit(1x);\n\nThe default width is 10n.\n"
                }
            ]
        },
        "General text domain": {
            "content": "",
            "subsections": [
                {
                    "name": "AT&T Macro",
                    "content": "Usage: .At [⟨version⟩] ...\n\n.At       AT&T UNIX\n.At v6 .  Version 6 AT&T UNIX.\n\nThe following values for ⟨version⟩ are possible:\n\n32v, v1, v2, v3, v4, v5, v6, v7, III, V, V.1, V.2, V.3, V.4\n"
                },
                {
                    "name": "BSD Macro",
                    "content": "Usage: .Bx {-alpha | -beta | -devel} ...\n.Bx [⟨version⟩ [⟨release⟩]] ...\n\n.Bx         BSD\n.Bx 4.3 .   4.3BSD.\n.Bx -devel  BSD (currently under development)\n\n⟨version⟩ will be prepended to the string ‘BSD’.  The following values for ⟨release⟩ are pos‐\nsible:\n\nReno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2\n"
                },
                {
                    "name": "NetBSD Macro",
                    "content": "Usage: .Nx [⟨version⟩] ...\n\n.Nx        NetBSD\n.Nx 1.4 .  NetBSD 1.4.\n\nFor  possible  values  of ⟨version⟩ see the description of the ‘.Os’ command above in section\n“Title macros”.\n"
                },
                {
                    "name": "FreeBSD Macro",
                    "content": "Usage: .Fx [⟨version⟩] ...\n\n.Fx        FreeBSD\n.Fx 2.2 .  FreeBSD 2.2.\n\nFor possible values of ⟨version⟩ see the description of the ‘.Os’ command  above  in  section\n“Title macros”.\n"
                },
                {
                    "name": "DragonFly Macro",
                    "content": "Usage: .Dx [⟨version⟩] ...\n\n.Dx        DragonFly\n.Dx 1.4 .  DragonFly 1.4.\n\nFor  possible  values  of ⟨version⟩ see the description of the ‘.Os’ command above in section\n“Title macros”.\n"
                },
                {
                    "name": "OpenBSD Macro",
                    "content": "Usage: .Ox [⟨version⟩] ...\n\n.Ox 1.0  OpenBSD 1.0\n"
                },
                {
                    "name": "BSD/OS Macro",
                    "content": "Usage: .Bsx [⟨version⟩] ...\n\n.Bsx 1.0  BSD/OS 1.0\n"
                },
                {
                    "name": "Unix Macro",
                    "content": "Usage: .Ux ...\n\n.Ux  Unix\n"
                },
                {
                    "name": "Emphasis Macro",
                    "content": "Text may be stressed or emphasized with the ‘.Em’ macro.  The  usual  font  for  emphasis  is\nitalic.\n\nUsage: .Em ⟨argument⟩ ...\n\n.Em does not          does not\n.Em exceed 1024 .     exceed 1024.\n.Em vide infra ) ) ,  vide infra)),\n\nThe default width is 10n.\n"
                },
                {
                    "name": "Font Mode",
                    "content": "The ‘.Bf’ font mode must be ended with the ‘.Ef’ macro (the latter takes no arguments).  Font\nmodes may be nested within other font modes.\n\n‘.Bf’ has the following syntax:\n\n.Bf ⟨font mode⟩\n\n⟨font mode⟩ must be one of the following three types:\n\nEm | -emphasis  Same as if the ‘.Em’ macro was used for the entire block of text.\nLi | -literal   Same as if the ‘.Li’ macro was used for the entire block of text.\nSy | -symbolic  Same as if the ‘.Sy’ macro was used for the entire block of text.\n\nBoth macros are neither callable nor parsed.\n"
                },
                {
                    "name": "Enclosure and Quoting Macros",
                    "content": "The  concept  of  enclosure  is  similar to quoting.  The object being to enclose one or more\nstrings between a pair of characters like quotes or parentheses.  The terms quoting  and  en‐\nclosure  are  used  interchangeably throughout this document.  Most of the one-line enclosure\nmacros end in small letter ‘q’ to give a hint of quoting, but there are a few irregularities.\nFor each enclosure macro, there is a pair of opening and closing macros  that  end  with  the\nlowercase letters ‘o’ and ‘c’ respectively.\n"
                },
                {
                    "name": "Quote   Open   Close   Function                  Result",
                    "content": ".Aq     .Ao    .Ac     Angle Bracket Enclosure   <string>\n.Bq     .Bo    .Bc     Bracket Enclosure         [string]\n.Brq    .Bro   .Brc    Brace Enclosure           {string}\n.Dq     .Do    .Dc     Double Quote              “string”\n.Eq     .Eo    .Ec     Enclose String (in XY)    XstringY\n.Pq     .Po    .Pc     Parenthesis Enclosure     (string)\n.Ql                    Quoted Literal            “string” or string\n.Qq     .Qo    .Qc     Straight Double Quote     \"string\"\n.Sq     .So    .Sc     Single Quote              ‘string’\n\nAll macros ending with ‘q’ and ‘o’ have a default width value of 12n.\n\n.Eo, .Ec  These  macros  expect the first argument to be the opening and closing strings, re‐\nspectively.\n\n.Es, .En  To work around the nine-argument limit in the original troff program, mdoc supports\ntwo other macros that are now obsolete.  ‘.Es’ uses its first and second parameters\nas opening and closing marks which are then used to enclose the arguments of ‘.En’.\nThe default width value is 12n for both macros.\n\n.Eq       The first and second arguments of this macro are the opening  and  closing  strings\nrespectively, followed by the arguments to be enclosed.\n\n.Ql       The  quoted literal macro behaves differently in troff and nroff modes.  If format‐\nted with nroff(1), a quoted literal is always quoted.  If formatted with troff,  an\nitem  is  only  quoted  if  the width of the item is less than three constant-width\ncharacters.  This is to make short strings more visible where the  font  change  to\nliteral (constant-width) is less noticeable.\n\nThe default width is 16n.\n\n.Pf       The prefix macro suppresses the whitespace between its first and second argument:\n\n.Pf ( Fa name2  (name2\n\nThe default width is 12n.\n\nThe ‘.Ns’ macro (see below) performs the analogous suffix function.\n\n.Ap       The  ‘.Ap’ macro inserts an apostrophe and exits any special text modes, continuing\nin ‘.No’ mode.\n\nExamples of quoting:\n\n.Aq                      ⟨⟩\n.Aq Pa ctype.h ) ,       ⟨ctype.h⟩),\n.Bq                      []\n.Bq Em Greek , French .  [Greek, French].\n.Dq                      “”\n.Dq string abc .         “string abc”.\n.Dq '\\[ha][A-Z]'         “'^[A-Z]'”\n.Ql man mdoc             ‘man mdoc’\n.Qq                      \"\"\n.Qq string ) ,           \"string\"),\n.Qq string Ns ),         \"string),\"\n.Sq                      ‘’\n.Sq string               ‘string’\n.Em or Ap ing            or'ing\n\nFor a good example of nested enclosure macros, see the ‘.Op’ option macro.   It  was  created\nfrom  the  same  underlying enclosure macros as those presented in the list above.  The ‘.Xo’\nand ‘.Xc’ extended argument list macros are discussed below.\n"
                },
                {
                    "name": "Normal text macro",
                    "content": "‘No’ formats subsequent argument(s) normally, ending the effect of ‘Em’ and similar.  Parsing\nis not suppressed, so you must prefix words like ‘No’ with ‘\\&’ to avoid their interpretation\nas mdoc macros.\n\nUsage: .No argument ...\n\n.Em Use caution No here .  → Use caution here.\n.Em No dogs allowed .      → No dogs allowed.\n.Em \\&No dogs allowed .    → No dogs allowed.\n\nThe default width is 12n.\n"
                },
                {
                    "name": "No-Space Macro",
                    "content": "The ‘.Ns’ macro suppresses insertion of a space between the current position  and  its  first\nparameter.   For  example,  it is useful for old style argument lists where there is no space\nbetween the flag and argument:\n\nUsage: ... ⟨argument⟩ Ns [⟨argument⟩] ...\n.Ns ⟨argument⟩ ...\n\n.Op Fl I Ns Ar directory  [-Idirectory]\n\nNote: The ‘.Ns’ macro always invokes the ‘.No’ macro after eliminating the space  unless  an‐\nother  macro  name  follows  it.   If  used  as a command (i.e., the second form above in the\n‘Usage’ line), ‘.Ns’ is identical to ‘.No’.\n"
                },
                {
                    "name": "(Sub)section cross references",
                    "content": "Use the ‘.Sx’ macro to cite a (sub)section heading within the given document.\n\nUsage: .Sx ⟨section-reference⟩ ...\n\n.Sx Files  → “Files”\n\nThe default width is 16n.\n"
                },
                {
                    "name": "Symbolics",
                    "content": "The symbolic emphasis macro is generally a boldface macro in either the symbolic sense or the\ntraditional English usage.\n\nUsage: .Sy ⟨symbol⟩ ...\n\n.Sy Important Notice  → Important Notice\n\nThe default width is 6n.\n"
                },
                {
                    "name": "Mathematical Symbols",
                    "content": "Use this macro for mathematical symbols and similar things.\n\nUsage: .Ms ⟨math symbol⟩ ...\n\n.Ms sigma  → sigma\n\nThe default width is 6n.\n"
                },
                {
                    "name": "References and Citations",
                    "content": "The following macros make a modest attempt to handle references.  At best, the macros make it\nconvenient to manually drop in a subset of refer(1) style references.\n\n.Rs     Reference start (does not take arguments).  In a section titled “See also”,  it\ncauses  a break and begins collection of reference information until the refer‐\nence end macro is read.\n.Re     Reference end (does not take arguments).  The reference is printed.\n.%A     Reference author name; one name per invocation.\n.%B     Book title.\n.%C     City/place.\n.%D     Date.\n.%I     Issuer/publisher name.\n.%J     Journal name.\n.%N     Issue number.\n.%O     Optional information.\n.%P     Page number.\n.%Q     Corporate or foreign author.\n.%R     Report name.\n.%T     Title of article.\n.%U     Optional hypertext reference.\n.%V     Volume.\n\nMacros beginning with ‘%’ are not callable but accept multiple arguments in  the  usual  way.\nOnly the ‘.Tn’ macro is handled properly as a parameter; other macros will cause strange out‐\nput.  ‘.%B’ and ‘.%T’ can be used outside of the ‘.Rs/.Re’ environment.\n\nExample:\n\n.Rs\n.%A \"Matthew Bar\"\n.%A \"John Foo\"\n.%T \"Implementation Notes on foobar(1)\"\n.%R \"Technical Report ABC-DE-12-345\"\n.%Q \"Drofnats College\"\n.%C \"Nowhere\"\n.%D \"April 1991\"\n.Re\n\nproduces\n\nMatthew Bar and John Foo, Implementation Notes on foobar(1), Technical Report ABC-\nDE-12-345, Drofnats College, Nowhere, April 1991.\n"
                },
                {
                    "name": "Trade Names or Acronyms",
                    "content": "The  trade name macro prints its arguments at a smaller type size.  It is intended to imitate\na small caps fonts for fully capitalized acronyms.\n\nUsage: .Tn ⟨symbol⟩ ...\n\n.Tn DEC    DEC\n.Tn ASCII  ASCII\n\nThe default width is 10n.\n"
                },
                {
                    "name": "Extended Arguments",
                    "content": "The .Xo and .Xc macros allow one to extend an argument list on a macro boundary for the ‘.It’\nmacro (see below).  Note that .Xo and .Xc are implemented similarly to all other macros open‐\ning and closing an enclosure (without inserting characters, of course).  This means that  the\nfollowing is true for those macros also.\n\nHere is an example of ‘.Xo’ using the space mode macro to turn spacing off:\n\n.Bd -literal -offset indent\n.Sm off\n.It Xo Sy I Ar operation\n.No \\en Ar count No \\en\n.Xc\n.Sm on\n.Ed\n\nproduces\n\nIoperation\\ncount\\n\n\nAnother one:\n\n.Bd -literal -offset indent\n.Sm off\n.It Cm S No / Ar oldpattern Xo\n.No / Ar newpattern\n.No / Op Cm g\n.Xc\n.Sm on\n.Ed\n\nproduces\n\nS/oldpattern/newpattern/[g]\n\nAnother example of ‘.Xo’ and enclosure macros: Test the value of a variable.\n\n.Bd -literal -offset indent\n.It Xo\n.Ic .ifndef\n.Oo \\&! Oc Ns Ar variable Oo\n.Ar operator variable No ...\n.Oc Xc\n.Ed\n\nproduces\n\n.ifndef [!]variable [operator variable ...]\n"
                }
            ]
        },
        "Page structure domain": {
            "content": "",
            "subsections": [
                {
                    "name": "Section headings",
                    "content": "The  following  ‘.Sh’  section  heading macros are required in every man page.  The remaining\nsection headings are recommended at the discretion of the author  writing  the  manual  page.\nThe  ‘.Sh’  macro  is  parsed but not generally callable.  It can be used as an argument in a\ncall to ‘.Sh’ only; it then reactivates the default font for ‘.Sh’.\n\nThe default width is 8n.\n\n.Sh Name           The ‘.Sh Name’ macro is mandatory.  If not  specified,  headers,  footers,\nand  page  layout  defaults  will not be set and things will be rather un‐\npleasant.  The Name section consists of at least three items.   The  first\nis the ‘.Nm’ name macro naming the subject of the man page.  The second is\nthe  name  description macro, ‘.Nd’, which separates the subject name from\nthe third item, which is the description.  The description should  be  the\nmost terse and lucid possible, as the space available is small.\n\n‘.Nd’ first prints ‘-’, then all its arguments.\n\n.Sh Library        This  section is for section two and three function calls.  It should con‐\nsist of a single ‘.Lb’ macro call; see “Library Names”.\n\n.Sh Synopsis       The “Synopsis” section describes the typical usage of the subject of a man\npage.  The macros required are either ‘.Nm’, ‘.Cd’, or ‘.Fn’ (and possibly\n‘.Fo’, ‘.Fc’, ‘.Fd’, and ‘.Ft’).  The function name  macro  ‘.Fn’  is  re‐\nquired  for  manual  page  sections  2 and 3; the command and general name\nmacro ‘.Nm’ is required for sections 1, 5, 6, 7, and 8.  Section 4 manuals\nrequire a ‘.Nm’, ‘.Fd’ or a ‘.Cd’ configuration device usage macro.   Sev‐\neral  other  macros may be necessary to produce the synopsis line as shown\nbelow:\n\ncat [-benstuv] [-] file ...\n\nThe following macros were used:\n\n.Nm cat\n.Op Fl benstuv\n.Op Fl\n.Ar file No ...\n\n.Sh Description    In most cases the first text in the “Description” section is a brief para‐\ngraph on the command, function or file, followed by a lexical list of  op‐\ntions  and respective explanations.  To create such a list, the ‘.Bl’ (be‐\ngin list), ‘.It’ (list item) and ‘.El’ (end list)  macros  are  used  (see\n“Lists and Columns” below).\n"
                },
                {
                    "name": ".Sh Implementation notes",
                    "content": "Implementation specific information should be placed here.\n\n.Sh Return values  Sections  2,  3  and  9  function return values should go here.  The ‘.Rv’\nmacro may be used to generate text for use in the “Return values”  section\nfor most section 2 and 3 library functions; see “Return Values”.\n\nThe following ‘.Sh’ section headings are part of the preferred manual page layout and must be\nused appropriately to maintain consistency.  They are listed in the order in which they would\nbe used.\n\n.Sh Environment    The  Environment  section  should reveal any related environment variables\nand clues to their behavior and/or usage.\n\n.Sh Files          Files which are used or created by the man page subject should  be  listed\nvia the ‘.Pa’ macro in the “Files” section.\n\n.Sh Examples       There  are  several ways to create examples.  See subsection “Examples and\nDisplays” below for details.\n\n.Sh Diagnostics    Diagnostic messages from a command should be placed in this section.   The\n‘.Ex’ macro may be used to generate text for use in the “Diagnostics” sec‐\ntion for most section 1, 6 and 8 commands; see “Exit Status”.\n\n.Sh Compatibility  Known  compatibility issues (e.g. deprecated options or parameters) should\nbe listed here.\n\n.Sh Errors         Specific error handling, especially from library functions (man page  sec‐\ntions  2, 3, and 9) should go here.  The ‘.Er’ macro is used to specify an\nerror (errno).\n\n.Sh See also       References to other material on the man page topic and cross references to\nother relevant man pages should be  placed  in  the  “See  also”  section.\nCross  references are specified using the ‘.Xr’ macro.  Currently refer(1)\nstyle references are not accommodated.\n\nIt is recommended that the cross references be sorted by  section  number,\nthen alphabetically by name within each section, then separated by commas.\nExample:\n\nls(1), ps(1), group(5), passwd(5)\n\n.Sh Standards      If  the command, library function, or file adheres to a specific implemen‐\ntation  such  as  IEEE  Std  1003.2  (“POSIX.2”)   or   ANSI   X3.159-1989\n(“ANSI C89”) this should be noted here.  If the command does not adhere to\nany standard, its history should be noted in the History section.\n\n.Sh History        Any command which does not adhere to any specific standards should be out‐\nlined historically in this section.\n\n.Sh Authors        Credits  should  be  placed  here.   Use the ‘.An’ macro for names and the\n‘.Aq’ macro for email addresses within optional contact information.   Ex‐\nplicitly  indicate  whether the person authored the initial manual page or\nthe software or whatever the person is being credited for.\n\n.Sh Bugs           Blatant problems with the topic go here.\n\nUser-specified ‘.Sh’ sections may be added; for example, this section was set with:\n\n.Sh \"Page structure domain\"\n"
                },
                {
                    "name": "Subsection headings",
                    "content": "Subsection headings have exactly the same syntax as section headings: ‘.Ss’ is parsed but not\ngenerally callable.  It can be used as an argument in a call to ‘.Ss’ only; it  then  reacti‐\nvates the default font for ‘.Ss’.\n\nThe default width is 8n.\n"
                },
                {
                    "name": "Paragraphs and Line Spacing",
                    "content": ".Pp  The  ‘.Pp’  paragraph  command may be used to specify a line space where necessary.  The\nmacro is not necessary after a ‘.Sh’ or ‘.Ss’ macro or before a  ‘.Bl’  or  ‘.Bd’  macro\n(which both assert a vertical distance unless the -compact flag is given).\n\nThe  macro is neither callable nor parsed and takes no arguments; an alternative name is\n‘.Lp’.\n"
                },
                {
                    "name": "Keeps",
                    "content": "The only keep that is implemented at this time is for words.  The  macros  are  ‘.Bk’  (begin\nkeep) and ‘.Ek’ (end keep).  The only option that ‘.Bk’ currently accepts is -words (also the\ndefault);  this  prevents  breaks in the middle of options.  In the example for make command-\nline arguments (see “What's in a Name”), the keep prevents nroff from placing  the  flag  and\nthe argument on separate lines.\n\nNeither macro is callable or parsed.\n\nMore work needs to be done on the keep macros; specifically, a -line option should be added.\n"
                },
                {
                    "name": "Examples and Displays",
                    "content": "There are seven types of displays.\n\n.D1  (This  is  D-one.)   Display  one  line  of indented text.  This macro is parsed but not\ncallable.\n\n-ldghfstru\n\nThe above was produced by: .D1 Fl ldghfstru.\n\n.Dl  (This is D-ell.)  Display one line of indented literal text.  The  ‘.Dl’  example  macro\nhas  been used throughout this file.  It allows the indentation (display) of one line of\ntext.  Its default font is set to constant width (literal).  ‘.Dl’  is  parsed  but  not\ncallable.\n\n% ls -ldg /usr/local/bin\n\nThe above was produced by: .Dl % ls \\-ldg /usr/local/bin.\n\n.Bd  Begin  display.   The ‘.Bd’ display must be ended with the ‘.Ed’ macro.  It has the fol‐\nlowing syntax:\n\n.Bd {-literal | -filled | -unfilled | -ragged | -centered} [-offset ⟨string⟩]\n[-file ⟨file name⟩] [-compact]\n\n-ragged            Fill, but do not adjust the right margin (only left-justify).\n-centered          Center lines between the current left and right  margin.   Note  that\neach single line is centered.\n-unfilled          Do  not  fill;  break lines where their input lines are broken.  This\ncan produce overlong lines without warning messages.\n-filled            Display a filled block.  The block of text is  formatted  (i.e.,  the\ntext is justified on both the left and right side).\n-literal           Display  block  with  literal font (usually fixed-width).  Useful for\nsource code or simple tabbed or spaced text.\n-file ⟨file name⟩  The file whose name follows the -file flag is read and displayed  be‐\nfore  any data enclosed with ‘.Bd’ and ‘.Ed’, using the selected dis‐\nplay type.  Any troff/mdoc commands in the file will be processed.\n-offset ⟨string⟩   If -offset is specified with one of the following strings, the string\nis interpreted to indicate the level of indentation for the forthcom‐\ning block of text:\n\nleft        Align block on the current left margin; this is  the  de‐\nfault mode of ‘.Bd’.\ncenter      Supposedly center the block.  At this time unfortunately,\nthe  block  merely  gets  left aligned about an imaginary\ncenter margin.\nindent      Indent by one default indent value or tab.   The  default\nindent value is also used for the ‘.D1’ and ‘.Dl’ macros,\nso  one is guaranteed the two types of displays will line\nup.  The indentation value is normally set to 6n or about\ntwo thirds of an inch (six constant width characters).\nindent-two  Indent two times the default indent value.\nright       This left aligns the block  about  two  inches  from  the\nright  side  of the page.  This macro needs work and per‐\nhaps may never do the right thing within troff.\n\nIf ⟨string⟩ is a valid numeric expression  instead  (with  a  scaling\nindicator  other than ‘u’), use that value for indentation.  The most\nuseful scaling indicators are ‘m’ and ‘n’, specifying  the  so-called\nEm and En square.  This is approximately the width of the letters ‘m’\nand  ‘n’  respectively  of  the  current font (for nroff output, both\nscaling indicators give the same values).  If ⟨string⟩  isn't  a  nu‐\nmeric  expression, it is tested whether it is an mdoc macro name, and\nthe default offset value associated with this  macro  is  used.   Fi‐\nnally,  if  all  tests  fail,  the  width of ⟨string⟩ (typeset with a\nfixed-width font) is taken as the offset.\n-compact           Suppress insertion of vertical space before begin of display.\n\n.Ed  End display (takes no arguments).\n"
                },
                {
                    "name": "Lists and Columns",
                    "content": "There are several types of lists which may be initiated  with  the  ‘.Bl’  begin-list  macro.\nItems  within  the  list are specified with the ‘.It’ item macro, and each list must end with\nthe ‘.El’ macro.  Lists may be nested within themselves and  within  displays.   The  use  of\ncolumns inside of lists or lists inside of columns is untested.\n\nIn  addition,  several  list attributes may be specified such as the width of a tag, the list\noffset, and compactness (blank lines between items allowed or disallowed).  Most of this doc‐\nument has been formatted with a tag style list (-tag).\n\nIt has the following syntax forms:\n\n.Bl {-hang | -ohang | -tag | -diag | -inset} [-width ⟨string⟩] [-offset ⟨string⟩]\n[-compact]\n.Bl -column [-offset ⟨string⟩] ⟨string1⟩ ⟨string2⟩ ...\n.Bl {-item | -enum [-nested] | -bullet | -hyphen | -dash} [-offset ⟨string⟩] [-compact]\n\nAnd now a detailed description of the list types.\n"
                },
                {
                    "name": "-bullet",
                    "content": ".Bl -bullet -offset indent -compact\n.It\nBullet one goes here.\n.It\nBullet two here.\n.El\n\nProduces:\n\n•   Bullet one goes here.\n•   Bullet two here.\n"
                },
                {
                    "name": "-dash  -hyphen",
                    "content": "A dash list.\n\n.Bl -dash -offset indent -compact\n.It\nDash one goes here.\n.It\nDash two here.\n.El\n\nProduces:\n\n-   Dash one goes here.\n-   Dash two here.\n"
                },
                {
                    "name": "-enum",
                    "content": ".Bl -enum -offset indent -compact\n.It\nItem one goes here.\n.It\nAnd item two here.\n.El\n\nThe result:\n\n1.   Item one goes here.\n2.   And item two here.\n\nIf you want to nest enumerated lists, use the -nested flag (starting with  the  sec‐\nond-level list):\n\n.Bl -enum -offset indent -compact\n.It\nItem one goes here\n.Bl -enum -nested -compact\n.It\nItem two goes here.\n.It\nAnd item three here.\n.El\n.It\nAnd item four here.\n.El\n\nResult:\n\n1.   Item one goes here.\n1.1.   Item two goes here.\n1.2.   And item three here.\n2.   And item four here.\n"
                },
                {
                    "name": "-item     -item",
                    "content": ".Bl -item -offset indent\n.It\nItem one goes here.\nItem one goes here.\nItem one goes here.\n.It\nItem two here.\nItem two here.\nItem two here.\n.El\n\nProduces:\n\nItem one goes here.  Item one goes here.  Item one goes here.\n\nItem two here.  Item two here.  Item two here.\n"
                },
                {
                    "name": "-tag      -width",
                    "content": "SL    sleep time of the process (seconds blocked)\nPAGEIN\nnumber  of  disk I/O operations resulting from references by the process\nto pages not loaded in core.\nUID   numerical user-id of process owner\nPPID  numerical id of parent of process priority (non-positive when in non-in‐\nterruptible wait)\n\nThe raw text:\n\n.Bl -tag -width \"PPID\" -compact -offset indent\n.It SL\nsleep time of the process (seconds blocked)\n.It PAGEIN\nnumber of disk I/O operations resulting from references\nby the process to pages not loaded in core.\n.It UID\nnumerical user-id of process owner\n.It PPID\nnumerical id of parent of process priority\n(non-positive when in non-interruptible wait)\n.El\n"
                },
                {
                    "name": "-diag",
                    "content": "cept  callable  macros  are ignored.  The -width flag is not meaningful in this con‐\ntext.\n\nExample:\n\n.Bl -diag\n.It You can't use Sy here.\nThe message says all.\n.El\n\nproduces\n\nYou can't use Sy here.  The message says all.\n"
                },
                {
                    "name": "-hang",
                    "content": "Hanged  labels appear similar to tagged lists when the label is  smaller  than\nthe label width.\n\nLonger hanged list labels blend into the paragraph unlike tagged paragraph la‐\nbels.\n\nAnd the unformatted text which created it:\n\n.Bl -hang -offset indent\n.It Em Hanged\nlabels appear similar to tagged lists when the\nlabel is smaller than the label width.\n.It Em Longer hanged list labels\nblend into the paragraph unlike\ntagged paragraph labels.\n.El\n"
                },
                {
                    "name": "-ohang",
                    "content": "to a separate line.\n\nSL\nsleep time of the process (seconds blocked)\n\nPAGEIN\nnumber of disk I/O operations resulting from  references  by  the  process  to\npages not loaded in core.\n\nUID\nnumerical user-id of process owner\n\nPPID\nnumerical  id  of  parent of process priority (non-positive when in non-inter‐\nruptible wait)\n\nThe raw text:\n\n.Bl -ohang -offset indent\n.It Sy SL\nsleep time of the process (seconds blocked)\n.It Sy PAGEIN\nnumber of disk I/O operations resulting from references\nby the process to pages not loaded in core.\n.It Sy UID\nnumerical user-id of process owner\n.It Sy PPID\nnumerical id of parent of process priority\n(non-positive when in non-interruptible wait)\n.El\n"
                },
                {
                    "name": "-inset",
                    "content": "Tag The tagged list (also called a tagged paragraph) is the most  common  type\nof list used in the Berkeley manuals.  Use a -width attribute as described be‐\nlow.\n\nDiag  Diag lists create section four diagnostic lists and are similar to inset\nlists except callable macros are ignored.\n\nHang Hanged labels are a matter of taste.\n\nOhang Overhanging labels are nice when space is constrained.\n\nInset Inset labels are useful for controlling blocks  of  paragraphs  and  are\nvaluable for converting mdoc manuals to other formats.\n\nHere is the source text which produced the above example:\n\n.Bl -inset -offset indent\n.It Em Tag\nThe tagged list (also called a tagged paragraph)\nis the most common type of list used in the\nBerkeley manuals.\n.It Em Diag\nDiag lists create section four diagnostic lists\nand are similar to inset lists except callable\nmacros are ignored.\n.It Em Hang\nHanged labels are a matter of taste.\n.It Em Ohang\nOverhanging labels are nice when space is constrained.\n.It Em Inset\nInset labels are useful for controlling blocks of\nparagraphs and are valuable for converting\n.Xr mdoc\nmanuals to other formats.\n.El\n"
                },
                {
                    "name": "-column",
                    "content": "each column  is  determined  by  the  arguments  to  the  -column  list,  ⟨string1⟩,\n⟨string2⟩,  etc.   If  ⟨stringN⟩  starts  with a ‘.’ (dot) immediately followed by a\nvalid mdoc macro name, interpret ⟨stringN⟩ and use the width of the result.   Other‐\nwise,  the  width of ⟨stringN⟩ (typeset with a fixed-width font) is taken as the Nth\ncolumn width.\n\nEach ‘.It’ argument is parsed to make a row, each column within the row is  a  sepa‐\nrate argument separated by a tab or the ‘.Ta’ macro.\n\nThe table:\n\nString    Nroff    Troff\n<=        <=       ≤\n>=        >=       ≥\n\nwas produced by:\n\n.Bl -column -offset indent \".Sy String\" \".Sy Nroff\" \".Sy Troff\"\n.It Sy String Ta Sy Nroff Ta Sy Troff\n.It Li <= Ta <= Ta \\*(<=\n.It Li >= Ta >= Ta \\*(>=\n.El\n\nDon't  abuse  this list type!  For more complicated cases it might be far better and\neasier to use tbl(1), the table preprocessor.\n\nOther keywords:\n"
                },
                {
                    "name": "-width",
                    "content": "macro name, interpret ⟨string⟩ and use the width of the result.  Almost all\nlists in this document use this option.\n\nExample:\n\n.Bl -tag -width \".Fl test Ao Ar string Ac\"\n.It Fl test Ao Ar string Ac\nThis is a longer sentence to show how the\n.Fl width\nflag works in combination with a tag list.\n.El\n\ngives:\n\n-test ⟨string⟩  This is a longer sentence to show how the -width flag works\nin combination with a tag list.\n\n(Note  that  the  current  state of mdoc is saved before ⟨string⟩ is inter‐\npreted; afterwards, all variables are restored again.  However, boxes (used\nfor enclosures) can't be saved in GNU troff(1); as a consequence, arguments\nmust always be balanced to avoid nasty errors.  For example, do  not  write\n‘.Ao  Ar  string’ but ‘.Ao Ar string Xc’ instead if you really need only an\nopening angle bracket.)\n\nOtherwise, if ⟨string⟩ is  a  valid  numeric  expression  (with  a  scaling\nindicator other than ‘u’), use that value for indentation.  The most useful\nscaling  indicators  are  ‘m’  and  ‘n’, specifying the so-called Em and En\nsquare.  This is approximately the width of the letters ‘m’ and ‘n’ respec‐\ntively of the current font (for nroff output, both scaling indicators  give\nthe  same  values).   If  ⟨string⟩ isn't a numeric expression, it is tested\nwhether it is an mdoc macro name, and the default  width  value  associated\nwith this macro is used.  Finally, if all tests fail, the width of ⟨string⟩\n(typeset with a fixed-width font) is taken as the width.\n\nIf a width is not specified for the tag list type, ‘6n’ is used.\n"
                },
                {
                    "name": "-offset",
                    "content": "to the value used in ‘.Dl’ or ‘.Bd’) is used.  If ⟨string⟩ is a  valid  nu‐\nmeric  expression  instead  (with  a scaling indicator other than ‘u’), use\nthat value for indentation.  The most useful scaling indicators are ‘m’ and\n‘n’, specifying the so-called Em and En square.  This is approximately  the\nwidth  of  the  letters  ‘m’  and ‘n’ respectively of the current font (for\nnroff output, both scaling indicators give the same values).   If  ⟨string⟩\nisn't  a numeric expression, it is tested whether it is an mdoc macro name,\nand the default offset value associated with this macro is used.   Finally,\nif  all tests fail, the width of ⟨string⟩ (typeset with a fixed-width font)\nis taken as the offset.\n"
                },
                {
                    "name": "-compact",
                    "content": "items.\n"
                }
            ]
        },
        "Miscellaneous macros": {
            "content": "A  double handful of macros fit only uncomfortably into one of the above sections.  Of these,\nwe couldn't find attested examples for ‘Me’ or ‘Ot’.  They are documented here for  complete‐\nness—if you know their proper usage, please send a mail to groff@gnu.org and include a speci‐\nmen with its provenance.\n\n.Bt  formats boilerplate text.\n\n.Bt  → is currently in beta test.\n\nIt is neither callable nor parsed and takes no arguments.  Its default width is 6n.\n\n.Fr  is an obsolete means of specifying a function return value.\n\nUsage: .Fr return-value ...\n\n‘Fr’  allows a break right before the return value (usually a single digit) which is bad\ntypographical behaviour.  Instead, set the return value with the rest of the code, using\n‘\\~’ to tie the return value to the previous word.\n\nIts default width is 12n.\n\n.Hf  Inlines the contents of a (header) file into the document.\n\nUsage: .Hf file\n\nIt first prints ‘File:’ followed by the file name, then the contents  of  file.   It  is\nneither callable nor parsed.\n\n.Lk  Embed hyperlink.\n\nUsage: .Lk uri [link-text]\n\nIts default width is 6n.\n\n.Me  Usage unknown.  The mdoc sources describe it as a macro for “menu entries”.\n\nIts default width is 6n.\n\n.Mt  Embed email address.\n\nUsage: .Mt email-address\n\nIts default width is 6n.\n\n.Ot  Usage unknown.  The mdoc sources describe it as “old function type (fortran)”.\n\n.Sm  Manipulate or toggle argument-spacing mode.\n\nUsage: .Sm [on | off] ...\n\nIf  argument-spacing  mode  is  off, no spaces between macro arguments are inserted.  If\ncalled without a parameter (or if the next parameter is neither ‘on’  nor  ‘off’),  ‘Sm’\ntoggles argument-spacing mode.\n\nIts default width is 8n.\n\n.Ud  formats boilerplate text.\n\n.Ud  → currently under development.\n\nIt is neither callable nor parsed and takes no arguments.  Its default width is 8n.\n",
            "subsections": []
        },
        "Predefined strings": {
            "content": "The following strings are predefined for compatibility with legacy mdoc documents.  Contempo‐\nrary  ones should use the alternatives shown in the “Prefer” column below.  See groffchar(7)\nfor a full discussion of these special character escape sequences.\n",
            "subsections": [
                {
                    "name": "String   7-bit     8-bit     UCS   Prefer   Meaning",
                    "content": "\\*(<=    <=        <=        ≤     \\(<=     less than or equal to\n\\*(>=    >=        >=        ≥     \\(>=     greater than or equal to\n\\*(Rq    \"         \"         ”     \\(rq     right double quote\n\\*(Lq    \"         \"         “     \\(lq     left double quote\n\\*(ua    ^         ^         ↑     \\(ua     vertical arrow up\n\\*(aa    '         ´         ´     \\(aa     acute accent\n\\*(ga    `         `         `     \\(ga     grave accent\n\\*(q     \"         \"         \"     \\(dq     neutral double quote\n\\*(Pi    pi        pi        π     \\(*p     lowercase pi\n\\*(Ne    !=        !=        ≠     \\(!=     not equals\n\\*(Le    <=        <=        ≤     \\(<=     less than or equal to\n\\*(Ge    >=        >=        ≥     \\(>=     greater than or equal to\n\\*(Lt    <         <         <     <        less than\n\\*(Gt    >         >         >     >        greater than\n\\*(Pm    +-        ±         ±     \\(+-     plus or minus\n\\*(If    infinity  infinity  ∞     \\(if     infinity\n\\*(Am    &         &         &     &        ampersand\n\\*(Na    NaN       NaN       NaN   NaN      not a number\n\\*(Ba    |         |         |     |        bar\n\nSome column headings are shorthand for standardized  character  encodings;  “7-bit”  for  ISO\n646:1991  IRV  (US-ASCII), “8-bit” for ISO 8859-1 (Latin-1) and IBM code page 1047, and “UCS”\nfor ISO 10646 (Unicode character set).  Historically, mdoc configured the string  definitions\nto  fit  the  capabilities expected of the output device.  Old typesetters lacked directional\ndouble quotes, producing repeated directional single quotes ‘‘like this’’; early versions  of\nmdoc  in  fact  defined the ‘Lq’ and ‘Rq’ strings this way.  Nowadays, output drivers take on\nthe responsibility of glyph substitution, as they possess relevant knowledge of their  avail‐\nable repertoires.\n"
                }
            ]
        },
        "Diagnostics": {
            "content": "The debugging macro ‘.Db’ offered by previous versions of mdoc is unavailable in GNU troff(1)\nsince the latter provides better facilities to check parameters; additionally, groff mdoc im‐\nplements many error and warning messages, making the package more robust and more verbose.\n\nThe  remaining debugging macro is ‘.Rd’, which dumps the package's global register and string\ncontents to the standard error stream.  A normal user will never need it.\n",
            "subsections": []
        },
        "Options": {
            "content": "The following groff options set registers (with -r) and strings (with -d) recognized and used\nby the mdoc macro package.  To ensure rendering consistent with  output  device  capabilities\nand reader preferences, man pages should never manipulate them.\n\nSetting  string  ‘AD’ configures the adjustment mode for most formatted text.  Typical values\nare ‘b’ for adjustment to both margins (the default), or ‘l’ for left alignment (ragged right\nmargin).  Any valid argument to groff's ‘ad’ request may be used.  See groff(7) for less-com‐\nmon choices.\ngroff -Tutf8 -dAD=l -mdoc groffmdoc.7 | less -R\n\nSetting register ‘C’ to 1 numbers output pages consecutively, rather than resetting the  page\nnumber to 1 (or the value of register ‘P’) with each new mdoc document.\n\nBy  default, the package inhibits page breaks, headers, and footers in the midst of the docu‐\nment text if it is being displayed with a terminal device such as ‘latin1’ or ‘utf8’, to  en‐\nable  more efficient viewing of the page.  This behavior can be changed to format the page as\nif for 66-line Teletype output by setting the continuous  rendering  register  ‘cR’  to  zero\nwhile calling groff(1).\ngroff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt\nOn HTML devices, it cannot be disabled.\n\nSection  headings (defined with ‘.Sh’) and page titles in headers (defined with ‘.Dt’) can be\npresented in full capitals by setting the registers ‘CS’ and ‘CT’, respectively, to 1.  These\ntransformations are off by default because they discard case distinction information.\n\nSetting register ‘D’ to 1 enables double-sided page layout, which is only distinct  when  not\ncontinuously  rendering.   It  places  the  page  number  at the bottom right on odd-numbered\n(recto) pages, and at the bottom left on even-numbered (verso) pages,  swapping  places  with\nthe arguments to ‘.Os’.\ngroff -Tps -rD1 -mdoc foo.man > foo.ps\n\nThe  value  of  the ‘FT’ register determines the footer's distance from the page bottom; this\namount is always negative and should specify a scaling unit.  At one half-inch above this lo‐\ncation, the page text is broken before writing the footer.  It is ignored if continuous  ren‐\ndering is enabled.  The default is -0.5i.\n\nThe  ‘HF’  string  sets the font used for section and subsection headings; the default is ‘B’\n(bold style of the default family).  Any valid argument to groff's ‘ft’ request may be used.\n\nNormally, automatic hyphenation is enabled using a mode appropriate to the groff locale;  see\nsection “Localization“ of groff(7).  It can be disabled by setting the ‘HY’ register to zero.\ngroff -Tutf8 -rHY=0 -mdoc foo.man | less -R\n\nThe paragraph and subsection heading indentation amounts can be changed by setting the regis‐\nters ‘IN’ and ‘SN’.\ngroff -Tutf8 -rIN=5n -rSN=2n -mdoc foo.man | less -R\nThe  default  paragraph  indentation is 7.2n on typesetters and 7n on terminals.  The default\nsubsection heading indentation amount is 3n; section headings are set with an indentation  of\nzero.\n\nThe  line  and  title  lengths can be changed by setting the registers ‘LL’ and ‘LT’, respec‐\ntively:\ngroff -Tutf8 -rLL=100n -rLT=100n -mdoc foo.man | less -R\nIf not set, both registers default to 78n for terminal devices and 6.5i otherwise.\n\nSetting the ‘P’ register starts enumeration of pages at its value.  The default is 1.\n\nTo change the document font size to 11p or 12p, set register ‘S’ accordingly:\ngroff -Tdvi -rS11 -mdoc foo.man > foo.dvi\nRegister ‘S’ is ignored when formatting for terminal devices.\n\nSetting the ‘X’ register to a page number p numbers its successors as  pa,  pb,  pc,  and  so\nforth.   The register tracking the suffixed page letter uses format ‘a’ (see the ‘af’ request\nin groff(7)).\n",
            "subsections": []
        },
        "Files": {
            "content": "/usr/share/groff/1.23.0/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, before any other  macros.   A\nuser typing, for example,\ngroff -mandoc page.1\nneed not know which package the file page.1 uses.  Multiple man pages, in either for‐\nmat, can be handled; andoc.tmac reloads each macro package as necessary.\n\n/usr/share/groff/1.23.0/tmac/doc.tmac\nimplements  the bulk of the groff mdoc package and loads further components as needed\nfrom the mdoc subdirectory.\n\n/usr/share/groff/1.23.0/tmac/mdoc.tmac\nis a wrapper that loads doc.tmac.\n\n/usr/share/groff/1.23.0/tmac/mdoc/doc-common\ndefines macros, registers, and strings concerned with  the  production  of  formatted\noutput.   It includes strings of the form ‘doc-volume-ds-X’ and ‘doc-volume-as-X’ for\nmanual section titles and architecture identifiers, respectively, where X is an argu‐\nment recognized by .Dt.\n\n/usr/share/groff/1.23.0/tmac/mdoc/doc-nroff\ndefines parameters appropriate for rendering to terminal devices.\n\n/usr/share/groff/1.23.0/tmac/mdoc/doc-ditroff\ndefines parameters appropriate for rendering to typesetter devices.\n\n/usr/share/groff/1.23.0/tmac/mdoc/doc-syms\ndefines many strings and macros that interpolate formatted text, such as names of op‐\nerating system releases, *BSD libraries, and standards documents.  The  string  names\nare  of  the  form  ‘doc-str-O-V’,  ‘doc-str-St--S-I’ (observe the double dashes), or\n‘doc-str-Lb-L’, where O is one of the operating system macros from  section  “General\ntext  domain” above, V is an encoding of an operating system release (sometimes omit‐\nted along with the ‘-’ preceding it), S an identifier for a standards body or commit‐\ntee, I one for an issue of a standard promulgated by S, and L a keyword identifying a\n*BSD library.\n\n/usr/share/groff/site-tmac/mdoc.local\nThis file houses local additions and customizations to the package.  It can be empty.\n\nSee also\nThe mandoc: https://mandoc.bsd.lv/ project maintains an  independent  implementation  of  the\nmdoc language and a renderer that directly parses its markup as well as that of man.\n\ngroff(1), man(1), troff(1), groffman(7), mdoc(7)\n",
            "subsections": []
        },
        "Bugs": {
            "content": "Section 3f has not been added to the header routines.\n\n‘.Fn’ needs to have a check to prevent splitting up the line if its length is too short.  Oc‐\ncasionally  it separates the last parenthesis, and sometimes looks ridiculous if output lines\nare being filled.\n\nThe list and display macros do not do any keeps and certainly should be able to.\n\nAs of groff 1.23, ‘Tn’ no longer changes the type size; this functionality may return in  the\nnext release.\n\ngroff 1.23.0                                31 March 2024                              groffmdoc(7)",
            "subsections": []
        }
    },
    "flags": [],
    "examples": [],
    "see_also": []
}