diff options
Diffstat (limited to 'tmac/groff_mdoc.7.man')
| -rw-r--r-- | tmac/groff_mdoc.7.man | 5375 |
1 files changed, 5375 insertions, 0 deletions
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man new file mode 100644 index 0000000..d161c86 --- /dev/null +++ b/tmac/groff_mdoc.7.man @@ -0,0 +1,5375 @@ +'\" t +.\" groff_mdoc.man +.\" +.\" A complete reference of the mdoc macro package for GNU troff. +.\" +.\" Based on NetBSD's mdoc.samples.7, version 1.21. +.\" +.\" +.\" Warning: You can't format this file with the old mdoc macros! +.\" +.\" +.\" Copyright (C) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" 3. [Deleted. See +.\" ftp://ftp.cs.berkeley.edu/pub/4bsd/README.Impt.License.Change] +.\" 4. Neither the name of the University nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" +.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +.\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR +.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mdoc.samples.7 8.2 (Berkeley) 12/30/93 +.\" +.\" This reference invokes every macro in the package several times and +.\" is guaranteed to give worst-case performance for an already +.\" extremely slow package. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_mdoc_7_man_C \n[.cp] +.cp 0 +. +. +.Dd @MDATE@ +.Dt groff_mdoc 7 +.Os groff @VERSION@ +. +. +.Sh Name +. +.Nm groff_mdoc +.Nd compose BSD-style manual (man) pages with GNU +.Xr roff +. +. +.Sh Synopsis +. +.Nm groff Fl m Ns Cm doc Ar file No ... +. +. +.Sh Description +. +The GNU implementation of the +.Xr mdoc +macro package is part of the +.Xr groff @MAN1EXT@ +document formatting system. +. +.Xr mdoc +is a +structurally- and semantically-oriented package for writing +.Ux +manual pages with +.Xr @g@troff @MAN1EXT@ . +. +Its predecessor, +the +.Xr man 7 +package, +primarily addressed page layout and presentational concerns, +leaving the selection of fonts and other typesetting details to the +individual author. +. +This discretion has led to divergent styling practices among authors +using it. +. +. +.Pp +.Xr mdoc +organizes its macros into +.Em domains . +. +The +.Em "page structure domain" +lays out the page and +comprises titles, +section headings, +displays, +and lists. +. +The +.Em "general text domain" +supplies macros to quote or style text, +or to interpolate common noun phrases. +. +The +.Em "manual domain" +offers semantic macros corresponding to the terminology used by +practitioners in discussion of +.Ux +commands, +routines, +and files. +. +Manual domain macros distinguish +command-line arguments and options, +function names, +function parameters, +pathnames, +variables, +cross references to other manual pages, +and so on. +. +These terms are meaningful both to the author and the readers of a +manual page. +. +It is hoped that the resulting increased consistency of the man page +corpus will enable easier translation to future documentation tools. +. +. +.Pp +Throughout +.Ux +documentation, +a manual entry is referred to simply as a +.Dq "man page" , +regardless of its length, +without gendered implication, +and irrespective of the macro package selected for its composition. +. +. +.Sh "Getting started" +. +The +.Xr mdoc +package attempts to simplify man page authorship and maintenance without +requiring mastery of the +.Xr roff +language. +. +This document presents only essential facts about +.Xr roff. +. +For further background, +including a discussion of basic typographical concepts like +.Dq breaking , +.Dq filling , +and +.Dq adjustment , +see +.Xr roff @MAN7EXT@ . +. +Specialized units of measurement also arise, +namely +ens, +vees, +inches, +and points, +abbreviated +.Dq n , +.Dq v , +.Dq i , +and +.Dq p , +respectively; +see section +.Sx Measurements +of +.Xr groff @MAN7EXT@ . +. +. +.Pp +For brief examples, +we employ an arrow notation illustrating a transformation of input on +the left to rendered output on the right. +. +Consider the +.Pf . Ic \&Dq +macro, +which double-quotes its arguments. +. +.Bl -tag -width ".Dq\ man page" -offset indent -compact +.It Li ".Dq man page" +\[->] +.Dq man page +.El +. +. +.Ss Usage +. +An +.Xr mdoc +.Em macro +is +.Em called +by placing the +.Xr roff +control character, +.Ql .\& +(dot) +at the beginning of a line followed by its name. +.\" XXX; All mdoc macro names except Brq, Bro, Brc are 2 characters long +.\" and thus portable to old troffs. Why the innovation here, when +.\" `Cq`, `Co`, and `Cc` were available? Try to sell this reform to +.\" Ingo Schwarze. +. +In this document, +we often discuss a macro name with this leading dot to identify it +clearly, +but the dot is +.Em not +part of its name. +. +Space or tab characters can separate the dot from the macro name. +. +Arguments may follow, +separated from the macro name and each other by spaces, +but +.Em not +tabs. +. +The dot at the beginning of the line prepares the formatter to expect a +macro name. +. +A dot followed immediately by a newline is ignored; +this is called the +.Em "empty request" . +. +To begin an input line with a dot +(or a neutral apostrophe +.Ql \[aq] ) +in some context other than a macro call, +precede it with the +.Ql \e& +escape sequence; +this is a dummy character, +not formatted for output. +. +The backslash is the +.Xr roff +escape character; +it can appear anywhere and it always followed by at least one more +character. +. +If followed by a newline, +the backslash escapes the input line break; +you can thus keep input lines to a reasonable length without affecting +their interpretation. +. +. +.Pp +Macros in GNU +.Xr troff +accept an unlimited number of arguments, +in contrast to other +.Xr troff Ns No s +that often can't handle more than nine. +. +In limited cases, +arguments may be continued or extended on the next input line without +resort to the +.Ql \[rs] Ns Em newline +escape sequence; +see subsection +.Sx "Extended arguments" +below. +. +Neutral double quotes +.Li \[dq] +can be used to group multiple words into an argument; +see subsection +.Sx "Passing space characters in an argument" +below. +. +. +.Pp +Most of +.Xr mdoc Ns No 's +general text and manual domain macros +.Em parse +their argument lists +for +.Em callable +macro names. +. +This means that an argument in the list matching a general text or +manual domain macro name +(and defined to be callable) +will be called with the remaining arguments when it is encountered. +. +In such cases, +the argument, +although the name of a macro, +is not preceded by a dot. +. +Macro calls can thus be nested. +. +This approach to macro argument processing is a unique characteristic of +the +.Xr mdoc +package, +not a general feature of +.Xr roff +syntax. +. +. +.Pp +For example, +the option macro, +.Pf . Ic \&Op , +may call the flag and argument macros, +.Pf . Ic \&Fl +and +.Pf . Ic \&Ar , +to specify an optional flag with an argument. +. +.\" Use width of second example below. +.Bl -tag -width ".Op\ \e&Fl\ s\ \e&Ar bytes" -offset indent -compact +.It Li ".Op Fl s Ar bytes" +\[->] +.Op Fl s Ar bytes +.El +. +To prevent a word from being interpreted as a macro name, +precede it with the dummy character. +. +.Bl -tag -width ".Op\ \e&Fl\ s\ \e&Ar bytes" -offset indent -compact +.It Li ".Op \e&Fl s \e&Ar bytes" +\[->] +.Op \&Fl s \&Ar bytes +.El +. +. +.Pp +In this document, +macros whose argument lists are parsed for callable arguments are +referred to as +.Em parsed , +and those that may be called from an argument list are referred to as +.Em callable . +. +This usage is a technical +.Em "faux pas" , +since all +.Xr mdoc +macros are in fact interpreted +(unless prevented with +.Ql \e& ) , +but as it is cumbersome to constantly refer to macros as +.Dq "being able to call other macros" , +we employ the term +.Dq parsed +instead. +. +Except where explicitly stated, +all +.Xr mdoc +macros are parsed and callable. +. +. +.Pp +In the following, +we term an +.Xr mdoc +macro that starts a line +(with a leading dot) +a +.Em command +if a distinction from those appearing as arguments of other macros is +necessary. +. +. +.Ss "Passing space characters in an argument" +. +Sometimes it is desirable to give a macro an argument containing one or +more space characters, +for instance to specify a particular arrangement of arguments demanded +by the macro. +. +Additionally, +quoting multi-word arguments that are to be treated the same makes +.Xr mdoc +work faster; +macros that parse arguments do so once +(at most) +for each. +. +For example, +the function command +.Pf . Ic \&Fn +expects its first argument to be the name of a function and any +remaining arguments to be function parameters. +. +Because C language standards mandate the inclusion of types +.Em and +identifiers in the parameter lists of function definitions, +each +.Ql \&Fn +parameter after the first will be at least two words in length, +as in +.Dq Ar "int foo" . +. +. +.Pp +There are a few ways to embed a space in a macro argument. +. +One is to use the unadjustable space escape sequence +.Li \[rs] Ns Em space . +. +The formatter treats this escape sequence as if it were any other +printable character, +and will not break a line there as it would a word space when the +output line is full. +. +This method is useful for macro arguments that are not expected to +straddle an output line boundary, +but has a drawback: +this space does not adjust as others do when the output line is +formatted. +. +An alternative is to use the unbreakable space escape sequence, +.Ql \[rs]\[ti] , +which cannot break but does adjust. +. +This +.Xr groff +extension is widely but not perfectly portable. +. +Another method is to enclose the string in double quotes. +. +.Bl -tag -width ".Fn\ fetch\ \[dq]char\ *str\[dq]" -offset indent \ +-compact +.It Li ".Fn fetch char\e *str" +\[->] +.Fn fetch char\ *str +.It Li ".Fn fetch char\e\[ti]*str" +\[->] +.Fn fetch char\~*str +.It Li ".Fn fetch \[dq]char *str\[dq]" +\[->] +.Fn fetch "char *str" +.El +. +If the +.Ql \[rs] +before the space in the first example +or the double quotes in the third example +were omitted, +.Ql .Fn +would see three arguments, +and the result would contain an undesired comma. +. +.\" Use same width as before so it's easier to see the discrepancy. +.Bl -tag -width ".Fn\ fetch\ \[dq]char\ *str\[dq]" -offset indent \ +-compact +.It Li ".Fn fetch char *str" +\[->] +.Fn fetch char *str +.El +. +. +.\".Pp +.\" For an example of what happens when the parameter list overlaps a +.\" newline boundary, +.\" see the +.\" .Sx Bugs +.\" section. +. +. +.Ss "Trailing space characters" +. +.\" XXX: This claim of confusion is nonsense. The formatter ignores +.\" them. If mdoc doesn't, that's a bug or design flaw. It's still +.\" good style not to have them. Whitespace churn makes diff(1) and +.\" revision control users unhappy. +.\" +.\".Xr @g@troff +.\"can be confused by space characters at the end of a line. +. +It is wise to remove trailing spaces from the ends of input lines. +. +Should the need arise to put a formattable space at the end of a line, +do so with the unadjustable or unbreakable space escape sequences. +. +. +.Ss "Formatting the backslash glyph" +. +When you need the +.Xr roff +escape character +.Ql \[rs] +to appear in the output, +use +.Ql \[rs]e +or +.Ql \[rs](rs +instead. +. +Technically, +.Ql \[rs]e +formats the current escape character; +it works reliably as long as no +.Xr roff +request is used to change it, +which should never happen in man pages. +. +.Ql \[rs](rs +is a +.Xr groff +special character escape sequence that explicitly formats the +.Dq "reverse solidus" +(backslash) glyph. +. +. +.Ss "Other possible pitfalls" +. +.Xr "groff mdoc" +warns when an empty input line is found outside of a +.Em display , +a topic presented in subsection +.Sx "Examples and displays" +below. +. +Use empty requests to space the source document for maintenance. +. +. +.Pp +Leading spaces cause a break and are formatted. +. +Avoid this behaviour if possible. +. +Similarly, +do not put more than one space between words in an ordinary text line; +they are not +.Dq normalized +to a single space as other text formatters might do. +. +. +.Pp +Don't try to use the neutral double quote character +.Ql \[dq] +to represent itself in an argument. +. +Use the special character escape sequence +.Ql \[rs](dq +to format it. +.\" That's NOT a groffism, but showed up in the "post" and "Latin1" +.\" devices of Tenth Edition Research Unix. +. +Further, +this glyph should not be used for conventional quotation; +.Xr mdoc +offers several quotation macros. +. +See subsection +.Sx "Enclosure and quoting macros" +below. +. +. +.Pp +The formatter attempts to detect the ends of sentences and by default +puts the equivalent of two spaces between sentences on the same output +line; +see +.Xr roff @MAN7EXT@ . +. +To defeat this detection in a parsed list of macro arguments, +put +.Ql \e& +before the punctuation mark. +. +Thus, +. +.Bd -literal -offset indent -compact +The +\&.Ql . +character. +\&.Pp +The +\&.Ql \e&. +character. +\&.Pp +\&.No test . +test +\&.Pp +\&.No test. +test +.Ed +. +gives +. +.Bd -filled -offset indent -compact +The +.Ql . +character +. +. +.Pp +The +.Ql \&. +character. +. +. +.Pp +.No test . +test +. +. +.Pp +.No test. +test +.Ed +. +as output. +. +As can be seen in the first and third output lines, +.Xr mdoc +handles punctuation characters specially in macro arguments. +. +This will be explained in section +.Sx "General syntax" +below. +. +. +.Pp +A comment in the source file of a man page can begin with +.Sq Li .\e" +at the start of an input line, +.Sq Li \e" +after other input, +or +.Sq Li \e# +anywhere +(the last is a +.Xr groff +extension); +the remainder of any such line is ignored. +. +. +.Sh "A man page template" +. +Use +.Xr mdoc +to construct a man page from the following template. +. +.Bd -literal -offset indent +\&.\e" The following three macro calls are required. +\&.Dd date +\&.Dt topic [section-identifier [section-keyword-or-title]] +\&.Os [package-or-operating system [version-or-release]] +\&.Sh Name +\&.Nm topic +\&.Nd summary-description +\&.\e" The next heading is used in sections 2 and 3. +\&.\e" .Sh Library +\&.\e" The next heading is used in sections 1-4, 6, 8, and 9. +\&.Sh Synopsis +\&.Sh Description +\&.\e" Uncomment and populate the following sections as needed. +\&.\e" .Sh \[dq]Implementation notes\[dq] +\&.\e" The next heading is used in sections 2, 3, and 9. +\&.\e" .Sh \[dq]Return values\[dq] +\&.\e" The next heading is used in sections 1, 3, 6, and 8. +\&.\e" .Sh Environment +\&.\e" .Sh Files +\&.\e" The next heading is used in sections 1, 6, and 8. +\&.\e" .Sh \[dq]Exit status\[dq] +\&.\e" .Sh Examples +\&.\e" The next heading is used in sections 1, 4, 6, 8, and 9. +\&.\e" .Sh Diagnostics +\&.\e" .Sh Compatibility +\&.\e" The next heading is used in sections 2, 3, 4, and 9. +\&.\e" .Sh Errors +\&.\e" .Sh \[dq]See also\[dq] +\&.\e" .Sh Standards +\&.\e" .Sh History +\&.\e" .Sh Authors +\&.\e" .Sh Caveats +\&.\e" .Sh Bugs +.Ed +. +. +.Pp +The first items in the template are the commands +.Pf . Ic \&Dd , +.Pf . Ic \&Dt , +and +.Pf . Ic \&Os . +. +They identify the page and are discussed below in section +.Sx "Title macros" . +. +. +.Pp +The remaining items in the template are section headings +.Pf ( Pf . Ic \&Sh ) ; +of which +.Sx Name +and +.Sx Description +are mandatory. +. +These headings are discussed in section +.Sx "Page structure domain" , +which follows section +.Sx "Manual domain" . +. +Familiarize yourself with manual domain macros first; +we use them to illustrate the use of page structure domain macros. +. +. +.Sh Conventions +. +In the descriptions of macros below, +square brackets surround optional arguments. +. +An ellipsis +.Pf ( Sq ... ) +represents repetition of the preceding argument zero or more times. +. +Alternative values of a parameter are separated with +.Ql | . +. +If a mandatory parameter can take one of several alternative values, +use braces to enclose the set, +with spaces and +.Ql | +separating the items. +. +.\" XXX: Angle brackets should only be necessary when space doesn't +.\" separate parameters. +.\" . +.\" Metasyntactic variables are specified within angle brackets. +.\"Bl -tag -width 6n -offset indent -compact +.Bl -tag -offset indent -compact +.It Nm ztar Xo +.Brq Cm c | Cm x +.Op Fl w Op Fl y | Fl z +.Op Fl f Ar archive +.Ar member No ... +.Xc +.El +. +An alternative to using braces is to separately synopsize distinct +operation modes, +particularly if the list of valid optional arguments is dependent on the +user's choice of a mandatory parameter. +. +.Bl -tag -offset indent -compact +.It Nm ztar Xo +.Cm c +.Op Fl w Op Fl y | Fl z +.Op Fl f Ar archive +.Ar member No ... +.Xc +.It Nm ztar Xo +.Cm x +.Op Fl w Op Fl y | Fl z +.Op Fl f Ar archive +.Ar member No ... +.Xc +.El +. +. +.Pp +Most macros affect subsequent arguments until another macro or a newline +is encountered. +. +For example, +.Sq Li ".Li ls Bq Ar file" +doesn't produce +.Sq Li "ls [file]" , +but +.Sq Li ls Bq Ar file . +. +Consequently, +a warning message is emitted for many commands if the first argument is +itself a macro, +since it cancels the effect of the preceding one. +.\" XXX: I don't think it is made clear which macros eat only one +.\" argument and which ones devour tokens until another macro is +.\" encountered. -- GBR +. +On rare occasions, +you might want to format a word along with surrounding brackets as a +literal. +. +.\" XXX: Why do we need the extra "\ " for the width parameter? Without +.\" it, the line breaks before the arrow on a 78n terminal. But there +.\" should be room anyway...bug? +.\" +.\" XXX: Arguably, Bq should respect the altered font family in a `Bl`, +.\" but it sets the brackets and argument in Times roman. Maybe all the +.\" enclosures work this way. +.Bl -tag -width "Li\ \[dq]ls\ [file]\[dq]\ " -offset indent -compact +.It Li ".Li \[dq]ls [file]\[dq]" +\[->] +.Li "ls [file]" +.Em "# list any files named e, f, i, or l" +.El +. +. +.Pp +Many macros possess an implicit width, +used when they are contained in lists and displays. +. +If you avoid relying on these default measurements, +you escape potential conflicts with site-local modifications of the +.Xr mdoc +package. +. +Explicit +.Fl width +and +.Fl offset +arguments to the +.Pf . Ic \&Bl +and +.Pf . Ic \&Bd +macros are preferable. +. +. +.Sh "Title macros" +. +We present the +.Sy mandatory +title macros first due to their importance even though they formally +belong to the page structure domain macros. +.\" XXX: This was formerly "...for someone who wishes to start writing a +.\" man page yesterday." +.\" +.\" Cute joke, but we're 800+ lines into this page source and four pages +.\" into the document when formatted for U.S. letter paper. We lost +.\" that kind of reader last _week_. +. +They designate the +topic, +date of last revision, +and the operating system or software project associated with the page. +. +Call each once at the beginning of the document. +. +They populate the page headers and footers, +which are in +.Xr roff +parlance termed +.Dq titles . +. +. +.Bl -tag -width 6n +.It Li .Dd Xo +.Ar date +.Xc +This first macro of any +.Xr mdoc +manual records the last modification date of the document source. +. +Arguments are concatenated and separated with space characters. +. +. +.Pp +Historically, +.Ar date +was written in U.S.\& traditional format, +.Do +.\" XXX: Em -> Ar when we de-Courierize .Ar. +.Em Month day Li , Em year +.Dc +where +.Em Month +is the full month name in English, +.Em day +an integer without a leading zero, +and +.Em year +the four-digit year. +. +This localism is not enforced, +however. +. +You may prefer ISO 8601 format, +.Em YYYY-MM-DD. +. +A +.Ar date +of the form +.Sq Li $Mdocdate: Ar Month day year Li $ +is also recognized. +. +It is used in +.Ox +manuals to automatically insert the current date when committing. +. +. +.Pp +This macro is neither callable nor parsed. +. +. +.br +.ne 5v +.It Li .Dt Ar topic Op Ar section-identifier \ +Op Ar section-keyword-or-title +. +.Ar topic +is the subject of the man page. +. +A +.Ar section-identifier +that begins with an integer in the range 1\[en]9 +or is one of the words +.Ql unass , +.Ql draft , +or +.Ql paper +selects a predefined section title. +. +This use of +.Dq section +has nothing to do with the section headings otherwise discussed in this +page; +it arises from the organizational scheme of printed and bound Unix +manuals. +. +. +.br +.ne 3v +.Pp +In this implementation, +the following titles are defined for integral section numbers. +. +. +.Bd -unfilled -offset indent +.TS +Lf(CR) L. +1 \*[doc-volume-ds-1] +2 \*[doc-volume-ds-2] +3 \*[doc-volume-ds-3] +4 \*[doc-volume-ds-4] +5 \*[doc-volume-ds-5] +6 \*[doc-volume-ds-6] +7 \*[doc-volume-ds-7] +8 \*[doc-volume-ds-8] +9 \*[doc-volume-ds-9] +.TE +.Ed +. +. +.Pp +A section title may be arbitrary or one of the following abbreviations. +. +. +.Bd -unfilled -offset indent +.TS +Lf(CR) L. +USD \*[doc-volume-ds-USD] +PS1 \*[doc-volume-ds-PS1] +AMD \*[doc-volume-ds-AMD] +SMM \*[doc-volume-ds-SMM] +URM \*[doc-volume-ds-URM] +PRM \*[doc-volume-ds-PRM] +KM \*[doc-volume-ds-KM] +IND \*[doc-volume-ds-IND] +LOCAL \*[doc-volume-ds-LOCAL] +CON \*[doc-volume-ds-CON] +.TE +.Ed +. +. +.Pp +For compatibility, +.Ql MMI +can be used for +.Ql IND , +and +.Ql LOC +for +.Ql LOCAL . +. +Values from the previous table will specify a new section title. +. +If +.Ar section-keyword-or-title +designates a computer architecture recognized by +.Xr "groff mdoc" , +its value is prepended to the default section title as specified by the +second parameter. +.\" mandoc(1) appears to put the architecture string after (or in place +.\" of) the section title, in parentheses. +. +By default, +the following architecture keywords are defined. +. +\# we use 'No' to avoid hyphenation +.\" Resort to ps/vs violence if necessary because this macro package is +.\" obsessed with dumping gigantic piles of identifiers on users, and I +.\" need the space to keep this macro description to a single page in +.\" PS/PDF(!). Lists of information like this simply beg to bit-rot. +.\" -- GBR +.br +.ps -2 +.vs -2 +.Bd -ragged -offset 4n +.No acorn26 , acorn32 , algor , alpha , amd64 , amiga , amigappc , +.No arc , arm , arm26 , arm32 , armish , atari , aviion , +.No beagle , bebox , cats , cesfic , cobalt , dreamcast , +.No emips , evbarm , evbmips , evbppc , evbsh3 , ews4800mips , +.No hp300 , hp700 , hpcarm , hpcmips , hpcsh , hppa , hppa64 , +.No i386 , ia64 , ibmnws , iyonix , landisk , loongson , luna68k , +.No luna88k , m68k , mac68k , macppc , mips , mips64 , mipsco , mmeye , +.No mvme68k , mvme88k , mvmeppc , netwinder , news68k , newsmips , +.No next68k , ofppc , palm , pc532 , playstation2 , pmax , pmppc , +.No powerpc , prep , rs6000 , sandpoint , sbmips , sgi , sgimips , sh3 , +.No shark , socppc , solbourne , sparc , sparc64 , sun2 , sun3 , +.No tahoe , vax , x68k , x86_64 , xen , zaurus +.Ed +.vs +.ps +. +. +.Pp +If a section title is not determined after the above matches have been +attempted, +.Ar section-keyword-or-title +is used. +. +. +.br +.ne 10v \" Keep explanatory paragraph with the following table. +.Pp +The effects of varying +.Ql .Dt +arguments on the page header content +are shown below. +. +Observe how +.Ql \[rs]& +prevents the numeral\~2 from being used to look up a predefined section +title. +. +. +.Pp +.\" On terminals, 2n is as far as we can offset without overrunning a +.\" 78n width. +.Bd -unfilled -offset 2n +.TS +tab(@); +Lf(CR)1 L2 L C R. +\&.Dt foo 2@\[->]@foo(2)@System Calls Manual@foo(2) +\&.Dt foo 2 m68k@\[->]@foo(2)@m68k System Calls Manual@foo(2) +\&.Dt foo 2 baz@\[->]@foo(2)@System Calls Manual@foo(2) +\&.Dt foo \[rs]&2 baz@\[->]@foo(2)@baz@foo(2) +\&.Dt foo \[dq]\[dq] baz@\[->]@foo@baz@foo +\&.Dt foo M Z80@\[->]@foo(M)@Z80@foo(M) +.TE +.Ed +. +. +.Pp +.Xr roff +strings define section titles and architecture identifiers. +. +Site-specific additions might be found in the file +.Pa mdoc.local ; +see section +.Sx Files +below. +. +. +.Pp +This macro is neither callable nor parsed. +. +. +.It Li .Os Op Ar operating-system-or-package-name \ +Op Ar version-or-release +. +This macro associates the document with a software distribution. +. +When composing a man page to be included in the base installation of an +operating system, +do not provide an argument; +.Xr mdoc +will supply it. +. +In this implementation, +that default is +.Dq "\*[doc-default-operating-system]" . +. +It may be overridden in the site configuration file, +.Pa mdoc.local ; +see section +.Sx Files +below. +. +A portable software package maintaining its own man pages can supply +its name and version number or release identifier as optional arguments. +. +A +.Em version-or-release +argument should use the standard nomenclature for the software +specified. +. +In the following table, +recognized +.Em version-or-release +arguments for some predefined operating systems are listed. +. +As with +.Pf . Ic \&Dt , +site additions might be defined in +.Pa mdoc.local . +. +.Bd -ragged -compact +.Bl -tag -width ".No DragonFly" -offset indent +.It ATT +7th, 7, III, 3, V, V.2, V.3, V.4 +.It BSD +3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4 +.It NetBSD +0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a, 1.2b, 1.2c, 1.2d, 1.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, 1.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, 3.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, 5.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, 6.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, 7.0.2, 7.1, 7.1.1, +7.1.2, 7.2, 8.0, 8.1 +.It FreeBSD +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, +2.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, +3.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, +4.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, +6.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, +9.2, 9.3, 10.0, 10.1, 10.2, 10.3, 10.4, 11.0, 11.1, 11.2, 11.3, 12.0, +12.1 +.It OpenBSD +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, +3.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, +4.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, +6.2, 6.3, 6.4, 6.5, 6.6 +.It DragonFly +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, +1.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, +2.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, +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, 3.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, 4.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, 4.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, 5.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, 5.5, 5.6, 5.6.1, 5.6.2 +.It Darwin +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, +8.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, 9.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, 10.7.0, +10.8.0, 11.0.0, 11.1.0, 11.2.0, 11.3.0, 11.4.0, 11.5.0, 12.0.0, 12.1.0, +12.2.0, 13.0.0, 13.1.0, 13.2.0, 13.3.0, 13.4.0, 14.0.0, 14.1.0, 14.2.0, +14.3.0, 14.4.0, 14.5.0, 15.0.0, 15.1.0, 15.2.0, 15.3.0, 15.4.0, 15.5.0, +15.6.0, 16.0.0, 16.1.0, 16.2.0, 16.3.0, 16.4.0, 16.5.0, 16.6.0, 17.0.0, +17.1.0, 17.2.0, 17.3.0, 17.4.0, 17.5.0, 17.6.0, 17.7.0, 18.0.0, 18.1.0, +18.2.0, 18.3.0, 18.4.0, 18.5.0, 18.6.0, 18.7.0, 19.0.0, 19.1.0, 19.2.0 +.El +.Ed +. +. +.Pp +Historically, +the first argument used with +.Pf . Ic \&Dt +was +.Li BSD +or +.Li ATT . +. +An unrecognized version argument after +.Li ATT +is replaced with +.Dq Ux ; +for other predefined abbreviations, +it is ignored and a warning diagnostic emitted. +. +Otherwise, +unrecognized arguments are displayed verbatim in the page footer. +. +For instance, +this page uses +.Dq Li .Os groff @VERSION@ +whereas a locally produced page might employ +.Dq Li .Os \[dq]UXYZ CS Department\[dq] , +omitting versioning. +. +. +.Pp +This macro is neither callable nor parsed. +.El +. +. +.br +.ne 4v +.Sh "Introduction to manual and general text domains" +. +. +.Ss "What's in a Name" Ns ... \" XXX: Ns not scrubbed for PDF bookmark +. +The manual domain macro names are derived from the day to day informal +language used to describe commands, subroutines and related files. +Slightly different variations of this language are used to describe the +three different aspects of writing a man page. +First, there is the description of +.Xr mdoc +macro command usage. +Second is the description of a +.Ux +command +.Em with +.Xr mdoc +macros, and third, the description of a command to a user in the verbal +sense; that is, discussion of a command in the text of a man page. +. +. +.Pp +In the first case, +.Xr @g@troff +macros are themselves a type of command; +the general syntax for a +.Xr troff +command is: +. +.Bd -filled -offset indent +.Li ".Xx argument1 argument2" ... +.Ed +. +. +.Pp +. +.Ql .Xx +is a macro command, and anything following it are arguments to +be processed. +In the second case, the description of a +.Ux +command using the manual domain macros is a bit more involved; +a typical +.Sx Synopsis +command line might be displayed as: +. +.Bd -filled -offset indent +.Nm filter +.Op Fl flag +.Ao Ar infile Ac Ao Ar outfile Ac +.Ed +. +. +.Pp +Here, +.Nm filter +is the command name and the +bracketed string +.Fl flag +is a +.Em flag +argument designated as optional by the option brackets. +In +.Xr mdoc +terms, +.Ao Ar infile Ac +and +.Ao Ar outfile Ac +are called +.Em meta arguments ; +in this example, the user has to replace the meta expressions given in angle +brackets with real file names. +Note that in this document meta arguments are used to describe +.Xr mdoc +commands; in most man pages, meta variables are not specifically written +with angle brackets. +. +The macros that formatted the above example: +. +.Bd -literal -offset indent +\&.Nm filter +\&.Op Fl flag +\&.Ao Ar infile Ac Ao Ar outfile Ac +.Ed +. +. +.Pp +In the third case, +discussion of commands and command syntax includes both examples above, +but may add more detail. +. +The arguments +.Ao Ar infile Ac +and +.Ao Ar outfile Ac +from the example above might be referred to as +.Em operands +or +.Em file arguments . +. +Some command-line argument lists are quite long: +. +.Bd -ragged +.Bl -tag -width ".Nm make" -offset indent -compact +.It Nm make +.Op Fl eiknqrstv +.Op Fl D Ar variable +.Op Fl d Ar flags +.Op Fl f Ar makefile +.Op Fl I Ar directory +.Op Fl j Ar max_jobs +.Op Ar variable Ns = Ns Ar value +.Bk +.Op Ar target No ... +.Ek +.El +.Ed +. +. +.Pp +Here one might talk about the command +.Xr make +and qualify the argument, +.Ar makefile , +as an argument to the flag, +.Fl f , +or discuss the optional file operand +.Ar target . +In the verbal context, such detail can prevent confusion, however the +.Xr mdoc +package does not have a macro for an argument +.Em to +a flag. +Instead the +.Ql \&Ar +argument macro is used for an operand or file argument like +.Ar target +as well as an argument to a flag like +.Ar variable . +The make command line was produced from: +. +.Bd -literal -offset indent +\&.Nm make +\&.Op Fl eiknqrstv +\&.Op Fl D Ar variable +\&.Op Fl d Ar flags +\&.Op Fl f Ar makefile +\&.Op Fl I Ar directory +\&.Op Fl j Ar max_jobs +\&.Op Ar variable Ns = Ns Ar value +\&.Bk +\&.Op Ar target ... +\&.Ek +.Ed +. +. +.Pp +The +.Ql .Bk +and +.Ql .Ek +macros are explained in +.Sx Keeps . +. +. +.Ss "General Syntax" +. +The manual domain and general text domain macros share a similar syntax +with a few minor deviations; +most notably, +.Ql .Ar , +.Ql .Fl , +.Ql .Nm , +and +.Ql .Pa +differ only when called without arguments; and +.Ql .Fn +and +.Ql .Xr +impose an order on their argument lists. +. +All manual domain macros are capable of recognizing and properly +handling punctuation, +provided each punctuation character is separated by a leading space. +. +If a command is given: +. +. +.Pp +.Dl \&.Ar sptr, ptr), +. +. +.Pp +The result is: +. +. +.Pp +.Dl Ar sptr, ptr), +. +. +.Pp +The punctuation is not recognized and all is output in the +font used by +.Ql .Ar . +If the punctuation is separated by a leading white space: +. +. +.Pp +.Dl \&.Ar "sptr , ptr ) ," +. +. +.Pp +The result is: +. +. +.Pp +.Dl Ar sptr , ptr ) , +. +. +.Pp +The punctuation is now recognized and output in the default font +distinguishing it from the argument strings. +. +To remove the special meaning from a punctuation character, +escape it with +.Ql \e& . +. +. +.Pp +The following punctuation characters are recognized by +.Xr mdoc : +. +.Bl -column -offset indent-two XXXXXX XXXXXX XXXXXX XXXXXX +.It Li .\& Ta Li ,\& Ta Li :\& Ta Li ;\& Ta Li (\& +.It Li )\& Ta Li [\& Ta Li ]\& Ta Li ?\& Ta Li !\& +.El +. +. +.Pp +. +.Xr troff +is limited as a macro language, +and has difficulty when presented with a string containing certain +mathematical, +logical, +or quotation character sequences: +. +.Bd -literal -offset indent-two +{+,\-,/,*,%,<,>,<=,>=,=,==,&,\[ga],\[aq],"} +.Ed +. +. +.Pp +The problem is that +.Xr troff +may assume it is supposed to actually perform the operation or +evaluation suggested by the characters. +. +To prevent the accidental evaluation of these characters, +escape them with +.Ql \e& . +. +Typical syntax is shown in the first manual domain macro displayed +below, +.Ql .Ad . +. +. +.Sh "Manual domain" +. +. +.Ss Addresses +. +The address macro identifies an address construct. +. +. +.Pp +.Dl Usage: .Ad Ao address Ac ... +. +. +.Pp +.Bl -tag -width ".Li .Ad\ f1\ ,\ f2\ ,\ f3\ :" -compact -offset 15n +.It Li ".Ad addr1" +.Ad addr1 +.It Li ".Ad addr1 ." +.Ad addr1 . +.It Li ".Ad addr1 , file2" +.Ad addr1 , file2 +.It Li ".Ad f1 , f2 , f3 :" +.Ad f1 , f2 , f3 : +.It Li ".Ad addr ) ) ," +.Ad addr ) ) , +.El +. +. +.Pp +The default width is 12n. +. +.Ss "Author Name" +. +The +.Ql .An +macro is used to specify the name of the author of the item being +documented, or the name of the author of the actual manual page. +. +. +.Pp +.Dl Usage: .An Ao author name Ac ... +. +. +.Pp +.Bl -tag -width ".Li .An\ \[dq]Joe\ Author\[dq]\ )\ )\ ," -offset 15n +.It Li ".An \[dq]Joe Author\[dq]" +.An "Joe Author" +.It Li ".An \[dq]Joe Author\[dq] ," +.An "Joe Author" , +.It Li ".An \[dq]Joe Author\[dq] Aq nobody@FreeBSD.org" +.An "Joe Author" Aq nobody@FreeBSD.org +.It Li ".An \[dq]Joe Author\[dq] ) ) ," +.An "Joe Author" ) ) , +.El +. +. +.Pp +The default width is 12n. +. +. +.Pp +In a section titled +.Dq Authors , +.Ql \&An +causes a break, +allowing each new name to appear on its own line. +. +If this is not desirable, +. +.Bd -literal -offset indent +\&.An \-nosplit +.Ed +. +. +.Pp +. +call will turn this off. +To turn splitting back on, write +. +.Bd -literal -offset indent +\&.An \-split +.Ed +. +. +.Ss Arguments +. +The +.Li .Ar +argument macro may be used whenever an argument is referenced. +. +If called without arguments, +.Sq Ar +is output. +. +This places the ellipsis in italics, +which is ugly and incorrect, +and will be noticed on terminals that underline text instead of using an +oblique typeface. +. +We recommend using +.Ql ".Ar file \&No ..." +instead. +. +. +.Pp +.Dl Usage: .Ar Oo Ao argument Ac Oc No ... +. +. +.Pp +.Bl -tag -width ".Li .Ar\ file1\ file2" -compact -offset 15n +.It Li .Ar +.Ar +.It Li .Ar file \&No ... +.Ar file No ... +.It Li ".Ar file1" +.Ar file1 +.It Li ".Ar file1 ." +.Ar file1 . +.It Li ".Ar file1 file2" +.Ar file1 file2 +.It Li ".Ar f1 f2 f3 :" +.Ar f1 f2 f3 : +.It Li ".Ar file ) ) ," +.Ar file ) ) , +.El +. +. +.Pp +. +The default width is 12n. +. +. +.Ss "Configuration Declaration (Section Four Only)" +. +The +.Ql .Cd +macro is used to demonstrate a +.Xr config 8 +declaration for a device interface in a section four manual. +. +. +.Pp +.Dl Usage: .Cd Ao argument Ac ... +. +. +.Pp +.Bl -tag -width ".Li .Cd\ Xdevice\ le0\ at\ scode?X" -offset 15n +.It Li ".Cd \[dq]device le0 at scode?\[dq]" +.Cd "device le0 at scode?" +.El +. +. +.Pp +In a section titled +.Dq Synopsis , +.Ql \&Cd +causes a break before and after its arguments. +. +. +.Pp +The default width is 12n. +. +. +.Ss "Command Modifiers" +. +The command modifier is identical to the +.Ql .Fl +(flag) command with the exception that the +.Ql .Cm +macro does not assert a dash in front of every argument. +Traditionally flags are marked by the preceding dash, however, some commands +or subsets of commands do not use them. +Command modifiers may also be specified in conjunction with interactive +commands such as editor commands. +See +.Sx Flags . +. +. +.Pp +The default width is 10n. +. +. +.Ss "Defined Variables" +. +A variable +(or constant) +that is defined in an include file is specified by the macro +.Ql .Dv . +. +. +.Pp +.Dl Usage: .Dv Ao defined-variable Ac ... +. +. +.Pp +.Bl -tag -width ".Li .Dv\ MAXHOSTNAMELEN" -compact -offset 15n +.It Li ".Dv MAXHOSTNAMELEN" +.Dv MAXHOSTNAMELEN +.It Li ".Dv TIOCGPGRP )" +.Dv TIOCGPGRP ) +.El +. +. +.Pp +. +The default width is 12n. +. +. +.Ss Errnos +. +The +.Ql .Er +errno macro specifies the error return value for section 2, +3, +and\~9 library routines. +. +The second example below shows +.Ql .Er +used with the +.Ql .Bq +general text domain macro, +as it would be used in a section two manual page. +. +. +.Pp +.Dl Usage: .Er Ao errno type Ac ... +.Pp +.Bl -tag -width ".Li .Bq\ Er\ ENOTDIR" -compact -offset 15n +.It Li ".Er ENOENT" +.Er ENOENT +.It Li ".Er ENOENT ) ;" +.Er ENOENT ) ; +.It Li ".Bq Er ENOTDIR" +.Bq Er ENOTDIR +.El +.Pp +. +The default width is 17n. +. +. +.Ss "Environment Variables" +. +The +.Ql .Ev +macro specifies an environment variable. +.Pp +.Dl Usage: .Ev Ao argument Ac ... +.Pp +.Bl -tag -width ".Li .Ev\ PRINTER\ )\ )\ ," -compact -offset 15n +.It Li ".Ev DISPLAY" +.Ev DISPLAY +.It Li ".Ev PATH ." +.Ev PATH . +.It Li ".Ev PRINTER ) ) ," +.Ev PRINTER ) ) , +.El +.Pp +. +The default width is 15n. +. +. +.Ss Flags +. +The +.Ql .Fl +macro handles command-line flags. +It prepends a dash, +.Ql \- , +to the flag. +. +For interactive command flags that are not prepended with a dash, +the +.Ql .Cm +(command modifier) +macro is identical, +but without the dash. +. +. +.Pp +.Dl Usage: .Fl Ao argument Ac ... +.Pp +.Bl -tag -width ".Li .Fl\ xyz\ )\ ," -compact -offset 15n +.It Li .Fl +.Fl +.It Li ".Fl cfv" +.Fl cfv +.It Li ".Fl cfv ." +.Fl cfv . +.It Li ".Cm cfv ." +.Cm cfv . +.It Li ".Fl s v t" +.Fl s v t +.It Li ".Fl \- ," +.Fl \- , +.It Li ".Fl xyz ) ," +.Fl xyz ) , +.It Li ".Fl |" +.Fl | +.El +.Pp +The +.Ql .Fl +macro without any arguments results in a dash representing stdin/stdout. +Note that giving +.Ql .Fl +a single dash will result in two dashes. +.Pp +The default width is 12n. +. +. +.Ss "Function Declarations" +. +The +.Ql .Fd +macro is used in the +.Sx Synopsis +section with section two or three functions. +It is neither callable nor parsed. +.Pp +.Dl Usage: .Fd Ao argument Ac ... +.Pp +.Bl -tag -width ".Li .Fd\ X#include\ <sys/types.h>X" -compact -offset 15n +.It Li ".Fd \[dq]#include <sys/types.h>\[dq]" +.Fd "#include <sys/types.h>" +.El +. +. +.Pp +In a section titled +.Dq Synopsis , +.Ql \&Fd +causes a break if a function has already been presented and a break has +not occurred, +leaving vertical space between one function declaration and the next. +.\" XXX: that's not what "break" means +. +. +.Pp +In a section titled +.Dq Synopsis , +the +.Ql \&In +macro represents the +.Li #include +statement, +and is the short form of the above example. +. +It specifies the C\~header file as being included in a C\~program. +. +It also causes a break. +. +. +.Pp +While not in the +.Dq Synopsis +section, +it represents the header file enclosed in angle brackets. +. +. +.Pp +.Dl Usage: .In Ao header file Ac +. +. +.Pp +.Bl -tag -width ".Li .In\ stdio.h" -compact -offset 15n +.nr in-synopsis-section 1 +.It Li ".In stdio.h" +.In stdio.h +.nr in-synopsis-section 0 +.It Li ".In stdio.h" +.In stdio.h +.El +. +. +.Ss "Function Types" +. +This macro is intended for the +.Dq Synopsis +section. +. +It may be used anywhere else in the man page without problems, +but its main purpose is to present the function type +(in BSD kernel normal form) +for the +.Dq Synopsis +of sections two and three. +. +(It causes a break, +allowing the function name to appear on the next line.) +. +. +.Pp +.Dl Usage: .Ft Ao type Ac ... +.Pp +.Bl -tag -width ".Li .Ft\ struct\ stat" -compact -offset 15n +.It Li ".Ft struct stat" +.Ft struct stat +.El +. +. +.Ss "Functions (Library Routines)" +. +The +.Ql .Fn +macro is modeled on +.Tn ANSI\~C +conventions. +.Pp +.Dl Usage: .Fn Ao function Ac Oo Ao parameter Ac Oc ... +.Pp +.Bl -tag -width ".Li .Fn\ align\ Xchar\ *ptrX\ ," -compact -offset 15n +.It Li ".Fn getchar" +.Fn getchar +.It Li ".Fn strlen ) ," +.Fn strlen ) , +.It Li ".Fn align \[dq]char *ptr\[dq] ," +.Fn align "char *ptr" , +.El +.Pp +Note that any call to another macro signals the end of the +.Ql .Fn +call (it will insert a closing parenthesis at that point). +. +. +.Pp +For functions with many parameters +(which is rare), +the macros +.Ql .Fo +(function open) +and +.Ql .Fc +(function close) +may be used with +.Ql .Fa +(function argument). +.Pp +Example: +. +.Bd -literal -offset indent +\&.Ft int +\&.Fo res_mkquery +\&.Fa "int op" +\&.Fa "char *dname" +\&.Fa "int class" +\&.Fa "int type" +\&.Fa "char *data" +\&.Fa "int datalen" +\&.Fa "struct rrec *newrr" +\&.Fa "char *buf" +\&.Fa "int buflen" +\&.Fc +.Ed +.Pp +. +Produces: +. +.Bd -ragged -offset indent +.Ft int +.Fo res_mkquery +.Fa "int op" +.Fa "char *dname" +.Fa "int class" +.Fa "int type" +.Fa "char *data" +.Fa "int datalen" +.Fa "struct rrec *newrr" +.Fa "char *buf" +.Fa "int buflen" +.Fc +.Ed +. +. +.Pp +Typically, +in a +.Dq Synopsis +section, +the function delcaration will begin the line. +. +If more than one function is presented in the +.Dq Synopsis +section and a function type has not been given, +a break will occur, +leaving vertical space between the current and prior function names. +.\" XXX: that's not what "break" means +. +. +.Pp +The default width values of +.Ql .Fn +and +.Ql .Fo +are 12n and 16n, +respectively. +. +. +.Ss "Function Arguments" +. +The +.Ql .Fa +macro is used to refer to function arguments (parameters) outside of the +.Sx Synopsis +section of the manual or inside the +.Sx Synopsis +section if the enclosure macros +.Ql .Fo +and +.Ql .Fc +instead of +.Ql .Fn +are used. +.Ql .Fa +may also be used to refer to structure members. +.Pp +.Dl Usage: .Fa Ao function argument Ac ... +.Pp +.Bl -tag -width ".Li .Fa\ d_namlen\ )\ )\ ," -compact -offset 15n +.It Li ".Fa d_namlen ) ) ," +.Fa d_namlen ) ) , +.It Li ".Fa iov_len" +.Fa iov_len +.El +.Pp +. +The default width is 12n. +. +. +.Ss "Return Values" +. +The +.Ql .Rv +macro generates text for use in the +.Sx Return values +section. +.Pp +.Dl Usage: .Rv Oo \-std Oc Op Ao function Ac ... +.Pp +For example, +.Ql ".Rv \-std atexit" +produces: +. +.Bd -ragged -offset indent +\# a small hack to suppress a warning message +.ds doc-section-old "\*[doc-section] +.ds doc-section 3 +.Rv -std atexit +.ds doc-section "\*[doc-section-old] +.Ed +.Pp +. +The +.Fl std +option is valid only for manual page sections\~2 and\~3. +Currently, this macro does nothing if used without the +.Fl std +flag. +. +. +.Ss "Exit Status" +. +The +.Ql .Ex +macro generates text for use in the +.Sx Diagnostics +section. +.Pp +.Dl Usage: .Ex Oo \-std Oc Op Ao utility Ac ... +.Pp +For example, +.Ql ".Ex \-std cat" +produces: +. +.Bd -ragged -offset indent +\# a small hack to suppress a warning message +.ds doc-section-old "\*[doc-section] +.ds doc-section 1 +.Ex -std cat +.ds doc-section "\*[doc-section-old] +.Ed +.Pp +. +The +.Fl std +option is valid only for manual page sections 1, 6 and\~8. +Currently, this macro does nothing if used without the +.Fl std +flag. +. +. +.Ss "Interactive Commands" +. +The +.Ql .Ic +macro designates an interactive or internal command. +.Pp +.Dl Usage: .Ic Ao argument Ac ... +.Pp +.Bl -tag -width ".Li .Ic\ setenv\ ,\ unsetenv" -compact -offset 15n +.It Li ".Ic :wq" +.Ic :wq +.It Li ".Ic \[dq]do while {...}\[dq]" +.Ic "do while {...}" +.It Li ".Ic setenv , unsetenv" +.Ic setenv , unsetenv +.El +.Pp +. +The default width is 12n. +. +. +.Ss "Library Names" +. +The +.Ql .Lb +macro is used to specify the library where a particular function is compiled +in. +.Pp +.Dl Usage: .Lb Ao argument Ac ... +.Pp +Available arguments to +.Ql .Lb +and their results are: +. +.Pp +.Bl -tag -width ".Li librpcsec_gss" -compact -offset indent +.It Li libarchive +.Lb libarchive +.It Li libarm +.Lb libarm +.It Li libarm32 +.Lb libarm32 +.It Li libbluetooth +.Lb libbluetooth +.It Li libbsm +.Lb libbsm +.It Li libc +.Lb libc +.It Li libc_r +.Lb libc_r +.It Li libcalendar +.Lb libcalendar +.It Li libcam +.Lb libcam +.It Li libcdk +.Lb libcdk +.It Li libcipher +.Lb libcipher +.It Li libcompat +.Lb libcompat +.It Li libcrypt +.Lb libcrypt +.It Li libcurses +.Lb libcurses +.It Li libdevinfo +.Lb libdevinfo +.It Li libdevstat +.Lb libdevstat +.It Li libdisk +.Lb libdisk +.It Li libdwarf +.Lb libdwarf +.It Li libedit +.Lb libedit +.It Li libelf +.Lb libelf +.It Li libevent +.Lb libevent +.It Li libfetch +.Lb libfetch +.It Li libform +.Lb libform +.It Li libgeom +.Lb libgeom +.It Li libgpib +.Lb libgpib +.It Li libi386 +.Lb libi386 +.It Li libintl +.Lb libintl +.It Li libipsec +.Lb libipsec +.It Li libipx +.Lb libipx +.It Li libiscsi +.Lb libiscsi +.It Li libjail +.Lb libjail +.It Li libkiconv +.Lb libkiconv +.It Li libkse +.Lb libkse +.It Li libkvm +.Lb libkvm +.It Li libm +.Lb libm +.It Li libm68k +.Lb libm68k +.It Li libmagic +.Lb libmagic +.It Li libmd +.Lb libmd +.It Li libmemstat +.Lb libmemstat +.It Li libmenu +.Lb libmenu +.It Li libnetgraph +.Lb libnetgraph +.It Li libnetpgp +.Lb libnetpgp +.It Li libossaudio +.Lb libossaudio +.It Li libpam +.Lb libpam +.It Li libpcap +.Lb libpcap +.It Li libpci +.Lb libpci +.It Li libpmc +.Lb libpmc +.It Li libposix +.Lb libposix +.It Li libprop +.Lb libprop +.It Li libpthread +.Lb libpthread +.It Li libpuffs +.Lb libpuffs +.It Li librefuse +.Lb librefuse +.It Li libresolv +.Lb libresolv +.It Li librpcsec_gss +.Lb librpcsec_gss +.It Li librpcsvc +.Lb librpcsvc +.It Li librt +.Lb librt +.It Li libsdp +.Lb libsdp +.It Li libssp +.Lb libssp +.It Li libSystem +.Lb libSystem +.It Li libtermcap +.Lb libtermcap +.It Li libterminfo +.Lb libterminfo +.It Li libthr +.Lb libthr +.It Li libufs +.Lb libufs +.It Li libugidfw +.Lb libugidfw +.It Li libulog +.Lb libulog +.It Li libusbhid +.Lb libusbhid +.It Li libutil +.Lb libutil +.It Li libvgl +.Lb libvgl +.It Li libx86_64 +.Lb libx86_64 +.It Li libz +.Lb libz +.El +. +. +.Pp +Site-specific additions might be found in the file +.Pa mdoc.local ; +see section +.Sx Files +below. +. +. +.Pp +In a section titled +.Dq Library , +.Ql \&Lb +causes a break before and after its arguments. +. +. +.Ss Literals +. +The +.Ql \&Li +literal macro may be used for special characters, +symbolic constants, +and other syntactical items that should be typed exactly as displayed. +. +. +.Pp +.Dl Usage: .Li Ao argument Ac ... +.Pp +.Bl -tag -width ".Li .Li\ cntrl\-D\ )\ ," -compact -offset 15n +.It Li ".Li \een" +.Li \en +.It Li ".Li M1 M2 M3 ;" +.Li M1 M2 M3 ; +.It Li ".Li cntrl\-D ) ," +.Li cntrl-D ) , +.It Li ".Li 1024 ..." +.Li 1024 ... +.El +.Pp +. +The default width is 16n. +. +. +.Ss Names +. +The +.Ql \&Nm +macro is used for the document title or page topic. +. +Upon its first call, +it has the peculiarity of remembering its argument, +which should always be the topic of the man page. +. +When subsequently called without arguments, +.Ql \&Nm +regurgitates this initial name for the sole purpose of making less work +for the author. +. +Use of +.Ql \&Nm +is also appropriate when presenting a command synopsis for the topic of +a man page in section 1, +6, +or 8. +. +Its behavior changes when presented with arguments of various forms. +. +. +.Pp +.Bl -tag -width ".Li .Nm\ groff_mdoc" -compact -offset 15n +.It Li ".Nm groff_mdoc" +.Nm groff_mdoc +.It Li ".Nm" +.Nm +.It Li ".Nm \e\-mdoc" +.Nm \-mdoc +.It Li ".Nm foo ) ) ," +.Nm foo ) ) , +.It Li ".Nm :" +.Nm : +.El +. +. +.Pp +By default, +the topic is set in boldface to reflect its prime importance in the +discussion. +. +Cross references to other man page topics should use +.Ql \&Xr ; +including a second argument for the section number enables them to be +hyperlinked. +. +By default, +cross-referenced topics are set in italics to avoid cluttering the page +with boldface. +. +. +.Pp +The default width is 10n. +. +. +.Ss Options +The +.Ql .Op +macro places option brackets around any remaining arguments on the +command line, +and places any trailing punctuation outside the brackets. +. +The macros +.Ql .Oo +and +.Ql .Oc +(which produce an opening and a closing option bracket, +respectively) +may be used across one or more lines or to specify the exact position of +the closing parenthesis. +. +. +.Pp +.Dl Usage: .Op Oo Ao option Ac Oc ... +.Pp +.Bl -tag -width ".Li .Op\ Fl\ c\ Ar\ objfil\ Op\ Ar\ corfil\ ," -compact -offset 15n +.It Li .Op +.Op +.It Li ".Op Fl k" +.Op Fl k +.It Li ".Op Fl k ) ." +.Op Fl k ) . +.It Li ".Op Fl k Ar kookfile" +.Op Fl k Ar kookfile +.It Li ".Op Fl k Ar kookfile ," +.Op Fl k Ar kookfile , +.It Li ".Op Ar objfil Op Ar corfil" +.Op Ar objfil Op Ar corfil +.It Li ".Op Fl c Ar objfil Op Ar corfil ," +.Op Fl c Ar objfil Op Ar corfil , +.It Li ".Op word1 word2" +.Op word1 word2 +.It Li ".Li .Op Oo Ao option Ac Oc ..." +.Li .Op Oo Ao option Ac Oc ... +.El +.Pp +Here a typical example of the +.Ql .Oo +and +.Ql .Oc +macros: +. +.Bd -literal -offset indent +\&.Oo +\&.Op Fl k Ar kilobytes +\&.Op Fl i Ar interval +\&.Op Fl c Ar count +\&.Oc +.Ed +.Pp +. +Produces: +. +.Bd -filled -offset indent +.Oo +.Op Fl k Ar kilobytes +.Op Fl i Ar interval +.Op Fl c Ar count +.Oc +.Ed +.Pp +. +The default width values of +.Ql .Op +and +.Ql .Oo +are 14n and 10n, respectively. +. +. +.Ss Pathnames +. +The +.Ql .Pa +macro formats file specifications. +. +If called without arguments, +.Sq Pa +(recognized by many shells) +is output, +representing the user's home directory. +. +. +.Pp +.Dl Usage: .Pa Oo Ao pathname Ac Oc ... +.Pp +.Bl -tag -width ".Li .Pa\ /tmp/fooXXXXX\ )\ ." -compact -offset 15n +.It Li .Pa +.Pa +.It Li ".Pa /usr/share" +.Pa /usr/share +.It Li ".Pa /tmp/fooXXXXX ) ." +.Pa /tmp/fooXXXXX ) . +.El +.Pp +. +The default width is 32n. +. +. +.Ss Standards +. +The +.Ql .St +macro replaces standard abbreviations with their formal names. +.Pp +.Dl Usage: .St Ao abbreviation Ac ... +.Pp +Available pairs for +.Dq Abbreviation/Formal Name +are: +. +.Pp +.Tn ANSI/ISO C +.Pp +.Bl -tag -width ".Li \-p1003.1g\-2000" -compact -offset indent +.It Li \-ansiC +.St -ansiC +.It Li \-ansiC\-89 +.St -ansiC-89 +.It Li \-isoC +.St -isoC +.It Li \-isoC\-90 +.St -isoC-90 +.It Li \-isoC\-99 +.St -isoC-99 +.It Li \-isoC\-2011 +.St -isoC-2011 +.El +.Pp +. +.Tn POSIX +Part 1: System API +.Pp +.Bl -tag -width ".Li \-p1003.1g\-2000" -compact -offset indent +.It Li \-iso9945\-1\-90 +.St -iso9945-1-90 +.It Li \-iso9945\-1\-96 +.St -iso9945-1-96 +.It Li \-p1003.1 +.St -p1003.1 +.It Li \-p1003.1\-88 +.St -p1003.1-88 +.It Li \-p1003.1\-90 +.St -p1003.1-90 +.It Li \-p1003.1\-96 +.St -p1003.1-96 +.It Li \-p1003.1b\-93 +.St -p1003.1b-93 +.It Li \-p1003.1c\-95 +.St -p1003.1c-95 +.It Li \-p1003.1g\-2000 +.St -p1003.1g-2000 +.It Li \-p1003.1i\-95 +.St -p1003.1i-95 +.It Li \-p1003.1\-2001 +.St -p1003.1-2001 +.It Li \-p1003.1\-2004 +.St -p1003.1-2004 +.It Li \-p1003.1\-2008 +.St -p1003.1-2008 +.El +.Pp +. +.Tn POSIX +Part 2: Shell and Utilities +.Pp +.Bl -tag -width ".Li \-p1003.1g\-2000" -compact -offset indent +.It Li \-iso9945\-2\-93 +.St -iso9945-2-93 +.It Li \-p1003.2 +.St -p1003.2 +.It Li \-p1003.2\-92 +.St -p1003.2-92 +.It Li \-p1003.2a\-92 +.St -p1003.2a-92 +.El +.Pp +. +X/Open +.Pp +.Bl -tag -width ".Li \-p1003.1g\-2000" -compact -offset indent +.It Li \-susv1 +.St -susv1 +.It Li \-susv2 +.St -susv2 +.It Li \-susv3 +.St -susv3 +.It Li \-susv4 +.St -susv4 +.It Li \-svid4 +.St -svid4 +.It Li \-xbd5 +.St -xbd5 +.It Li \-xcu5 +.St -xcu5 +.It Li \-xcurses4.2 +.St -xcurses4.2 +.It Li \-xns5 +.St -xns5 +.It Li \-xns5.2 +.St -xns5.2 +.It Li \-xpg3 +.St -xpg3 +.It Li \-xpg4 +.St -xpg4 +.It Li \-xpg4.2 +.St -xpg4.2 +.It Li \-xsh5 +.St -xsh5 +.El +.Pp +. +Miscellaneous +.Pp +.Bl -tag -width ".Li \-p1003.1g\-2000" -compact -offset indent +.It Li \-ieee754 +.St -ieee754 +.It Li \-iso8601 +.St -iso8601 +.It Li \-iso8802\-3 +.St -iso8802-3 +.El +. +. +.Ss "Variable Types" +The +.Ql .Vt +macro may be used whenever a type is referenced. +. +In a section titled +.Dq Synopsis , +.Ql \&Vt +causes a break +(useful for old-style C variable declarations). +. +. +.Pp +.Dl Usage: .Vt Ao type Ac ... +.Pp +.Bl -tag -width ".Li .Vt\ extern\ char\ *optarg\ ;" -compact -offset 15n +.It Li ".Vt extern char *optarg ;" +.Vt extern char *optarg ; +.It Li ".Vt FILE *" +.Vt FILE * +.El +. +. +.Ss Variables +. +Generic variable reference. +.Pp +.Dl Usage: .Va Ao variable Ac ... +.Pp +.Bl -tag -width ".Li .Va\ Xchar\ sX\ ]\ )\ )\ ," -compact -offset 15n +.It Li ".Va count" +.Va count +.It Li ".Va settimer ," +.Va settimer , +.It Li ".Va \[dq]int *prt\[dq] ) :" +.Va "int *prt" ) : +.It Li ".Va \[dq]char s\[dq] ] ) ) ," +.Va "char s" ] ) ) , +.El +.Pp +. +The default width is 12n. +. +. +.Ss "Manual Page Cross References" +. +The +.Ql .Xr +macro expects the first argument to be a manual page name. +. +The optional second argument, +if a string +(defining the manual section), +is +put into parentheses. +. +. +.Pp +.Dl Usage: .Xr Ao man page name Ac Oo Ao section Ac Oc ... +. +. +.Pp +.Bl -tag -width ".Li .Xr\ xinit\ 1x\ ;" -compact -offset 15n +.It Li ".Xr mdoc" +.Xr mdoc +.It Li ".Xr mdoc ," +.Xr mdoc , +.It Li ".Xr mdoc 7" +.Xr mdoc 7 +.It Li ".Xr xinit 1x ;" +.Xr xinit 1x ; +.El +. +. +.Pp +The default width is 10n. +. +. +.Sh "General text domain" +. +. +.Ss "AT&T Macro" +. +.Pp +.Dl Usage: .At Oo Ao version Ac Oc ... +.Pp +.Bl -tag -width ".Li .At\ v6\ ." -compact -offset 15n +.It Li .At +.At +.It Li ".At v6 ." +.At v6 . +.El +.Pp +The following values for +.Ao version Ac +are possible: +.Pp +.Dl 32v, v1, v2, v3, v4, v5, v6, v7, III, V, V.1, V.2, V.3, V.4 +. +. +.Ss "BSD Macro" +. +.Pp +.Dl "Usage: .Bx" Bro \-alpha | \-beta | \-devel Brc ... +.Dl " .Bx" Oo Ao version Ac Oo Ao release Ac Oc Oc ... +.Pp +.Bl -tag -width ".Li .Bx\ -devel" -compact -offset 15n +.It Li .Bx +.Bx +.It Li ".Bx 4.3 ." +.Bx 4.3 . +.It Li ".Bx \-devel" +.Bx -devel +.El +.Pp +.Ao version Ac +will be prepended to the string +.Sq Bx . +The following values for +.Ao release Ac +are possible: +.Pp +.Dl Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2 +. +. +.Ss "NetBSD Macro" +. +.Pp +.Dl Usage: .Nx Oo Ao version Ac Oc ... +.Pp +.Bl -tag -width ".Li .Nx\ 1.4\ ." -compact -offset 15n +.It Li .Nx +.Nx +.It Li ".Nx 1.4 ." +.Nx 1.4 . +.El +.Pp +For possible values of +.Ao version Ac +see the description of the +.Ql .Os +command above in section +.Sx "Title macros" . +. +. +.Ss "FreeBSD Macro" +. +.Pp +.Dl Usage: .Fx Oo Ao version Ac Oc ... +.Pp +.Bl -tag -width ".Li .Fx\ 2.2\ ." -compact -offset 15n +.It Li .Fx +.Fx +.It Li ".Fx 2.2 ." +.Fx 2.2 . +.El +.Pp +For possible values of +.Ao version Ac +see the description of the +.Ql .Os +command above in section +.Sx "Title macros" . +. +. +.Ss "DragonFly Macro" +. +.Pp +.Dl Usage: .Dx Oo Ao version Ac Oc ... +.Pp +.Bl -tag -width ".Li .Dx\ 1.4\ ." -compact -offset 15n +.It Li .Dx +.Dx +.It Li ".Dx 1.4 ." +.Dx 1.4 . +.El +.Pp +For possible values of +.Ao version Ac +see the description of the +.Ql .Os +command above in section +.Sx "Title macros" . +. +. +.Ss "OpenBSD Macro" +. +.Pp +.Dl Usage: .Ox Oo Ao version Ac Oc ... +.Pp +.Bl -tag -width ".Li .Ox\ 1.0" -compact -offset 15n +.It Li ".Ox 1.0" +.Ox 1.0 +.El +. +. +.Ss "BSD/OS Macro" +. +.Pp +.Dl Usage: .Bsx Oo Ao version Ac Oc ... +.Pp +.Bl -tag -width ".Li .Bsx\ 1.0" -compact -offset 15n +.It Li ".Bsx 1.0" +.Bsx 1.0 +.El +. +. +.Ss "Unix Macro" +. +.Pp +.Dl Usage: .Ux ... +.Pp +.Bl -tag -width ".Li .Ux" -compact -offset 15n +.It Li .Ux +.Ux +.El +. +. +.Ss "Emphasis Macro" +. +Text may be stressed or emphasized with the +.Ql .Em +macro. +The usual font for emphasis is italic. +.Pp +.Dl Usage: .Em Ao argument Ac ... +.Pp +.Bl -tag -width ".Li .Em\ vide\ infra\ )\ )\ ," -compact -offset 15n +.It Li ".Em does not" +.Em does not +.It Li ".Em exceed 1024 ." +.Em exceed 1024 . +.It Li ".Em vide infra ) ) ," +.Em vide infra ) ) , +.El +.Pp +. +The default width is 10n. +. +. +.Ss "Font Mode" +. +The +.Ql .Bf +font mode must be ended with the +.Ql .Ef +macro (the latter takes no arguments). +Font modes may be nested within other font modes. +.Pp +.Ql .Bf +has the following syntax: +.Pp +.Dl .Bf Ao font mode Ac +.Pp +.Ao font mode Ac +must be one of the following three types: +.Pp +.Bl -tag -width ".Sy \&Sy | Fl symbolic" -compact -offset indent +.It Sy \&Em | Fl emphasis +Same as if the +.Ql .Em +macro was used for the entire block of text. +.It Sy \&Li | Fl literal +Same as if the +.Ql .Li +macro was used for the entire block of text. +.It Sy \&Sy | Fl symbolic +Same as if the +.Ql .Sy +macro was used for the entire block of text. +.El +.Pp +Both macros are neither callable nor parsed. +. +. +.Ss "Enclosure and Quoting Macros" +. +The concept of enclosure is similar to quoting. +The object being to enclose one or more strings between a pair of characters +like quotes or parentheses. +The terms quoting and enclosure are used interchangeably throughout this +document. +Most of the one-line enclosure macros end in small letter +.Ql q +to give a hint of quoting, but there are a few irregularities. +. +For each enclosure macro, +there is a pair of opening and closing macros that end with the +lowercase letters +.Ql o +and +.Ql c +respectively. +.Pp +\# XXX +.if t \ +. ne 10 +. +.TS +lb lb lb lb lb +l l l l l. +Quote Open Close Function Result +\&.Aq .Ao .Ac Angle Bracket Enclosure <string> +\&.Bq .Bo .Bc Bracket Enclosure [string] +\&.Brq .Bro .Brc Brace Enclosure {string} +\&.Dq .Do .Dc Double Quote \[lq]string\[rq] +\&.Eq .Eo .Ec Enclose String (in XY) XstringY +\&.Pq .Po .Pc Parenthesis Enclosure (string) +\&.Ql Quoted Literal \[lq]string\[rq] or string +\&.Qq .Qo .Qc Straight Double Quote "string" +\&.Sq .So .Sc Single Quote \[oq]string\[cq] +.TE +.Pp +All macros ending with +.Sq q +and +.Sq o +have a default width value of 12n. +. +.Bl -tag -width ".Li .Ec , .Eo" +.It Li .Eo , .Ec +These macros expect the first argument to be the opening and closing +strings, +respectively. +. +.It Li .Es , .En +To work around the nine-argument limit in the original +.Xr troff \" generic +program, +.Xr mdoc +supports two other macros that are now obsolete. +. +.Ql .Es +uses its first and second parameters as opening and closing marks which +are then used to enclose the arguments of +.Ql .En . +. +The default width value is 12n for both macros. +. +.It Li .Eq +The first and second arguments of this macro are the opening and +closing strings respectively, followed by the arguments to be enclosed. +.It Li .Ql +The quoted literal macro behaves differently in +.Xr troff \" mode +and +.Xr nroff \" mode +modes. +. +If formatted with +.Xr @g@nroff @MAN1EXT@ , +a quoted literal is always quoted. +. +If formatted with +.Xr @g@troff , +an item is only quoted if the width of the item is less than three +constant-width characters. +. +This is to make short strings more visible where the font change to +literal (constant-width) is less noticeable. +. +. +.Pp +The default width is 16n. +. +.It Li .Pf +The prefix macro suppresses the whitespace between its first and second +argument: +. +.Bl -tag -width ".Li .Pf\ (\ Fa\ name2" -offset indent +.It Li ".Pf ( Fa name2" +.Pf ( Fa name2 +.El +.Pp +. +The default width is 12n. +.Pp +The +.Ql .Ns +macro (see below) performs the analogous suffix function. +.It Li .Ap +The +.Ql .Ap +macro inserts an apostrophe and exits any special text modes, continuing in +.Ql .No +mode. +.El +.Pp +. +Examples of quoting: +. +.Pp +.Bl -tag -width ".Li .Bq\ Em\ Greek\ ,\ French\ ." -compact -offset indent +.It Li .Aq +.Aq +.It Li ".Aq Pa ctype.h ) ," +.Aq Pa ctype.h ) , +.It Li .Bq +.Bq +.It Li ".Bq Em Greek , French ." +.Bq Em Greek , French . +.It Li .Dq +.Dq +.It Li ".Dq string abc ." +.Dq string abc . +.It Li ".Dq \[aq]\[rs][ha][A\-Z]\[aq]" +.Dq '\[ha][A-Z]' +.It Li ".Ql man mdoc" +.Ql man mdoc +.It Li .Qq +.Qq +.It Li ".Qq string ) ," +.Qq string ) , +.It Li ".Qq string Ns )," +.Qq string Ns ), +.It Li .Sq +.Sq +.It Li ".Sq string" +.Sq string +.It Li ".Em or Ap ing" +.Em or Ap ing +.El +.Pp +. +For a good example of nested enclosure macros, see the +.Ql .Op +option macro. +It was created from the same underlying enclosure macros as those presented +in the list above. +The +.Ql .Xo +and +.Ql .Xc +extended argument list macros are discussed below. +. +. +.Ss "Normal text macro" +. +.Ql \&No +formats subsequent argument(s) normally, +ending the effect of +.Ql \&Em +and similar. +. +Parsing is +.Em not +suppressed, +so you must prefix words like +.Ql \&No +with +.Ql \e& +to avoid their interpretation as +.Xr mdoc +macros. +. +. +.Pp +.Dl Usage: .No Ar argument No ... +. +. +.Pp +.Bl -tag -width ".Li .Em\ Use\ caution\ No\ here\ ." \ +-compact -offset 15n +.It Li ".Em Use caution No here ." +\[->] +.Em Use caution No here . +.It Li ".Em No dogs allowed ." +\[->] +.\" We cheat here to prevent a diagnostic warning. We want to +.\" illustrate output that may surprise the novice. +.Em \&No No dogs allowed . +.It Li ".Em \e&No dogs allowed ." +\[->] +.Em \&No dogs allowed . +.El +. +. +.Pp +The default width is 12n. +. +. +.Ss "No-Space Macro" +. +The +.Ql .Ns +macro suppresses insertion of a space between the current position and its +first parameter. +For example, it is useful for old style argument lists where there is no +space between the flag and argument: +.Pp +.Dl "Usage:" ... Ao argument Ac \&Ns Oo Ao argument Ac Oc ... +.Dl " " .Ns Ao argument Ac ... +.Pp +.Bl -tag -width ".Li .Op\ Fl\ I\ Ns\ Ar\ directory" -compact -offset 15n +.It Li ".Op Fl I Ns Ar directory" +.Op Fl I Ns Ar directory +.El +.Pp +Note: The +.Ql .Ns +macro always invokes the +.Ql .No +macro after eliminating the space unless another macro name follows it. +If used as a command (i.e., the second form above in the +.Sq Usage +line), +.Ql .Ns +is identical to +.Ql .No . +. +. +.Ss "(Sub)section cross references" +. +Use the +.Ql .Sx +macro to cite a (sub)section heading within the given document. +. +. +.Pp +.Dl Usage: .Sx Ao section-reference Ac ... +. +. +.Pp +.Bl -tag -width ".Li .Sx\ Files" -offset 15n +.It Li ".Sx Files" +\[->] +.Sx Files +.El +. +. +.Pp +The default width is 16n. +. +. +.Ss Symbolics +. +The symbolic emphasis macro is generally a boldface macro in either the +symbolic sense or the traditional English usage. +. +. +.Pp +.Dl Usage: .Sy Ao symbol Ac ... +. +. +.Pp +.Bl -tag -width ".Li .Sy\ Important\ Notice" -compact -offset 15n +.It Li ".Sy Important Notice" +\[->] +.Sy Important Notice +.El +. +. +.Pp +The default width is 6n. +. +. +.Ss "Mathematical Symbols" +. +Use this macro for mathematical symbols and similar things. +. +. +.Pp +.Dl Usage: .Ms Ao math symbol Ac ... +. +. +.Pp +.Bl -tag -width ".Li .Ms\ sigma" -compact -offset 15n +.It Li ".Ms sigma" +\[->] +.Ms sigma +.El +. +. +.Pp +The default width is 6n. +. +. +.Ss "References and Citations" +. +The following macros make a modest attempt to handle references. +. +At best, +the macros make it convenient to manually drop in a subset of +.Xr @g@refer @MAN1EXT@ +style references. +. +. +.Pp +.Bl -tag -width 6n -offset indent -compact +.It Li .Rs +Reference start +(does not take arguments). +. +In a section titled +.Dq "See also" , +it causes a break +and begins collection of reference information until the reference end +macro is read. +. +.It Li .Re +Reference end (does not take arguments). +The reference is printed. +.It Li .%A +Reference author name; one name per invocation. +.It Li .%B +Book title. +.It Li .%C +City/place. +.It Li .%D +Date. +.It Li .%I +Issuer/publisher name. +.It Li .%J +Journal name. +.It Li .%N +Issue number. +.It Li .%O +Optional information. +.It Li .%P +Page number. +.It Li .%Q +Corporate or foreign author. +.It Li .%R +Report name. +.It Li .%T +Title of article. +.It Li .%U +Optional hypertext reference. +.It Li .%V +Volume. +.El +.Pp +Macros beginning with +.Ql % +are not callable but accept multiple arguments in the usual way. +Only the +.Ql .Tn +macro is handled properly as a parameter; other macros will cause strange +output. +.Ql .%B +and +.Ql .%T +can be used outside of the +.Ql .Rs/.Re +environment. +.Pp +Example: +. +.Bd -literal -offset indent +\&.Rs +\&.%A "Matthew Bar" +\&.%A "John Foo" +\&.%T "Implementation Notes on foobar(1)" +\&.%R "Technical Report ABC\-DE\-12\-345" +\&.%Q "Drofnats College" +\&.%C "Nowhere" +\&.%D "April 1991" +\&.Re +.Ed +.Pp +produces +. +.Bd -ragged -offset indent +.Rs +.%A "Matthew Bar" +.%A "John Foo" +.%T "Implementation Notes on foobar(1)" +.%R "Technical Report ABC-DE-12-345" +.%Q "Drofnats College" +.%C "Nowhere" +.%D "April 1991" +.Re +.Ed +. +.Ss "Trade Names or Acronyms" +. +The trade name macro prints its arguments at a smaller type size. +. +It is intended to imitate a small caps fonts for fully capitalized +acronyms. +. +. +.Pp +.Dl Usage: .Tn Ao symbol Ac ... +.Pp +.Bl -tag -width ".Li .Tn\ ASCII" -compact -offset 15n +.It Li ".Tn DEC" +.Tn DEC +.It Li ".Tn ASCII" +.Tn ASCII +.El +.Pp +. +The default width is 10n. +. +. +.Ss "Extended Arguments" +. +The +.Li .Xo +and +.Li .Xc +macros allow one to extend an argument list on a macro boundary for the +.Ql .It +macro (see below). +Note that +.Li .Xo +and +.Li .Xc +are implemented similarly to all other macros opening and closing an +enclosure (without inserting characters, of course). +This means that the following is true for those macros also. +.Pp +Here is an example of +.Ql .Xo +using the space mode macro to turn spacing off: +. +.Bd -literal -offset indent +\&.Bd \-literal \-offset indent +\&.Sm off +\&.It Xo Sy I Ar operation +\&.No \een Ar count No \een +\&.Xc +\&.Sm on +\&.Ed +.Ed +.Pp +. +produces +. +.Bd -filled -offset indent +.Bl -tag -compact +.Sm off +.It Xo Sy I Ar operation +.No \en Ar count No \en +.Xc +.Sm on +.El +.Ed +.Pp +. +Another one: +. +.Bd -literal -offset indent +\&.Bd \-literal \-offset indent +\&.Sm off +\&.It Cm S No / Ar old_pattern Xo +\&.No / Ar new_pattern +\&.No / Op Cm g +\&.Xc +\&.Sm on +\&.Ed +.Ed +.Pp +. +produces +. +.Bd -filled -offset indent +.Bl -tag -compact +.Sm off +.It Cm S No \&/ Ar old_pattern Xo +.No \&/ Ar new_pattern +.No \&/ Op Cm g +.Xc +.Sm on +.El +.Ed +.Pp +. +Another example of +.Ql .Xo +and enclosure macros: Test the value of a variable. +. +.Bd -literal -offset indent +\&.Bd \-literal \-offset indent +\&.It Xo +\&.Ic .ifndef +\&.Oo \e&! Oc Ns Ar variable Oo +\&.Ar operator variable No ... +\&.Oc Xc +\&.Ed +.Ed +.Pp +. +produces +. +.Bd -filled -offset indent +.Bl -tag -width flag -compact +.It Xo +.Ic .ifndef +.Oo \&! Oc Ns Ar variable Oo +.Ar operator variable No ... +.Oc Xc +.El +.Ed +.Pp +. +. +.Sh "Page structure domain" +. +. +.Ss "Section headings" +. +The following +.Ql .Sh +section heading macros are required in every man page. +. +The remaining section headings are recommended at the discretion of the +author writing the manual page. +The +.Ql .Sh +macro is parsed but not generally callable. +It can be used as an argument in a call to +.Ql .Sh +only; it then reactivates the default font for +.Ql .Sh . +.Pp +The default width is 8n. +. +.Bl -tag -width ".Li .Sh\ Return\ values" +.It Li ".Sh Name" +The +.Ql ".Sh Name" +macro is mandatory. +. +If not specified, +headers, +footers, +and page layout defaults will not be set and things will be rather +unpleasant. +. +The +.Em Name +section consists of at least three items. +The first is the +.Ql .Nm +name macro naming the subject of the man page. +The second is the name description macro, +.Ql .Nd , +which separates the subject name from the third item, which is the +description. +The description should be the most terse and lucid possible, as the space +available is small. +.Pp +.Ql .Nd +first prints +.Ql \- , +then all its arguments. +. +.It Li ".Sh Library" +This section is for section two and three function calls. +It should consist of a single +.Ql .Lb +macro call; +see +.Sx "Library Names" . +. +.It Li ".Sh Synopsis" +The +.Sx Synopsis +section describes the typical usage of the subject of a man page. +The macros required are either +.Ql .Nm , +.Ql .Cd , +or +.Ql .Fn +(and possibly +.Ql .Fo , +.Ql .Fc , +.Ql .Fd , +and +.Ql .Ft ) . +The function name macro +.Ql .Fn +is required for manual page sections\~2 and\~3; the command and general name +macro +.Ql .Nm +is required for sections 1, 5, 6, 7, and\~8. +Section\~4 manuals require a +.Ql .Nm , +.Ql .Fd +or a +.Ql .Cd +configuration device usage macro. +Several other macros may be necessary to produce the synopsis line as shown +below: +. +.Bd -filled -offset indent +.Nm cat +.Op Fl benstuv +.Op Fl +.Ar file No ... +.Ed +.Pp +. +The following macros were used: +.Pp +.Dl ".Nm cat" +.Dl ".Op Fl benstuv" +.Dl ".Op Fl" +.Dl ".Ar file No ..." +. +.It Li ".Sh Description" +In most cases the first text in the +.Sx Description +section is a brief paragraph on the command, function or file, followed by a +lexical list of options and respective explanations. +To create such a list, the +.Ql .Bl +(begin list), +.Ql .It +(list item) and +.Ql .El +(end list) +macros are used (see +.Sx Lists and Columns +below). +. +.It Li ".Sh Implementation notes" +Implementation specific information should be placed here. +. +.It Li ".Sh Return values" +Sections 2, 3 and\~9 function return values should go here. +The +.Ql .Rv +macro may be used to generate text for use in the +.Sx Return values +section for most section 2 and 3 library functions; +see +.Sx "Return Values" . +.El +.Pp +. +The following +.Ql .Sh +section headings are part of the preferred manual page layout and must +be used appropriately to maintain consistency. +They are listed in the order in which they would be used. +. +.Bl -tag -width ".Li .Sh\ Compatibility" +.It Li ".Sh Environment" +The +.Em Environment +section should reveal any related environment variables and clues to their +behavior and/or usage. +. +.It Li ".Sh Files" +Files which are used or created by the man page subject should be listed via +the +.Ql .Pa +macro in the +.Sx Files +section. +. +.It Li ".Sh Examples" +There are several ways to create examples. +See subsection +.Sx "Examples and Displays" +below for details. +. +.It Li ".Sh Diagnostics" +Diagnostic messages from a command should be placed in this section. +The +.Ql .Ex +macro may be used to generate text for use in the +.Sx Diagnostics +section for most section 1, 6 and\~8 commands; +see +.Sx "Exit Status" . +. +.It Li ".Sh Compatibility" +Known compatibility issues (e.g.\& deprecated options or parameters) +should be listed here. +. +.It Li ".Sh Errors" +Specific error handling, especially from library functions (man page +sections 2, 3, and\~9) should go here. +The +.Ql .Er +macro is used to specify an error (errno). +. +.It Li ".Sh See also" +References to other material on the man page topic and cross references +to other relevant man pages should be placed in the +.Sx "See also" +section. +. +Cross references are specified using the +.Ql .Xr +macro. +. +Currently +.Xr @g@refer @MAN1EXT@ +style references are not accommodated. +. +. +.Pp +It is recommended that the cross references be sorted by section number, +then alphabetically by name within each section, +then separated by commas. +. +Example: +. +. +.Pp +.Xr ls 1 , +.Xr ps 1 , +.Xr group 5 , +.Xr passwd 5 +. +.It Li ".Sh Standards" +If the command, +library function, +or file adheres to a specific implementation such as +.St -p1003.2 +or +.St -ansiC +this should be noted here. +. +If the command does not adhere to any standard, +its history should be noted in the +.Em History +section. +. +.It Li ".Sh History" +Any command which does not adhere to any specific standards should be +outlined historically in this section. +. +.It Li ".Sh Authors" +Credits should be placed here. +. +Use the +.Ql .An +macro for names and the +.Ql .Aq +macro for email addresses within optional contact information. +. +Explicitly indicate whether the person authored the initial manual page +or the software or whatever the person is being credited for. +.It Li ".Sh Bugs" +Blatant problems with the topic go here. +.El +.Pp +. +User-specified +.Ql .Sh +sections may be added; for example, this section was set with: +. +.Bd -literal -offset 15n +\&.Sh "Page structure domain" +.Ed +. +. +.Ss "Subsection headings" +. +Subsection headings have exactly the same syntax as section headings: +.Ql .Ss +is parsed but not generally callable. +It can be used as an argument in a call to +.Ql .Ss +only; it then reactivates the default font for +.Ql .Ss . +.Pp +The default width is 8n. +. +. +.Ss "Paragraphs and Line Spacing" +. +.Bl -tag -width ".Li .Pp" +.It Li .Pp +The +.Ql .Pp +paragraph command may be used to specify a line space where necessary. +The macro is not necessary after a +.Ql .Sh +or +.Ql .Ss +macro or before a +.Ql .Bl +or +.Ql .Bd +macro (which both assert a vertical distance unless the +.Fl compact +flag is given). +.Pp +The macro is neither callable nor parsed and takes no arguments; an +alternative name is +.Ql .Lp . +.El +. +.\" XXX +. +.\" This worked with version one, need to redo for version three +.\" .Pp +.\" .Ds I +.\" .Cw (ax+bx+c) \ is\ produced\ by\ \& +.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& +.\" .Cl Cx \t\t +.\" .Li \&.Cx\ ( +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va ax +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy \+ +.\" .Cx +.\" .Cl Cx \&(\& +.\" .Va ax +.\" .Cx + +.\" .Va by +.\" .Cx + +.\" .Va c ) +.\" .Cx \t +.\" .Em is produced by +.\" .Cx \t +.\" .Li \&.Va by +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy \+ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va c ) +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.\" This example shows the same equation in a different format. +.\" The spaces +.\" around the +.\" .Li \&+ +.\" signs were forced with +.\" .Li \e : +.\" .Pp +.\" .Ds I +.\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \& +.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& +.\" .Cl Cx \t\t +.\" .Li \&.Cx\ ( +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va a +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy x +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx \e\ +\e\ \e& +.\" .Cx +.\" .Cl Cx \&(\& +.\" .Va a +.\" .Sy x +.\" .Cx \ +\ \& +.\" .Va b +.\" .Sy y +.\" .Cx \ +\ \& +.\" .Va c ) +.\" .Cx \t +.\" .Em is produced by +.\" .Cl Cx \t\t +.\" .Li \&.Va b +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Sy y +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx \e\ +\e\ \e& +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Va c ) +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +.\" The incantation below was +.\" lifted from the +.\" .Xr adb 1 +.\" manual page: +.\" .Pp +.\" .Ds I +.\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by +.\" .Cl Cx \t\t +.\" .Li \&.Cx Op Sy ?/ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Nm m +.\" .Cx +.\" .Cl Cx Op Sy ?/ +.\" .Nm m +.\" .Ad \ b1 e1 f1 +.\" .Op Sy ?/ +.\" .Cx \t +.\" .Em is produced by +.\" .Cx \t +.\" .Li \&.Ar \e\ b1 e1 f1 +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Op Sy ?/ +.\" .Cx +.\" .Cl Cx \t\t +.\" .Li \&.Cx +.\" .Cx +.\" .Cw +.\" .De +.\" .Pp +. +. +.Ss Keeps +. +The only keep that is implemented at this time is for words. +. +The macros are +.Ql .Bk +(begin keep) +and +.Ql .Ek +(end keep). +. +The only option that +.Ql .Bk +currently accepts is +.Fl words +(also the default); +this prevents breaks in the middle of options. +. +In the example for +.Nm make +command-line arguments +(see +.Sx What's in a Name ) , +the keep prevents +.Xr @g@nroff +from placing the flag and the argument on separate lines. +. +. +.Pp +Neither macro is callable or parsed. +. +. +.Pp +More work needs to be done on the keep macros; +specifically, +a +.Fl line +option should be added. +. +. +.Ss "Examples and Displays" +. +There are seven types of displays. +. +. +.Pp +.Bl -tag -width ".Li .D1" +.It Li .D1 +(This is D-one.) +Display one line of indented text. +This macro is parsed but not callable. +. +. +.Pp +.D1 Fl ldghfstru +. +. +.Pp +The above was produced by: +.Li ".D1 Fl ldghfstru" . +. +.It Li .Dl +(This is D-ell.) +Display one line of indented +.Em literal +text. +The +.Ql .Dl +example macro has been used throughout this file. +It allows the indentation (display) of one line of text. +Its default font is set to constant width (literal). +.Ql .Dl +is parsed but not callable. +. +. +.Pp +.Dl % ls \-ldg /usr/local/bin +. +. +.Pp +The above was produced by: +.Li ".Dl % ls \e\-ldg /usr/local/bin" . +. +.It Li .Bd +Begin display. +The +.Ql .Bd +display must be ended with the +.Ql .Ed +macro. +It has the following syntax: +. +. +.Pp +.Bd -ragged -compact +.Bl -tag -width ".Li .Bd" -offset indent +.It Li .Bd Xo +.Bro \-literal | \-filled | \-unfilled | \-ragged | \-centered Brc +.Oo \-offset Ao string Ac Oc Oo \-file Ao file name Ac Oc Oo \-compact Oc Xc +.El +.Ed +. +. +.Pp +.Bl -tag -width ".Fl file Ao Ar file name Ac " -compact +.It Fl ragged +Fill, but do not adjust the right margin (only left-justify). +. +.It Fl centered +Center lines between the current left and right margin. +. +Note that each single line is centered. +. +.It Fl unfilled +Do not fill; +break lines where their input lines are broken. +. +This can produce overlong lines without warning messages. +. +.It Fl filled +Display a filled block. +The block of text is formatted (i.e., the text is justified on both the left +and right side). +. +.It Fl literal +Display block with literal font (usually fixed-width). +. +Useful for source code or simple tabbed or spaced text. +. +.It Fl file Ao Ar file name Ac +The file whose name follows the +.Fl file +flag is read and displayed before any data enclosed with +.Ql .Bd +and +.Ql .Ed , +using the selected display type. +. +Any +.Xr @g@troff/ Ns Xr mdoc +commands in the file will be processed. +. +.It Fl offset Ao Ar string Ac +If +.Fl offset +is specified with one of the following strings, the string is interpreted to +indicate the level of indentation for the forthcoming block of text: +. +. +.Pp +.Bl -tag -width ".Ar indent-two" -compact +.It Ar left +Align block on the current left margin; this is the default mode of +.Ql .Bd . +.It Ar center +Supposedly center the block. +At this time unfortunately, the block merely gets left aligned about an +imaginary center margin. +.It Ar indent +Indent by one default indent value or tab. +The default indent value is also used for the +.Ql .D1 +and +.Ql .Dl +macros, so one is guaranteed the two types of displays will line up. +The indentation value is normally set to\~6n or about two thirds of an inch +(six constant width characters). +.It Ar indent\-two +Indent two times the default indent value. +.It Ar right +This +.Em left +aligns the block about two inches from the right side of the page. +This macro needs work and perhaps may never do the right thing within +.Xr @g@troff . +.El +. +. +.Pp +If +.Ao string Ac +is a valid numeric expression instead +.Pf ( Em with a scaling indicator other than +.Sq Em u ) , +use that value for indentation. +The most useful scaling indicators are +.Sq m +and +.Sq n , +specifying the so-called +.Em \&Em +and +.Em "En square" . +. +This is approximately the width of the letters +.Sq m +and +.Sq n +respectively +of the current font +(for +.Xr nroff +output, +both scaling indicators give the same values). +. +If +.Ao string Ac +isn't a numeric expression, it is tested whether it is an +.Xr mdoc +macro name, and the default offset value associated with this macro is used. +Finally, if all tests fail, +the width of +.Ao string Ac +(typeset with a fixed-width font) is taken as the offset. +.It Fl compact +Suppress insertion of vertical space before begin of display. +.El +. +.It Li .Ed +End display (takes no arguments). +.El +. +. +.Ss "Lists and Columns" +. +There are several types of lists which may be initiated with the +.Ql .Bl +begin-list macro. +. +Items within the list are specified with the +.Ql .It +item macro, +and each list must end with the +.Ql .El +macro. +. +Lists may be nested within themselves and within displays. +. +The use of columns inside of lists or lists inside of columns is +untested. +. +. +.Pp +In addition, +several list attributes may be specified such as the width of a tag, +the list offset, +and compactness +(blank lines between items allowed or disallowed). +. +Most of this document has been formatted with a tag style list +.Pf ( Fl tag ) . +. +. +.Pp +It has the following syntax forms: +. +. +.Pp +.Bd -ragged -compact +.Bl -tag -width ".Li .Bl" -offset indent -compact +.It Li .Bl Xo +.Bro \-hang | \-ohang | \-tag | \-diag | \-inset Brc +.Oo \-width Ao string Ac Oc +.Oo \-offset Ao string Ac Oc Oo \-compact Oc Xc +.It Li .Bl Xo +.No \-column Oo \-offset Ao string Ac Oc +.Ao string1 Ac Ao string2 Ac ... Xc +.It Li .Bl Xo +.Bro \-item | \-enum Oo \-nested Oc | \-bullet | \-hyphen | \-dash Brc +.Oo \-offset Ao string Ac Oc Oo \-compact Oc Xc +.El +.Ed +. +. +.Pp +And now a detailed description of the list types. +. +. +.Pp +.Bl -tag -width ".Fl column" -compact +.It Fl bullet +A bullet list. +. +.Bd -literal -offset indent +\&.Bl \-bullet \-offset indent \-compact +\&.It +Bullet one goes here. +\&.It +Bullet two here. +\&.El +.Ed +. +. +.Pp +Produces: +. +. +.Pp +.Bl -bullet -offset indent -compact +.It +Bullet one goes here. +.It +Bullet two here. +.El +. +. +.Pp +. +.It Fl dash No ( or Fl hyphen ) +A dash list. +. +.Bd -literal -offset indent +\&.Bl \-dash \-offset indent \-compact +\&.It +Dash one goes here. +\&.It +Dash two here. +\&.El +.Ed +. +. +.Pp +Produces: +. +. +.Pp +.Bl -dash -offset indent -compact +.It +Dash one goes here. +.It +Dash two here. +.El +. +. +.Pp +.It Fl enum +An enumerated list. +. +.Bd -literal -offset indent +\&.Bl \-enum \-offset indent \-compact +\&.It +Item one goes here. +\&.It +And item two here. +\&.El +.Ed +. +. +.Pp +The result: +. +. +.Pp +.Bl -enum -offset indent -compact +.It +Item one goes here. +.It +And item two here. +.El +. +. +.Pp +If you want to nest enumerated lists, +use the +.Fl nested +flag +(starting with the second-level list): +. +.Bd -literal -offset indent +\&.Bl \-enum \-offset indent \-compact +\&.It +Item one goes here +\&.Bl \-enum \-nested \-compact +\&.It +Item two goes here. +\&.It +And item three here. +\&.El +\&.It +And item four here. +\&.El +.Ed +. +. +.Pp +Result: +. +. +.Pp +.Bl -enum -offset indent -compact +.It +Item one goes here. +.Bl -enum -nested -compact +.It +Item two goes here. +.It +And item three here. +.El +.It +And item four here. +.El +. +. +.Pp +. +.It Fl item +A list of type +.Fl item +without list markers. +. +.Bd -literal -offset indent +\&.Bl \-item \-offset indent +\&.It +Item one goes here. +Item one goes here. +Item one goes here. +\&.It +Item two here. +Item two here. +Item two here. +\&.El +.Ed +. +. +.Pp +Produces: +. +. +.Pp +.Bl -item -offset indent +.It +Item one goes here. +Item one goes here. +Item one goes here. +.It +Item two here. +Item two here. +Item two here. +.El +. +. +.Pp +.It Fl tag +A list with tags. +Use +.Fl width +to specify the tag width. +. +. +.Pp +.Bl -tag -width "PPID" -compact -offset indent +.It SL +sleep time of the process (seconds blocked) +.It PAGEIN +number of disk I/O operations resulting from references by the process +to pages not loaded in core. +.It UID +numerical user-id of process owner +.It PPID +numerical id of parent of process priority +(non-positive when in non-interruptible wait) +.El +. +. +.Pp +The raw text: +. +.Bd -literal -offset indent +\&.Bl \-tag \-width "PPID" \-compact \-offset indent +\&.It SL +sleep time of the process (seconds blocked) +\&.It PAGEIN +number of disk I/O operations resulting from references +by the process to pages not loaded in core. +\&.It UID +numerical user\-id of process owner +\&.It PPID +numerical id of parent of process priority +(non\-positive when in non\-interruptible wait) +\&.El +.Ed +. +. +.Pp +.It Fl diag +Diag lists create section four diagnostic lists and are similar to inset +lists except callable macros are ignored. +The +.Fl width +flag is not meaningful in this context. +. +. +.Pp +Example: +. +.Bd -literal -offset indent +\&.Bl \-diag +\&.It You can't use Sy here. +The message says all. +\&.El +.Ed +. +. +.Pp +produces +. +.Bl -diag +.It You can't use Sy here. +The message says all. +.El +. +. +.Pp +.It Fl hang +A list with hanging tags. +. +.Bl -hang -offset indent +.It Em Hanged +labels appear similar to tagged lists when the +label is smaller than the label width. +.It Em Longer hanged list labels +blend into the paragraph unlike +tagged paragraph labels. +.El +. +. +.Pp +And the unformatted text which created it: +. +.Bd -literal -offset indent +\&.Bl \-hang \-offset indent +\&.It Em Hanged +labels appear similar to tagged lists when the +label is smaller than the label width. +\&.It Em Longer hanged list labels +blend into the paragraph unlike +tagged paragraph labels. +\&.El +.Ed +. +. +.Pp +.It Fl ohang +Lists with overhanging tags do not use indentation for the items; +tags are written to a separate line. +. +. +.Pp +.Bl -ohang -offset indent +.It Sy SL +sleep time of the process (seconds blocked) +.It Sy PAGEIN +number of disk I/O operations resulting from references by the process +to pages not loaded in core. +.It Sy UID +numerical user-id of process owner +.It Sy PPID +numerical id of parent of process priority +(non-positive when in non-interruptible wait) +.El +. +. +.Pp +The raw text: +. +.Bd -literal -offset indent +\&.Bl \-ohang \-offset indent +\&.It Sy SL +sleep time of the process (seconds blocked) +\&.It Sy PAGEIN +number of disk I/O operations resulting from references +by the process to pages not loaded in core. +\&.It Sy UID +numerical user\-id of process owner +\&.It Sy PPID +numerical id of parent of process priority +(non\-positive when in non\-interruptible wait) +\&.El +.Ed +. +. +.Pp +.It Fl inset +Here is an example of inset labels: +.Bl -inset -offset indent +.It Em Tag +The tagged list (also called a tagged paragraph) +is the most common type of list used in the +Berkeley manuals. +Use a +.Fl width +attribute as described below. +.It Em Diag +Diag lists create section four diagnostic lists +and are similar to inset lists except callable +macros are ignored. +.It Em Hang +Hanged labels are a matter of taste. +.It Em Ohang +Overhanging labels are nice when space is constrained. +.It Em Inset +Inset labels are useful for controlling blocks of +paragraphs and are valuable for converting +.Xr mdoc +manuals to other formats. +.El +. +. +.Pp +Here is the source text which produced the above example: +. +.Bd -literal -offset indent +\&.Bl \-inset \-offset indent +\&.It Em Tag +The tagged list (also called a tagged paragraph) +is the most common type of list used in the +Berkeley manuals. +\&.It Em Diag +Diag lists create section four diagnostic lists +and are similar to inset lists except callable +macros are ignored. +\&.It Em Hang +Hanged labels are a matter of taste. +\&.It Em Ohang +Overhanging labels are nice when space is constrained. +\&.It Em Inset +Inset labels are useful for controlling blocks of +paragraphs and are valuable for converting +\&.Xr mdoc +manuals to other formats. +\&.El +.Ed +. +. +.Pp +. +.It Fl column +This list type generates multiple columns. +The number of columns and the width of each column is determined by the +arguments to the +.Fl column +list, +.Aq Ar string1 , +.Aq Ar string2 , +etc. +If +.Aq Ar stringN +starts with a +.Ql .\& +(dot) immediately followed by a valid +.Xr mdoc +macro name, interpret +.Aq Ar stringN +and use the width of the result. +Otherwise, the width of +.Aq Ar stringN +(typeset with a fixed-width font) is taken as the +.Ar N Ns th +column width. +. +. +.Pp +Each +.Ql .It +argument is parsed to make a row, each column within the row is a separate +argument separated by a tab or the +.Ql .Ta +macro. +. +. +.Pp +The table: +. +.Bl -column -offset indent ".Sy String" ".Sy Nroff" ".Sy Troff" +.It Sy String Ta Sy Nroff Ta Sy Troff +.It Li <= Ta <= Ta \*(<= +.It Li >= Ta >= Ta \*(>= +.El +. +. +.Pp +was produced by: +. +.Bd -literal +\&.Bl \-column \-offset indent ".Sy String" ".Sy Nroff" ".Sy Troff" +\&.It Sy String Ta Sy Nroff Ta Sy Troff +\&.It Li <= Ta <= Ta \e*(<= +\&.It Li >= Ta >= Ta \e*(>= +\&.El +.Ed +. +. +.Pp +Don't abuse this list type! +. +For more complicated cases it might be far better and easier to use +.Xr @g@tbl @MAN1EXT@ , +the table preprocessor. +.El +. +. +.Pp +Other keywords: +. +.Bl -tag -width ".Fl indent Ao Ar string Ac" +.It Fl width Ao Ar string Ac +If +.Aq Ar string +starts with a +.Ql .\& +(dot) immediately followed by a valid +.Xr mdoc +macro name, interpret +.Aq Ar string +and use the width of the result. +. +Almost all lists in this document use this option. +. +. +.Pp +Example: +. +.Bd -literal -offset indent +\&.Bl \-tag \-width ".Fl test Ao Ar string Ac" +\&.It Fl test Ao Ar string Ac +This is a longer sentence to show how the +\&.Fl width +flag works in combination with a tag list. +\&.El +.Ed +. +. +.Pp +gives: +. +.Bl -tag -width ".Fl test Ao Ar string Ac" +.It Fl test Ao Ar string Ac +This is a longer sentence to show how the +.Fl width +flag works in combination with a tag list. +.El +. +. +.Pp +(Note that the current state of +.Xr mdoc +is saved before +.Aq Ar string +is interpreted; +afterwards, +all variables are restored again. +. +However, +boxes +(used for enclosures) +can't be saved in +.Tn GNU +.Xr @g@troff @MAN1EXT@ ; +as a consequence, +arguments must always be +.Em balanced +to avoid nasty errors. +. +For example, +do not write +.Ql ".Ao Ar string" +but +.Ql ".Ao Ar string Xc" +instead if you really need only an opening angle bracket.) +. +. +.Pp +Otherwise, +if +.Aq Ar string +is a valid numeric expression +.Em ( with a scaling indicator other than +.Sq Em u ) , +use that value for indentation. +The most useful scaling indicators are +.Sq m +and +.Sq n , +specifying the so-called +.Em \&Em +and +.Em "En square" . +This is approximately the width of the letters +.Sq m +and +.Sq n +respectively +of the current font +(for +.Xr @g@nroff +output, +both scaling indicators give the same values). +. +If +.Aq Ar string +isn't a numeric expression, it is tested whether it is an +.Xr mdoc +macro name, and the default width value associated with this macro is used. +Finally, if all tests fail, +the width of +.Aq Ar string +(typeset with a fixed-width font) is taken as the width. +. +. +.Pp +If a width is not specified for the tag list type, +.Sq 6n +is used. +.It Fl offset Ao Ar string Ac +If +.Aq Ar string +is +.Ar indent , +a default indent value (normally set to\~6n, +similar to the value used in +.Ql .Dl +or +.Ql .Bd ) +is used. +If +.Aq Ar string +is a valid numeric expression instead +.Pf ( Em with a scaling indicator other than +.Sq Em u ) , +use that value for indentation. +The most useful scaling indicators are +.Sq m +and +.Sq n , +specifying the so-called +.Em \&Em +and +.Em "En square" . +. +This is approximately the width of the letters +.Sq m +and +.Sq n +respectively +of the current font +(for +.Xr nroff +output, +both scaling indicators give the same values). +. +If +.Aq Ar string +isn't a numeric expression, it is tested whether it is an +.Xr mdoc +macro name, and the default offset value associated with this macro is used. +Finally, if all tests fail, +the width of +.Aq Ar string +(typeset with a fixed-width font) is taken as the offset. +.It Fl compact +Suppress insertion of vertical space before the list and between list items. +.El +. +. +.Sh "Miscellaneous macros" +. +A double handful of macros fit only uncomfortably into one of the above +sections. +. +Of these, +we couldn't find attested examples for +.Ql \&Me +or +.Ql \&Ot . +. +They are documented here for completeness\[em]if you know their proper +usage, +please send a mail to +.Mt groff@gnu.org +and include a specimen with its provenance. +. +. +.Bl -tag -width ".Li .Bt" +.It Li .Bt +formats boilerplate text. +. +.\" XXX: .Bt gets parsed (i.e., called) _and_ measured even _with_ a +.\" leading dot. See Savannah #63672. +.Bl -tag -width \&.Bt -offset indent +.It Li .Bt +\[->] +.Bt +.El +. +. +.Pp +It is neither callable nor parsed and takes no arguments. +. +Its default width is 6n. +. +. +.It Li .Fr +is an obsolete means of specifying a function return value. +. +. +.Pp +.D1 Usage: Pf . Ic \&Fr Ar return-value No ... +. +. +.Pp +.Ql \&Fr +allows a break right before the return value +(usually a single digit) +which is bad typographical behaviour. +. +Instead, +set the return value with the rest of the code, +using +.Ql \[rs]\[ti] +to tie the return value to the previous word. +. +. +.Pp +Its default width is 12n. +. +. +.It Li .Hf +Inlines the contents of a (header) file into the document. +. +. +.Pp +.D1 Usage: Pf . Ic \&Hf Ar file +. +. +.Pp +It first prints +.Ql File: +followed by the file name, +then the contents of +.Ar file . +. +It is neither callable nor parsed. +. +. +.It Li .Lk +Embed hyperlink. +. +. +.Pp +.D1 Usage: Pf . Ic \&Lk Ar uri Op Ar link-text +. +. +.Pp +Its default width is 6n. +. +. +.It Li .Me +Usage unknown. +. +The +.Xr mdoc +sources describe it as a macro for +.Dq "menu entries" . +. +. +.Pp +Its default width is 6n. +. +. +.It Li .Mt +Embed email address. +. +. +.Pp +.D1 Usage: Pf . Ic \&Mt Ar email-address +. +. +.Pp +Its default width is 6n. +. +. +.It Li .Ot +Usage unknown. +The +.Xr mdoc +sources describe it as +.Dq "old function type (fortran)" . +. +. +.It Li .Sm +Manipulate or toggle argument-spacing mode. +. +. +.Pp +.D1 Usage: Pf . Ic \&Sm Oo Li on | Li off Oc ... +. +. +.Pp +If argument-spacing mode is off, +no spaces between macro arguments are inserted. +. +If called without a parameter +(or if the next parameter is neither +.Ql on +nor +.Ql off ) , +.Ql \&Sm +toggles argument-spacing mode. +. +. +.Pp +Its default width is 8n. +.\" XXX: The package demands it, but how is that meaningful? +. +. +.It Li .Ud +formats boilerplate text. +. +.\" XXX: .Ud gets parsed (i.e., called) _and_ measured even _with_ a +.\" leading dot. See Savannah #63672. +.Bl -tag -width \&.Ud -offset indent +.It Li .Ud +\[->] +.Ud +.El +. +. +.Pp +It is neither callable nor parsed and takes no arguments. +. +Its default width is 8n. +.El +. +. +.Sh "Predefined strings" +. +The following strings are predefined for compatibility with legacy +.Xr mdoc +documents. +. +Contemporary ones should use the alternatives shown in the +.Dq Prefer +column below. +. +See +.Xr groff_char @MAN7EXT@ +for a full discussion of these special character escape sequences. +. +. +.Pp +.\" Note: This table pushes 80-column ASCII and Latin-1 terminals to +.\" the limits of their capacity. Observe the spacing parameters of the +.\" 2nd and 3rd columns; we had to steal a character cell from each (the +.\" default is 3) because in the UCS column, the word "infinity" gets +.\" written out in full, which in turn pushes the >= and Ge rows past +.\" the 78n norm. Update with caution. See Savannah #59424. +.TS +Cb Lb2 Lb2 Lb Lb Lb +Lf(CR) L2 L2 L Lf(CR) L. +String 7-bit 8-bit UCS Prefer Meaning +\[rs]*(<= <= <= \*[<=] \[rs](<= less than or equal to +\[rs]*(>= >= >= \*[>=] \[rs](>= greater than or equal to +\[rs]*(Rq " " \*[Rq] \[rs](rq right double quote +\[rs]*(Lq " " \*[Lq] \[rs](lq left double quote +\[rs]*(ua \[ha] \[ha] \*[ua] \[rs](ua vertical arrow up +\[rs]*(aa \[aq] \' \*[aa] \[rs](aa acute accent +\[rs]*(ga \` \` \*[ga] \[rs](ga grave accent +\[rs]*(q \&" \&" \*[q] \[rs](dq neutral double quote +\[rs]*(Pi pi pi \*[Pi] \[rs](*p lowercase pi +\[rs]*(Ne != != \*[Ne] \[rs](!= not equals +\[rs]*(Le <= <= \*[Le] \[rs](<= less than or equal to +\[rs]*(Ge >= >= \*[Ge] \[rs](>= greater than or equal to +\[rs]*(Lt < < \*[Lt] < less than +\[rs]*(Gt > > \*[Gt] > greater than +\[rs]*(Pm +\- \[+-] \*[Pm] \[rs](+\- plus or minus +\[rs]*(If infinity infinity \*[If] \[rs](if infinity +\[rs]*(Am \*[Am] \*[Am] \*[Am] & ampersand +\[rs]*(Na \*[Na] \*[Na] \*[Na] NaN not a number +\[rs]*(Ba \*[Ba] \*[Ba] \*[Ba] | bar +.TE +. +. +.Pp +Some column headings are shorthand for standardized character encodings; +\[lq]7-bit\[rq] for ISO 646:1991 IRV (US-ASCII), +\[lq]8-bit\[rq] for ISO 8859-1 (Latin-1) and IBM code page 1047, +and +\[lq]UCS\[rq] for ISO 10646 (Unicode character set). +. +Historically, \" (\[ti]1989) +.Xr mdoc +configured the string definitions to fit the capabilities expected of +the output device. +. +Old typesetters \" like the C/A/T +lacked directional double quotes, +producing repeated directional single quotes +\[oq]\[oq]like this\[cq]\[cq]; +early versions of +.Xr mdoc +in fact defined the +.Ql Lq +and +.Ql Rq +strings this way. \" thanks to Ingo Schwarze for the research +. +Nowadays, +output drivers \" technically, their macro files or font descriptions +take on the responsibility of glyph substitution, +as they possess relevant knowledge of their available repertoires. +. +. +.Sh Diagnostics +. +The debugging macro +.Ql .Db +offered by +previous versions of +.Xr mdoc +is unavailable in +.Tn GNU +.Xr @g@troff @MAN1EXT@ +since the latter provides better facilities to check parameters; +additionally, +.Xr "groff mdoc" +implements many error and warning messages, +making the package more robust and more verbose. +. +. +.Pp +The remaining debugging macro is +.Ql .Rd , +which dumps the package's global register and string contents to the +standard error stream. +. +A normal user will never need it. +. +. +.Sh Options +. +The following +.Xr groff +options set registers +(with +.Fl r ) +and strings +(with +.Fl d ) +recognized and used by the +.Xr mdoc +macro package. +. +To ensure rendering consistent with output device capabilities and +reader preferences, +man pages should never manipulate them. +. +. +.Pp +Setting string +.Ql AD +configures the adjustment mode for most formatted text. +. +Typical values are +.Ql b +for adjustment to both margins +(the default), +or +.Ql l +for left alignment +(ragged right margin). +. +Any valid argument to +.Xr groff Ns 's +.Ql ad +request may be used. +. +See +.Xr groff @MAN7EXT@ +for less-common choices. +. +.Dl groff \-Tutf8 \-dAD=l \-mdoc groff_mdoc.7 | less \-R +. +. +.Pp +Setting register +.Ql C +to\~1 numbers output pages consecutively, +rather than resetting the page number to\~1 +(or the value of register +.Ql P ) +with each new +.Xr mdoc +document. +. +. +.Pp +By default, +the package inhibits page breaks, +headers, +and footers in the midst of the document text if it is being displayed +with a terminal device such as +.Sq latin1 +or +.Sq utf8 , +to enable more efficient viewing of the page. +. +This behavior can be changed to format the page as if for 66-line +Teletype output by setting the continuous rendering register +.Ql cR +to zero while calling +.Xr groff @MAN1EXT@ . +. +.Dl groff \-Tlatin1 \-rcR=0 \-mdoc foo.man > foo.txt +. +On HTML devices, +it cannot be disabled. +. +. +.Pp +Section headings +(defined with +.Ql .Sh ) +and page titles in headers +(defined with +.Ql .Dt ) +can be presented in full capitals by setting the registers +.Ql CS +and +.Ql CT , +respectively, +to 1. +. +These transformations are off by default because they discard case +distinction information. +. +. +.Pp +Setting register +.Ql D +to\~1 enables double-sided page layout, +which is only distinct when not continuously rendering. +. +It places the page number at the bottom right on odd-numbered (recto) +pages, +and at the bottom left on even-numbered (verso) pages, +swapping places with the arguments to +.Ql .Os . +. +.Dl groff \-Tps \-rD1 \-mdoc foo.man > foo.ps +. +. +.Pp +The value of the +.Ql FT +register determines the footer's distance from the page bottom; +this amount is always negative and should specify a scaling unit. +. +At one half-inch above this location, +the page text is broken before writing the footer. +. +It is ignored if continuous rendering is enabled. +. +The default is \-0.5i. +. +. +.Pp +The +.Ql HF +string sets +the font used for section and subsection headings; +the default is +.Ql B +(bold style of the default family). +. +Any valid argument to +.Xr groff Ns 's +.Ql ft +request may be used. +. +. +.Pp +Normally, +automatic hyphenation is enabled using a mode appropriate to the +.Xr groff +locale; +see section \[lq]Localization\[lq] of +.Xr groff @MAN7EXT@ . +. +It can be disabled by setting the +.Ql HY +register to zero. +. +.Dl groff \-Tutf8 \-rHY=0 \-mdoc foo.man | less \-R +. +. +.Pp +The paragraph and subsection heading indentation amounts can be changed +by setting the registers +.Ql IN +and +.Ql SN . +. +.Dl groff \-Tutf8 \-rIN=5n \-rSN=2n \-mdoc foo.man | less \-R +. +The default paragraph indentation is 7.2n on typesetters and 7n on +terminals. +. +The default subsection heading indentation amount is 3n; +section headings are set with an indentation of zero. +. +. +.Pp +The line and title lengths can be changed by setting the registers +.Ql LL +and +.Ql LT , +respectively: +. +.Dl groff \-Tutf8 \-rLL=100n \-rLT=100n \-mdoc foo.man | less \-R +. +If not set, +both registers default to 78n for terminal devices and 6.5i otherwise. +. +. +.Pp +Setting the +.Ql P +register starts enumeration of pages at its value. +. +The default is\~1. +. +. +.Pp +To change the document font size to 11p or 12p, +set register +.Ql S +accordingly: +. +.Dl groff \-Tdvi \-rS11 \-mdoc foo.man > foo.dvi +. +Register +.Ql S +is ignored when formatting for terminal devices. +. +. +.Pp +Setting the +.Ql X +register to a page number +.Ar p +numbers its successors as +.Ar p Ns Li a , +.Ar p Ns Li b , +.Ar p Ns Li c , +and so forth. +. +The register tracking the suffixed page letter uses format +.Ql a +(see the +.Ql af +request in +.Xr groff @MAN7EXT@ ) . +. +. +.br +.ne 4v +.Sh Files +. +.Bl -tag +.It Pa @MACRODIR@/\:andoc\:.tmac +This brief +.Xr groff +program detects whether the +.Xr man +or +.Xr mdoc +macro package is being used by a document and loads the correct macro +definitions, +taking advantage of the fact that pages using them must call +.Li TH +or +.Li Dd , +respectively, +before any other macros. +. +A user typing, +for example, +.Dl groff \-mandoc page.1 +need not know which package the file +.Pa page.1 +uses. +. +Multiple man pages, +in either format, +can be handled; +.Pa \%andoc\:.tmac +reloads each macro package as necessary. +. +. +.It Pa @MACRODIR@/\:doc\:.tmac +implements the bulk of the +.Xr groff Xr mdoc +package and loads further components as needed from the +.Pa mdoc +subdirectory. +. +. +.It Pa @MACRODIR@/\:mdoc\:.tmac +is a wrapper that loads +.Pa doc.tmac . +. +. +.It Pa @MACRODIR@/\:mdoc/\:doc\-common +defines macros, +registers, +and strings +concerned with the production of formatted output. +.\" XXX: This is a weak explanation. The boundary between doc.tmac's +.\" concerns and doc-common's is not at all clear to GBR. Should some +.\" of these files be merged? +. +It includes strings of the form +.Ql doc\-volume\-ds\- Ns Ar X +and +.Ql doc\-volume\-as\- Ns Ar X +for manual section titles and architecture identifiers, +respectively, +where +.Ar X +is an argument recognized by +.Pf . Ic \&Dt . +. +. +.It Pa @MACRODIR@/\:mdoc/\:doc\-nroff +defines parameters appropriate for rendering to terminal devices. +. +. +.It Pa @MACRODIR@/\:mdoc/\:doc\-ditroff +defines parameters appropriate for rendering to typesetter devices. +. +. +.It Pa @MACRODIR@/\:mdoc/\:doc\-syms +defines many strings and macros that interpolate formatted text, +such as names of operating system releases, +*BSD libraries, +and standards documents. +. +The string names are of the form +.Ql doc\-str\- Ns Ar O Ns Li \- Ns Ar V , +.Ql doc\-str\-St Ns Li \-\- Ns Ar S Ns Li \- Ns Ar I +(observe the double dashes), +or +.Ql doc\-str\-Lb\- Ns Ar L , +where +.Ar O +is one of the operating system macros from section +.Sx "General text domain" +above, +.Ar V +is an encoding of an operating system release +(sometimes omitted along with the +.Ql \- +preceding it), +.Ar S +an identifier for a standards body or committee, +.Ar I +one for an issue of a standard promulgated by +.Ar S , +and +.Ar L +a keyword identifying a *BSD library. +. +. +.It Pa @LOCALMACRODIR@/\:mdoc\:.local +This file houses local additions and customizations to the package. +. +It can be empty. +.El +. +. +.Sh "See also" +. +The +.Lk https://mandoc.bsd.lv/ mandoc +project maintains an independent implementation of the +.Xr mdoc +language and a renderer that directly parses its markup as well as that +of +.Xr man . +. +. +.Pp +.Xr groff @MAN1EXT@ , +.Xr man 1 , +.Xr @g@troff @MAN1EXT@ , +.Xr groff_man @MAN7EXT@ , +.Xr mdoc 7 +. +. +.Sh Bugs +. +Section 3f has not been added to the header routines. +. +. +.Pp +.Ql .Fn +needs to have a check to prevent splitting up the line if its length is +too short. +. +Occasionally it separates the last parenthesis, +and sometimes looks ridiculous if output lines are being filled. +. +. +.Pp +The list and display macros do not do any keeps and certainly should be +able to. +. +. +.Pp +As of +.Xr groff +1.23, +.Ql \&Tn +no longer changes the type size; +this functionality may return in the next release. +.\" Note what happens if the parameter list overlaps a newline +.\" boundary. +.\" to make sure a line boundary is crossed: +.\" .Bd -literal +.\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[] +.\" .Ed +.\" . +.\" . +.\" .Pp +.\" produces, nudge nudge, +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , +.\" nudge +.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] . +.\" . +.\" . +.\" .Pp +.\" If double quotes are used, for example: +.\" .Bd -literal +.\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q +.\" .Ed +.\" . +.\" . +.\" .Pp +.\" produces, nudge nudge, +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , +.\" nudge +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , +.\" nudge +.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" . +.\" . +.\" . +.\" .Pp +.\" Not a pretty sight... +.\" In a paragraph, a long parameter containing unpaddable spaces as +.\" in the former example will cause +.\" .Xr @g@troff +.\" to break the line and spread +.\" the remaining words out. +.\" The latter example will adjust nicely to +.\" justified margins, but may break in between an argument and its +.\" declaration. +.\" In +.\" .Xr @g@nroff +.\" the right margin is normally ragged and the problem is not as +.\" severe. +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_mdoc_7_man_C] +.do rr *groff_groff_mdoc_7_man_C +. +. +.\" Local Variables: +.\" mode: nroff +.\" fill-column: 72 +.\" End: +.\" vim: set filetype=groff textwidth=72: |