{
    "mode": "man",
    "parameter": "GROFF_MDOC",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/GROFF_MDOC/7/json",
    "generated": "2026-05-30T06:08:14Z",
    "synopsis": "groff -mdoc file ...",
    "sections": {
        "NAME": {
            "content": "groffmdoc — reference for groff's mdoc implementation\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "groff -mdoc file ...\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "A complete reference for writing UNIX manual pages with the -mdoc macro package; a\ncontent-based and domain-based formatting package for GNU troff(1).  Its predecessor, the\n-man(7) package, addressed page layout leaving the manipulation of fonts and other typesetting\ndetails to the individual author.  In -mdoc, page layout macros make up the page structure\ndomain which consists of macros for titles, section headers, displays and lists – essentially\nitems which affect the physical position of text on a formatted page.  In addition to the page\nstructure domain, there are two more domains, the manual domain and the general text domain.\nThe general text domain is defined as macros which perform tasks such as quoting or emphasizing\npieces of text.  The manual domain is defined as macros that are a subset of the day to day in‐\nformal language used to describe commands, routines and related UNIX files.  Macros in the man‐\nual domain handle command names, command-line arguments and options, function names, function\nparameters, pathnames, variables, cross references to other manual pages, and so on.  These do‐\nmain items have value for both the author and the future user of the manual page.  Hopefully,\nthe consistency gained across the manual set will provide easier translation to future documen‐\ntation tools.\n\nThroughout the UNIX manual pages, a manual entry is simply referred to as a man page, regard‐\nless of actual length and without sexist intention.\n",
            "subsections": []
        },
        "GETTING STARTED": {
            "content": "The material presented in the remainder of this document is outlined as follows:\n\n1.   TROFF IDIOSYNCRASIES\nMacro Usage\nPassing Space Characters in an Argument\nTrailing Blank Space Characters\nEscaping Special Characters\nOther Possible Pitfalls\n\n2.   A MANUAL PAGE TEMPLATE\n\n3.   CONVENTIONS\n\n4.   TITLE MACROS\n\n5.   INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS\nWhat's in a Name...\nGeneral Syntax\n\n6.   MANUAL DOMAIN\nAddresses\nAuthor Name\nArguments\nConfiguration Declarations (Section Four Only)\nCommand Modifiers\nDefined Variables\nErrno's\nEnvironment Variables\nFlags\nFunction Declarations\nFunction Types\nFunctions (Library Routines)\nFunction Arguments\nReturn Values\nExit Status\nInteractive Commands\nLibrary Names\nLiterals\nNames\nOptions\nPathnames\nStandards\nVariable Types\nVariables\nManual Page Cross References\n\n7.   GENERAL TEXT DOMAIN\nAT&T Macro\nBSD Macro\nNetBSD Macro\nFreeBSD Macro\nDragonFly Macro\nOpenBSD Macro\nBSD/OS Macro\nUNIX Macro\nEmphasis Macro\nFont Mode\nEnclosure and Quoting Macros\nNo-Op or Normal Text Macro\nNo-Space Macro\nSection Cross References\nSymbolics\nMathematical Symbols\nReferences and Citations\nTrade Names (or Acronyms and Type Names)\nExtended Arguments\n\n8.   PAGE STRUCTURE DOMAIN\nSection Headers\nSubsection Headers\nParagraphs and Line Spacing\nKeeps\nExamples and Displays\nLists and Columns\n\n9.   MISCELLANEOUS MACROS\n\n10.  PREDEFINED STRINGS\n\n11.  DIAGNOSTICS\n\n12.  FORMATTING WITH GROFF, TROFF, AND NROFF\n\n13.  FILES\n\n14.  SEE ALSO\n\n15.  BUGS\n",
            "subsections": []
        },
        "TROFF IDIOSYNCRASIES": {
            "content": "The -mdoc package attempts to simplify the process of writing a man page.  Theoretically, one\nshould not have to learn the tricky details of GNU troff(1) to use -mdoc; however, there are a\nfew limitations which are unavoidable and best gotten out of the way.  And, too, be forewarned,\nthis package is not fast.\n",
            "subsections": [
                {
                    "name": "Macro Usage",
                    "content": "As in GNU troff(1), a macro is called by placing a ‘.’ (dot character) at the beginning of a\nline followed by the two-character (or three-character) name for the macro.  There can be space\nor tab characters between the dot and the macro name.  Arguments may follow the macro separated\nby spaces (but no tabs).  It is the dot character at the beginning of the line which causes GNU\ntroff(1) to interpret the next two (or more) characters as a macro name.  A single starting dot\nfollowed by nothing is ignored.  To place a ‘.’ (dot character) at the beginning of an input\nline in some context other than a macro invocation, precede the ‘.’ (dot) with the ‘\\&’ escape\nsequence which translates literally to a zero-width space, and is never displayed in the out‐\nput.\n\nIn general, GNU troff(1) macros accept an unlimited number of arguments (contrary to other ver‐\nsions of troff which can't handle more than nine arguments).  In limited cases, arguments may\nbe continued or extended on the next line (See Extended Arguments below).  Almost all macros\nhandle quoted arguments (see Passing Space Characters in an Argument below).\n\nMost of the -mdoc general text domain and manual domain macros are special in that their argu‐\nment lists are parsed for callable macro names.  This means an argument on the argument list\nwhich matches a general text or manual domain macro name (and which is defined to be callable)\nwill be executed or called when it is processed.  In this case the argument, although the name\nof a macro, is not preceded by a ‘.’ (dot).  This makes it possible to nest macros; for example\nthe option macro, ‘.Op’, may call the flag and argument macros, ‘Fl’ and ‘Ar’, to specify an\noptional flag with an argument:\n\n[-s bytes]  is produced by ‘.Op Fl s Ar bytes’\n\nTo prevent a string from being interpreted as a macro name, precede the string with the escape\nsequence ‘\\&’:\n\n[Fl s Ar bytes]  is produced by ‘.Op \\&Fl s \\&Ar bytes’\n\nHere the strings ‘Fl’ and ‘Ar’ are not interpreted as macros.  Macros whose argument lists are\nparsed for callable arguments are referred to as parsed and macros which may be called from an\nargument list are referred to as callable throughout this document.  This is a technical faux\npas as almost all of the macros in -mdoc are parsed, but as it was cumbersome to constantly re‐\nfer to macros as being callable and being able to call other macros, the term parsed has been\nused.\n\nIn the following, we call an -mdoc macro which starts a line (with a leading dot) a command if\nthis distinction is necessary.\n"
                },
                {
                    "name": "Passing Space Characters in an Argument",
                    "content": "Sometimes it is desirable to give as an argument a string containing one or more blank space\ncharacters, say, to specify arguments to commands which expect particular arrangement of items\nin the argument list.  Additionally, it makes -mdoc working faster.  For example, the function\ncommand ‘.Fn’ expects the first argument to be the name of a function and any remaining argu‐\nments to be function parameters.  As ANSI C stipulates the declaration of function parameters\nin the parenthesized parameter list, each parameter is guaranteed to be at minimum a two word\nstring.  For example, int foo.\n\nThere are two possible ways to pass an argument which contains an embedded space.  One way of\npassing a string containing blank spaces is to use the hard or unpaddable space character ‘\\ ’,\nthat is, a blank space preceded by the escape character ‘\\’.  This method may be used with any\nmacro but has the side effect of interfering with the adjustment of text over the length of a\nline.  Troff sees the hard space as if it were any other printable character and cannot split\nthe string into blank or newline separated pieces as one would expect.  This method is useful\nfor strings which are not expected to overlap a line boundary.  An alternative is to use ‘\\~’,\na paddable (i.e. stretchable), unbreakable space (this is a GNU troff(1) extension).  The sec‐\nond method is to enclose the string with double quotes.\n\nFor example:\n\nfetch(char *str)  is created by ‘.Fn fetch char\\ *str’\n\nfetch(char *str)  can also be created by ‘.Fn fetch \"char *str\"’\n\nIf the ‘\\’ before the space in the first example or double quotes in the second example were\nomitted, ‘.Fn’ would see three arguments, and the result would be:\n\nfetch(char, *str)\n"
                },
                {
                    "name": "Trailing Blank Space Characters",
                    "content": "Troff can be confused by blank space characters at the end of a line.  It is a wise preventive\nmeasure to globally remove all blank spaces from ⟨blank-space⟩⟨end-of-line⟩ character se‐\nquences.  Should the need arise to use a blank character at the end of a line, it may be forced\nwith an unpaddable space and the ‘\\&’ escape character.  For example, ‘string\\ \\&’.\n"
                },
                {
                    "name": "Escaping Special Characters",
                    "content": "Special characters like the newline character ‘\\n’ are handled by replacing the ‘\\’ with ‘\\e’\n(e.g. ‘\\en’) to preserve the backslash.\n"
                },
                {
                    "name": "Other Possible Pitfalls",
                    "content": "A warning is emitted when an empty input line is found outside of displays (see below).  Use\n‘.sp’ instead.  (Well, it is even better to use -mdoc macros to avoid the usage of low-level\ncommands.)\n\nLeading spaces will cause a break and are output directly.  Avoid this behaviour if possible.\nSimilarly, do not use more than one space character between words in an ordinary text line;\ncontrary to other text formatters, they are not replaced with a single space.\n\nYou can't pass ‘\"’ directly as an argument.  Use ‘\\*[q]’ (or ‘\\*q’) instead.\n\nBy default, troff(1) inserts two space characters after a punctuation mark closing a sentence;\ncharacters like ‘)’ or ‘'’ are treated transparently, not influencing the sentence-ending be‐\nhaviour.  To change this, insert ‘\\&’ before or after the dot:\n\nThe\n.Ql .\ncharacter.\n.Pp\nThe\n.Ql \\&.\ncharacter.\n.Pp\n.No test .\ntest\n.Pp\n.No test.\ntest\n\ngives\n\nThe ‘’.  character\n\nThe ‘.’ character.\n\ntest.  test\n\ntest. test\n\nAs can be seen in the first and third line, -mdoc handles punctuation characters specially in\nmacro arguments.  This will be explained in section General Syntax below.  In the same way, you\nhave to protect trailing full stops of abbreviations with a trailing zero-width space:\n‘e.g.\\&’.\n\nA comment in the source file of a man page can be either started with ‘.\\\"’ on a single line,\n‘\\\"’ after some input, or ‘\\#’ anywhere (the latter is a GNU troff(1) extension); the rest of\nsuch a line is ignored.\n"
                }
            ]
        },
        "A MANUAL PAGE TEMPLATE": {
            "content": "The body of a man page is easily constructed from a basic template:\n\n.\\\" The following commands are required for all man pages.\n.Dd Month day, year\n.Dt DOCUMENTTITLE [section number] [architecture/volume]\n.Os [OPERATINGSYSTEM] [version/release]\n.Sh NAME\n.Nm name\n.Nd one line description of name\n.\\\" This next command is for sections 2 and 3 only.\n.\\\" .Sh LIBRARY\n.Sh SYNOPSIS\n.Sh DESCRIPTION\n.\\\" The following commands should be uncommented and\n.\\\" used where appropriate.\n.\\\" .Sh IMPLEMENTATION NOTES\n.\\\" This next command is for sections 2, 3, and 9 only\n.\\\"     (function return values).\n.\\\" .Sh RETURN VALUES\n.\\\" This next command is for sections 1, 6, 7, and 8 only.\n.\\\" .Sh ENVIRONMENT\n.\\\" .Sh FILES\n.\\\" This next command is for sections 1, 6, and 8 only\n.\\\"     (command return values to the shell).\n.\\\" .Sh EXIT STATUS\n.\\\" .Sh EXAMPLES\n.\\\" This next command is for sections 1, 4, 6, 7, 8, and 9 only\n.\\\"     (fprintf/stderr type diagnostics).\n.\\\" .Sh DIAGNOSTICS\n.\\\" .Sh COMPATIBILITY\n.\\\" This next command is for sections 2, 3, 4, and 9 only\n.\\\"     (settings of the errno variable).\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’; the document date,\nthe operating system the man page or subject source is developed or modified for, and the man\npage title (in upper case) along with the section of the manual the page belongs in.  These\ncommands identify the page and are discussed below in TITLE MACROS.\n\nThe remaining items in the template are section headers (.Sh); of which NAME, SYNOPSIS, and\nDESCRIPTION are mandatory.  The headers are discussed in PAGE STRUCTURE DOMAIN, after presenta‐\ntion of MANUAL DOMAIN.  Several content macros are used to demonstrate page layout macros;\nreading about content macros before page layout macros is recommended.\n",
            "subsections": []
        },
        "CONVENTIONS": {
            "content": "In the description of all macros below, optional arguments are put into brackets.  An ellipsis\n(‘...’) represents zero or more additional arguments.  Alternative values for a parameter are\nseparated with ‘|’.  If there are alternative values for a mandatory parameter, braces are used\n(together with ‘|’) to enclose the value set.  Meta-variables are specified within angles.\n\nExample:\n\n.Xx ⟨foo⟩ {bar1 | bar2} [-test1 [-test2 | -test3]] ...\n\nExcept stated explicitly, all macros are parsed and callable.\n\nNote that a macro takes effect up to the next nested macro.  For example, ‘.Ic foo Aq bar’\ndoesn't produce ‘foo <bar>’ but ‘foo ⟨bar⟩’.  Consequently, a warning message is emitted for\nmost commands if the first argument is a macro itself since it cancels the effect of the call‐\ning command completely.  Another consequence is that quoting macros never insert literal\nquotes; ‘foo <bar>’ has been produced by ‘.Ic \"foo <bar>\"’.\n\nMost macros have a default width value which can be used to specify a label width (-width) or\noffset (-offset) for the ‘.Bl’ and ‘.Bd’ macros.  It is recommended not to use this rather ob‐\nscure feature to avoid dependencies on local modifications of the -mdoc package.\n",
            "subsections": []
        },
        "TITLE MACROS": {
            "content": "The title macros are part of the page structure domain but are presented first and separately\nfor someone who wishes to start writing a man page yesterday.  Three header macros designate\nthe document title or manual page title, the operating system, and the date of authorship.\nThese macros are called once at the very beginning of the document and are used to construct\nheaders and footers only.\n\n.Dt [⟨document title⟩] [⟨section number⟩] [⟨volume⟩]\nThe document title is the subject of the man page and must be in CAPITALS due to troff\nlimitations.  If omitted, ‘UNTITLED’ is used.  The section number may be a number in\nthe range 1, ..., 9 or ‘unass’, ‘draft’, or ‘paper’.  If it is specified, and no volume\nname is given, a default volume name is used.\n\nUnder BSD, the following sections are defined:\n\n1   BSD General Commands Manual\n2   BSD System Calls Manual\n3   BSD Library Functions Manual\n4   BSD Kernel Interfaces Manual\n5   BSD File Formats Manual\n6   BSD Games Manual\n7   BSD Miscellaneous Information Manual\n8   BSD System Manager's Manual\n9   BSD Kernel Developer's Manual\n\nA volume name may be arbitrary or one of the following:\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 the\nprevious table will specify a new volume name.  If the third parameter is a keyword\ndesignating a computer architecture, its value is prepended to the default volume name\nas specified by the second parameter.  By default, the following architecture keywords\nare 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 the section number is neither a numeric expression in the range 1 to 9 nor one of\nthe above described keywords, the third parameter is used verbatim as the volume name.\n\nIn the following examples, the left (which is identical to the right) and the middle\npart of the manual page header strings are shown.  Note how ‘\\&’ prevents the digit 7\nfrom being a valid numeric expression.\n\n.Dt FOO 7       ‘FOO(7)’ ‘BSD Miscellaneous Information Manual’\n.Dt FOO 7 bar   ‘FOO(7)’ ‘BSD Miscellaneous Information Manual’\n.Dt FOO \\&7 bar\n‘FOO(7)’ ‘bar’\n.Dt FOO 2 i386  ‘FOO(2)’ ‘BSD/i386 System Calls Manual’\n.Dt FOO \"\" bar  ‘FOO’ ‘bar’\n\nLocal, OS-specific additions might be found in the file mdoc.local; look for strings\nnamed ‘volume-ds-XXX’ (for the former type) and ‘volume-as-XXX’ (for the latter type);\n‘XXX’ then denotes the keyword to be used with the ‘.Dt’ macro.\n\nThis macro is neither callable nor parsed.\n\n.Os [⟨operating system⟩] [⟨release⟩]\nIf the first parameter is empty, the default ‘BSD’ is used.  This may be overridden in\nthe local configuration file, mdoc.local.  In general, the name of the operating system\nshould be the common acronym, e.g. BSD or ATT.  The release should be the standard re‐\nlease nomenclature for the system specified.  In the following table, the possible sec‐\nond arguments for some predefined operating systems are listed.  Similar to ‘.Dt’, lo‐\ncal additions might be defined in mdoc.local; look for strings named\n‘operating-system-XXX-YYY’, where ‘XXX’ is the acronym for the operating system and\n‘YYY’ the release ID.\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, 9.1,\n9.2, 9.3, 10.0, 10.1, 10.2, 10.3, 10.4, 11.0, 11.1, 11.2, 11.3, 12.0,\n12.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, 3.3,\n3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 4.0, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7,\n4.8, 4.9, 5.0, 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 5.9, 6.0, 6.1,\n6.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, 2.9,\n2.9.1, 2.10, 2.10.1, 2.11, 2.12, 2.13, 3.0, 3.0.1, 3.0.2, 3.1, 3.2,\n3.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, 3.6.2,\n3.7, 3.8, 3.8.1, 3.8.2, 4.0, 4.0.1, 4.0.2, 4.0.3, 4.0.4, 4.0.5, 4.0.6,\n4.1, 4.2, 4.2.1, 4.2.2, 4.2.3, 4.2.4, 4.3, 4.4, 4.4.1, 4.4.2, 4.4.3,\n4.5, 4.6, 4.6.1, 4.6.2, 4.7, 4.8, 4.8.1, 4.9, 5.0, 5.0.1, 5.0.2, 5.1,\n5.2, 5.2.1, 5.2.2, 5.3, 5.4, 5.4.1, 5.4.2, 5.4.3, 5.5, 5.6, 5.6.1,\n5.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, 8.9.0,\n8.10.0, 8.11.0, 9.0.0, 9.1.0, 9.2.0, 9.3.0, 9.4.0, 9.5.0, 9.6.0,\n9.7.0, 9.8.0, 10.0.0, 10.1.0, 10.2.0, 10.3.0, 10.4.0, 10.5.0, 10.6.0,\n10.7.0, 10.8.0, 11.0.0, 11.1.0, 11.2.0, 11.3.0, 11.4.0, 11.5.0,\n12.0.0, 12.1.0, 12.2.0, 13.0.0, 13.1.0, 13.2.0, 13.3.0, 13.4.0,\n14.0.0, 14.1.0, 14.2.0, 14.3.0, 14.4.0, 14.5.0, 15.0.0, 15.1.0,\n15.2.0, 15.3.0, 15.4.0, 15.5.0, 15.6.0, 16.0.0, 16.1.0, 16.2.0,\n16.3.0, 16.4.0, 16.5.0, 16.6.0, 17.0.0, 17.1.0, 17.2.0, 17.3.0,\n17.4.0, 17.5.0, 17.6.0, 17.7.0, 18.0.0, 18.1.0, 18.2.0, 18.3.0,\n18.4.0, 18.5.0, 18.6.0, 18.7.0, 19.0.0, 19.1.0, 19.2.0\n\nFor ATT, an unknown second parameter will be replaced with the string UNIX; for the\nother predefined acronyms it will be ignored and a warning message emitted.  Unrecog‐\nnized arguments are displayed as given in the page footer.  For instance, a typical\nfooter might be:\n\n.Os BSD 4.3\n\ngiving ‘4.3 Berkeley Distribution’, or for a locally produced set\n\n.Os CS Department\n\nwhich will produce ‘CS Department’.\n\nIf the ‘.Os’ macro is not present, the bottom left corner of the manual page will be\nugly.\n\nThis macro is neither callable nor parsed.\n\n.Dd [⟨month⟩ ⟨day⟩, ⟨year⟩]\nIf ‘Dd’ has no arguments, ‘Epoch’ is used for the date string.  If it has exactly three\narguments, they are concatenated, separated with unbreakable space:\n\n.Dd January 25, 2001\n\nThe month's name shall not be abbreviated.\n\nWith any other number of arguments, the current date is used, ignoring the parameters.\n\nAs a special exception, the format\n\n.Dd $Mdocdate: ⟨month⟩ ⟨day⟩ ⟨year⟩ $\n\nis also recognized.  It is used in OpenBSD manuals to automatically insert the current\ndate when committing.\n\nThis macro is neither callable nor parsed.\n",
            "subsections": []
        },
        "INTRODUCTION OF 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 language\nare used to describe the three different aspects of writing a man page.  First, there is the\ndescription of -mdoc macro command usage.  Second is the description of a UNIX command with",
            "subsections": [
                {
                    "name": "-mdoc",
                    "content": "discussion of a command in the text of a man page.\n\nIn the first case, troff(1) 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 sec‐\nond case, the description of a UNIX command using the content macros is a bit more involved; a\ntypical 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 brack‐\nets with real file names.  Note that in this document meta arguments are used to describe -mdoc\ncommands; in most man pages, meta variables are not specifically written with angle brackets.\nThe macros which 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, but\nmay add more detail.  The arguments ⟨infile⟩ and ⟨outfile⟩ from the example above might be re‐\nferred to as operands or file arguments.  Some command-line argument lists are quite long:\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 de‐\ntail can prevent confusion, however the -mdoc package does not have a macro for an argument to\na flag.  Instead the ‘Ar’ argument macro is used for an operand or file argument like target as\nwell as an argument to a flag like variable.  The make command line was produced from:\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"
                },
                {
                    "name": "General Syntax",
                    "content": "The manual domain and general text domain macros share a similar syntax with a few minor devia‐\ntions; most notably, ‘.Ar’, ‘.Fl’, ‘.Nm’, and ‘.Pa’ differ only when called without arguments;\nand ‘.Fn’ and ‘.Xr’ impose an order on their argument lists.  All content macros are capable of\nrecognizing and properly handling punctuation, provided each punctuation character is separated\nby 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 punctua‐\ntion 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 ar‐\ngument 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 contain‐\ning a member of the mathematical, logical or quotation set:\n\n{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',\"}\n\nThe problem is that troff may assume it is supposed to actually perform the operation or evalu‐\nation suggested by the characters.  To prevent the accidental evaluation of these characters,\nescape them with ‘\\&’.  Typical syntax is shown in the first content macro displayed below,\n‘.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 the\nname 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 the AUTHORS section, the ‘.An’ command causes a line break allowing each new name to appear\non its own 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 argu‐\nments, the ‘file ...’ string is output.\n\nUsage: .Ar [⟨argument⟩] ...\n\n.Ar              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 sec‐\ntion four manual.\n\nUsage: .Cd ⟨argument⟩ ...\n\n.Cd \"device le0 at scode?\"  device le0 at scode?\n\nIn the SYNOPSIS section a ‘.Cd’ command causes a line break before and after its arguments are\nprinted.\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 ‘.Cm’\nmacro does not assert a dash in front of every argument.  Traditionally flags are marked by the\npreceding dash, however, some commands or subsets of commands do not use them.  Command modi‐\nfiers may also be specified in conjunction with interactive commands such as editor commands.\nSee Flags.\n\nThe default width is 10n.\n"
                },
                {
                    "name": "Defined Variables",
                    "content": "A variable (or constant) which 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": "Errno's",
                    "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, as\nit 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 inter‐\nactive command flags, which are not prepended with a dash, the ‘.Cm’ (command modifier) macro\nis 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 the SYNOPSIS section a ‘.Fd’ command causes a line break if a function has already been pre‐\nsented and a break has not occurred.  This leaves a nice vertical space in between the previous\nfunction call and the declaration for the next function.\n\nThe ‘.In’ macro, while in the SYNOPSIS section, represents the #include statement, and is the\nshort form of the above example.  It specifies the C header file as being included in a C pro‐\ngram.  It also causes a line break.\n\nWhile not in the SYNOPSIS section, it represents the header file enclosed in angle brackets.\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 page\nwithout problems, but its main purpose is to present the function type in kernel normal form\nfor the SYNOPSIS of sections two and three (it causes a line break, allowing the function name\nto 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 closing\nparenthesis at that point).\n\nFor functions with many parameters (which is rare), the macros ‘.Fo’ (function open) and ‘.Fc’\n(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\nIn the SYNOPSIS section, the function will always begin at the beginning of line.  If there is\nmore than one function presented in the SYNOPSIS section and a function type has not been\ngiven, a line break will occur, leaving a nice vertical space between the current function name\nand the one prior.\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 ‘.Fc’\ninstead 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 does\nnothing 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\nLocal, OS-specific additions might be found in the file mdoc.local; look for strings named\n‘str-Lb-XXX’.  ‘XXX’ then denotes the keyword to be used with the ‘.Lb’ macro.\n\nIn the LIBRARY section an ‘.Lb’ command causes a line break before and after its arguments are\nprinted.\n"
                },
                {
                    "name": "Literals",
                    "content": "The ‘.Li’ literal macro may be used for special characters, variable constants, etc. - anything\nwhich should be displayed as it would be typed.\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 subject name.  It has the peculiarity of re‐\nmembering the first argument it was called with, which should always be the subject name of the\npage.  When called without arguments, ‘.Nm’ regurgitates this initial name for the sole purpose\nof making less work for the author.  ‘.Nm’ causes a line break within the SYNOPSIS section.\n\nNote: A section two or three document function name is addressed with the ‘.Nm’ in the NAME\nsection, and with ‘.Fn’ in the SYNOPSIS and remaining sections.  For interactive commands, such\nas the ‘while’ command keyword in csh(1), the ‘.Ic’ macro should be used.  While ‘.Ic’ is\nnearly identical to ‘.Nm’, it can not recall the first argument it was invoked with.\n\nUsage: .Nm [⟨argument⟩] ...\n\n.Nm groffmdoc  groffmdoc\n.Nm \\-mdoc      -mdoc\n.Nm foo ) ) ,   foo)),\n.Nm :           groffmdoc:\n\nThe default width is 10n.\n"
                },
                {
                    "name": "Options",
                    "content": "The ‘.Op’ macro places option brackets around any remaining arguments on the command line, and\nplaces any trailing punctuation outside the brackets.  The macros ‘.Oo’ and ‘.Oc’ (which pro‐\nduce an opening and a closing option bracket respectively) may be used across one or more lines\nor 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 path or file names.  If called without arguments, the ‘~’ string is\noutput, which represents the current 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-susv2          Version 2 of the Single UNIX Specification (“SUSv2”)\n-susv3          Version 3 of the Single UNIX Specification (“SUSv3”)\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 the SYNOPSIS section, it causes\na line break (useful for old style 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 argu‐\nment, 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 possi‐\nble:\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\nTITLE 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\nTITLE 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\nTITLE 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 enclo‐\nsure are used interchangeably throughout this document.  Most of the one-line enclosure macros\nend in small letter ‘q’ to give a hint of quoting, but there are a few irregularities.  For\neach enclosure macro there is also a pair of open and close macros which end in small letters\n‘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 XX)    XXstring\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 respec‐\ntively.\n\n.Es, .En  Due to the nine-argument limit in the original troff program two other macros have\nbeen implemented which are now rather obsolete: ‘.Es’ takes the first and second pa‐\nrameter as the left and right enclosure string, which are then used to enclose the\narguments of ‘.En’.  The 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 re‐\nspectively, followed by the arguments to be enclosed.\n\n.Ql       The quoted literal macro behaves differently in troff and nroff mode.  If formatted\nwith nroff, a quoted literal is always quoted.  If formatted with troff, an item is\nonly quoted if the width of the item is less than three constant width characters.\nThis is to make short strings more visible where the font change to literal (constant\nwidth) 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 in\n‘.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 ´^[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 from\nthe same underlying enclosure macros as those presented in the list above.  The ‘.Xo’ and ‘.Xc’\nextended argument list macros are discussed below.\n"
                },
                {
                    "name": "No-Op or Normal Text Macro",
                    "content": "The ‘.No’ macro can be used in a macro command line for parameters which should not be format‐\nted.  Be careful to add ‘\\&’ to the word ‘No’ if you really want that English word (and not the\nmacro) as a parameter.\n\nUsage: .No ⟨argument⟩ ...\n\n.No test Ta with Ta tabs  test     with     tabs\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 pa‐\nrameter.  For example, it is useful for old style argument lists where there is no space be‐\ntween 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 another\nmacro name follows it.  If used as a command (i.e., the second form above in the ‘Usage’ line),\n‘.Ns’ is identical to ‘.No’.\n"
                },
                {
                    "name": "Section Cross References",
                    "content": "The ‘.Sx’ macro designates a reference to a section header within the same 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).  Causes a line break in the SEE ALSO\nsection and begins collection of reference information until the reference end\nmacro 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 and Type Names)",
                    "content": "The trade name macro prints its arguments in a smaller font.  Its intended use is to imitate a\nsmall caps fonts for uppercase 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 opening\nand closing an enclosure (without inserting characters, of course).  This means that the fol‐\nlowing is true for those macros also.\n\nHere is an example of ‘.Xo’ using the space mode macro to turn spacing off:\n\n.Sm off\n.It Xo Sy I Ar operation\n.No \\en Ar count No \\en\n.Xc\n.Sm on\n\nproduces\n\nIoperation\\ncount\\n\n\nAnother one:\n\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\nproduces\n\nS/oldpattern/newpattern/[g]\n\nAnother example of ‘.Xo’ and enclosure macros: Test the value of a variable.\n\n.It Xo\n.Ic .ifndef\n.Oo \\&! Oc Ns Ar variable Oo\n.Ar operator variable ...\n.Oc Xc\n\nproduces\n\n.ifndef [!]variable [operator variable ...]\n"
                }
            ]
        },
        "PAGE STRUCTURE DOMAIN": {
            "content": "",
            "subsections": [
                {
                    "name": "Section Headers",
                    "content": "The following ‘.Sh’ section header macros are required in every man page.  The remaining sec‐\ntion headers are recommended at the discretion of the author writing the manual page.  The\n‘.Sh’ macro is parsed but not generally callable.  It can be used as an argument in a call to\n‘.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 and\npage layout defaults will not be set and things will be rather unpleasant.\nThe NAME section consists of at least three items.  The first is the ‘.Nm’\nname macro naming the subject of the man page.  The second is the name de‐\nscription macro, ‘.Nd’, which separates the subject name from the third\nitem, which is the description.  The description should be the most terse\nand 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 consist\nof 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 required\nfor manual page sections 2 and 3; the command and general name macro ‘.Nm’\nis required for sections 1, 5, 6, 7, and 8.  Section 4 manuals require a\n‘.Nm’, ‘.Fd’ or a ‘.Cd’ configuration device usage macro.  Several other\nmacros may be necessary to produce the synopsis line as shown below:\n\ncat [-benstuv] [-] file ...\n\nThe following macros were used:\n\n.Nm cat\n.Op Fl benstuv\n.Op Fl\n.Ar\n\n.Sh DESCRIPTION    In most cases the first text in the DESCRIPTION section is a brief paragraph\non the command, function or file, followed by a lexical list of options and\nrespective explanations.  To create such a list, the ‘.Bl’ (begin list),\n‘.It’ (list item) and ‘.El’ (end list) macros are used (see Lists and\nColumns below).\n\n.Sh IMPLEMENTATION NOTES\nImplementation specific information should be placed here.\n\n.Sh RETURN VALUES  Sections 2, 3 and 9 function return values should go here.  The ‘.Rv’ macro\nmay be used to generate text for use in the RETURN VALUES section for most\nsection 2 and 3 library functions; see Return Values.\n\nThe following ‘.Sh’ section headers 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 and\nclues to their behavior and/or usage.\n\n.Sh FILES          Files which are used or created by the man page subject should be listed via\nthe ‘.Pa’ macro in the FILES section.\n\n.Sh EXAMPLES       There are several ways to create examples.  See the Examples and Displays\nsection 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 section\nfor most section 1, 6 and 8 commands; see Exit Status.\n\n.Sh COMPATIBILITY  Known compatibility issues (e.g. deprecated options or parameters) should be\nlisted 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.  Cross\nreferences are specified using the ‘.Xr’ macro.  Currently refer(1) style\nreferences are not accommodated.\n\nIt is recommended that the cross references are sorted on the section num‐\nber, then alphabetically on the names within a section, and placed in that\norder and comma separated.  Example:\n\nls(1), ps(1), group(5), passwd(5)\n\n.Sh STANDARDS      If the command, library function or file adheres to a specific implementa‐\ntion such as IEEE Std 1003.2 (“POSIX.2”) or ANSI X3.159-1989 (“ANSI C89”)\nthis should be noted here.  If the command does not adhere to any standard,\nits 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 ‘.Aq’\nmacro for e-mail addresses within optional contact information.  Explicitly\nindicate whether the person authored the initial manual page or the software\nor 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 Headers",
                    "content": "Subsection headers have exactly the same syntax as section headers: ‘.Ss’ is parsed but not\ngenerally callable.  It can be used as an argument in a call to ‘.Ss’ only; it then reactivates\nthe 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 keep)\nand ‘.Ek’ (end keep).  The only option that ‘.Bk’ accepts currently is -words (this is also the\ndefault if no option is given) which is useful for preventing line breaks in the middle of op‐\ntions.  In the example for the make command-line arguments (see What's in a Name), the keep\nprevented nroff from placing up the flag and the argument on separate lines.\n\nBoth macros are neither callable nor parsed.\n\nMore work needs to be done with 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 has\nbeen used throughout this file.  It allows the indentation (display) of one line of text.\nIts default font is set to constant width (literal).  ‘.Dl’ is parsed but not callable.\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 follow‐\ning syntax:\n\n.Bd {-literal | -filled | -unfilled | -ragged | -centered} [-offset ⟨string⟩] [-file\n⟨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 each\nsingle line is centered.\n-unfilled          Do not fill; display a block of text as typed, using line breaks as\nspecified by the user.  This can produce overlong lines without warning\nmessages.\n-filled            Display a filled block.  The block of text is formatted (i.e., the text\nis 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 before\nany data enclosed with ‘.Bd’ and ‘.Ed’, using the selected display\ntype.  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 forthcoming\nblock of text:\n\nleft        Align block on the current left margin; this is the default\nmode of ‘.Bd’.\ncenter      Supposedly center the block.  At this time unfortunately,\nthe block merely gets left aligned about an imaginary cen‐\nter margin.\nindent      Indent by one default indent value or tab.  The default in‐\ndent value is also used for the ‘.D1’ and ‘.Dl’ macros, so\none is guaranteed the two types of displays will line up.\nThe indentation value is normally set to 6n or about two\nthirds 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 right\nside of the page.  This macro needs work and perhaps may\nnever do the right thing within troff.\n\nIf ⟨string⟩ is a valid numeric expression instead (with a scale\nindicator other than ‘u’), use that value for indentation.  The most\nuseful scale indicators are ‘m’ and ‘n’, specifying the so-called Em\nand En square.  This is approximately the width of the letters ‘m’ and\n‘n’ respectively of the current font (for nroff output, both scale in‐\ndicators give the same values).  If ⟨string⟩ isn't a numeric expres‐\nsion, it is tested whether it is an -mdoc macro name, and the default\noffset value associated with this macro is used.  Finally, if all tests\nfail, the width of ⟨string⟩ (typeset with a fixed-width font) is taken\nas 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.  Items\nwithin the list are specified with the ‘.It’ item macro, and each list must end with the ‘.El’\nmacro.  Lists may be nested within themselves and within displays.  The use of columns inside\nof lists or lists inside of columns is unproven.\n\nIn addition, several list attributes may be specified such as the width of a tag, the list off‐\nset, and compactness (blank lines between items allowed or disallowed).  Most of this document\nhas 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 second-\nlevel 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's resulting from references by the process to pages not\nloaded 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\n.Tn I/O Ns 's\nresulting from references by the process\nto 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": "callable macros are ignored.  The -width flag is not meaningful in this context.\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 the\nlabel 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": "a separate line.\n\nSL\nsleep time of the process (seconds blocked)\n\nPAGEIN\nnumber of disk I/O's resulting from references by the process to pages not\nloaded in core.\n\nUID\nnumerical user-id of process owner\n\nPPID\nnumerical id of parent of process priority (non-positive when in non-interrupt‐\nible 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\n.Tn I/O Ns 's\nresulting from references by the process\nto 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 of\nlist used in the Berkeley manuals.  Use a -width attribute as described below.\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 valu‐\nable 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.Nm -mdoc\nmanuals to other formats.\n.El\n"
                },
                {
                    "name": "-column",
                    "content": "each column is determined by the arguments to the -column list, ⟨string1⟩, ⟨string2⟩,\netc.  If ⟨stringN⟩ starts with a ‘.’ (dot) immediately followed by a valid -mdoc macro\nname, interpret ⟨stringN⟩ and use the width of the result.  Otherwise, the width of\n⟨stringN⟩ (typeset with a fixed-width font) is taken as the Nth column width.\n\nEach ‘.It’ argument is parsed to make a row, each column within the row is a separate\nargument 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 -mdoc",
                    "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 scale indicator\nother than ‘u’), use that value for indentation.  The most useful scale indi‐\ncators are ‘m’ and ‘n’, specifying the so-called Em and En square.  This is\napproximately the width of the letters ‘m’ and ‘n’ respectively of the cur‐\nrent font (for nroff output, both scale indicators give the same values).  If\n⟨string⟩ isn't a numeric expression, it is tested whether it is an -mdoc\nmacro name, and the default width value associated with this macro is used.\nFinally, if all tests fail, the width of ⟨string⟩ (typeset with a fixed-width\nfont) is taken as the width.\n\nIf a width is not specified for the tag list type, ‘6n’ is used.\n"
                },
                {
                    "name": "-offset",
                    "content": "the value used in ‘.Dl’ or ‘.Bd’) is used.  If ⟨string⟩ is a valid numeric\nexpression instead (with a scale indicator other than ‘u’), use that value\nfor indentation.  The most useful scale indicators are ‘m’ and ‘n’, specify‐\ning the so-called Em and En square.  This is approximately the width of the\nletters ‘m’ and ‘n’ respectively of the current font (for nroff output, both\nscale indicators give the same values).  If ⟨string⟩ isn't a numeric expres‐\nsion, it is tested whether it is an -mdoc macro name, and the default offset\nvalue associated with this macro is used.  Finally, if all tests fail, the\nwidth of ⟨string⟩ (typeset with a fixed-width font) is taken as the offset.\n"
                },
                {
                    "name": "-compact",
                    "content": ""
                }
            ]
        },
        "MISCELLANEOUS MACROS": {
            "content": "Here a list of the remaining macros which do not fit well into one of the above sections.  We\ncouldn't find real examples for the following macros: ‘.Me’ and ‘.Ot’.  They are documented\nhere for completeness - if you know how to use them properly please send a mail to\ngroff@gnu.org (including an example).\n\n.Bt  prints\n\nis currently in beta test.\n\nIt is neither callable nor parsed and takes no arguments.\n\n.Fr\n\nUsage: .Fr ⟨function return value⟩ ...\n\nDon't use this macro.  It allows a break right before the return value (usually a single\ndigit) which is bad typographical behaviour.  Use ‘\\~’ to tie the return value to the pre‐\nvious word.\n\n.Hf  Use this macro to include a (header) file literally.  It first prints ‘File:’ followed by\nthe file name, then the contents of ⟨file⟩.\n\nUsage: .Hf ⟨file⟩\n\nIt is neither callable nor parsed.\n\n.Lk  To be written.\n\n.Me  Exact usage unknown.  The documentation in the -mdoc source file describes it as a macro\nfor “menu entries”.\n\nIts default width is 6n.\n\n.Mt  To be written.\n\n.Ot  Exact usage unknown.  The documentation in the -mdoc source file describes it as “old\nfunction type (fortran)”.\n\n.Sm  Activate (toggle) space mode.\n\nUsage: .Sm [on | off] ...\n\nIf space mode is off, no spaces between macro arguments are inserted.  If called without a\nparameter (or if the next parameter is neither ‘on’ nor ‘off’, ‘.Sm’ toggles space mode.\n\n.Ud  prints\n\ncurrently under development.\n\nIt is neither callable nor parsed and takes no arguments.\n",
            "subsections": []
        },
        "PREDEFINED STRINGS": {
            "content": "The following strings are predefined:\n",
            "subsections": [
                {
                    "name": "String   Nroff      Troff   Meaning",
                    "content": "<=       <=         ≤       less equal\n>=       >=         ≥       greater equal\nRq       ''         ”       right double quote\nLq       ``         “       left double quote\nua       ^          ↑       upwards arrow\naa       ´          ´       acute accent\nga       `          `       grave accent\nq        \"          \"       straight double quote\nPi       pi         π       greek pi\nNe       !=         ≠       not equal\nLe       <=         ≤       less equal\nGe       >=         ≥       greater equal\nLt       <          <       less than\nGt       >          >       greater than\nPm       +-         ±       plus minus\nIf       infinity   ∞       infinity\nAm       &          &       ampersand\nNa       NaN        NaN     not a number\nBa       |          |       vertical bar\n\nThe names of the columns Nroff and Troff are a bit misleading; Nroff shows the ASCII represen‐\ntation, while Troff gives the best glyph form available.  For example, a Unicode enabled\nTTY-device will have proper glyph representations for all strings, whereas the enhancement for\na Latin1 TTY-device is only the plus-minus sign.\n\nString names which consist of two characters can be written as ‘\\*(xx’; string names which con‐\nsist of one character can be written as ‘\\*x’.  A generic syntax for a string name of any\nlength is ‘\\*[xxx]’ (this is a GNU troff(1) extension).\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "The debugging macro ‘.Db’ available in previous versions of -mdoc has been removed since GNU\ntroff(1) provides better facilities to check parameters; additionally, many error and warning\nmessages have been added to this macro package, making it both more robust and verbose.\n\nThe only remaining debugging macro is ‘.Rd’ which yields a register dump of all global regis‐\nters and strings.  A normal user will never need it.\n",
            "subsections": [
                {
                    "name": "FORMATTING WITH GROFF, TROFF, AND NROFF",
                    "content": "By default, the package inhibits page breaks, headers, and footers if displayed with a TTY de‐\nvice like ‘latin1’ or ‘unicode’, to make the manual more efficient for viewing on-line.  This\nbehaviour can be changed (e.g. to create a hardcopy of the TTY output) by setting the register\n‘cR’ to zero while calling groff(1), resulting in multiple pages instead of a single, very long\npage:\n\ngroff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt\n\nFor double-sided printing, set register ‘D’ to 1:\n\ngroff -Tps -rD1 -mdoc foo.man > foo.ps\n\nTo change the document font size to 11pt or 12pt, set register ‘S’ accordingly:\n\ngroff -Tdvi -rS11 -mdoc foo.man > foo.dvi\n\nRegister ‘S’ is ignored for TTY devices.\n\nThe line and title length can be changed by setting the registers ‘LL’ and ‘LT’, respectively:\n\ngroff -Tutf8 -rLL=100n -rLT=100n -mdoc foo.man | less\n\nIf not set, both registers default to 78n for TTY devices and 6.5i otherwise.\n"
                }
            ]
        },
        "FILES": {
            "content": "doc.tmac          The main manual macro package.\nmdoc.tmac         A wrapper file to call doc.tmac.\nmdoc/doc-common   Common strings, definitions, stuff related typographic output.\nmdoc/doc-nroff    Definitions used for a TTY output device.\nmdoc/doc-ditroff  Definitions used for all other devices.\nmdoc.local        Local additions and customizations.\nandoc.tmac        Use this file if you don't know whether the -mdoc or the -man package should\nbe used.  Multiple man pages (in either format) can be handled.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "groff(1), man(1), troff(1), groffman(7)\n",
            "subsections": []
        },
        "BUGS": {
            "content": "Section 3f has not been added to the header routines.\n\n‘.Nm’ font should be changed in NAME section.\n\n‘.Fn’ needs to have a check to prevent splitting up if the line length is too short.  Occasion‐\nally it separates the last parenthesis, and sometimes looks ridiculous if a line is in fill\nmode.\n\nThe list and display macros do not do any keeps and certainly should be able to.\n\nBSD                            November 2, 2010                            BSD",
            "subsections": []
        }
    },
    "summary": "groffmdoc — reference for groff's mdoc implementation",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "groff",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/groff/1/json"
        },
        {
            "name": "man",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/man/1/json"
        },
        {
            "name": "troff",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/troff/1/json"
        },
        {
            "name": "groffman",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/groffman/7/json"
        }
    ]
}