=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.56 retrieving revision 1.82 diff -u -p -r1.56 -r1.82 --- mandoc/mdoc.7 2009/08/18 14:27:16 1.56 +++ mandoc/mdoc.7 2010/01/07 19:10:10 1.82 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.56 2009/08/18 14:27:16 kristaps Exp $ +.\" $Id: mdoc.7,v 1.82 2010/01/07 19:10:10 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -14,613 +14,2065 @@ .\" 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: January 7 2010 $ .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" , -is also ignored. +.Sq \&.\e" , +is also ignored. Macro lines with only a control charater and optionally +whitespace are stripped from input. . . -. 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 +.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 -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. +.Sq \ef +escape followed by an indicator: B (bold), I, (italic), R (Roman), or P +(revert to previous mode): +.Pp +.D1 \efBbold\efR \efIitalic\efP +.Pp +A numerical representation 3, 2, or 1 (bold, italic, and Roman, +respectively) may be used instead. A text decoration is valid within +the current font scope only: if a macro opens a font scope alongside +its own scope, such as +.Sx \&Bf +.Cm \&Sy , +in-scope invocations of +.Sq \ef +are only valid within the font scope of the macro. If +.Sq \ef +is specified outside of any font scope, such as in unenclosed, free-form +text, it will affect the remainder of the document. +.Pp +Text may also be sized with the +.Sq \es +escape, whose syntax is one of +.Sq \es+-n +for one-digit numerals; +.Sq \es(+-nn +or +.Sq \es+-(nn +for two-digit numerals; and +.Sq \es[+-N] , +.Sq \es+-[N] , +.Sq \es'+-N' , +or +.Sq \es+-'N' +for arbitrary-digit numerals: +.Pp +.D1 \es+1bigger\es-1 +.D1 \es[+10]much bigger\es[-10] +.D1 \es+(10much bigger\es-(10 +.D1 \es+'100'much much bigger\es-'100' +.Pp +Note these forms are +.Em not +recommended for +.Nm , +which encourages semantic annotation. . . -. Ss Predefined Strings -Historically, -. Xr groff 1 -also defined a set of package-specific -. Dq predefined strings , -which, like -. Sx Special Characters , +.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* : +.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. . +.Ss Dates +There are several macros in +.Nm +that require a date argument. The canonical form for dates is the +American format: +.Pp +.D1 Cm Month Day , Year +.Pp +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 +Reduced form dates are broken-down canonical form dates: +.Pp +.D1 Cm Month , Year +.D1 Cm Year +.Pp +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 +.Pp +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 -Each -. Nm -document must begin with a document prologue, containing, in order, -. Sq \&Dd , -. Sq \&Dt , +A well-formed +.Nm +document consists of a document prologue followed by one or more +sections. +.Pp +The prologue, which consists of (in order) the +.Sx \&Dd , +.Sx \&Dt , and -. Sq \&Os , -then the NAME section containing at least one -. Sq \&Nm +.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 -. Sq \&Nd : -. Bd -literal -offset indent +.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 mdoc -\&.Nd mdoc language reference -. Ed -. Pp -Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged, -but non-compulsory. +\&.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. +.Pp +See +.Sx \&Nm +and +.Sx \&Nd . . +.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 . . +.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 . +.Pp +See +.Sx \&Op , +.Sx \&Cd , +.Sx \&Fn , +.Sx \&Ft , +and +.Sx \&Vt . +. +.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 +.Pp +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 +.Fl 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 +. +. .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 -and -. Sq \&.\ \ \ \&Pp -are equivalent. Macro names are two or three characters in length. -. Pp +sit between the control character and the macro name. Thus, the +following are equivalent: +.Bd -literal -offset indent +\&.Pp +\&.\ \ \ \&Pp +.Ed +. +.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 +.Sx \&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 +.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 . -. Ss Block full-implicit +. +.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 +.Po +.Sx \&It Fl bullet , +.Fl hyphen , +.Fl dash , +.Fl enum , +.Fl item +.Pc +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 -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 +.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 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 . -. Ss Block partial-explicit +. +.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 +.Po +.Sx \&Fo , +.Sx \&Eo +.Pc and/or tail -. Pq So \&Ec Sc . -. Bd -literal -offset indent +.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 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 +.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 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 . -. Ss Block partial-implicit +. +.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 +.Ed . +.Pp +.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent +.It Em Macro Ta Em Callable Ta Em Parsable +.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 . -. Ss In-line +. +.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 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 +.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 +.\" Begins a list composed of one or more list entries. A list entry is +.\" specified by the +.\" .Sx \&It +.\" macro, which consists of a head and optional body. By default, a list +.\" is preceded by a blank line. A list must specify one of the following +.\" list types: +.\" .Bl -tag -width 12n +.\" .It Fl bullet +.\" A list offset by a bullet. The head of list entries must be empty. +.\" List entry bodies are justified after the bullet. +.\" .It Fl column +.\" A columnated list. The number of columns is specified as arguments to +.\" the +.\" .Sx \&Bl +.\" macro (the deprecated form of following the invocation of +.\" .Fl column +.\" is also accepted). Arguments dictate the width of columns specified in +.\" list entries. List entry bodies must be left empty. Columns specified +.\" in the list entry head are justified to their position in the sequence +.\" of columns. +.\" .It Fl dash +.\" A list offset by a dash (hyphen). The head of list entries must be +.\" empty. List entry bodies are justified past the dash. +.\" .It Fl diag +.\" Like +.\" .Fl inset +.\" lists, but with additional formatting to the head. +.\" .It Fl enum +.\" A list offset by a number indicating list entry position. The head of +.\" list entries must be empty. List entry bodies are justified past the +.\" enumeration. +.\" .It Fl hang +.\" Like +.\" .Fl tag , +.\" but instead of list bodies justifying to the head on the first line, +.\" they trail the head text. +.\" .It Fl hyphen +.\" Synonym for +.\" .Fl dash . +.\" .It Fl inset +.\" Like +.\" .Fl tag , +.\" but list entry bodies aren't justified. +.\" .It Fl item +.\" An un-justified list. This produces blocks of text. +.\" .It Fl ohang +.\" List bodies are placed on the line following the head. +.\" .It Fl tag +.\" A list offset by list entry heads. List entry bodies are justified +.\" after the head. +.\" .El +.\" .Pp +.\" More... +.\" . +.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 +Command-line flag. Used when listing arguments to command-line +utilities. Prints a fixed-width hyphen +.Sq \- +before each delimited argument. If no arguments are provided, a hyphen +is still printed. +.Pp +Examples: +.Bd -literal -offset indent +\&.Fl a b c +\&.Fl +\&.Op Fl o Ns Ar file +.Ed +.Pp +See also +.Sx \&Cm . +. +.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 . +.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 -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 +.Pq somewhere between 1.15 and 1.19 . +. +.Pp +.Bl -dash -compact +.It +The comment syntax +.Sq \e." +is no longer accepted. +.It +In +.Xr groff 1 , +the +.Sx \&Pa +macro does not format its arguments when used in the FILES section under +certain list types. This irregular behaviour has been discontinued. +.It +Historic +.Xr groff 1 +does not print a dash for empty +.Sx \&Fl +arguments. This behaviour has been discontinued. +.It +.Xr groff 1 +behaves strangely (even between versions) when specifying +.Sq \ef +escapes within line-macro scopes. These aberrations have been +normalised. +.It +Negative scaling units are now truncated to zero instead of creating +interesting conditions, such as with +.Sx \&sp +.Fl 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 +.It +Display types +.Sx \&Bd +.Fl center +and +.Fl right +are aliases for +.Fl left . The -. Sq \&sp -macro does not accept negative numbers. -. It +.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 +.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 +.Sx \&It +.Fl nested is assumed for all lists (it wasn't in historic groff): any list may be nested and -. Sq \-enum +.Fl 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 +.It Some manuals use -. Sq \&Li +.Sx \&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 +.Sx \&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 . -. -. -.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 -. +.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 +.\" .