=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.1 retrieving revision 1.73 diff -u -p -r1.1 -r1.73 --- mandoc/mdoc.7 2009/03/13 07:46:10 1.1 +++ mandoc/mdoc.7 2009/11/02 11:39:40 1.73 @@ -1,537 +1,1929 @@ -.\" $Id: mdoc.7,v 1.1 2009/03/13 07:46:10 kristaps Exp $ +.\" $Id: mdoc.7,v 1.73 2009/11/02 11:39:40 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the -.\" above copyright notice and this permission notice appear in all -.\" copies. +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. .\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL -.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE -.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL -.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR -.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER -.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR -.\" PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: March 13 2009 $ -.Dt mdoc 7 +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: November 2 2009 $ +.Dt MDOC 7 .Os -.\" SECTION +. +. .Sh NAME .Nm mdoc -.Nd mdoc macro reference -.\" SECTION +.Nd mdoc language reference +. +. .Sh DESCRIPTION The .Nm mdoc -language is used to format -.Bx +language is used to format +.Bx .Ux -manuals. An +manuals. In this reference document, we describe its syntax, structure, +and usage. Our reference implementation is +.Xr mandoc 1 . +The +.Sx COMPATIBILITY +section describes compatibility with +.Xr groff 1 . +. +.Pp +An .Nm document follows simple rules: lines beginning with the control character .Sq \. are parsed for macros. Other lines are interpreted within the scope of -prior macros. Macros are either two or three characters in length. -.\" SECTION -.Sh CHARACTER ENCODING +prior macros: +.Bd -literal -offset indent +\&.Sh Macro lines change control state. +Other lines are interpreted within the current state. +.Ed +. +. +.Sh LANGUAGE SYNTAX .Nm -documents may contain only printable alphanumeric characters, the space -character -.Sq \ , -and, in certain circumstances, the tab character -.Sq \et . -All manuals must have -.Sq \en -line termination. -.\" SUB-SECTION -.Ss Special Characters -Within a macro line, the following characters are special: -.\" PARAGRAPH +documents may contain only graphable 7-bit ASCII characters, the space +character, and, in certain circumstances, the tab character. All +manuals must have +.Ux +line terminators. +. +. +.Ss Comments +Text following a +.Sq \e" , +whether in a macro or free-form text line, is ignored to the end of +line. A macro line with only a control character and comment escape, +.Sq \&.\e" , +is also ignored. Macro lines with only a control charater and optionally +whitespace are stripped from input. +. +. +.Ss Reserved Characters +Within a macro line, the following characters are reserved: .Pp -.Bl -tag -width Ds -offset XXXX -compact +.Bl -tag -width Ds -offset indent -compact .It \&. -period +.Pq period .It \&, -comma +.Pq comma .It \&: -colon +.Pq colon .It \&; -semicolon +.Pq semicolon .It \&( -left-parenthesis +.Pq left-parenthesis .It \&) -right-parenthesis +.Pq right-parenthesis .It \&[ -left-bracket +.Pq left-bracket .It \&] -right-bracket +.Pq right-bracket .It \&? -question +.Pq question .It \&! -exclmamation +.Pq exclamation +.It \&| +.Pq vertical bar .El +. .Pp -Use of these characters must either be escaped with a non-breaking space +Use of reserved characters is described in +.Sx MACRO SYNTAX . +For general use in macro lines, these characters must either be escaped +with a non-breaking space .Pq Sq \e& -or, if applicable, an appropriate escape-sequence used. -.\" SUB-SECTION +or, if applicable, an appropriate escape sequence used. +. +. .Ss Special Characters -Special character sequences begin with the escape character -.Sq \\ -and followed by either an open-parenthesis +Special characters may occur in both macro and free-form lines. +Sequences begin with the escape character +.Sq \e +followed by either an open-parenthesis .Sq \&( for two-character sequences; an open-bracket .Sq \&[ for n-character sequences (terminated at a close-bracket .Sq \&] ) ; -or a single one-character sequence. +or a single one-character sequence. See +.Xr mandoc_char 7 +for a complete list. Examples include +.Sq \e(em +.Pq em-dash +and +.Sq \ee +.Pq back-slash . +. +. +.Ss Text Decoration +Terms may be text-decorated using the +.Sq \ef +escape followed by an indicator: B (bold), I, (italic), or P and R +(Roman, or reset). This form is not recommended for +.Nm , +which encourages semantic, not presentation, annotation. +. +. +.Ss Predefined Strings +Historically, +.Xr groff 1 +also defined a set of package-specific +.Dq predefined strings , +which, like +.Sx Special Characters , +demark special output characters and strings by way of input codes. +Predefined strings are escaped with the slash-asterisk, +.Sq \e* : +single-character +.Sq \e*X , +two-character +.Sq \e*(XX , +and N-character +.Sq \e*[N] . +See +.Xr mandoc_char 7 +for a complete list. Examples include +.Sq \e*(Am +.Pq ampersand +and +.Sq \e*(Ba +.Pq vertical bar . +. +. +.Ss Whitespace +In non-literal free-form lines, consecutive blocks of whitespace are +pruned from input and added later in the output filter, if applicable: +.Bd -literal -offset indent +These spaces are pruned from input. +\&.Bd \-literal +These are not. +\&.Ed +.Ed +. .Pp -Characters may alternatively be escaped by a slash-asterisk, -.Sq \\* , -with the same combinations as described above. This form, however, is -deprecated. The following is a table of all available escapes, arranged -by classification. +In macro lines, whitespace delimits arguments and is discarded. If +arguments are quoted, whitespace within the quotes is retained. +. .Pp -Grammatic: +Blank lines are only permitted within literal contexts, as are lines +containing only whitespace. Tab characters are only acceptable when +delimiting +.Sq \&Bl \-column +or when in a literal context. +. +. +.Ss Quotation +Macro arguments may be quoted with a double-quote to group +space-delimited terms or to retain blocks of whitespace. A quoted +argument begins with a double-quote preceded by whitespace. The next +double-quote not pair-wise adjacent to another double-quote terminates +the literal, regardless of surrounding whitespace. +. .Pp -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(em -.Pq em-dash -.It \\(en -.Pq en-dash -.It \e- -.Pq hyphen -.It \\\\ -.Pq back-slash -.It \e' -.Pq apostrophe -.It \e` -.Pq back-tick -.It \\ -.Pq space -.It \\. -.Pq period -.El -.\" PARAGRAPH +This produces tokens +.Sq a" , +.Sq b c , +.Sq de , +and +.Sq fg" . +Note that any quoted term, be it argument or macro, is indiscriminately +considered literal text. Thus, the following produces +.Sq \&Em a : +.Bd -literal -offset indent +\&.Em "Em a" +.Ed +. .Pp -Enclosures: +In free-form mode, quotes are regarded as opaque text. +. +.Ss Dates +There are several macros in +.Nm +that require a date argument. The canonical form for dates is the +American format: .Pp -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(rC -.Pq right brace -.It \\(lC -.Pq left brace -.It \\(ra -.Pq right angle -.It \\(la -.Pq left angle -.It \\(rB -.Pq right bracket -.It \\(lB -.Pq left bracket -.It \\q -.Pq double-quote -.It \\(lq -.Pq left double-quote -.It \\(Lq -.Pq left double-quote, deprecated -.It \\(rq -.Pq right double-quote -.It \\(Rq -.Pq right double-quote, deprecated -.It \\(oq -.Pq left single-quote -.It \\(aq -.Pq right single-quote -.El -.\" PARAGRAPH +.D1 Cm Month Day , Year .Pp -Indicatives: +The +.Cm Day +value is an optionally zero-padded numeral. The +.Cm Month +value is the full month name. The +.Cm Year +value is the full four-digit year. .Pp -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(<- -.Pq left arrow -.It \\(-> -.Pq right arrow -.It \\(ua -.Pq up arrow -.It \\(da -.Pq down arrow -.El -.\" PARAGRAPH +Reduced form dates are broken-down canonical form dates: .Pp -Mathematical: +.D1 Cm Month , Year +.D1 Cm Year .Pp -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(Gt -.Pq greater-than, deprecated -.It \\(Lt -.Pq less-than, deprecated -.It \\(<= -.Pq less-than-equal -.It \\(Le -.Pq less-than-equal, deprecated -.It \\(>= -.Pq greater-than-equal -.It \\(Ge -.Pq greater-than-equal -.It \\(== -.Pq equal -.It \\(!= -.Pq not equal -.It \\(Ne -.Pq not equal, deprecated -.It \\(if -.Pq infinity -.It \\(If -.Pq infinity, deprecated -.It \\(na -.Pq NaN , an extension -.It \\(Na -.Pq NaN, deprecated -.It \\(+- -.Pq plus-minus -.It \\(Pm -.Pq plus-minus, deprecated -.It \\(** -.Pq asterisk +Some examples of valid dates follow: +.Pp +.D1 "May, 2009" Pq reduced form +.D1 "2009" Pq reduced form +.D1 "May 20, 2009" Pq canonical form +. +.Ss Scaling Widths +Many macros support scaled widths for their arguments, such as +stipulating a two-inch list indentation with the following: +.Bd -literal -offset indent +\&.Bl -tag -width 2i +.Ed +. +.Pp +The syntax for scaled widths is +.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , +where a decimal must be preceded or proceeded by at least one digit. +Negative numbers, while accepted, are truncated to zero. The following +scaling units are accepted: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It c +centimetre +.It i +inch +.It P +pica (~1/6 inch) +.It p +point (~1/72 inch) +.It f +synonym for +.Sq u +.It v +default vertical span +.It m +width of rendered +.Sq m +.Pq em +character +.It n +width of rendered +.Sq n +.Pq en +character +.It u +default horizontal span +.It M +mini-em (~1/100 em) .El -.\" PARAGRAPH .Pp -Diacritics: +Using anything other than +.Sq m , +.Sq n , +.Sq u , +or +.Sq v +is necessarily non-portable across output media. See +.Sx COMPATIBILITY . +. +. +.Sh MANUAL STRUCTURE +A well-formed +.Nm +document consists of a document prologue followed by one or more +sections. .Pp -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(ga -.Pq accent grave -.It \\(aa -.Pq accent accute +The prologue, which consists of (in order) the +.Sx \&Dd , +.Sx \&Dt , +and +.Sx \&Os +macros, is required for every document. +.Pp +The first section (sections are denoted by +.Sx \&Sh ) +must be the NAME section, consisting of at least one +.Sx \&Nm +followed by +.Sx \&Nd . +.Pp +Following that, convention dictates specifying at least the SYNOPSIS and +DESCRIPTION sections, although this varies between manual sections. +.Pp +The following is a well-formed skeleton +.Nm +file: +.Bd -literal -offset indent +\&.Dd $\&Mdocdate$ +\&.Dt mdoc 7 +\&.Os +\&. +\&.Sh NAME +\&.Nm foo +\&.Nd a description goes here +\&.\e\*q The next is for sections 2 & 3 only. +\&.\e\*q .Sh LIBRARY +\&. +\&.Sh SYNOPSIS +\&.Nm foo +\&.Op Fl options +\&.Ar +\&. +\&.Sh DESCRIPTION +The +\&.Nm +utility processes files ... +\&.\e\*q .Sh IMPLEMENTATION NOTES +\&.\e\*q The next is for sections 1 & 8 only. +\&.\e\*q .Sh EXIT STATUS +\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q .Sh RETURN VALUES +\&.\e\*q The next is for sections 1, 6, 7, & 8 only. +\&.\e\*q .Sh ENVIRONMENT +\&.\e\*q .Sh FILES +\&.\e\*q .Sh EXAMPLES +\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. +\&.\e\*q .Sh DIAGNOSTICS +\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q .Sh ERRORS +\&.\e\*q .Sh SEE ALSO +\&.\e\*q .Xr foobar 1 +\&.\e\*q .Sh STANDARDS +\&.\e\*q .Sh HISTORY +\&.\e\*q .Sh AUTHORS +\&.\e\*q .Sh CAVEATS +\&.\e\*q .Sh BUGS +\&.\e\*q .Sh SECURITY CONSIDERATIONS +.Ed +.Pp +The sections in a +.Nm +document are conventionally ordered as they appear above. Sections +should be composed as follows: +.Bl -ohang -offset Ds +.It Em NAME +The name(s) and a short description of the documented material. The +syntax for this as follows: +.Bd -literal -offset indent +\&.Nm name0 +\&.Nm name1 +\&.Nm name2 +\&.Nd a short description +.Ed +.Pp +The +.Sx \&Nm +macro(s) must precede the +.Sx \&Nd +macro. +. +.It Em LIBRARY +The name of the library containing the documented material, which is +assumed to be a function in a section 2 or 3 manual. The syntax for +this is as follows: +.Bd -literal -offset indent +\&.Lb libarm +.Ed +.Pp +See +.Sx \&Lb +for details. +. +.It Em SYNOPSIS +Documents the utility invocation syntax, function call syntax, or device +configuration. +.Pp +For the first, utilities (sections 1, 6, and 8), this is +generally structured as follows: +.Bd -literal -offset indent +\&.Nm foo +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +\&.Nm bar +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +.Ed +.Pp +For the second, function calls (sections 2, 3, 9): +.Bd -literal -offset indent +\&.Vt extern const char *global; +\&.In header.h +\&.Ft "char *" +\&.Fn foo "const char *src" +\&.Ft "char *" +\&.Fn bar "const char *src" +.Ed +.Pp +And for the third, configurations (section 4): +.Bd -literal -offset indent +\&.Cd \*qit* at isa? port 0x2e\*q +\&.Cd \*qit* at isa? port 0x4e\*q +.Ed +.Pp +Manuals not in these sections generally don't need a +.Em SYNOPSIS . +. +.It Em DESCRIPTION +This expands upon the brief, one-line description in +.Em NAME . +It usually contains a break-down of the options (if documenting a +command), such as: +.Bd -literal -offset indent +The arguments are as follows: +\&.Bl \-tag \-width Ds +\&.It Fl v +Print verbose information. +\&.El +.Ed +Manuals not documenting a command won't include the above fragment. +. +.It Em IMPLEMENTATION NOTES +Implementation-specific notes should be kept here. This is useful when +implementing standard functions that may have side effects or notable +algorithmic implications. +. +.It Em EXIT STATUS +Command exit status for section 1, 6, and 8 manuals. This section is +the dual of +.Em RETURN VALUES , +which is used for functions. Historically, this information was +described in +.Em DIAGNOSTICS , +a practise that is now discouraged. +.Pp +See +.Sx \&Ex . +. +.It Em RETURN VALUES +This section is the dual of +.Em EXIT STATUS , +which is used for commands. It documents the return values of functions +in sections 2, 3, and 9. +.Pp +See +.Sx \&Rv . +. +.It Em ENVIRONMENT +Documents any usages of environment variables, e.g., +.Xr environ 7 . +.Pp +See +.Sx \&Ev . +. +.It Em FILES +Documents files used. It's helpful to document both the file and a +short description of how the file is used (created, modified, etc.). +.Pp +See +.Sx \&Pa . +. +.It Em EXAMPLES +Example usages. This often contains snippets of well-formed, +well-tested invocations. Make doubly sure that your examples work +properly! +. +.It Em DIAGNOSTICS +Documents error conditions. This is most useful in section 4 manuals. +Historically, this section was used in place of +.Em EXIT STATUS +for manuals in sections 1, 6, and 8; however, this practise is +discouraged. +.Pp +See +.Sx \&Bl No \-diag . +. +.It Em ERRORS +Documents error handling in sections 2, 3, and 9. +.Pp +See +.Sx \&Er . +. +.It Em SEE ALSO +References other manuals with related topics. This section should exist +for most manuals. Cross-references should conventionally be ordered +first by section, then alphabetically. +.Pp +See +.Sx \&Xr . +. +.It Em STANDARDS +References any standards implemented or used. If not adhering to any +standards, the +.Em HISTORY +section should be used instead. +.Pp +See +.Sx \&St . +. +.It Em HISTORY +The history of any manual without a +.Em STANDARDS +section should be described in this section. +. +.It Em AUTHORS +Credits to authors, if applicable, should appear in this section. +Authors should generally be noted by both name and an e-mail address. +.Pp +See +.Sx \&An . +. +.It Em CAVEATS +Explanations of common misuses and misunderstandings should be explained +in this section. +. +.It Em BUGS +Extant bugs should be described in this section. +. +.It Em SECURITY CONSIDERATIONS +Documents any security precautions that operators should consider. +. .El -.\" PARAGRAPH +. +. +.Sh MACRO SYNTAX +Macros are one to three three characters in length and begin with a +control character , +.Sq \&. , +at the beginning of the line. An arbitrary amount of whitespace may +sit between the control character and the macro name. Thus, the +following are equivalent: +.Bd -literal -offset indent +\&.Pp +\&.\ \ \ \&Pp +.Ed +. .Pp -Special symbols: +The syntax of a macro depends on its classification. In this section, +.Sq \-arg +refers to macro arguments, which may be followed by zero or more +.Sq parm +parameters; +.Sq \&Yo +opens the scope of a macro; and if specified, +.Sq \&Yc +closes it out. +. .Pp -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(bu -.Pq bullet -.It \\(ba -.Pq bar -.It \\(Ba -.Pq bar, deprecated -.It \\(co -.Pq copyright -.It \\& -.Pq non-breaking space -.It \\e -.Pq escape -.It \\(Am -.Pq ampersand, deprecated -.El -.\" SECTION -.Sh CLASSIFICATION -Macros are classified in an ontology described by scope rules. -.Bl -tag -width "in-lineX" -.\" LIST-ITEM -.It Em Block -Block macros enclose other block macros, in-line macros or text, and -may span multiple lines. -.Qq Implicit -block scope is closed by a subsequent invocation of the same macro, -one of a set of corresponding closure macros or end-of-file. -.Qq Explicit -block scope is closed by a corresponding closure macro. -.Bl -tag -width "partial-blockX" -.\" LIST-ITEM -.It Em Full-block -Always spans multiple lines. Consists optionally of one or more -.Qq heads , -subsequent macros or text on the same line following invocation; a -.Qq body , -which spans subsequent lines of text or macros; and an optional -.Qq tail , -macros or text on the same line following closure. -.\" LIST-ITEM -.It Em Partial-block -May span multiple lines. Consists optionally of a -.Qq head , -text immediately following invocation; always a -.Qq body , -text or macros following the head on the same and subsequent lines; and -optionally a -.Qq tail , -text immediately following closure. +The +.Em Callable +column indicates that the macro may be called subsequent to the initial +line-macro. If a macro is not callable, then its invocation after the +initial line macro is interpreted as opaque text, such that +.Sq \&.Fl \&Sh +produces +.Sq Fl \&Sh . +. +.Pp +The +.Em Parsable +column indicates whether the macro may be followed by further +(ostensibly callable) macros. If a macro is not parsable, subsequent +macro invocations on the line will be interpreted as opaque text. +. +.Pp +The +.Em Scope +column, if applicable, describes closure rules. +. +. +.Ss Block full-explicit +Multi-line scope closed by an explicit closing macro. All macros +contains bodies; only +.Sx \&Bf +contains a head. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc +.Ed +. +.Pp +.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX" +.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope +.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed +.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef +.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek +.It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El +.It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd +.It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf +.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk +.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl .El -.\" LIST-ITEM -.It Em In-line -In-line macros may only enclose text and span at most a single line. If -a macro is parsable, its scope may be closed by subsequent macros or -delimiting punctuation. In-line macros follow different conventions for -closure; see -.Sx MACROS -for per-macro details. -.El -.\" .\" SUB-SECTION -.\" .Ss Examples -.\" The following examples illustrate each macro classification. -.\" .\" PARAGRAPH -.\" .Pp -.\" Implicit full-block. Has head, body and no tail. Scope closed by -.\" second -.\" .Sq \&Sh -.\" invocation. -.\" .Bd -literal -offset XXXX -.\" \&.Sh SECTION 1 -.\" body... -.\" \&.Sh SECTION 2 -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Nested implicit full-block, where the subsection -.\" .Sq \&Ss -.\" is within the scope of the parent section -.\" .Sq \&Sh -.\" and closed along with its parent by the subsequent -.\" .Sq \&Sh . -.\" .Bd -literal -offset XXXX -.\" \&.Sh SECTION 1 -.\" \&.Ss Subsection 1 -.\" body... -.\" \&.Sh SECTION 2 -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Explicit full-block. Has a head, a body and no tail. Scope closed by -.\" .Sq \&Ef -.\" invocation. -.\" .Bd -literal -offset XXXX -.\" \&.Bf symbolic -.\" body... -.\" \&.Ef -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Nested explicit/implicit scope. -.\" .Sq \&It -.\" macro is an implicit block whose scope is closed by the explicit -.\" .Sq \&El -.\" closure. -.\" .Bd -literal -offset XXXX -.\" \&.Bl \-bullet -.\" \&.It head -.\" body... -.\" \&.El -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Explicit partial-block. Has head, body and tail. Scope closed by -.\" .Sq \&Ec -.\" invocation. -.\" .Bd -literal -offset XXX -.\" \&.Eo head body... \&Ec tail -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Implicit partial-block. Has only body. Scope is closed by end-of-line. -.\" .Bd -literal -offset XXX -.\" \&.Sq body... -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Explicit partial-block with only body and scope closed by -.\" .Sq \&Ac -.\" invocation. -.\" .Bd -literal -offset XXXX -.\" \&.Ao body... \&Ac -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Implicit partial-block enclosing explicit partial-block. -.\" .Bd -literal -offset XXX -.\" \&.Sq body... \&Ao body... \&Ac -.\" .Ed -.\" .\" PARAGRAPH -.\" .Pp -.\" Inline macros, several in sequence. Scope is closed for -.\" .Sq \&Fl -.\" by the punctuation delimiter and -.\" .Sq \&Ar -.\" by the end-of-line. -.\" .Bd -literal -offset XXXX -.\" \&.Fl text0 text1 ; Ar text0 text1 -.\" .Ed -.\" SECTION -.Sh MACROS -This section contains a complete list of all -.Nm -macros, arranged ontologically then alphanumerically by macro name. A -.Qq callable -macro is may be invoked subsequent to the initial macro-line macro. A -.Qq parsable -macro May be followed by further (ostensibly callable) macros. -.\" SUB-SECTION +. +. .Ss Block full-implicit -The head of these macros follows invocation; the body is the content of -subsequent lines prior to closure. None of these macros have tails; -some +Multi-line scope closed by end-of-file or implicitly by another macro. +All macros have bodies; some .Po -.Sq \&It \-bullet , -.Sq \-hyphen , -.Sq \-dash , -.Sq \-enum +.Sx \&It Fl bullet , +.Fl hyphen , +.Fl dash , +.Fl enum , +.Fl item .Pc -don't have heads. +don't have heads; only one +.Po +.Sx \&It Fl column +.Pc +has multiple heads. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB +\(lBbody...\(rB +.Ed +. .Pp -.Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX -.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing -.It \&.Sh Ta \&No Ta \&No Ta \&.Sh -.It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss -.It \&.It Ta \&No Ta Yes Ta \&.It, \&.El +.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX" +.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope +.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El +.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh +.It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh +.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss .El -.\" SUB-SECTION -.Ss Block full-explicit -None of these macros are callable or parsed. The last column indicates -the explicit scope rules. All contains bodies, some may contain heads -.Pq So \&Bf Sc . +. +. +.Ss Block partial-explicit +Like block full-explicit, but also with single-line scope. Each +has at least a body and, in limited circumstances, a head +.Po +.Sx \&Fo , +.Sx \&Eo +.Pc +and/or tail +.Pq Sx \&Ec . +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc \(lBtail...\(rB + +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ +\(lBbody...\(rB \&Yc \(lBtail...\(rB +.Ed +. .Pp -.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX +.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope -.It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed -.It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd -.It \&.Bl Ta \&No Ta \&No Ta closed by \&.El -.It \&.El Ta \&No Ta \&No Ta opened by \&.Bl -.It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef -.It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf +.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao +.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac +.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo +.It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc +.It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro +.It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc +.It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do +.It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc +.It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo +.It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec +.It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo +.It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc +.It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo +.It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc +.It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po +.It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc +.It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo +.It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc +.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs +.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re +.It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So +.It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc +.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo +.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc .El -.\" SUB-SECTION +. +. .Ss Block partial-implicit -All of these are callable and parsed for further macros. Their scopes -close at the invocation's end-of-line. +Like block full-implicit, but with single-line scope closed by +.Sx Reserved Characters +or end of line. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB +.Ed +. .Pp -.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX +.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent .It Em Macro Ta Em Callable Ta Em Parsable -.It \&.Aq Ta Yes Ta Yes -.It \&.Op Ta Yes Ta Yes -.It \&.Bq Ta Yes Ta Yes -.It \&.Dq Ta Yes Ta Yes -.It \&.Pq Ta Yes Ta Yes -.It \&.Qq Ta Yes Ta Yes -.It \&.Sq Ta Yes Ta Yes -.It \&.Brq Ta Yes Ta Yes +.It Sx \&Aq Ta Yes Ta Yes +.It Sx \&Bq Ta Yes Ta Yes +.It Sx \&Brq Ta Yes Ta Yes +.It Sx \&D1 Ta \&No Ta \&Yes +.It Sx \&Dl Ta \&No Ta Yes +.It Sx \&Dq Ta Yes Ta Yes +.It Sx \&Op Ta Yes Ta Yes +.It Sx \&Pq Ta Yes Ta Yes +.It Sx \&Ql Ta Yes Ta Yes +.It Sx \&Qq Ta Yes Ta Yes +.It Sx \&Sq Ta Yes Ta Yes .El -.\" SUB-SECTION -.Ss Block partial-explicit -Each of these contains at least a body and, in limited circumstances, a -head -.Pq So \&Fo Sc , So \&Eo Sc -and/or tail -.Pq So \&Ec Sc . +. +. +.Ss In-line +Closed by +.Sx Reserved Characters , +end of line, fixed argument lengths, and/or subsequent macros. In-line +macros have only text children. If a number (or inequality) of +arguments is +.Pq n , +then the macro accepts an arbitrary number of arguments. +.Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... + +\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN +.Ed +. .Pp -.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX -.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope -.It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac -.It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao -.It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo -.It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc -.It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po -.It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc -.It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc -.It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do -.It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc -.It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo -.It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc -.It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro -.It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo -.It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc -.It \&.So Ta Yes Ta Yes Ta closed by \&.Sc -.It \&.Sc Ta Yes Ta Yes Ta opened by \&.So -.It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo -.It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc -.It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo -.It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec -.It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo -.It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc +.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent +.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments +.It Sx \&%A Ta \&No Ta \&No Ta >0 +.It Sx \&%B Ta \&No Ta \&No Ta >0 +.It Sx \&%C Ta \&No Ta \&No Ta >0 +.It Sx \&%D Ta \&No Ta \&No Ta >0 +.It Sx \&%I Ta \&No Ta \&No Ta >0 +.It Sx \&%J Ta \&No Ta \&No Ta >0 +.It Sx \&%N Ta \&No Ta \&No Ta >0 +.It Sx \&%O Ta \&No Ta \&No Ta >0 +.It Sx \&%P Ta \&No Ta \&No Ta >0 +.It Sx \&%Q Ta \&No Ta \&No Ta >0 +.It Sx \&%R Ta \&No Ta \&No Ta >0 +.It Sx \&%T Ta \&No Ta \&No Ta >0 +.It Sx \&%U Ta \&No Ta \&No Ta >0 +.It Sx \&%V Ta \&No Ta \&No Ta >0 +.It Sx \&Ad Ta Yes Ta Yes Ta n +.It Sx \&An Ta Yes Ta Yes Ta n +.It Sx \&Ap Ta Yes Ta Yes Ta 0 +.It Sx \&Ar Ta Yes Ta Yes Ta n +.It Sx \&At Ta Yes Ta Yes Ta 1 +.It Sx \&Bsx Ta Yes Ta Yes Ta n +.It Sx \&Bt Ta \&No Ta \&No Ta 0 +.It Sx \&Bx Ta Yes Ta Yes Ta n +.It Sx \&Cd Ta Yes Ta Yes Ta >0 +.It Sx \&Cm Ta Yes Ta Yes Ta n +.It Sx \&Db Ta \&No Ta \&No Ta 1 +.It Sx \&Dd Ta \&No Ta \&No Ta >0 +.It Sx \&Dt Ta \&No Ta \&No Ta n +.It Sx \&Dv Ta Yes Ta Yes Ta n +.It Sx \&Dx Ta Yes Ta Yes Ta n +.It Sx \&Em Ta Yes Ta Yes Ta >0 +.It Sx \&En Ta \&No Ta \&No Ta 0 +.It Sx \&Er Ta Yes Ta Yes Ta >0 +.It Sx \&Es Ta \&No Ta \&No Ta 0 +.It Sx \&Ev Ta Yes Ta Yes Ta n +.It Sx \&Ex Ta \&No Ta \&No Ta n +.It Sx \&Fa Ta Yes Ta Yes Ta n +.It Sx \&Fd Ta \&No Ta \&No Ta >0 +.It Sx \&Fl Ta Yes Ta Yes Ta n +.It Sx \&Fn Ta Yes Ta Yes Ta >0 +.It Sx \&Fr Ta \&No Ta \&No Ta n +.It Sx \&Ft Ta Yes Ta Yes Ta n +.It Sx \&Fx Ta Yes Ta Yes Ta n +.It Sx \&Hf Ta \&No Ta \&No Ta n +.It Sx \&Ic Ta Yes Ta Yes Ta >0 +.It Sx \&In Ta \&No Ta \&No Ta n +.It Sx \&Lb Ta \&No Ta \&No Ta 1 +.It Sx \&Li Ta Yes Ta Yes Ta n +.It Sx \&Lk Ta Yes Ta Yes Ta n +.It Sx \&Lp Ta \&No Ta \&No Ta 0 +.It Sx \&Ms Ta Yes Ta Yes Ta >0 +.It Sx \&Mt Ta Yes Ta Yes Ta >0 +.It Sx \&Nm Ta Yes Ta Yes Ta n +.It Sx \&No Ta Yes Ta Yes Ta 0 +.It Sx \&Ns Ta Yes Ta Yes Ta 0 +.It Sx \&Nx Ta Yes Ta Yes Ta n +.It Sx \&Os Ta \&No Ta \&No Ta n +.It Sx \&Ot Ta \&No Ta \&No Ta n +.It Sx \&Ox Ta Yes Ta Yes Ta n +.It Sx \&Pa Ta Yes Ta Yes Ta n +.It Sx \&Pf Ta \&No Ta Yes Ta 1 +.It Sx \&Pp Ta \&No Ta \&No Ta 0 +.It Sx \&Rv Ta \&No Ta \&No Ta n +.It Sx \&Sm Ta \&No Ta \&No Ta 1 +.It Sx \&St Ta \&No Ta Yes Ta 1 +.It Sx \&Sx Ta Yes Ta Yes Ta >0 +.It Sx \&Sy Ta Yes Ta Yes Ta >0 +.It Sx \&Tn Ta Yes Ta Yes Ta >0 +.It Sx \&Ud Ta \&No Ta \&No Ta 0 +.It Sx \&Ux Ta Yes Ta Yes Ta n +.It Sx \&Va Ta Yes Ta Yes Ta n +.It Sx \&Vt Ta Yes Ta Yes Ta >0 +.It Sx \&Xr Ta Yes Ta Yes Ta >0, <3 +.It Sx \&br Ta \&No Ta \&No Ta 0 +.It Sx \&sp Ta \&No Ta \&No Ta 1 +.El +. +. +.Sh REFERENCE +This section is a canonical reference of all macros, arranged +alphabetically. For the scoping of individual macros, see +.Sx MACRO SYNTAX . +. +.Ss \&%A +Author name of an +.Sx \&Rs +block. Multiple authors should each be accorded their own +.Sx \%%A +line. Author names should be ordered with full or abbreviated +forename(s) first, then full surname. +. +.Ss \&%B +Book title of an +.Sx \&Rs +block. This macro may also be used in a non-bibliographic context when +referring to book titles. +. +.Ss \&%C +Publication city or location of an +.Sx \&Rs +block. +.Pp +.Em Remarks : +this macro is not implemented in +.Xr groff 1 . +. +.Ss \&%D +Publication date of an +.Sx \&Rs +block. This should follow the reduced or canonical form syntax +described in +.Sx Dates . +. +.Ss \&%I +Publisher or issuer name of an +.Sx \&Rs +block. +. +.Ss \&%J +Journal name of an +.Sx \&Rs +block. +. +.Ss \&%N +Issue number (usually for journals) of an +.Sx \&Rs +block. +. +.Ss \&%O +Optional information of an +.Sx \&Rs +block. +. +.Ss \&%P +Book or journal page number of an +.Sx \&Rs +block. +. +.Ss \&%Q +Institutional author (school, government, etc.) of an +.Sx \&Rs +block. Multiple institutional authors should each be accorded their own +.Sx \&%Q +line. +. +.Ss \&%R +Technical report name of an +.Sx \&Rs +block. +. +.Ss \&%T +Article title of an +.Sx \&Rs +block. This macro may also be used in a non-bibliographical context +when referring to article titles. +. +.Ss \&%U +URI of reference document. +. +.Ss \&%V +Volume number of an +.Sx \&Rs +block. +. +.Ss \&Ac +Closes an +.Sx \&Ao +block. Does not have any tail arguments. +. +.Ss \&Ad +Address construct: usually in the context of an computational address in +memory, not a physical (post) address. +.Pp +Examples: +.Bd -literal -offset indent +\&.Ad [0,$] +\&.Ad 0x00000000 +.Ed +. +.Ss \&An +Author name. This macro may alternatively accepts the following +arguments, although these may not be specified along with a parameter: +.Bl -tag -width 12n -offset indent +.It Fl split +Renders a line break before each author listing. +.It Fl nosplit +The opposite of +.Fl split . .El -.\" SUB-SECTION -.Ss General -.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX -.It Em Macro Ta Em Callable Ta Em Parsable -.It \&.Dd Ta \& Ta \& -.It \&.Dt Ta \& Ta \& -.It \&.Os Ta \& Ta \& -.It \&.Pp Ta \& Ta \& -.It \&.D1 Ta \& Ta \& -.It \&.Dl Ta \& Ta Yes -.It \&.Ad Ta Yes Ta Yes -.It \&.An Ta \& Ta Yes -.It \&.Ar Ta Yes Ta Yes -.It \&.Cd Ta Yes Ta \& -.It \&.Cm Ta Yes Ta Yes -.It \&.Dv Ta Yes Ta Yes -.It \&.Er Ta Yes Ta Yes -.It \&.Ev Ta Yes Ta Yes -.It \&.Ex Ta \& Ta \& -.It \&.Fa Ta Yes Ta Yes -.It \&.Fd Ta \& Ta \& -.It \&.Fl Ta Yes Ta Yes -.It \&.Fn Ta Yes Ta Yes -.It \&.Ft Ta \& Ta \& -.It \&.Ic Ta Yes Ta Yes -.It \&.In Ta \& Ta \& -.It \&.Li Ta Yes Ta Yes -.It \&.Nd Ta \& Ta \& -.It \&.Nm Ta Yes Ta Yes -.It \&.Ot Ta \& Ta \& -.It \&.Pa Ta Yes Ta Yes -.It \&.Rv Ta \& Ta \& -.It \&.St Ta Yes Ta \& -.It \&.Va Ta Yes Ta Yes -.It \&.Vt Ta Yes Ta Yes -.It \&.Xr Ta Yes Ta Yes -.It \&.%A Ta \& Ta \& -.It \&.%B Ta \& Ta \& -.It \&.%C Ta \& Ta \& -.It \&.%D Ta \& Ta \& -.It \&.%I Ta \& Ta \& -.It \&.%J Ta \& Ta \& -.It \&.%N Ta \& Ta \& -.It \&.%O Ta \& Ta \& -.It \&.%P Ta \& Ta \& -.It \&.%R Ta \& Ta \& -.It \&.%T Ta \& Ta \& -.It \&.%V Ta \& Ta \& -.It \&.At Ta Yes Ta Yes -.It \&.Bsx Ta Yes Ta Yes -.It \&.Bx Ta Yes Ta Yes -.It \&.Db Ta \& Ta \& -.It \&.Em Ta Yes Ta Yes -.It \&.Fx Ta Yes Ta Yes -.It \&.Ms Ta \& Ta Yes -.It \&.No Ta Yes Ta Yes -.It \&.Ns Ta Yes Ta Yes -.It \&.Nx Ta Yes Ta Yes -.It \&.Ox Ta Yes Ta Yes -.It \&.Pf Ta \& Ta Yes -.It \&.Ql Ta Yes Ta Yes -.It \&.Re Ta \& Ta \& -.It \&.Rs Ta \& Ta \& -.It \&.Sm Ta \& Ta \& -.It \&.Sx Ta Yes Ta Yes -.It \&.Sy Ta Yes Ta Yes -.It \&.Tn Ta Yes Ta Yes -.It \&.Ux Ta Yes Ta Yes -.It \&.Bk Ta \& Ta \& -.It \&.Ek Ta \& Ta \& -.It \&.Bt Ta \& Ta \& -.It \&.Hf Ta \& Ta \& -.It \&.Fr Ta \& Ta \& -.It \&.Ud Ta \& Ta \& -.It \&.Lb Ta \& Ta \& -.It \&.Ap Ta Yes Ta Yes -.It \&.Lp Ta \& Ta \& -.It \&.Lk Ta \& Ta Yes -.It \&.Mt Ta \& Ta Yes +.Pp +In the AUTHORS section, the default is not to split the first author +listing, but all subsequent author listings, whether or not they're +interspersed by other macros or text, are split. Thus, specifying +.Fl split +will cause the first listing also to be split. If not in the AUTHORS +section, the default is not to split. +.Pp +Examples: +.Bd -literal -offset indent +\&.An -nosplit +\&.An J. E. Hopcraft , +\&.An J. D. Ullman . +.Ed +.Pp +.Em Remarks : +the effects of +.Fl split +or +.Fl nosplit +are re-set when entering the AUTHORS section, so if one specifies +.Sx \&An Fl nosplit +in the general document body, it must be re-specified in the AUTHORS +section. +. +.Ss \&Ao +Begins a block enclosed by angled brackets. Does not have any head +arguments. +.Pp +Examples: +.Bd -literal -offset indent +\&.Fl -key= Ns Ao Ar val Ac +.Ed +.Pp +See also +.Sx \&Aq . +. +.Ss \&Ap +Inserts an apostrophe without any surrounding white-space. This is +generally used as a grammatic device when referring to the verb form of +a function: +.Bd -literal -offset indent +\&.Fn execve Ap d +.Ed +. +.Ss \&Aq +Encloses its arguments in angled brackets. +.Pp +Examples: +.Bd -literal -offset indent +\&.Fl -key= Ns Aq Ar val +.Ed +.Pp +.Em Remarks : +this macro is often abused for rendering URIs, which should instead use +.Sx \&Lk +or +.Sx \&Mt , +or to note pre-processor +.Dq Li #include +statements, which should use +.Sx \&In . +.Pp +See also +.Sx \&Ao . +. +.Ss \&Ar +Command arguments. If an argument is not provided, the string +.Dq file ... +is used as a default. +.Pp +Examples: +.Bd -literal -offset indent +\&.Fl o Ns Ar file1 +\&.Ar +\&.Ar arg1 , arg2 . +.Ed +. +.Ss \&At +Formats an AT&T version. Accepts at most one parameter: +.Bl -tag -width 12n -offset indent +.It Cm v[1-7] | 32v +A version of +.At . +.It Cm V[.[1-4]]? +A system version of +.At . .El +.Pp +Note that these parameters do not begin with a hyphen. +.Pp +Examples: +.Bd -literal -offset indent +\&.At +\&.At V.1 +.Ed +.Pp +See also +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Nx , +.Sx \&Ox , +and +.Sx \&Ux . +. +.Ss \&Bc +Closes a +.Sx \&Bo +block. Does not have any tail arguments. +. +.Ss \&Bd +Begins a display block. A display is collection of macros or text which +may be collectively offset or justified in a manner different from that +of the enclosing context. By default, the block is preceded by a +vertical space. +.Pp +Each display is associated with a type, which must be one of the +following arguments: +.Bl -tag -width 12n -offset indent +.It Fl ragged +Only left-justify the block. +.It Fl unfilled +Do not justify the block at all. +.It Fl filled +Left- and right-justify the block. +.It Fl literal +Alias for +.Fl unfilled . +.It Fl centered +Centre-justify each line. +.El +.Pp +The type must be provided first. Secondary arguments are as follows: +.Bl -tag -width 12n -offset indent +.It Fl offset Ar width +Offset by the value of +.Ar width , +which is interpreted as one of the following, specified in order: +.Bl -item +.It +As one of the pre-defined strings +.Ar indent , +the width of standard indentation; +.Ar indent-two , +twice +.Ar indent ; +.Ar left , +which has no effect ; +.Ar right , +which justifies to the right margin; and +.Ar center , +which aligns around an imagined centre axis. +.It +As a precalculated width for a named macro. The most popular is the +imaginary macro +.Ar \&Ds , +which resolves to +.Ar 6n . +.It +As a scaling unit following the syntax described in +.Sx Scaling Widths . +.It +As the calculated string length of the opaque string. +.El +.Pp +If unset, it will revert to the value of +.Ar 8n +as described in +.Sx Scaling Widths . +.It Fl compact +Do not assert a vertical space before the block. +.It Fl file Ar file +Prepend the file +.Ar file +before any text or macros within the block. +.El +.Pp +Examples: +.Bd -literal -offset indent +\&.Bd \-unfilled \-offset two-indent \-compact + Hello world. +\&.Ed +.Ed +.Pp +See also +.Sx \&D1 +and +.Sx \&Dl . +. +.Ss \&Bf +.Ss \&Bk +.Ss \&Bl +. +.Ss \&Bo +Begins a block enclosed by square brackets. Does not have any head +arguments. +.Pp +Examples: +.Bd -literal -offset indent +\&.Bo 1 , +\&.Dv BUFSIZ Bc +.Ed +.Pp +See also +.Sx \&Bq . +. +.Ss \&Bq +Encloses its arguments in square brackets. +.Pp +Examples: +.Bd -literal -offset indent +\&.Bq 1 , Dv BUFSIZ +.Ed +.Pp +.Em Remarks : +this macro is sometimes abused to emulate optional arguments for +commands; the correct macros to use for this purpose are +.Sx \&Op , +.Sx \&Oo , +and +.Sx \&Oc . +.Pp +See also +.Sx \&Bo . +. +.Ss \&Brc +Closes a +.Sx \&Bro +block. Does not have any tail arguments. +. +.Ss \&Bro +Begins a block enclosed by curly braces. Does not have any head +arguments. +.Pp +Examples: +.Bd -literal -offset indent +\&.Bro 1 , ... , +\&.Va n Brc +.Ed +.Pp +See also +.Sx \&Brq . +. +.Ss \&Brq +Encloses its arguments in curly braces. +.Pp +Examples: +.Bd -literal -offset indent +\&.Brq 1 , ... , Va n +.Ed +.Pp +See also +.Sx \&Bro . +. +.Ss \&Bsx +Format the BSD/OS version provided as an argument, or a default value if +no argument is provided. +.Pp +Examples: +.Bd -literal -offset indent +\&.Bsx 1.0 +\&.Bsx +.Ed +.Pp +See also +.Sx \&At , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Nx , +.Sx \&Ox , +and +.Sx \&Ux . +. +.Ss \&Bt +Prints +.Dq is currently in beta test. +. +.Ss \&Bx +Format the BSD version provided as an argument, or a default value if no +argument is provided. +.Pp +Examples: +.Bd -literal -offset indent +\&.Bx 4.4 +\&.Bx +.Ed +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Nx , +.Sx \&Ox , +and +.Sx \&Ux . +. +.Ss \&Cd +Configuration declaration (suggested for use only in section four +manuals). This denotes strings accepted by +.Xr config 8 . +.Pp +Examples: +.Bd -literal -offset indent +\&.Cd device le0 at scode? +.Ed +.Pp +.Em Remarks : +this macro is commonly abused by using quoted literals to retain +white-space and align consecutive +.Sx \&Cd +declarations. This practise is discouraged. +. +.Ss \&Cm +Command modifiers. Useful when specifying configuration options or +keys. +.Pp +Examples: +.Bd -literal -offset indent +\&.Cm ControlPath +\&.Cm ControlMaster +.Ed +.Pp +See also +.Sx \&Fl . +. +.Ss \&D1 +One-line indented display. This is formatted by the default rules and +is useful for simple indented statements. It is followed by a newline. +.Pp +Examples: +.Bd -literal -offset indent +\&.D1 Fl abcdefgh +.Ed +.Pp +See also +.Sx \&Bd +and +.Sx \&Dl . +. +.Ss \&Db +.Ss \&Dc +Closes a +.Sx \&Do +block. Does not have any tail arguments. +. +.Ss \&Dd +Document date. This is the mandatory first macro of any +.Nm +manual. Its calling syntax is as follows: +.Pp +.D1 \. Ns Sx \&Dd Cm date +.Pp +The +.Cm date +field may be either +.Ar $\&Mdocdate$ , +which signifies the current manual revision date dictated by +.Xr cvs 1 , +or instead a valid canonical date as specified by +.Sx Dates . +If a date does not conform, the current date is used instead. +.Pp +Examples: +.Bd -literal -offset indent +\&.Dd $\&Mdocdate$ +\&.Dd $\&Mdocdate: July 21 2007$ +\&.Dd July 21, 2007 +.Ed +.Pp +See also +.Sx \&Dt +and +.Sx \&Os . +. +.Ss \&Dl +One-line intended display. This is formatted as literal text and is +useful for commands and invocations. It is followed by a newline. +.Pp +Examples: +.Bd -literal -offset indent +\&.Dl % mandoc mdoc.7 | less +.Ed +.Pp +See also +.Sx \&Bd +and +.Sx \&D1 . +. +.Ss \&Do +Begins a block enclosed by double quotes. Does not have any head +arguments. +.Pp +Examples: +.Bd -literal -offset indent +\&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot +.Ed +.Pp +See also +.Sx \&Dq . +. +.Ss \&Dq +Encloses its arguments in double quotes. +.Pp +Examples: +.Bd -literal -offset indent +\&.Dq April is the cruellest month +\e(em T.S. Eliot +.Ed +.Pp +See also +.Sx \&Do . +. +.Ss \&Dt +Document title. This is the mandatory second macro of any +.Nm +file. Its calling syntax is as follows: +.Pp +.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch +.Pp +Its arguments are as follows: +.Bl -tag -width Ds -offset Ds +.It Cm title +The document's title (name). This should be capitalised and is +required. +.It Cm section +The manual section. This may be one of +.Ar 1 +.Pq utilities , +.Ar 2 +.Pq system calls , +.Ar 3 +.Pq libraries , +.Ar 3p +.Pq Perl libraries , +.Ar 4 +.Pq devices , +.Ar 5 +.Pq file formats , +.Ar 6 +.Pq games , +.Ar 7 +.Pq miscellaneous , +.Ar 8 +.Pq system utilities , +.Ar 9 +.Pq kernel functions , +.Ar X11 +.Pq X Window System , +.Ar X11R6 +.Pq X Window System , +.Ar unass +.Pq unassociated , +.Ar local +.Pq local system , +.Ar draft +.Pq draft manual , +or +.Ar paper +.Pq paper . +It is also required and should correspond to the manual's filename +suffix. +.It Cm volume +This overrides the volume inferred from +.Ar section . +This field is optional, and if specified, must be one of +.Ar USD +.Pq users' supplementary documents , +.Ar PS1 +.Pq programmers' supplementary documents , +.Ar AMD +.Pq administrators' supplementary documents , +.Ar SMM +.Pq system managers' manuals , +.Ar URM +.Pq users' reference manuals , +.Ar PRM +.Pq programmers' reference manuals , +.Ar KM +.Pq kernel manuals , +.Ar IND +.Pq master index , +.Ar MMI +.Pq master index , +.Ar LOCAL +.Pq local manuals , +.Ar LOC +.Pq local manuals , +or +.Ar CON +.Pq contributed manuals . +.It Cm arch +This specifies a specific relevant architecture. If +.Cm volume +is not provided, it may be used in its place, else it may be used +subsequent that. It, too, is optional. It must be one of +.Ar alpha , +.Ar amd64 , +.Ar amiga , +.Ar arc , +.Ar arm , +.Ar armish , +.Ar aviion , +.Ar hp300 , +.Ar hppa , +.Ar hppa64 , +.Ar i386 , +.Ar landisk , +.Ar luna88k , +.Ar mac68k , +.Ar macppc , +.Ar mvme68k , +.Ar mvme88k , +.Ar mvmeppc , +.Ar pmax , +.Ar sgi , +.Ar socppc , +.Ar sparc , +.Ar sparc64 , +.Ar sun3 , +.Ar vax , +or +.Ar zaurus . +.El +.Pp +Examples: +.Bd -literal -offset indent +\&.Dt FOO 1 +\&.Dt FOO 4 KM +\&.Dt FOO 9 i386 +\&.Dt FOO 9 KM i386 +.Ed +.Pp +See also +.Sx \&Dd +and +.Sx \&Os . +. +.Ss \&Dv +Defined variables such as preprocessor constants. +.Pp +Examples: +.Bd -literal -offset indent +\&.Dv BUFSIZ +\&.Dv STDOUT_FILENO +.Ed +.Pp +See also +.Sx \&Er . +. +.Ss \&Dx +Format the DragonFly BSD version provided as an argument, or a default +value if no argument is provided. +.Pp +Examples: +.Bd -literal -offset indent +\&.Dx 2.4.1 +\&.Dx +.Ed +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Fx , +.Sx \&Nx , +.Sx \&Ox , +and +.Sx \&Ux . +. +.Ss \&Ec +.Ss \&Ed +.Ss \&Ef +.Ss \&Ek +.Ss \&El +.Ss \&Em +Denotes text that should be emphasised. Note that this is a +presentation term and should not be used for stylistically decorating +technical terms. +.Pp +Examples: +.Bd -literal -offset indent +\&.Ed Warnings! +\&.Ed Remarks : +.Ed +. +.Ss \&En +.Ss \&Eo +.Ss \&Er +Error constants (suggested for use only in section two manuals). +.Pp +Examples: +.Bd -literal -offset indent +\&.Er EPERM +\&.Er ENOENT +.Ed +.Pp +See also +.Sx \&Dv . +. +.Ss \&Es +. +.Ss \&Ev +Environmental variables such as those specified in +.Xr environ 7 . +.Pp +Examples: +.Bd -literal -offset indent +\&.Ev DISPLAY +\&.Ev PATH +.Ed +. +.Ss \&Ex +Inserts text regarding a utility's exit values. This macro must have +first the +.Fl std +argument specified, then an optional +.Ar utility . +If +.Ar utility +is not provided, the document's name as stipulated in +.Sx \&Nm +is provided. +.Ss \&Fa +.Ss \&Fc +.Ss \&Fd +.Ss \&Fl +.Ss \&Fn +.Ss \&Fo +.Ss \&Fr +.Ss \&Ft +.Ss \&Fx +Format the FreeBSD version provided as an argument, or a default value +if no argument is provided. +.Pp +Examples: +.Bd -literal -offset indent +\&.Fx 7.1 +\&.Fx +.Ed +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Nx , +.Sx \&Ox , +and +.Sx \&Ux . +. +.Ss \&Hf +.Ss \&Ic +.Ss \&In +.Ss \&It +.Ss \&Lb +.Ss \&Li +.Ss \&Lk +Format a hyperlink. The calling syntax is as follows: +.Pp +.D1 \. Ns Sx \&Lk Cm uri Op Cm name +.Pp +Examples: +.Bd -literal -offset indent +\&.Lk http://bsd.lv "The BSD.lv Project" +\&.Lk http://bsd.lv +.Ed +.Pp +See also +.Sx \&Mt . +. +.Ss \&Lp +.Ss \&Ms +.Ss \&Mt +.Ss \&Nd +.Ss \&Nm +.Ss \&No +.Ss \&Ns +.Ss \&Nx +Format the NetBSD version provided as an argument, or a default value if +no argument is provided. +.Pp +Examples: +.Bd -literal -offset indent +\&.Nx 5.01 +\&.Nx +.Ed +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Ox , +and +.Sx \&Ux . +. +.Ss \&Oc +.Ss \&Oo +.Ss \&Op +.Ss \&Os +Document operating system version. This is the mandatory third macro of +any +.Nm +file. Its calling syntax is as follows: +.Pp +.D1 \. Ns Sx \&Os Op Cm system +.Pp +The optional +.Cm system +parameter specifies the relevant operating system or environment. Left +unspecified, it defaults to the local operating system version. This is +the suggested form. +.Pp +Examples: +.Bd -literal -offset indent +\&.Os +\&.Os KTH/CSC/TCS +\&.Os BSD 4.3 +.Ed +.Pp +See also +.Sx \&Dd +and +.Sx \&Dt . +. +.Ss \&Ot +Unknown usage. +.Pp +.Em Remarks : +this macro has been deprecated. +. +.Ss \&Ox +Format the OpenBSD version provided as an argument, or a default value +if no argument is provided. +.Pp +Examples: +.Bd -literal -offset indent +\&.Ox 4.5 +\&.Ox +.Ed +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Nx , +and +.Sx \&Ux . +. +.Ss \&Pa +.Ss \&Pc +.Ss \&Pf +.Ss \&Po +.Ss \&Pp +.Ss \&Pq +.Ss \&Qc +.Ss \&Ql +.Ss \&Qo +.Ss \&Qq +. +.Ss \&Re +Closes a +.Sx \&Rs +block. Does not have any tail arguments. +. +.Ss \&Rs +Begins a bibliographic +.Pq Dq reference +block. Does not have any head arguments. The block macro may only +contain +.Sx \&%A , +.Sx \&%B , +.Sx \&%C , +.Sx \&%D , +.Sx \&%I , +.Sx \&%J , +.Sx \&%N , +.Sx \&%O , +.Sx \&%P , +.Sx \&%Q , +.Sx \&%R , +.Sx \&%T , +and +.Sx \&%V +child macros (at least one must be specified). +.Pp +Examples: +.Bd -literal -offset indent +\&.Rs +\&.%A J. E. Hopcroft +\&.%A J. D. Ullman +\&.%B Introduction to Automata Theory, Languages, and Computation +\&.%I Addison-Wesley +\&.%C Reading, Massachusettes +\&.%D 1979 +\&.Re +.Ed +.Pp +If an +.Sx \&Rs +block is used within a SEE ALSO section, a vertical space is asserted +before the rendered output, else the block continues on the current +line. +. +.Ss \&Rv +.Ss \&Sc +.Ss \&Sh +.Ss \&Sm +.Ss \&So +.Ss \&Sq +.Ss \&Ss +.Ss \&St +.Ss \&Sx +.Ss \&Sy +.Ss \&Tn +.Ss \&Ud +.Ss \&Ux +Format the UNIX name. Accepts no argument. +.Pp +Examples: +.Bd -literal -offset indent +\&.Ux +.Ed +.Pp +See also +.Sx \&At , +.Sx \&Bsx , +.Sx \&Bx , +.Sx \&Dx , +.Sx \&Fx , +.Sx \&Nx , +and +.Sx \&Ox . +. +.Ss \&Va +.Ss \&Vt +.Ss \&Xc +.Ss \&Xo +.Ss \&Xr +.Ss \&br +.Ss \&sp +. +. +.Sh COMPATIBILITY +This section documents compatibility with other roff implementations, at +this time limited to +.Xr groff 1 . +The term +.Qq historic groff +refers to those versions before the +.Pa doc.tmac +file re-write +.Pq somewhere between 1.15 and 1.19 . +. +.Pp +.Bl -dash -compact +.It +Negative scaling units are now truncated to zero instead of creating +interesting conditions, such as with +.Sq \&sp -1i . +Furthermore, the +.Sq f +scaling unit, while accepted, is rendered as the default unit. +.It +In quoted literals, groff allowed pair-wise double-quotes to produce a +standalone double-quote in formatted output. This idiosyncratic +behaviour is no longer applicable. +.It +Display types +.Sx \&Bd Fl center +and +.Fl right +are aliases for +.Fl left . +The +.Fl file Ar file +argument is ignored. Since text is not right-justified, +.Fl ragged +and +.Fl filled +are aliases, as are +.Fl literal +and +.Fl unfilled . +.It +Blocks of whitespace are stripped from both macro and free-form text +lines (except when in literal mode), while groff would retain whitespace +in free-form text lines. +.It +Historic groff has many un-callable macros. Most of these (excluding +some block-level macros) are now callable, conforming to the +non-historic groff version. +.It +The vertical bar +.Sq \(ba +made historic groff +.Qq go orbital +but is a proper delimiter in this implementation. +.It +.Sx \&It Fl nested +is assumed for all lists (it wasn't in historic groff): any list may be +nested and +.Fl enum +lists will restart the sequence only for the sub-list. +.It +Some manuals use +.Sx \&Li +incorrectly by following it with a reserved character and expecting the +delimiter to render. This is not supported. +.It +In groff, the +.Sx \&Fo +macro only produces the first parameter. This is no longer the case. +.El +. +. +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr mandoc_char 7 +. +. +.Sh AUTHORS +The +.Nm +reference was written by +.An Kristaps Dzonsons Aq kristaps@kth.se . +.\" +.\" XXX: this really isn't the place for these caveats. +.\" . +.\" . +.\" .Sh CAVEATS +.\" There are many ambiguous parts of mdoc. +.\" . +.\" .Pp +.\" .Bl -dash -compact +.\" .It +.\" .Sq \&Fa +.\" should be +.\" .Sq \&Va +.\" as function arguments are variables. +.\" .It +.\" .Sq \&Ft +.\" should be +.\" .Sq \&Vt +.\" as function return types are still types. Furthermore, the +.\" .Sq \&Ft +.\" should be removed and +.\" .Sq \&Fo , +.\" which ostensibly follows it, should follow the same convention as +.\" .Sq \&Va . +.\" .It +.\" .Sq \&Va +.\" should formalise that only one or two arguments are acceptable: a +.\" variable name and optional, preceding type. +.\" .It +.\" .Sq \&Fd +.\" is ambiguous. It's commonly used to indicate an include file in the +.\" synopsis section. +.\" .Sq \&In +.\" should be used, instead. +.\" .It +.\" Only the +.\" .Sq \-literal +.\" argument to +.\" .Sq \&Bd +.\" makes sense. The remaining ones should be removed. +.\" .It +.\" The +.\" .Sq \&Xo +.\" and +.\" .Sq \&Xc +.\" macros should be deprecated. +.\" .It +.\" The +.\" .Sq \&Dt +.\" macro lacks clarity. It should be absolutely clear which title will +.\" render when formatting the manual page. +.\" .It +.\" A +.\" .Sq \&Lx +.\" should be provided for Linux (\(`a la +.\" .Sq \&Ox , +.\" .Sq \&Nx +.\" etc.). +.\" .It +.\" There's no way to refer to references in +.\" .Sq \&Rs/Re +.\" blocks. +.\" .It +.\" The \-split and \-nosplit dictates via +.\" .Sq \&An +.\" are re-set when entering and leaving the AUTHORS section. +.\" .El +.\" .