=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.2 retrieving revision 1.56 diff -u -p -r1.2 -r1.56 --- mandoc/mdoc.7 2009/03/13 09:08:59 1.2 +++ mandoc/mdoc.7 2009/08/18 14:27:16 1.56 @@ -1,597 +1,626 @@ -.\" $Id: mdoc.7,v 1.2 2009/03/13 09:08:59 kristaps Exp $ +.\" $Id: mdoc.7,v 1.56 2009/08/18 14:27:16 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: August 18 2009 $ +.Dt MDOC 7 .Os -.\" SECTION +. +. .Sh NAME -.Nm mdoc -.Nd mdoc macro reference -.\" SECTION +. Nm mdoc +. Nd mdoc language reference +. +. .Sh DESCRIPTION The -.Nm mdoc -language is used to format -.Bx -.Ux -manuals. An -.Nm +. Nm mdoc +language is used to format +. Bx +. Ux +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 \. +. 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 -.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 Reserved Characters +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 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. +. +. +. Ss Reserved Characters Within a macro line, the following characters are reserved: -.Bl -tag -width 12n -offset XXXX -compact -.It \&. -.Pq period -.It \&, -.Pq comma -.It \&: -.Pq colon -.It \&; -.Pq semicolon -.It \&( -.Pq left-parenthesis -.It \&) -.Pq right-parenthesis -.It \&[ -.Pq left-bracket -.It \&] -.Pq right-bracket -.It \&? -.Pq question -.It \&! -.Pq exclmamation -.El -.Pp -Use of these characters must either be escaped with a non-breaking space -.Pq Sq \e& -or, if applicable, an appropriate escape-sequence used. Use of reserved -characters is described later in this document. -.\" SUB-SECTION -.Ss Special Characters -Special character sequences begin with the escape character -.Sq \\ -and followed by either an open-parenthesis -.Sq \&( +. Bl -tag -width Ds -offset indent -compact +. It \&. +. Pq period +. It \&, +. Pq comma +. It \&: +. Pq colon +. It \&; +. Pq semicolon +. It \&( +. Pq left-parenthesis +. It \&) +. Pq right-parenthesis +. It \&[ +. Pq left-bracket +. It \&] +. Pq right-bracket +. It \&? +. Pq question +. It \&! +. Pq exclamation +. It \&| +. Pq vertical bar +. El +. Pp +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. +. +. +. Ss Special Characters +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 \&[ +. Sq \&[ for n-character sequences (terminated at a close-bracket -.Sq \&] ) ; -or a single one-character sequence. -.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. -.Pp -Grammatic: -.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 -.Pp -Enclosures: -.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 -.Pp -Indicatives: -.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 -.Pp -Mathematical: -.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 -.El -.\" PARAGRAPH -.Pp -Diacritics: -.Bl -tag -width 12n -offset "XXXX" -compact -.It \\(ga -.Pq accent grave -.It \\(aa -.Pq accent accute -.El -.\" PARAGRAPH -.Pp -Special symbols: -.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 ONTOLOGY -Macros are classified in an ontology described by scope rules. -.Bl -inset -.\" LIST-ITEM -.It Em 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 -inset -offset XXXX -.\" LIST-ITEM -.It Em Full-block -macros always span multiple lines. They consist 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 -macros may span multiple lines. They 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. -.El -.\" LIST-ITEM -.It Em 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 SYNTAX -The syntax of macro invocation depends on classification. -.Qq \-arg -refers to the macro arguments (which may contain zero or more values). -In these illustrations, -.Sq \&.Yo -opens the scope of a macro, and if specified, -.Sq \&.Yc -closes it out (closure may be implicit at end-of-line or end-of-file). -.Pp -Block full-explicit (may contain head, body, tail): -.Bd -literal -offset XXXX -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB +. Sq \&] ) ; +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 +In macro lines, whitespace delimits arguments and is discarded. If +arguments are quoted, whitespace within the quotes is retained. +. Pp +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 +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 +In free-form mode, quotes are regarded as opaque text. +. +. +.Sh MANUAL STRUCTURE +Each +. Nm +document must begin with a document prologue, containing, in order, +. Sq \&Dd , +. Sq \&Dt , +and +. Sq \&Os , +then the NAME section containing at least one +. Sq \&Nm +followed by +. Sq \&Nd : +. Bd -literal -offset indent +\&.Dd $\&Mdocdate$ +\&.Dt mdoc 7 +\&.Os +\&.Sh NAME +\&.Nm mdoc +\&.Nd mdoc language reference +. Ed +. Pp +Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged, +but non-compulsory. +. +. +.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, +. Sq \&.Pp +and +. Sq \&.\ \ \ \&Pp +are equivalent. Macro names are two or three characters in length. +. Pp +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 +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 +. Pq Sq \&Bf +contains a head. +. Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \(lBbody...\(rB -\&.Yc \(lBtail...\(rB -.Ed -.Pp -Block full-implicit (may contain zero or more heads, body, no tail): -.Bd -literal -offset XXXX -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB -\(lBbody...\(rB \&.Yc -.Ed -.Pp -Block partial-explicit (may contain head, multi-line body, tail): -.Bd -literal -offset XXXX -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB +. 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 \&Bd Ta \&No Ta \&No Ta closed by \&Ed +. It \&Bf Ta \&No Ta \&No Ta closed by \&Ef +. It \&Bk Ta \&No Ta \&No Ta closed by \&Ek +. It \&Bl Ta \&No Ta \&No Ta closed by \&El +. It \&Ed Ta \&No Ta \&No Ta opened by \&Bd +. It \&Ef Ta \&No Ta \&No Ta opened by \&Bf +. It \&Ek Ta \&No Ta \&No Ta opened by \&Bk +. It \&El Ta \&No Ta \&No Ta opened by \&Bl +. El +. +. +. Ss Block full-implicit +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 , +. Sq \-item +. Pc +don't have heads, while +. Sq \&It \-column +may have multiple heads. +. Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB \(lBbody...\(rB +. Ed +. Pp +. Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX" +. It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope +. It \&It Ta \&No Ta Yes Ta closed by \&It, \&El +. It \&Nd Ta \&No Ta \&No Ta closed by \&Sh +. It \&Sh Ta \&No Ta \&No Ta closed by \&Sh +. It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss +. El +. +. +. 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 +. Pq So \&Fo Sc , So \&Eo Sc +and/or tail +. Pq So \&Ec Sc . +. Bd -literal -offset indent +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB \&.Yc \(lBtail...\(rB -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \ +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ \(lBbody...\(rB \&Yc \(lBtail...\(rB -.Ed -.Pp -Block partial-implicit (no head, body, no tail): -.Bd -literal -offset XXXX -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB -.Ed -.Pp -In-line (may be closed by end-of-line, reserved character, subsequent -macro invocation or finite number of arguments): -.Bd -literal -offset XXX -\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... +. Ed +. Pp +. Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent +. It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope +. It \&Ac Ta Yes Ta Yes Ta opened by \&Ao +. It \&Ao Ta Yes Ta Yes Ta closed by \&Ac +. It \&Bc Ta Yes Ta Yes Ta closed by \&Bo +. It \&Bo Ta Yes Ta Yes Ta opened by \&Bc +. It \&Brc Ta Yes Ta Yes Ta opened by \&Bro +. It \&Bro Ta Yes Ta Yes Ta closed by \&Brc +. It \&Dc Ta Yes Ta Yes Ta opened by \&Do +. It \&Do Ta Yes Ta Yes Ta closed by \&Dc +. It \&Ec Ta Yes Ta Yes Ta opened by \&Eo +. It \&Eo Ta Yes Ta Yes Ta closed by \&Ec +. It \&Fc Ta Yes Ta Yes Ta opened by \&Fo +. It \&Fo Ta \&No Ta \&No Ta closed by \&Fc +. It \&Oc Ta Yes Ta Yes Ta closed by \&Oo +. It \&Oo Ta Yes Ta Yes Ta opened by \&Oc +. It \&Pc Ta Yes Ta Yes Ta closed by \&Po +. It \&Po Ta Yes Ta Yes Ta opened by \&Pc +. It \&Qc Ta Yes Ta Yes Ta opened by \&Oo +. It \&Qo Ta Yes Ta Yes Ta closed by \&Oc +. It \&Re Ta \&No Ta \&No Ta opened by \&Rs +. It \&Rs Ta \&No Ta \&No Ta closed by \&Re +. It \&Sc Ta Yes Ta Yes Ta opened by \&So +. It \&So Ta Yes Ta Yes Ta closed by \&Sc +. It \&Xc Ta Yes Ta Yes Ta opened by \&Xo +. It \&Xo Ta Yes Ta Yes Ta closed by \&Xc +. El +. +. +. Ss Block partial-implicit +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 indent +. It Em Macro Ta Em Callable Ta Em Parsable +. It \&Aq Ta Yes Ta Yes +. It \&Bq Ta Yes Ta Yes +. It \&Brq Ta Yes Ta Yes +. It \&D1 Ta \&No Ta \&Yes +. It \&Dl Ta \&No Ta Yes +. It \&Dq Ta Yes Ta Yes +. It \&Op Ta Yes Ta Yes +. It \&Pq Ta Yes Ta Yes +. It \&Ql Ta Yes Ta Yes +. It \&Qq Ta Yes Ta Yes +. It \&Sq Ta Yes Ta Yes +. El +. +. +. 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 -\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... ; +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... -\&.Yy \(lB\-arg \(lBval...\(rB\(rB args... Xx - -\&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN -.Ed -.\" -.Sh MACROS -This section contains a complete list of all -.Nm -macros, arranged ontologically. 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 -.Po -.Sq \&It \-bullet , -.Sq \-hyphen , -.Sq \-dash , -.Sq \-enum , -.Sq \-item -.Pc -don't have heads. -.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 -.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 . -.Pp -.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX -.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 \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek -.It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk -.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. -.Pp -.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX -.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 \&.D1 Ta \&No Ta \&Yes -.It \&.Dl Ta \&No Ta Yes -.It \&.Ql 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 . -.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 -.It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs -.It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re -.El -.\" SUB-SECTION -.Ss In-line -In-line macros have only text children. -.Pp -.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX -.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments -.It \&.Dd Ta \&No Ta \&No Ta \& -.It \&.Dt Ta \&No Ta \&No Ta \& -.It \&.Os Ta \&No Ta \&No Ta \& -.It \&.Pp Ta \&No Ta \&No Ta 0 -.It \&.Ad Ta Yes Ta Yes Ta \& -.It \&.An Ta \&No Ta Yes Ta \& -.It \&.Ar Ta Yes Ta Yes Ta \& -.It \&.Cd Ta Yes Ta \&No Ta \& -.It \&.Cm Ta Yes Ta Yes Ta \& -.It \&.Dv Ta Yes Ta Yes Ta \& -.It \&.Er Ta Yes Ta Yes Ta \& -.It \&.Ev Ta Yes Ta Yes Ta \& -.It \&.Ex Ta \&No Ta \&No Ta \& -.It \&.Fa Ta Yes Ta Yes Ta \& -.It \&.Fd Ta \&No Ta \&No Ta \& -.It \&.Fl Ta Yes Ta Yes Ta \& -.It \&.Fn Ta Yes Ta Yes Ta \& -.It \&.Ft Ta \&No Ta Yes Ta \& -.It \&.Ic Ta Yes Ta Yes Ta \& -.It \&.In Ta \&No Ta \&No Ta \& -.It \&.Li Ta Yes Ta Yes Ta \& -.It \&.Nd Ta \&No Ta \&No Ta \& -.It \&.Nm Ta Yes Ta Yes Ta \& -.It \&.Ot Ta \&No Ta \&No Ta \& -.It \&.Pa Ta Yes Ta Yes Ta \& -.It \&.Rv Ta \&No Ta \&No Ta \& -.It \&.St Ta \&No Ta Yes Ta \& -.It \&.Va Ta Yes Ta Yes Ta \& -.It \&.Vt Ta Yes Ta Yes Ta \& -.It \&.Xr Ta Yes Ta Yes Ta \& -.It \&.%A Ta \&No Ta \&No Ta \& -.It \&.%B Ta \&No Ta \&No Ta \& -.It \&.%C Ta \&No Ta \&No Ta \& -.It \&.%D Ta \&No Ta \&No Ta \& -.It \&.%I Ta \&No Ta \&No Ta \& -.It \&.%J Ta \&No Ta \&No Ta \& -.It \&.%N Ta \&No Ta \&No Ta \& -.It \&.%O Ta \&No Ta \&No Ta \& -.It \&.%P Ta \&No Ta \&No Ta \& -.It \&.%R Ta \&No Ta \&No Ta \& -.It \&.%T Ta \&No Ta \&No Ta \& -.It \&.%V Ta \&No Ta \&No Ta \& -.It \&.At Ta Yes Ta Yes Ta \& -.It \&.Bsx Ta Yes Ta Yes Ta \& -.It \&.Bx Ta Yes Ta Yes Ta \& -.It \&.Db Ta \&No Ta \&No Ta \& -.It \&.Em Ta Yes Ta Yes Ta \& -.It \&.Fx Ta Yes Ta Yes Ta \& -.It \&.Ms Ta \&No Ta Yes Ta \& -.It \&.No Ta Yes Ta Yes Ta \& -.It \&.Ns Ta Yes Ta Yes Ta \& -.It \&.Nx Ta Yes Ta Yes Ta \& -.It \&.Ox Ta Yes Ta Yes Ta \& -.It \&.Pf Ta \&No Ta Yes Ta \& -.It \&.Sm Ta \&No Ta \&No Ta \& -.It \&.Sx Ta Yes Ta Yes Ta \& -.It \&.Sy Ta Yes Ta Yes Ta \& -.It \&.Tn Ta Yes Ta Yes Ta \& -.It \&.Ux Ta Yes Ta Yes Ta \& -.It \&.Bt Ta \&No Ta \&No Ta \& -.It \&.Hf Ta \&No Ta \&No Ta \& -.It \&.Fr Ta \&No Ta \&No Ta \& -.It \&.Ud Ta \&No Ta \&No Ta \& -.It \&.Lb Ta \&No Ta \&No Ta \& -.It \&.Ap Ta Yes Ta Yes Ta \& -.It \&.Lp Ta \&No Ta \&No Ta \& -.It \&.Lk Ta \&No Ta Yes Ta \& -.It \&.Mt Ta \&No Ta Yes Ta \& -.El -.\" SECTION +\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN +. Ed +. Pp +. Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent +. It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments +. It \&%A Ta \&No Ta \&No Ta >0 +. It \&%B Ta \&No Ta \&No Ta >0 +. It \&%C Ta \&No Ta \&No Ta >0 +. It \&%D Ta \&No Ta \&No Ta >0 +. It \&%I Ta \&No Ta \&No Ta >0 +. It \&%J Ta \&No Ta \&No Ta >0 +. It \&%N Ta \&No Ta \&No Ta >0 +. It \&%O Ta \&No Ta \&No Ta >0 +. It \&%P Ta \&No Ta \&No Ta >0 +. It \&%R Ta \&No Ta \&No Ta >0 +. It \&%T Ta \&No Ta \&No Ta >0 +. It \&%V Ta \&No Ta \&No Ta >0 +. It \&Ad Ta Yes Ta Yes Ta n +. It \&An Ta Yes Ta Yes Ta n +. It \&Ap Ta Yes Ta Yes Ta 0 +. It \&Ar Ta Yes Ta Yes Ta n +. It \&At Ta Yes Ta Yes Ta 1 +. It \&Bsx Ta Yes Ta Yes Ta n +. It \&Bt Ta \&No Ta \&No Ta 0 +. It \&Bx Ta Yes Ta Yes Ta n +. It \&Cd Ta Yes Ta Yes Ta >0 +. It \&Cm Ta Yes Ta Yes Ta n +. It \&Db Ta \&No Ta \&No Ta 1 +. It \&Dd Ta \&No Ta \&No Ta >0 +. It \&Dt Ta \&No Ta \&No Ta n +. It \&Dv Ta Yes Ta Yes Ta n +. It \&Dx Ta Yes Ta Yes Ta n +. It \&Em Ta Yes Ta Yes Ta >0 +. It \&En Ta \&No Ta \&No Ta 0 +. It \&Er Ta Yes Ta Yes Ta >0 +. It \&Es Ta \&No Ta \&No Ta 0 +. It \&Ev Ta Yes Ta Yes Ta n +. It \&Ex Ta \&No Ta \&No Ta 0 +. It \&Fa Ta Yes Ta Yes Ta n +. It \&Fd Ta \&No Ta \&No Ta >0 +. It \&Fl Ta Yes Ta Yes Ta n +. It \&Fn Ta Yes Ta Yes Ta >0 +. It \&Fr Ta \&No Ta \&No Ta n +. It \&Ft Ta Yes Ta Yes Ta n +. It \&Fx Ta Yes Ta Yes Ta n +. It \&Hf Ta \&No Ta \&No Ta n +. It \&Ic Ta Yes Ta Yes Ta >0 +. It \&In Ta \&No Ta \&No Ta n +. It \&Lb Ta \&No Ta \&No Ta 1 +. It \&Li Ta Yes Ta Yes Ta n +. It \&Lk Ta Yes Ta Yes Ta n +. It \&Lp Ta \&No Ta \&No Ta 0 +. It \&Ms Ta Yes Ta Yes Ta >0 +. It \&Mt Ta Yes Ta Yes Ta >0 +. It \&Nm Ta Yes Ta Yes Ta n +. It \&No Ta Yes Ta Yes Ta 0 +. It \&Ns Ta Yes Ta Yes Ta 0 +. It \&Nx Ta Yes Ta Yes Ta n +. It \&Os Ta \&No Ta \&No Ta n +. It \&Ot Ta \&No Ta \&No Ta n +. It \&Ox Ta Yes Ta Yes Ta n +. It \&Pa Ta Yes Ta Yes Ta n +. It \&Pf Ta \&No Ta Yes Ta 1 +. It \&Pp Ta \&No Ta \&No Ta 0 +. It \&Rv Ta \&No Ta \&No Ta 0 +. It \&Sm Ta \&No Ta \&No Ta 1 +. It \&St Ta \&No Ta Yes Ta 1 +. It \&Sx Ta Yes Ta Yes Ta >0 +. It \&Sy Ta Yes Ta Yes Ta >0 +. It \&Tn Ta Yes Ta Yes Ta >0 +. It \&Ud Ta \&No Ta \&No Ta 0 +. It \&Ux Ta Yes Ta Yes Ta n +. It \&Va Ta Yes Ta Yes Ta n +. It \&Vt Ta Yes Ta Yes Ta >0 +. It \&Xr Ta Yes Ta Yes Ta >0, <3 +. It \&br Ta \&No Ta \&No Ta 0 +. It \&sp Ta \&No Ta \&No Ta 1 +. El +. +. +.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 +The +. Sq \-split +or +. Sq \-nosplit +argument to +. Sq \&An +applies to the whole document, not just to the current section as it +does in groff. +. 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 +The +. Sq \&sp +macro does not accept negative numbers. +. 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 +. Sq \&It \-nested +is assumed for all lists (it wasn't in historic groff): any list may be +nested and +. Sq \-enum +lists will restart the sequence only for the sub-list. +. It +. Sq \&It \-column +syntax where column widths may be preceded by other arguments (instead +of proceeded) is not supported. +. It +The +. Sq \&At +macro only accepts a single parameter. +. It +Some manuals use +. Sq \&Li +incorrectly by following it with a reserved character and expecting the +delimiter to render. This is not supported. +. It +In groff, the +. Sq \&Fo +macro only produces the first parameter. This is no longer the case. +. El +. +. .Sh SEE ALSO -.Xr mdoctree 1 , -.Xr mdoclint 1 , -.Xr mdocterm 1 , -.Xr mdoc 3 -.\" SECTION +. Xr mandoc 1 , +. Xr mandoc_char 7 +. +. .Sh AUTHORS The -.Nm -utility was written by -.An Kristaps Dzonsons Aq kristaps@kth.se . +. Nm +reference was written by +. An Kristaps Dzonsons Aq kristaps@kth.se . +. +. +.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 +.