X-Git-Url: https://git.cameronkatri.com/mandoc.git/blobdiff_plain/7f67988eac2d1c3957c780d882706906cbb3b441..9425244d2b742390e69a9fedde12afadefb6802b:/mdoc.7 diff --git a/mdoc.7 b/mdoc.7 index 439383c3..ff47d5ae 100644 --- a/mdoc.7 +++ b/mdoc.7 @@ -1,6 +1,7 @@ -.\" $Id: mdoc.7,v 1.119 2010/06/04 22:16:27 kristaps Exp $ +.\" $Id: mdoc.7,v 1.159 2010/09/26 19:46:48 schwarze Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -14,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 4 2010 $ +.Dd $Mdocdate: September 26 2010 $ .Dt MDOC 7 .Os .Sh NAME @@ -26,8 +27,12 @@ The language is used to format .Bx .Ux -manuals. In this reference document, we describe its syntax, structure, -and usage. Our reference implementation is mandoc; the +manuals. +This reference document describes its syntax, structure, and +usage. +The reference implementation is +.Xr mandoc 1 ; +the .Sx COMPATIBILITY section describes compatibility with other troff \-mdoc implementations. .Pp @@ -36,7 +41,8 @@ An document follows simple rules: lines beginning with the control character .Sq \. -are parsed for macros. Other lines are interpreted within the scope of +are parsed for macros. +Other lines are interpreted within the scope of prior macros: .Bd -literal -offset indent \&.Sh Macro lines change control state. @@ -45,18 +51,20 @@ Other lines are interpreted within the current state. .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 +character, and, in certain circumstances, the tab character. +All manuals must have .Ux line terminators. .Ss Comments Text following a -.Sq \e" , +.Sq \e\*q , whether in a macro or free-form text line, is ignored to the end of -line. A macro line with only a control character and comment escape, -.Sq \&.\e" , -is also ignored. Macro lines with only a control charater and optionally -whitespace are stripped from input. +line. +A macro line with only a control character and comment escape, +.Sq \&.\e\*q , +is also ignored. +Macro lines with only a control character and optional whitespace are +stripped from input. .Ss Reserved Characters Within a macro line, the following characters are reserved: .Pp @@ -87,10 +95,10 @@ Within a macro line, the following characters are reserved: .Pp Use of reserved characters is described in .Sx MACRO SYNTAX . -For general use in macro lines, these characters must either be escaped +For general use in macro lines, these characters can either be escaped with a non-breaking space .Pq Sq \e& -or, if applicable, an appropriate escape sequence used. +or, if applicable, an appropriate escape sequence can be used. .Ss Special Characters Special characters may occur in both macro and free-form lines. Sequences begin with the escape character @@ -101,7 +109,7 @@ for two-character sequences; an open-bracket .Sq \&[ for n-character sequences (terminated at a close-bracket .Sq \&] ) ; -or a single one-character sequence. +or a single one character sequence. See .Xr mandoc_char 7 for a complete list. @@ -114,7 +122,7 @@ and .Ss Text Decoration Terms may be text-decorated using the .Sq \ef -escape followed by an indicator: B (bold), I, (italic), R (Roman), or P +escape followed by an indicator: B (bold), I (italic), R (Roman), or P (revert to previous mode): .Pp .D1 \efBbold\efR \efIitalic\efP @@ -134,40 +142,19 @@ If 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 +Note this form is .Em not recommended for .Nm , which encourages semantic annotation. .Ss Predefined Strings Historically, -.Xr groff 1 +troff 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. +mark special output characters and strings by way of input codes. Predefined strings are escaped with the slash-asterisk, .Sq \e* : single-character @@ -187,7 +174,7 @@ and .Pq vertical bar . .Ss Whitespace Whitespace consists of the space character. -In free-form lines, whitespace is preserved within a line; un-escaped +In free-form lines, whitespace is preserved within a line; unescaped trailing spaces are stripped from input (unless in a literal context). Blank free-form lines, which may include whitespace, are only permitted within literal contexts. @@ -195,24 +182,18 @@ within literal contexts. In macro lines, whitespace delimits arguments and is discarded. If arguments are quoted, whitespace within the quotes is retained. .Ss Quotation -Macro arguments may be quoted with a double-quote to group +Macro arguments may be quoted with double-quotes 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 +The next double-quote not pairwise 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. +Note that any quoted text, even if it would cause a macro invocation +when unquoted, is considered literal text. Thus, the following produces -.Sq \&Em a : +.Sq Op "Fl a" : .Bd -literal -offset indent -\&.Em "Em a" +\&.Op "Fl a" .Ed .Pp In free-form mode, quotes are regarded as opaque text. @@ -297,7 +278,7 @@ is necessarily non-portable across output media. See .Sx COMPATIBILITY . .Ss Sentence Spacing -When composing a manual, make sure that your sentences end at the end of +When composing a manual, make sure that sentences end at the end of a line. By doing so, front-ends will be able to apply the proper amount of spacing after the end of sentence (unescaped) period, exclamation mark, @@ -309,7 +290,8 @@ delimiters ( .Sq \&" ) . .Pp The proper spacing is also intelligently preserved if a sentence ends at -the boundary of a macro line, e.g., +the boundary of a macro line. +For example: .Pp .D1 \&Xr mandoc 1 \. .D1 \&Fl T \&Ns \&Cm ascii \. @@ -319,12 +301,12 @@ A well-formed document consists of a document prologue followed by one or more sections. .Pp -The prologue, which consists of (in order) the +The prologue, which consists of the .Sx \&Dd , .Sx \&Dt , and .Sx \&Os -macros, is required for every document. +macros in that order, is required for every document. .Pp The first section (sections are denoted by .Sx \&Sh ) @@ -333,8 +315,11 @@ must be the NAME section, consisting of at least one followed by .Sx \&Nd . .Pp -Following that, convention dictates specifying at least the SYNOPSIS and -DESCRIPTION sections, although this varies between manual sections. +Following that, convention dictates specifying at least the +.Em SYNOPSIS +and +.Em DESCRIPTION +sections, although this varies between manual sections. .Pp The following is a well-formed skeleton .Nm @@ -346,8 +331,9 @@ file: \&.Sh NAME \&.Nm foo \&.Nd a description goes here -\&.\e\*q The next is for sections 2, 3, & 9 only. \&.\e\*q .Sh LIBRARY +\&.\e\*q For sections 2, 3, & 9 only. +\&.\e\*q Not used in OpenBSD. \&.Sh SYNOPSIS \&.Nm foo \&.Op Fl options @@ -357,18 +343,19 @@ The \&.Nm utility processes files ... \&.\e\*q .Sh IMPLEMENTATION NOTES -\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q Not used in OpenBSD. \&.\e\*q .Sh RETURN VALUES -\&.\e\*q The next is for sections 1, 6, 7, & 8 only. +\&.\e\*q For sections 2, 3, & 9 only. \&.\e\*q .Sh ENVIRONMENT +\&.\e\*q For sections 1, 6, 7, & 8 only. \&.\e\*q .Sh FILES -\&.\e\*q The next is for sections 1 & 8 only. \&.\e\*q .Sh EXIT STATUS +\&.\e\*q For sections 1, 6, & 8 only. \&.\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 For sections 1, 4, 6, 7, & 8 only. \&.\e\*q .Sh ERRORS +\&.\e\*q For sections 2, 3, & 9 only. \&.\e\*q .Sh SEE ALSO \&.\e\*q .Xr foobar 1 \&.\e\*q .Sh STANDARDS @@ -377,21 +364,22 @@ utility processes files ... \&.\e\*q .Sh CAVEATS \&.\e\*q .Sh BUGS \&.\e\*q .Sh SECURITY CONSIDERATIONS +\&.\e\*q Not used in OpenBSD. .Ed .Pp -The sections in a +The sections in an .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 name(s) and a one line description of the documented material. The syntax for this as follows: .Bd -literal -offset indent -\&.Nm name0 -\&.Nm name1 +\&.Nm name0 , +\&.Nm name1 , \&.Nm name2 -\&.Nd a short description +\&.Nd a one line description .Ed .Pp The @@ -433,8 +421,8 @@ generally structured as follows: .Pp For the second, function calls (sections 2, 3, 9): .Bd -literal -offset indent -\&.Vt extern const char *global; \&.In header.h +\&.Vt extern const char *global; \&.Ft "char *" \&.Fn foo "const char *src" \&.Ft "char *" @@ -450,17 +438,48 @@ And for the third, configurations (section 4): Manuals not in these sections generally don't need a .Em SYNOPSIS . .Pp -See -.Sx \&Op , +Some macros are displayed differently in the +.Em SYNOPSIS +section, particularly +.Sx \&Nm , .Sx \&Cd , +.Sx \&Fd , .Sx \&Fn , -.Sx \&Ft , +.Sx \&Fo , +.Sx \&In , +.Sx \&Vt , and -.Sx \&Vt . +.Sx \&Ft . +All of these macros are output on their own line. +If two such dissimilar macros are pairwise invoked (except for +.Sx \&Ft +before +.Sx \&Fo +or +.Sx \&Fn ) , +they are separated by a vertical space, unless in the case of +.Sx \&Fo , +.Sx \&Fn , +and +.Sx \&Ft , +which are always separated by vertical space. +.Pp +When text and macros following an +.Sx \&Nm +macro starting an input line span multiple output lines, +all output lines but the first will be indented to align +with the text immediately following the +.Sx \&Nm +macro, up to the next +.Sx \&Nm , +.Sx \&Sh , +or +.Sx \&Ss +macro or the end of an enclosing block, whichever comes first. .It Em DESCRIPTION -This expands upon the brief, one-line description in +This expands upon the brief, one line description in .Em NAME . -It usually contains a break-down of the options (if documenting a +It usually contains a breakdown of the options (if documenting a command), such as: .Bd -literal -offset indent The arguments are as follows: @@ -476,31 +495,30 @@ 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 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. +This section 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 . +Lists the environment variables used by the utility, +and explains the syntax and semantics of their values. +The +.Xr environ 7 +manual provides examples of typical content and formatting. .Pp See .Sx \&Ev . .It Em FILES Documents files used. -It's helpful to document both the file and a short description of how +It's helpful to document both the file name and a short description of how the file is used (created, modified, etc.). .Pp See .Sx \&Pa . .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. +This section documents the +command exit status for section 1, 6, and 8 utilities. Historically, this information was described in .Em DIAGNOSTICS , a practise that is now discouraged. @@ -510,7 +528,7 @@ See .It Em EXAMPLES Example usages. This often contains snippets of well-formed, well-tested invocations. -Make doubly sure that your examples work properly! +Make sure that examples work properly! .It Em DIAGNOSTICS Documents error conditions. This is most useful in section 4 manuals. @@ -544,26 +562,25 @@ section should be used instead. See .Sx \&St . .It Em HISTORY -The history of any manual without a -.Em STANDARDS -section should be described in this section. +A brief history of the subject, including where support first appeared. .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. +Credits to the person or persons who wrote the code and/or documentation. +Authors should generally be noted by both name and email address. .Pp See .Sx \&An . .It Em CAVEATS -Explanations of common misuses and misunderstandings should be explained +Common misuses and misunderstandings should be explained in this section. .It Em BUGS -Extant bugs should be described in this section. +Known bugs, limitations, and work-arounds 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 , +control character, .Sq \&. , at the beginning of the line. An arbitrary amount of whitespace may sit between the control character @@ -596,10 +613,10 @@ produces .Sq Fl \&Sh . .Pp The -.Em Parsable +.Em Parsed 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 +If a macro is not parsed, subsequent macro invocations on the line will be interpreted as opaque text. .Pp The @@ -616,8 +633,8 @@ contains a head. \&.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 +.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX" +.It Em Macro Ta Em Callable Ta Em Parsed 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 @@ -639,7 +656,9 @@ All macros have bodies; some .Pc don't have heads; only one .Po -.Sx \&It Fl column +.Sx \&It +in +.Sx \&Bl Fl column .Pc has multiple heads. .Bd -literal -offset indent @@ -647,13 +666,24 @@ has multiple heads. \(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 +.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" +.It Em Macro Ta Em Callable Ta Em Parsed 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 \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss .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 +.Pp +Note that the +.Sx \&Nm +macro is a +.Sx Block full-implicit +macro only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . .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 @@ -672,8 +702,8 @@ and/or tail \(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 +.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed 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 @@ -707,8 +737,8 @@ or end of line. \&.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 +.Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed .It Sx \&Aq Ta Yes Ta Yes .It Sx \&Bq Ta Yes Ta Yes .It Sx \&Brq Ta Yes Ta Yes @@ -741,15 +771,15 @@ If a number (or inequality) of arguments is .Pq n , then the macro accepts an arbitrary number of arguments. .Bd -literal -offset indent -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb +\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(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 +.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent +.It Em Macro Ta Em Callable Ta Em Parsed 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 @@ -775,7 +805,7 @@ then the macro accepts an arbitrary number of arguments. .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 \&Dd Ta \&No Ta \&No Ta n .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 @@ -833,28 +863,27 @@ For the scoping of individual macros, see .Ss \&%A Author name of an .Sx \&Rs -block. Multiple authors should each be accorded their own +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. +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 +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 +block. +This should follow the reduced or canonical form syntax described in .Sx Dates . .Ss \&%I Publisher or issuer name of an @@ -879,7 +908,8 @@ block. .Ss \&%Q Institutional author (school, government, etc.) of an .Sx \&Rs -block. Multiple institutional authors should each be accorded their own +block. +Multiple institutional authors should each be accorded their own .Sx \&%Q line. .Ss \&%R @@ -889,8 +919,9 @@ 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. +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 @@ -898,51 +929,50 @@ Volume number of an .Sx \&Rs block. .Ss \&Ac -Closes an +Close an .Sx \&Ao -block. Does not have any tail arguments. +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. +Memory address. +Do not use this for postal addresses. .Pp Examples: .D1 \&.Ad [0,$] .D1 \&.Ad 0x00000000 .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 +Requires either the name of an author or one of the following arguments: +.Pp +.Bl -tag -width "-nosplitX" -offset indent -compact .It Fl split -Renders a line break before each author listing. +Start a new output line before each subsequent invocation of +.Sx \&An . .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 +The default is +.Fl nosplit . +The effect of selecting either of the .Fl split -will cause the first listing also to be split. -If not in the AUTHORS section, the default is not to split. +modes ends at the beginning of the +.Em AUTHORS +section. +In the +.Em AUTHORS +section, the default is +.Fl nosplit +for the first author listing and +.Fl split +for all other author listings. .Pp Examples: .D1 \&.An -nosplit -.D1 \&.An J. D. Ullman . -.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. +.D1 \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv .Ss \&Ao -Begins a block enclosed by angled brackets. +Begin a block enclosed by angle brackets. Does not have any head arguments. .Pp Examples: @@ -951,14 +981,14 @@ Examples: 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 +Inserts an apostrophe without any surrounding whitespace. +This is generally used as a grammatical device when referring to the verb +form of a function. +.Pp +Examples: +.D1 \&.Fn execve \&Ap d .Ss \&Aq -Encloses its arguments in angled brackets. +Encloses its arguments in angle brackets. .Pp Examples: .D1 \&.Fl -key= \&Ns \&Aq \&Ar val @@ -978,7 +1008,7 @@ See also .Ss \&Ar Command arguments. If an argument is not provided, the string -.Dq file ... +.Dq file ...\& is used as a default. .Pp Examples: @@ -987,17 +1017,18 @@ Examples: .D1 \&.Ar arg1 , arg2 . .Ss \&At Formats an AT&T version. -Accepts at most one parameter: -.Bl -tag -width 12n -offset indent +Accepts one optional argument: +.Pp +.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact .It Cm v[1-7] | 32v A version of .At . .It Cm V[.[1-4]]? -A system version of -.At . +A version of +.At V . .El .Pp -Note that these parameters do not begin with a hyphen. +Note that these arguments do not begin with a hyphen. .Pp Examples: .D1 \&.At @@ -1013,81 +1044,93 @@ See also and .Sx \&Ux . .Ss \&Bc -Closes a +Close a .Sx \&Bo -block. Does not have any tail arguments. +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. +Begin a display block. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Bd +.Fl Ns Ar type +.Op Fl offset Ar width +.Op Fl compact +.Ed +.Pp +Display blocks are used to select a different indentation and +justification than the one used by the surrounding text. +They may contain both macro lines and free-form text lines. +By default, a display block is preceded by a vertical space. +.Pp +The +.Ar type +must be one of the following: +.Bl -tag -width 13n -offset indent +.It Fl centered +Centre-justify each line. +Using this display type is not recommended; many +.Nm +implementations render it poorly. .It Fl filled Left- and right-justify the block. .It Fl literal -Alias for -.Fl unfilled . -.It Fl centered -Centre-justify each line. +Do not justify the block at all. +Preserve white space as it appears in the input. +.It Fl ragged +Only left-justify the block. +.It Fl unfilled +An alias for +.Fl literal . .El .Pp -The type must be provided first. -Secondary arguments are as follows: -.Bl -tag -width 12n -offset indent +The +.Ar type +must be provided first. +Additional arguments may follow: +.Bl -tag -width 13n -offset indent .It Fl offset Ar width -Offset by the value of +Indent the display by the .Ar width , -which is interpreted as one of the following, specified in order: +which may be one of the following: .Bl -item .It -As one of the pre-defined strings -.Ar indent , +One of the pre-defined strings +.Cm indent , the width of standard indentation; -.Ar indent-two , +.Cm indent-two , twice -.Ar indent ; -.Ar left , -which has no effect ; -.Ar right , -which justifies to the right margin; and -.Ar center , +.Cm indent ; +.Cm left , +which has no effect; +.Cm right , +which justifies to the right margin; or +.Cm center , which aligns around an imagined centre axis. .It -As a precalculated width for a named macro. +A macro invocation, which selects a predefined width +associated with that macro. The most popular is the imaginary macro .Ar \&Ds , which resolves to -.Ar 6n . +.Sy 6n . .It -As a scaling unit following the syntax described in +A width using the syntax described in .Sx Scaling Widths . .It -As the calculated string length of the opaque string. +An arbitrary string, which indents by the length of this string. .El .Pp -If unset, it will revert to the value of -.Ar 8n -as described in -.Sx Scaling Widths . +When the argument is missing, +.Fl offset +is ignored. .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. +Do not assert vertical space before the display. .El .Pp Examples: .Bd -literal -offset indent -\&.Bd \-unfilled \-offset two-indent \-compact +\&.Bd \-literal \-offset indent \-compact Hello world. \&.Ed .Ed @@ -1097,120 +1140,191 @@ See also and .Sx \&Dl . .Ss \&Bf +Change the font mode for a scoped block of text. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Bf +.Oo +.Fl emphasis | literal | symbolic | +.Cm \&Em | \&Li | \&Sy +.Oc +.Ed +.Pp +The +.Fl emphasis +and +.Cm \&Em +argument are equivalent, as are +.Fl symbolic +and +.Cm \&Sy , +and +.Fl literal +and +.Cm \&Li . +Without an argument, this macro does nothing. +The font mode continues until broken by a new font mode in a nested +scope or +.Sx \&Ef +is encountered. +.Pp +See also +.Sx \&Li , +.Sx \&Ef , +.Sx \&Em , +and +.Sx \&Sy . .Ss \&Bk +Keep the output generated from each macro input line together +on one single output line. +Line breaks in free-form text lines are unaffected. +The syntax is as follows: +.Pp +.D1 Pf \. Sx \&Bk Fl words +.Pp +The +.Fl words +argument is required; additional arguments are ignored. +.Pp +The following example will not break within each +.Sx \&Op +macro line: +.Bd -literal -offset indent +\&.Bk \-words +\&.Op Fl f Ar flags +\&.Op Fl o Ar output +\&.Ek +.Ed +.Pp +Be careful in using over-long lines within a keep block! +Doing so will clobber the right margin. .Ss \&Bl -Begins a list composed of one or more list entries. -A list is associated with a type, which is a required argument. -Other arguments are -.Fl width , -defined per-type as accepting a literal or -.Sx Scaling Widths -value; -.Fl offset , -also accepting a literal or -.Sx Scaling Widths -value setting the list's global offset; and -.Fl compact , -suppressing the default vertical space printed before each list entry. -A list entry is specified by the +Begin a list. +Lists consist of items started by the .Sx \&It -macro, which consists of a head and optional body (depending on the list -type). +macro, containing a head or a body or both. +The list syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Bl +.Fl Ns Ar type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.Op HEAD ... +.Ed +.Pp +The list +.Ar type +is mandatory and must be specified first. +The +.Fl width +and +.Fl offset +arguments accept +.Sx Scaling Widths +or use the length of the given string. +The +.Fl offset +is a global indentation for the whole list, affecting both item heads +and bodies. +For those list types supporting it, the +.Fl width +argument requests an additional indentation of item bodies, +to be added to the +.Fl offset . +Unless the +.Fl compact +argument is specified, list entries are separated by vertical space. +.Pp A list must specify one of the following list types: .Bl -tag -width 12n -offset indent .It Fl bullet -A list offset by a bullet. -The head of list entries must be empty. -List entry bodies are positioned after the bullet. -The +No item heads can be specified, but a bullet will be printed at the head +of each item. +Item bodies start on the same output line as the bullet +and are indented according to the .Fl width -argument varies the width of list bodies' left-margins. +argument. .It Fl column A columnated list. The .Fl width -argument has no effect. -The number of columns is specified as parameters to the -.Sx \&Bl -macro. -These dictate the width of columns either as +argument has no effect; instead, each argument specifies the width +of one column, using either the .Sx Scaling Widths -or literal text. -If the initial macro of a +syntax or the string length of the argument. +If the first line of the body of a .Fl column list is not an -.Sx \&It , -an .Sx \&It -context spanning each line is implied until an +macro line, +.Sx \&It +contexts spanning one input line each are implied until an .Sx \&It -line macro is encountered, at which point list bodies are interpreted as +macro line is encountered, at which point items start being interpreted as described in the .Sx \&It documentation. .It Fl dash -A list offset by a dash (hyphen). -The head of list entries must be empty. -List entry bodies are positioned past the dash. -The -.Fl width -argument varies the width of list bodies' left-margins. +Like +.Fl bullet , +except that dashes are used in place of bullets. .It Fl diag Like .Fl inset , -but with additional formatting to the head. -The -.Fl width -argument varies the width of list bodies' left-margins. +except that item heads are not parsed for macro invocations. +.\" but with additional formatting to the head. .It Fl enum -An enumerated list offset by the enumeration from 1. -The head of list entries must be empty. -List entry bodies are positioned after the enumeration. -The -.Fl width -argument varies the width of list bodies' left-margins. +A numbered list. +Formatted like +.Fl bullet , +except that cardinal numbers are used in place of bullets, +starting at 1. .It Fl hang Like .Fl tag , -but instead of list bodies positioned after the head, they trail the -head text. -The -.Fl width -argument varies the width of list bodies' left-margins. +except that the first lines of item bodies are not indented, but follow +the item heads like in +.Fl inset +lists. .It Fl hyphen Synonym for .Fl dash . .It Fl inset -List bodies follow the list head. -The +Item bodies follow items heads on the same line, using normal inter-word +spacing. +Bodies are not indented, and the .Fl width argument is ignored. .It Fl item -This produces blocks of text. -The head of list entries must be empty. -The +No item heads can be specified, and none are printed. +Bodies are not indented, and the .Fl width argument is ignored. .It Fl ohang -List bodies are positioned on the line following the head. +Item bodies start on the line following item heads and are not indented. The .Fl width argument is ignored. .It Fl tag -A list offset by list entry heads. List entry bodies are positioned -after the head as specified by the +Item bodies are indented according to the .Fl width argument. +When an item head fits inside the indentation, the item body follows +this head on the same output line. +Otherwise, the body starts on the output line following the head. .El .Pp See also +.Sx \&El +and .Sx \&It . .Ss \&Bo -Begins a block enclosed by square brackets. +Begin a block enclosed by square brackets. Does not have any head arguments. .Pp Examples: -.Bd -literal -offset indent +.Bd -literal -offset indent -compact \&.Bo 1 , \&.Dv BUFSIZ \&Bc .Ed @@ -1234,15 +1348,16 @@ and See also .Sx \&Bo . .Ss \&Brc -Closes a +Close a .Sx \&Bro -block. Does not have any tail arguments. +block. +Does not have any tail arguments. .Ss \&Bro -Begins a block enclosed by curly braces. +Begin a block enclosed by curly braces. Does not have any head arguments. .Pp Examples: -.Bd -literal -offset indent +.Bd -literal -offset indent -compact \&.Bro 1 , ... , \&.Va n \&Brc .Ed @@ -1276,7 +1391,7 @@ and .Sx \&Ux . .Ss \&Bt Prints -.Dq is currently in beta test. +.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. @@ -1295,7 +1410,7 @@ See also and .Sx \&Ux . .Ss \&Cd -Configuration declaration. +Kernel configuration declaration. This denotes strings accepted by .Xr config 8 . .Pp @@ -1304,7 +1419,7 @@ Examples: .Pp .Em Remarks : this macro is commonly abused by using quoted literals to retain -white-space and align consecutive +whitespace and align consecutive .Sx \&Cd declarations. This practise is discouraged. @@ -1332,33 +1447,36 @@ See also and .Sx \&Dl . .Ss \&Db -Start a debugging context. -This macro is parsed, but generally ignored. -Its calling syntax is as follows: +Switch debugging mode. +Its syntax is as follows: .Pp -.D1 \. Ns Sx \&Db Cm on | off +.D1 Pf \. Sx \&Db Cm on | off +.Pp +This macro is ignored by +.Xr mandoc 1 . .Ss \&Dc -Closes a +Close a .Sx \&Do -block. Does not have any tail arguments. +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: +Its syntax is as follows: .Pp -.D1 \. Ns Sx \&Dd Cm date +.D1 Pf \. Sx \&Dd Op Ar date .Pp The -.Cm date -field may be either +.Ar date +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. +If a date does not conform or is empty, the current date is used. .Pp Examples: .D1 \&.Dd $\&Mdocdate$ @@ -1376,23 +1494,30 @@ invocations. It is followed by a newline. .Pp Examples: -.D1 \&.Dl % mandoc mdoc.7 | less +.D1 \&.Dl % mandoc mdoc.7 \e(ba less .Pp See also .Sx \&Bd and .Sx \&D1 . .Ss \&Do -Begins a block enclosed by double quotes. Does not have any head -arguments. +Begin a block enclosed by double quotes. +Does not have any head arguments. .Pp Examples: -.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot +.Bd -literal -offset indent -compact +\&.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. +Encloses its arguments in +.Dq typographic +double-quotes. .Pp Examples: .Bd -literal -offset indent -compact @@ -1401,24 +1526,35 @@ Examples: .Ed .Pp See also +.Sx \&Qq , +.Sx \&Sq , +and .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 Op Cm title Op Cm section Op Cm volume | arch +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Dt +.Oo +.Ar title +.Oo +.Ar section +.Op Ar volume | arch +.Oc +.Oc +.Ed .Pp Its arguments are as follows: .Bl -tag -width Ds -offset Ds -.It Cm title +.It Ar title The document's title (name), defaulting to -.Qq UNKNOWN +.Dq UNKNOWN if unspecified. It should be capitalised. -.It Cm section +.It Ar section The manual section. This may be one of .Ar 1 @@ -1455,9 +1591,9 @@ or .Ar paper .Pq paper . It should correspond to the manual's filename suffix and defaults to -.Qq 1 +.Dq 1 if unspecified. -.It Cm volume +.It Ar volume This overrides the volume inferred from .Ar section . This field is optional, and if specified, must be one of @@ -1486,10 +1622,10 @@ This field is optional, and if specified, must be one of or .Ar CON .Pq contributed manuals . -.It Cm arch +.It Ar arch This specifies a specific relevant architecture. If -.Cm volume +.Ar volume is not provided, it may be used in its place, else it may be used subsequent that. It, too, is optional. @@ -1560,11 +1696,28 @@ See also and .Sx \&Ux . .Ss \&Ec +Close a scope started by +.Sx \&Eo . +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ec Op Ar TERM +.Pp +The +.Ar TERM +argument is used as the enclosure tail, for example, specifying \e(rq +will emulate +.Sx \&Dc . .Ss \&Ed +End a display context started by +.Sx \&Bd . .Ss \&Ef +End a font mode context started by +.Sx \&Bf . .Ss \&Ek +End a keep context started by +.Sx \&Bk . .Ss \&El -Ends a list context started by +End a list context started by .Sx \&Bl . .Pp See also @@ -1579,8 +1732,26 @@ stylistically decorating technical terms. Examples: .D1 \&.Em Warnings! .D1 \&.Em Remarks : +.Pp +See also +.Sx \&Bf , +.Sx \&Sy , +and +.Sx \&Li . .Ss \&En +This macro is obsolete and not implemented in +.Xr mandoc 1 . .Ss \&Eo +An arbitrary enclosure. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Eo Op Ar TERM +.Pp +The +.Ar TERM +argument is used as the enclosure head, for example, specifying \e(lq +will emulate +.Sx \&Do . .Ss \&Er Display error constants. .Pp @@ -1591,6 +1762,7 @@ Examples: See also .Sx \&Dv . .Ss \&Es +This macro is obsolete and not implemented. .Ss \&Ev Environmental variables such as those specified in .Xr environ 7 . @@ -1599,24 +1771,36 @@ Examples: .D1 \&.Ev DISPLAY .D1 \&.Ev PATH .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 +Insert a standard sentence regarding exit values. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ex Fl std Op Ar utility +.Pp +When .Ar utility -is not provided, the document's name as stipulated in +is not specified, the document's name set by .Sx \&Nm -is provided. +is used. +.Pp +See also +.Sx \&Rv . .Ss \&Fa Function argument. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Fa +.Op Cm argtype +.Cm argname +.Ed +.Pp This may be invoked for names with or without the corresponding type. It is also used to specify the field name of a structure. Most often, the .Sx \&Fa macro is used in the .Em SYNOPSIS +within +.Sx \&Fo section when documenting multi-line function prototypes. If invoked with multiple arguments, the arguments are separated by a comma. @@ -1628,7 +1812,12 @@ Examples: .D1 \&.Fa \(dqconst char *p\(dq .D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq .D1 \&.Fa foo +.Pp +See also +.Sx \&Fo . .Ss \&Fc +End a function context started by +.Sx \&Fo . .Ss \&Fd Historically used to document include files. This usage has been deprecated in favour of @@ -1636,6 +1825,8 @@ This usage has been deprecated in favour of Do not use this macro. .Pp See also +.Sx MANUAL STRUCTURE +and .Sx \&In . .Ss \&Fl Command-line flag. @@ -1657,37 +1848,84 @@ See also .Sx \&Cm . .Ss \&Fn A function name. -Its calling syntax is as follows: +Its syntax is as follows: .Bd -ragged -offset indent .Pf \. Ns Sx \&Fn .Op Cm functype .Cm funcname .Op Oo Cm argtype Oc Cm argname .Ed -If invoked in the -.Em SYNOPSIS -section, vertical space is asserted before and after the macro. -In all cases, the function arguments are surrounded in parenthesis and +.Pp +Function arguments are surrounded in parenthesis and are delimited by commas. If no arguments are specified, blank parenthesis are output. .Pp Examples: .D1 \&.Fn "int funcname" "int arg0" "int arg1" -.D1 \&.Fn funcname .D1 \&.Fn funcname "int arg0" .D1 \&.Fn funcname arg0 +.Bd -literal -offset indent -compact +\&.Ft functype +\&.Fn funcname +.Ed .Pp See also +.Sx MANUAL STRUCTURE +and +.Sx \&Ft . +.Ss \&Fo +Begin a function block. +This is a multi-line version of +.Sx \&Fn . +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Fo Cm funcname +.Pp +Invocations usually occur in the following context: +.Bd -ragged -offset indent +.Pf \. Sx \&Ft Cm functype +.br +.Pf \. Sx \&Fo Cm funcname +.br +.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname +.br +\.\.\. +.br +.Pf \. Sx \&Fc +.Ed +.Pp +A +.Sx \&Fo +scope is closed by +.Pp +See also +.Sx MANUAL STRUCTURE , .Sx \&Fa , -.Sx \&Fo , .Sx \&Fc , and .Sx \&Ft . -.Ss \&Fo -.Ss \&Fr .Ss \&Ft +A function type. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ft Cm functype +.Pp +Examples: +.D1 \&.Ft int +.Bd -literal -offset indent -compact +\&.Ft functype +\&.Fn funcname +.Ed +.Pp +See also +.Sx MANUAL STRUCTURE , +.Sx \&Fn , +and +.Sx \&Fo . .Ss \&Fx -Format the FreeBSD version provided as an argument, or a default value +Format the +.Fx +version provided as an argument, or a default value if no argument is provided. .Pp Examples: @@ -1704,23 +1942,43 @@ See also and .Sx \&Ux . .Ss \&Hf +This macro is obsolete and not implemented. .Ss \&Ic +Designate an internal or interactive command. +This is similar to +.Sx \&Cm +but used for instructions rather than values. +.Pp +Examples: +.D1 \&.Ic hash +.D1 \&.Ic alias +.Pp +Note that using +.Sx \&Bd Fl literal +or +.Sx \&D1 +is preferred for displaying code; the +.Sx \&Ic +macro is used when referring to specific instructions. .Ss \&In An -.Qq include +.Dq include file. In the .Em SYNOPSIS section (only if invoked as the line macro), the first argument is preceded by -.Qq #include , -the arguments is enclosed in angled braces, and a newline is asserted. -In all other invocations, only angled braces will enclose the argument. +.Dq #include , +the arguments is enclosed in angle brackets. .Pp -Examples +Examples: .D1 \&.In sys/types +.Pp +See also +.Sx MANUAL STRUCTURE . .Ss \&It -A list item. The syntax of this macro depends on the list type. +A list item. +The syntax of this macro depends on the list type. .Pp Lists of type @@ -1729,9 +1987,9 @@ of type .Fl inset , and .Fl diag -have the following calling syntax: +have the following syntax: .Pp -.D1 \. Ns Sx \&It Cm args +.D1 Pf \. Sx \&It Cm args .Pp Lists of type .Fl bullet , @@ -1740,9 +1998,9 @@ Lists of type .Fl hyphen and .Fl item -have the following calling syntax: +have the following syntax: .Pp -.D1 \. Ns Sx \&It +.D1 Pf \. Sx \&It .Pp with subsequent lines interpreted within the scope of the .Sx \&It @@ -1753,11 +2011,11 @@ or another .Pp The .Fl tag -list has syntax +list has the following syntax: .Pp -.D1 \. Ns Sx \&It Op Cm args +.D1 Pf \. Sx \&It Op Cm args .Pp -with subsequent lines interpreted as with +Subsequent lines are interpreted as with .Fl bullet and family. The line arguments correspond to the list's left-hand side; body @@ -1766,11 +2024,11 @@ arguments correspond to the list's contents. The .Fl column list is the most complicated. -Its syntax is +Its syntax is as follows: .Pp -.D1 \. Ns Sx \&It Op Cm args +.D1 Pf \. Sx \&It Op Cm args .Pp -where +The .Cm args are phrases, a mix of macros and text corresponding to a line column, delimited by tabs or the special @@ -1782,19 +2040,19 @@ are interpreted within the scope of the last phrase. Calling the pseudo-macro .Sq \&Ta will open a new phrase scope (this must occur on a macro line to be -interpreted as a macro). Note that the tab phrase delimiter may only be -used within the +interpreted as a macro). +Note that the tab phrase delimiter may only be used within the .Sx \&It line itself. Subsequent this, only the .Sq \&Ta pseudo-macro may be used to delimit phrases. -Furthermore, note that quoted sections propogate over tab-delimited +Furthermore, note that quoted sections propagate over tab-delimited phrases on an .Sx \&It , for example, .Pp -.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ; +.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&; .Pp will preserve the semicolon whitespace except for the last. .Pp @@ -1802,9 +2060,9 @@ See also .Sx \&Bl . .Ss \&Lb Specify a library. -The calling syntax is as follows: +The syntax is as follows: .Pp -.D1 \. Ns Sx \&Lb Cm library +.D1 Pf \. Sx \&Lb Cm library .Pp The .Cm library @@ -1824,36 +2082,133 @@ Examples: .D1 \&.Lb libz .D1 \&.Lb mdoc .Ss \&Li +Denotes text that should be in a literal font mode. +Note that this is a presentation term and should not be used for +stylistically decorating technical terms. +.Pp +See also +.Sx \&Bf , +.Sx \&Sy , +and +.Sx \&Em . .Ss \&Lk Format a hyperlink. -The calling syntax is as follows: +Its syntax is as follows: .Pp -.D1 \. Ns Sx \&Lk Cm uri Op Cm name +.D1 Pf \. Sx \&Lk Cm uri Op Cm name .Pp Examples: -.D1 \&.Lk http://bsd.lv "The BSD.lv Project" +.D1 \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q .D1 \&.Lk http://bsd.lv .Pp See also .Sx \&Mt . .Ss \&Lp +Synonym for +.Sx \&Pp . .Ss \&Ms +Display a mathematical symbol. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ms Cm symbol +.Pp +Examples: +.D1 \&.Ms sigma +.D1 \&.Ms aleph .Ss \&Mt Format a -.Qq mailto: +.Dq mailto: hyperlink. -The calling syntax is as follows: +Its syntax is as follows: .Pp -.D1 \. Ns Sx \&Mt Cm address +.D1 Pf \. Sx \&Mt Cm address .Pp Examples: .D1 \&.Mt discuss@manpages.bsd.lv .Ss \&Nd +A one line description of the manual's content. +This may only be invoked in the +.Em SYNOPSIS +section subsequent the +.Sx \&Nm +macro. +.Pp +Examples: +.D1 \&.Sx \&Nd mdoc language reference +.D1 \&.Sx \&Nd format and display UNIX manuals +.Pp +The +.Sx \&Nd +macro technically accepts child macros and terminates with a subsequent +.Sx \&Sh +invocation. +Do not assume this behaviour: some +.Xr whatis 1 +database generators are not smart enough to parse more than the line +arguments and will display macros verbatim. +.Pp +See also +.Sx \&Nm . .Ss \&Nm +The name of the manual page, or \(em in particular in section 1, 6, +and 8 pages \(em of an additional command or feature documented in +the manual page. +When first invoked, the +.Sx \&Nm +macro expects a single argument, the name of the manual page. +Usually, the first invocation happens in the +.Em NAME +section of the page. +The specified name will be remembered and used whenever the macro is +called again without arguments later in the page. +The +.Sx \&Nm +macro uses +.Sx Block full-implicit +semantics when invoked as the first macro on an input line in the +.Em SYNOPSIS +section; otherwise, it uses ordinary +.Sx In-line +semantics. +.Pp +Examples: +.Bd -literal -offset indent +\&.Sh SYNOPSIS +\&.Nm cat +\&.Op Fl benstuv +\&.Op Ar +.Ed +.Pp +In the +.Em SYNOPSIS +of section 2, 3 and 9 manual pages, use the +.Sx \&Fn +macro rather than +.Sx \&Nm +to mark up the name of the manual page. .Ss \&No +A +.Dq noop +macro used to terminate prior macro contexts. +.Pp +Examples: +.D1 \&.Sx \&Fl ab \&No cd \&Fl ef .Ss \&Ns +Suppress a space. +Following invocation, text is interpreted as free-form text until a +macro is encountered. +.Pp +Examples: +.D1 \&.Fl o \&Ns \&Ar output +.Pp +See also +.Sx \&No +and +.Sx \&Sm . .Ss \&Nx -Format the NetBSD version provided as an argument, or a default value if +Format the +.Nx +version provided as an argument, or a default value if no argument is provided. .Pp Examples: @@ -1870,16 +2225,39 @@ See also and .Sx \&Ux . .Ss \&Oc +Close multi-line +.Sx \&Oo +context. .Ss \&Oo +Multi-line version of +.Sx \&Op . +.Pp +Examples: +.Bd -literal -offset indent -compact +\&.Oo +\&.Op Fl flag Ns Ar value +\&.Oc +.Ed .Ss \&Op +Command-line option. +Used when listing options to command-line utilities. +Prints the argument(s) in brackets. +.Pp +Examples: +.D1 \&.Op \&Fl a \&Ar b +.D1 \&.Op \&Ar a | b +.Pp +See also +.Sx \&Oo . .Ss \&Os Document operating system version. This is the mandatory third macro of any .Nm -file. Its calling syntax is as follows: +file. +Its syntax is as follows: .Pp -.D1 \. Ns Sx \&Os Op Cm system +.D1 Pf \. Sx \&Os Op Cm system Op Cm version .Pp The optional .Cm system @@ -1902,7 +2280,9 @@ Unknown usage. .Em Remarks : this macro has been deprecated. .Ss \&Ox -Format the OpenBSD version provided as an argument, or a default value +Format the +.Ox +version provided as an argument, or a default value if no argument is provided. .Pp Examples: @@ -1919,22 +2299,74 @@ See also and .Sx \&Ux . .Ss \&Pa +A file-system path. +.Pp +Examples: +.D1 \&.Pa /usr/bin/mandoc +.D1 \&.Pa /usr/share/man/man7/mdoc.7 +.Pp +See also +.Sx \&Lk . .Ss \&Pc +Close parenthesised context opened by +.Sx \&Po . .Ss \&Pf +Removes the space +.Pq Dq prefix +between its arguments. +Its syntax is as follows: +.Pp +.D1 Pf \. \&Pf Cm prefix suffix +.Pp +The +.Cm suffix +argument may be a macro. +.Pp +Examples: +.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix .Ss \&Po +Multi-line version of +.Sx \&Pq . .Ss \&Pp +Break a paragraph. +This will assert vertical space between prior and subsequent macros +and/or text. .Ss \&Pq +Parenthesised enclosure. +.Pp +See also +.Sx \&Po . .Ss \&Qc +Close quoted context opened by +.Sx \&Qo . .Ss \&Ql +Format a single-quoted literal. +See also +.Sx \&Qq +and +.Sx \&Sq . .Ss \&Qo +Multi-line version of +.Sx \&Qq . .Ss \&Qq +Encloses its arguments in +.Dq typewriter +double-quotes. +Consider using +.Sx \&Dq . +.Pp +See also +.Sx \&Dq , +.Sx \&Sq , +and +.Sx \&Qo . .Ss \&Re -Closes a +Close an .Sx \&Rs block. Does not have any tail arguments. .Ss \&Rs -Begins a bibliographic +Begin a bibliographic .Pq Dq reference block. Does not have any head arguments. @@ -1951,6 +2383,7 @@ The block macro may only contain .Sx \&%Q , .Sx \&%R , .Sx \&%T , +.Sx \&%U , and .Sx \&%V child macros (at least one must be specified). @@ -1973,19 +2406,203 @@ 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 +Inserts text regarding a function call's return value. +This macro must consist of the +.Fl std +argument followed by an optional +.Ar function . +If +.Ar function +is not provided, the document's name as stipulated by the first +.Sx \&Nm +is provided. +.Pp +See also +.Sx \&Ex . .Ss \&Sc +Close single-quoted context opened by +.Sx \&So . .Ss \&Sh +Begin a new section. +For a list of conventional manual sections, see +.Sx MANUAL STRUCTURE . +These sections should be used unless it's absolutely necessary that +custom sections be used. +.Pp +Section names should be unique so that they may be keyed by +.Sx \&Sx . +.Pp +See also +.Sx \&Pp , +.Sx \&Ss , +and +.Sx \&Sx . .Ss \&Sm +Switches the spacing mode for output generated from macros. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Sm Cm on | off +.Pp +By default, spacing is +.Cm on . +When switched +.Cm off , +no white space is inserted between macro arguments and between the +output generated from adjacent macros, but free-form text lines +still get normal spacing between words and sentences. .Ss \&So +Multi-line version of +.Sx \&Sq . .Ss \&Sq +Encloses its arguments in +.Dq typewriter +single-quotes. +.Pp +See also +.Sx \&Dq , +.Sx \&Qq , +and +.Sx \&So . .Ss \&Ss +Begin a new sub-section. +Unlike with +.Sx \&Sh , +there's no convention for sub-sections. +Conventional sections, as described in +.Sx MANUAL STRUCTURE , +rarely have sub-sections. +.Pp +Sub-section names should be unique so that they may be keyed by +.Sx \&Sx . +.Pp +See also +.Sx \&Pp , +.Sx \&Sh , +and +.Sx \&Sx . .Ss \&St +Replace an abbreviation for a standard with the full form. +The following standards are recognised: +.Pp +.Bl -tag -width "-p1003.1g-2000X" -compact +.It \-p1003.1-88 +.St -p1003.1-88 +.It \-p1003.1-90 +.St -p1003.1-90 +.It \-p1003.1-96 +.St -p1003.1-96 +.It \-p1003.1-2001 +.St -p1003.1-2001 +.It \-p1003.1-2004 +.St -p1003.1-2004 +.It \-p1003.1-2008 +.St -p1003.1-2008 +.It \-p1003.1 +.St -p1003.1 +.It \-p1003.1b +.St -p1003.1b +.It \-p1003.1b-93 +.St -p1003.1b-93 +.It \-p1003.1c-95 +.St -p1003.1c-95 +.It \-p1003.1g-2000 +.St -p1003.1g-2000 +.It \-p1003.1i-95 +.St -p1003.1i-95 +.It \-p1003.2-92 +.St -p1003.2-92 +.It \-p1003.2a-92 +.St -p1003.2a-92 +.It \-p1387.2-95 +.St -p1387.2-95 +.It \-p1003.2 +.St -p1003.2 +.It \-p1387.2 +.St -p1387.2 +.It \-isoC +.St -isoC +.It \-isoC-90 +.St -isoC-90 +.It \-isoC-amd1 +.St -isoC-amd1 +.It \-isoC-tcor1 +.St -isoC-tcor1 +.It \-isoC-tcor2 +.St -isoC-tcor2 +.It \-isoC-99 +.St -isoC-99 +.It \-iso9945-1-90 +.St -iso9945-1-90 +.It \-iso9945-1-96 +.St -iso9945-1-96 +.It \-iso9945-2-93 +.St -iso9945-2-93 +.It \-ansiC +.St -ansiC +.It \-ansiC-89 +.St -ansiC-89 +.It \-ansiC-99 +.St -ansiC-99 +.It \-ieee754 +.St -ieee754 +.It \-iso8802-3 +.St -iso8802-3 +.It \-ieee1275-94 +.St -ieee1275-94 +.It \-xpg3 +.St -xpg3 +.It \-xpg4 +.St -xpg4 +.It \-xpg4.2 +.St -xpg4.2 +.St -xpg4.3 +.It \-xbd5 +.St -xbd5 +.It \-xcu5 +.St -xcu5 +.It \-xsh5 +.St -xsh5 +.It \-xns5 +.St -xns5 +.It \-xns5.2 +.St -xns5.2 +.It \-xns5.2d2.0 +.St -xns5.2d2.0 +.It \-xcurses4.2 +.St -xcurses4.2 +.It \-susv2 +.St -susv2 +.It \-susv3 +.St -susv3 +.It \-svid4 +.St -svid4 +.El .Ss \&Sx +Reference a section or sub-section. +The referenced section or sub-section name must be identical to the +enclosed argument, including whitespace. +.Pp +Examples: +.D1 \&.Sx MANUAL STRUCTURE .Ss \&Sy +Format enclosed arguments in symbolic +.Pq Dq boldface . +Note that this is a presentation term and should not be used for +stylistically decorating technical terms. +.Pp +See also +.Sx \&Bf , +.Sx \&Li , +and +.Sx \&Em . .Ss \&Tn +Format a tradename. +.Pp +Examples: +.D1 \&.Tn IBM .Ss \&Ud Prints out -.Dq currently under development. +.Dq currently under development . .Ss \&Ux Format the UNIX name. Accepts no argument. @@ -2003,14 +2620,21 @@ See also and .Sx \&Ox . .Ss \&Va +A variable name. +.Pp +Examples: +.D1 \&.Va foo +.D1 \&.Va const char *bar ; .Ss \&Vt A variable type. -This is also used for indicating global variables in the SYNOPSIS +This is also used for indicating global variables in the +.Em SYNOPSIS section, in which case a variable name is also specified. Note that it accepts .Sx Block partial-implicit -syntax when invoked as the first macro in the SYNOPSIS section, else it -accepts ordinary +syntax when invoked as the first macro in the +.Em SYNOPSIS +section, else it accepts ordinary .Sx In-line syntax. .Pp @@ -2020,10 +2644,10 @@ which is used for function return types. .Pp Examples: .D1 \&.Vt unsigned char -.D1 \&.Vt extern const char * const sys_signame[] ; +.D1 \&.Vt extern const char * const sys_signame[] \&; .Pp See also -.Sx \&Ft +.Sx MANUAL STRUCTURE and .Sx \&Va . .Ss \&Xc @@ -2036,9 +2660,9 @@ since this limit has been lifted, the macro has been deprecated. .Ss \&Xr Link to another manual .Pq Qq cross-reference . -Its calling syntax is +Its syntax is as follows: .Pp -.D1 \. Ns Sx \&Xr Cm name section +.D1 Pf \. Sx \&Xr Cm name section .Pp The .Cm name @@ -2051,14 +2675,35 @@ is followed by non-punctuation, an .Sx \&Ns is inserted into the token stream. This behaviour is for compatibility with -.Xr groff 1 . +GNU troff. .Pp Examples: .D1 \&.Xr mandoc 1 -.D1 \&.Xr mandoc 1 ; +.D1 \&.Xr mandoc 1 \&; .D1 \&.Xr mandoc 1 \&Ns s behaviour .Ss \&br +Emits a line-break. +This macro should not be used; it is implemented for compatibility with +historical manuals. +.Pp +Consider using +.Sx \&Pp +in the event of natural paragraph breaks. .Ss \&sp +Emits vertical space. +This macro should not be used; it is implemented for compatibility with +historical manuals. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&sp Op Cm height +.Pp +The +.Cm height +argument must be formatted as described in +.Sx Scaling Widths . +If unspecified, +.Sx \&sp +asserts a single vertical space. .Sh COMPATIBILITY This section documents compatibility between mandoc and other other troff implementations, at this time limited to GNU troff @@ -2073,189 +2718,173 @@ file re-write Heirloom troff, the other significant troff implementation accepting \-mdoc, is similar to historic groff. .Pp +The following problematic behaviour is found in groff: +.ds hist (Historic groff only.) +.Pp .Bl -dash -compact .It -Historic groff does not break before an +.Sx \&At +with unknown arguments produces no output at all. +\*[hist] +Newer groff and mandoc print +.Qq AT&T UNIX +and the arguments. +.It +.Sx \&Bd Fl column +does not recognize trailing punctuation characters when they immediately +precede tabulator characters, but treats them as normal text and +outputs a space before them. +.It +.Sx \&Bd Fl ragged compact +does not start a new line. +\*[hist] +.It +.Sx \&Dd +without an argument prints +.Dq Epoch . +In mandoc, it resolves to the current date. +.It +.Sx \&Fl +does not print a dash for an empty argument. +\*[hist] +.It .Sx \&Fn -when not invoked as the line macro in the +does not start a new line unless invoked as the line macro in the .Em SYNOPSIS section. +\*[hist] .It -Historic groff formats the -.Sx \&In -badly: trailing arguments are trashed and -.Em SYNOPSIS -is not specially treated. +.Sx \&Fo +with +.Pf non- Sx \&Fa +children causes inconsistent spacing between arguments. +In mandoc, a single space is always inserted between arguments. .It -groff does not accept the -.Sq \&Ta -pseudo-macro as a line macro. -mandoc does. +.Sx \&Ft +in the +.Em SYNOPSIS +causes inconsistent vertical spacing, depending on whether a prior +.Sx \&Fn +has been invoked. +See +.Sx \&Ft +and +.Sx \&Fn +for the normalised behaviour in mandoc. .It -The comment syntax -.Sq \e." -is no longer accepted. +.Sx \&In +ignores additional arguments and is not treated specially in the +.Em SYNOPSIS . +\*[hist] .It -In groff, the -.Sx \&Pa -macro does not format its arguments when used in the FILES section under -certain list types. -mandoc does. +.Sx \&It +sometimes requires a +.Fl nested +flag. +\*[hist] +In new groff and mandoc, any list may be nested by default and +.Fl enum +lists will restart the sequence only for the sub-list. .It -Historic groff does not print a dash for empty -.Sx \&Fl -arguments. -mandoc and newer groff implementations do. +.Sx \&Li +followed by a reserved character is incorrectly used in some manuals +instead of properly quoting that character, which sometimes works with +historic groff. .It -groff behaves irregularly when specifying -.Sq \ef -.Sx Text Decoration -within line-macro scopes. -mandoc follows a consistent system. +.Sx \&Lk +only accepts a single link-name argument; the remainder is misformatted. .It -In mandoc, negative scaling units are truncated to zero; groff would -move to prior lines. -Furthermore, the -.Sq f -scaling unit, while accepted, is rendered as the default unit. +.Sx \&Pa +does not format its arguments when used in the FILES section under +certain list types. .It -In quoted literals, groff allowed pair-wise double-quotes to produce a -standalone double-quote in formatted output. -This idiosyncratic behaviour is not applicable in mandoc. +.Sx \&Ta +can only be called by other macros, but not at the beginning of a line. .It -Display types -.Sx \&Bd -.Fl center -and -.Fl right -are aliases for -.Fl left -in manodc. Furthermore, the -.Fl file Ar file -argument is ignored. -Lastly, since text is not right-justified in mandoc (or even groff), -.Fl ragged -and -.Fl filled -are aliases, as are -.Fl literal -and -.Fl unfilled . +.Sx \&%C +is not implemented. .It Historic groff has many un-callable macros. -Most of these (excluding some block-level macros) are now callable. +Most of these (excluding some block-level macros) are callable +in new groff and mandoc. .It -The vertical bar .Sq \(ba -made historic groff -.Qq go orbital -but has been a proper delimiter since then. +(vertical bar) is not fully supported as a delimiter. +\*[hist] .It -.Sx \&It Fl nested -is assumed for all lists (it wasn't in historic groff): any list may be -nested and -.Fl enum -lists will restart the sequence only for the sub-list. +.Sq \ef +.Pq font face +and +.Sq \ef +.Pq font family face +.Sx Text Decoration +escapes behave irregularly when specified within line-macro scopes. .It -Some manuals use -.Sx \&Li -incorrectly by following it with a reserved character and expecting the -delimiter to render. -This is not supported in mandoc. +Negative scaling units return to prior lines. +Instead, mandoc truncates them to zero. +.El +.Pp +The following features are unimplemented in mandoc: +.Pp +.Bl -dash -compact .It -In groff, the -.Sx \&Fo -macro only produces the first parameter. -This is not the case in mandoc. +.Sx \&Bd +.Fl file Ar file . .It -In groff, the -.Sx \&Cd , -.Sx \&Er , -.Sx \&Ex , +.Sx \&Bd +.Fl offset Ar center and -.Sx \&Rv -macros were stipulated only to occur in certain manual sections. -mandoc does not have these restrictions. +.Fl offset Ar right . +Groff does not implement centered and flush-right rendering either, +but produces large indentations. .It -Newer groff and mandoc print -.Qq AT&T UNIX -prior to unknown arguments of -.Sx \&At ; -older groff did nothing. +The +.Sq \eh +.Pq horizontal position , +.Sq \ev +.Pq vertical position , +.Sq \em +.Pq text colour , +.Sq \eM +.Pq text filling colour , +.Sq \ez +.Pq zero-length character , +.Sq \ew +.Pq string length , +.Sq \ek +.Pq horizontal position marker , +.Sq \eo +.Pq text overstrike , +and +.Sq \es +.Pq text size +escape sequences are all discarded in mandoc. +.It +The +.Sq \ef +scaling unit is accepted by mandoc, but rendered as the default unit. +.It +In quoted literals, groff allows pairwise double-quotes to produce a +standalone double-quote in formatted output. +This is not supported by mandoc. .El .Sh SEE ALSO +.Xr man 1 , .Xr mandoc 1 , .Xr mandoc_char 7 +.Sh HISTORY +The +.Nm +language first appeared as a troff macro package in +.Bx 4.4 . +It was later significantly updated by Werner Lemberg and Ruslan Ermilov +in groff-1.17. +The standalone implementation that is part of the +.Xr mandoc 1 +utility written by Kristaps Dzonsons appeared in +.Ox 4.6 . .Sh AUTHORS The .Nm reference was written by .An Kristaps Dzonsons Aq kristaps@bsd.lv . -.\" -.\" 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 -.\" .