diff options
Diffstat (limited to 'mdoc.7')
| -rw-r--r-- | mdoc.7 | 734 |
1 files changed, 376 insertions, 358 deletions
@@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.56 2009/08/18 14:27:16 kristaps Exp $ +.\" $Id: mdoc.7,v 1.57 2009/08/20 12:08:40 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se> .\" @@ -14,215 +14,222 @@ .\" 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 $ +.Dd $Mdocdate: August 20 2009 $ .Dt MDOC 7 .Os . . .Sh NAME -. Nm mdoc -. Nd mdoc language reference +.Nm mdoc +.Nd mdoc language reference . . .Sh DESCRIPTION The -. Nm mdoc +.Nm mdoc language is used to format -. Bx -. Ux +.Bx +.Ux manuals. In this reference document, we describe its syntax, structure, and usage. Our reference implementation is -. Xr mandoc 1 . +.Xr mandoc 1 . The -. Sx COMPATIBILITY +.Sx COMPATIBILITY section describes compatibility with -. Xr groff 1 . -. Pp +.Xr groff 1 . +. +.Pp An -. Nm +.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: -. Bd -literal -offset indent +.Bd -literal -offset indent \&.Sh Macro lines change control state. Other lines are interpreted within the current state. -. Ed +.Ed . . .Sh LANGUAGE SYNTAX -. Nm +.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 +.Ux line terminators. . . -. Ss Comments +.Ss Comments Text following a -. Sq \e" , +.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" , +.Sq \&.\e" , is also ignored. . . -. Ss Reserved Characters +.Ss Reserved Characters Within a macro line, the following characters are reserved: -. 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 +.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 . +.Sx MACRO SYNTAX . For general use in macro lines, these characters must either be escaped with a non-breaking space -. Pq Sq \e& +.Pq Sq \e& or, if applicable, an appropriate escape sequence used. . . -. Ss Special Characters +.Ss Special Characters Special characters may occur in both macro and free-form lines. Sequences begin with the escape character -. Sq \e +.Sq \e followed by either an open-parenthesis -. Sq \&( +.Sq \&( for two-character sequences; an open-bracket -. Sq \&[ +.Sq \&[ for n-character sequences (terminated at a close-bracket -. Sq \&] ) ; +.Sq \&] ) ; or a single one-character sequence. See -. Xr mandoc_char 7 +.Xr mandoc_char 7 for a complete list. Examples include -. Sq \e(em -. Pq em-dash +.Sq \e(em +.Pq em-dash and -. Sq \ee -. Pq back-slash . +.Sq \ee +.Pq back-slash . . . -. Ss Text Decoration +.Ss Text Decoration Terms may be text-decorated using the -. Sq \ef +.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 , +.Nm , which encourages semantic, not presentation, annotation. . . -. Ss Predefined Strings +.Ss Predefined Strings Historically, -. Xr groff 1 +.Xr groff 1 also defined a set of package-specific -. Dq predefined strings , +.Dq predefined strings , which, like -. Sx Special Characters , +.Sx Special Characters , demark special output characters and strings by way of input codes. Predefined strings are escaped with the slash-asterisk, -. Sq \e* : +.Sq \e* : single-character -. Sq \e*X , +.Sq \e*X , two-character -. Sq \e*(XX , +.Sq \e*(XX , and N-character -. Sq \e*[N] . +.Sq \e*[N] . See -. Xr mandoc_char 7 +.Xr mandoc_char 7 for a complete list. Examples include -. Sq \e*(Am -. Pq ampersand +.Sq \e*(Am +.Pq ampersand and -. Sq \e*(Ba -. Pq vertical bar . +.Sq \e*(Ba +.Pq vertical bar . . . -. Ss Whitespace +.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 +.Bd -literal -offset indent These spaces are pruned from input. \&.Bd \-literal These are not. \&.Ed -. Ed -. Pp +.Ed +. +.Pp In macro lines, whitespace delimits arguments and is discarded. If arguments are quoted, whitespace within the quotes is retained. -. Pp +. +.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 +.Sq \&Bl \-column or when in a literal context. . . -. Ss Quotation +.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 +. +.Pp This produces tokens -. Sq a" , -. Sq b c , -. Sq de , +.Sq a" , +.Sq b c , +.Sq de , and -. Sq fg" . +.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 +.Sq \&Em a : +.Bd -literal -offset indent \&.Em "Em a" -. Ed -. Pp +.Ed +. +.Pp In free-form mode, quotes are regarded as opaque text. . . .Sh MANUAL STRUCTURE Each -. Nm +.Nm document must begin with a document prologue, containing, in order, -. Sq \&Dd , -. Sq \&Dt , +.Sq \&Dd , +.Sq \&Dt , and -. Sq \&Os , +.Sq \&Os , then the NAME section containing at least one -. Sq \&Nm +.Sq \&Nm followed by -. Sq \&Nd : -. Bd -literal -offset indent +.Sq \&Nd : +.Bd -literal -offset indent \&.Dd $\&Mdocdate$ \&.Dt mdoc 7 \&.Os \&.Sh NAME \&.Nm mdoc \&.Nd mdoc language reference -. Ed -. Pp +.Ed +. +.Pp Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged, but non-compulsory. . @@ -230,397 +237,408 @@ but non-compulsory. .Sh MACRO SYNTAX Macros are one to three three characters in length and begin with a control character , -. Sq \&. , +.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 +.Sq \&.Pp and -. Sq \&.\ \ \ \&Pp +.Sq \&.\ \ \ \&Pp are equivalent. Macro names are two or three characters in length. -. Pp +. +.Pp The syntax of a macro depends on its classification. In this section, -. Sq \-arg +.Sq \-arg refers to macro arguments, which may be followed by zero or more -. Sq parm +.Sq parm parameters; -. Sq \&Yo +.Sq \&Yo opens the scope of a macro; and if specified, -. Sq \&Yc +.Sq \&Yc closes it out. -. Pp +. +.Pp The -. Em Callable +.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 +.Sq \&.Fl Sh produces -. Sq Fl Sh . -. Pp +.Sq Fl Sh . +. +.Pp The -. Em Parsable +.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 +. +.Pp The -. Em Scope +.Em Scope column, if applicable, describes closure rules. . . -. Ss Block full-explicit +.Ss Block full-explicit Multi-line scope closed by an explicit closing macro. All macros contains bodies; only -. Pq Sq \&Bf +.Pq Sq \&Bf contains a head. -. Bd -literal -offset indent +.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 \&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 +.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 +.Po +.Sq \&It \-bullet , +.Sq \-hyphen , +.Sq \-dash , +.Sq \-enum , +.Sq \-item +.Pc don't have heads, while -. Sq \&It \-column +.Sq \&It \-column may have multiple heads. -. Bd -literal -offset indent +.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 +.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 +.Pq So \&Fo Sc , So \&Eo Sc and/or tail -. Pq So \&Ec Sc . -. Bd -literal -offset indent +.Pq So \&Ec Sc . +.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 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 +.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 +.Sx Reserved Characters or end of line. -. Bd -literal -offset indent +.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 +.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 , +.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 , +.Pq n , then the macro accepts an arbitrary number of arguments. -. Bd -literal -offset indent +.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" "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 +.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 . +.Xr groff 1 . The term -. Qq historic groff +.Qq historic groff refers to those versions before the -. Pa doc.tmac +.Pa doc.tmac file re-write -. Pq somewhere between 1.15 and 1.19 . -. Pp -. Bl -dash -compact -. It +.Pq somewhere between 1.15 and 1.19 . +. +.Pp +.Bl -dash -compact +.It The -. Sq \-split +.Sq \-split or -. Sq \-nosplit +.Sq \-nosplit argument to -. Sq \&An +.Sq \&An applies to the whole document, not just to the current section as it does in groff. -. It +.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 +.It The -. Sq \&sp +.Sq \&sp macro does not accept negative numbers. -. It +.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 +.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 +.It The vertical bar -. Sq \(ba +.Sq \(ba made historic groff -. Qq go orbital +.Qq go orbital but is a proper delimiter in this implementation. -. It -. Sq \&It \-nested +.It +.Sq \&It \-nested is assumed for all lists (it wasn't in historic groff): any list may be nested and -. Sq \-enum +.Sq \-enum lists will restart the sequence only for the sub-list. -. It -. Sq \&It \-column +.It +.Sq \&It \-column syntax where column widths may be preceded by other arguments (instead of proceeded) is not supported. -. It +.It The -. Sq \&At +.Sq \&At macro only accepts a single parameter. -. It +.It Some manuals use -. Sq \&Li +.Sq \&Li incorrectly by following it with a reserved character and expecting the delimiter to render. This is not supported. -. It +.It In groff, the -. Sq \&Fo +.Sq \&Fo macro only produces the first parameter. This is no longer the case. -. El +.El . . .Sh SEE ALSO -. Xr mandoc 1 , -. Xr mandoc_char 7 +.Xr mandoc 1 , +.Xr mandoc_char 7 . . .Sh AUTHORS The -. Nm +.Nm reference was written by -. An Kristaps Dzonsons Aq kristaps@kth.se . +.An Kristaps Dzonsons Aq kristaps@kth.se . . . .Sh CAVEATS There are many ambiguous parts of mdoc. -. Pp -. Bl -dash -compact -. It -. Sq \&Fa +. +.Pp +.Bl -dash -compact +.It +.Sq \&Fa should be -. Sq \&Va +.Sq \&Va as function arguments are variables. -. It -. Sq \&Ft +.It +.Sq \&Ft should be -. Sq \&Vt +.Sq \&Vt as function return types are still types. Furthermore, the -. Sq \&Ft +.Sq \&Ft should be removed and -. Sq \&Fo , +.Sq \&Fo , which ostensibly follows it, should follow the same convention as -. Sq \&Va . -. It -. Sq \&Va +.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 +.It +.Sq \&Fd is ambiguous. It's commonly used to indicate an include file in the synopsis section. -. Sq \&In +.Sq \&In should be used, instead. -. It +.It Only the -. Sq \-literal +.Sq \-literal argument to -. Sq \&Bd +.Sq \&Bd makes sense. The remaining ones should be removed. -. It +.It The -. Sq \&Xo +.Sq \&Xo and -. Sq \&Xc +.Sq \&Xc macros should be deprecated. -. It +.It The -. Sq \&Dt +.Sq \&Dt macro lacks clarity. It should be absolutely clear which title will render when formatting the manual page. -. It +.It A -. Sq \&Lx +.Sq \&Lx should be provided for Linux (\(`a la -. Sq \&Ox , -. Sq \&Nx +.Sq \&Ox , +.Sq \&Nx etc.). -. It +.It There's no way to refer to references in -. Sq \&Rs/Re +.Sq \&Rs/Re blocks. -. It +.It The \-split and \-nosplit dictates via -. Sq \&An +.Sq \&An are re-set when entering and leaving the AUTHORS section. -. El +.El . |