X-Git-Url: https://git.cameronkatri.com/mandoc.git/blobdiff_plain/552fc9527e9860994ee41541a4e78e873be4315a..4c2b73111562cd3b6e5744162ecbd5ca4d045661:/mdoc.7 diff --git a/mdoc.7 b/mdoc.7 index c7e6f924..f1f57a98 100644 --- a/mdoc.7 +++ b/mdoc.7 @@ -1,6 +1,7 @@ -.\" $Id: mdoc.7,v 1.73 2009/11/02 11:39:40 kristaps Exp $ +.\" $Id: mdoc.7,v 1.140 2010/07/19 21:59:48 kristaps Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se> +.\" 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,63 +15,54 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: November 2 2009 $ +.Dd $Mdocdate: July 19 2010 $ .Dt MDOC 7 .Os -. -. .Sh NAME .Nm mdoc .Nd mdoc language reference -. -. .Sh DESCRIPTION The .Nm mdoc language is used to format .Bx .Ux -manuals. In this reference document, we describe its syntax, structure, -and usage. Our reference implementation is -.Xr mandoc 1 . -The +manuals. +In this reference document, we describe its syntax, structure, and +usage. +Our reference implementation is mandoc; the .Sx COMPATIBILITY -section describes compatibility with -.Xr groff 1 . -. +section describes compatibility with other troff \-mdoc implementations. .Pp An .Nm -document follows simple rules: lines beginning with the control +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. Other lines are interpreted within the current state. .Ed -. -. .Sh LANGUAGE SYNTAX .Nm documents may contain only graphable 7-bit ASCII characters, the space -character, and, in certain circumstances, the tab character. All -manuals must have +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 optionally whitespace are +stripped from input. .Ss Reserved Characters Within a macro line, the following characters are reserved: .Pp @@ -98,7 +90,6 @@ Within a macro line, the following characters are reserved: .It \&| .Pq vertical bar .El -. .Pp Use of reserved characters is described in .Sx MACRO SYNTAX . @@ -106,8 +97,6 @@ For general use in macro lines, these characters must either be escaped with a non-breaking space .Pq Sq \e& or, if applicable, an appropriate escape sequence used. -. -. .Ss Special Characters Special characters may occur in both macro and free-form lines. Sequences begin with the escape character @@ -118,33 +107,52 @@ for two-character sequences; an open-bracket .Sq \&[ for n-character sequences (terminated at a close-bracket .Sq \&] ) ; -or a single one-character sequence. See +or a single one-character sequence. +See .Xr mandoc_char 7 -for a complete list. Examples include +for a complete list. +Examples include .Sq \e(em .Pq em-dash and .Sq \ee .Pq back-slash . -. -. .Ss Text Decoration Terms may be text-decorated using the .Sq \ef -escape followed by an indicator: B (bold), I, (italic), or P and R -(Roman, or reset). This form is not recommended for +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 +Note this form is +.Em not +recommended for .Nm , -which encourages semantic, not presentation, annotation. -. -. +which encourages semantic annotation. .Ss Predefined Strings -Historically, +Historically, .Xr groff 1 -also defined a set of package-specific +also defined a set of package-specific .Dq predefined strings , -which, like +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 @@ -155,43 +163,28 @@ and N-character .Sq \e*[N] . See .Xr mandoc_char 7 -for a complete list. Examples include +for a complete list. +Examples include .Sq \e*(Am .Pq ampersand and .Sq \e*(Ba .Pq vertical bar . -. -. .Ss Whitespace -In non-literal free-form lines, consecutive blocks of whitespace are -pruned from input and added later in the output filter, if applicable: -.Bd -literal -offset indent -These spaces are pruned from input. -\&.Bd \-literal -These are not. -\&.Ed -.Ed -. -.Pp -In macro lines, whitespace delimits arguments and is discarded. If -arguments are quoted, whitespace within the quotes is retained. -. -.Pp -Blank lines are only permitted within literal contexts, as are lines -containing only whitespace. Tab characters are only acceptable when -delimiting -.Sq \&Bl \-column -or when in a literal context. -. -. +Whitespace consists of the space character. +In free-form lines, whitespace is preserved within a line; un-escaped +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. +.Pp +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 -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. -. +space-delimited terms or to retain blocks of whitespace. +A quoted argument begins with a double-quote preceded by whitespace. +The next double-quote not pair-wise adjacent to another double-quote +terminates the literal, regardless of surrounding whitespace. .Pp This produces tokens .Sq a" , @@ -200,28 +193,29 @@ This produces tokens and .Sq fg" . Note that any quoted term, be it argument or macro, is indiscriminately -considered literal text. Thus, the following produces +considered literal text. +Thus, the following produces .Sq \&Em a : .Bd -literal -offset indent \&.Em "Em a" .Ed -. .Pp In free-form mode, quotes are regarded as opaque text. -. .Ss Dates There are several macros in .Nm -that require a date argument. The canonical form for dates is the -American format: +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 +value is an optionally zero-padded numeral. +The .Cm Month -value is the full month name. The +value is the full month name. +The .Cm Year value is the full four-digit year. .Pp @@ -235,20 +229,18 @@ Some examples of valid dates follow: .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: +Negative numbers, while accepted, are truncated to zero. +The following scaling units are accepted: .Pp .Bl -tag -width Ds -offset indent -compact .It c @@ -286,10 +278,26 @@ Using anything other than .Sq u , or .Sq v -is necessarily non-portable across output media. See +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 +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, +or question mark followed by zero or more non-sentence closing +delimiters ( +.Ns Sq \&) , +.Sq \&] , +.Sq \&' , +.Sq \&" ) . +.Pp +The proper spacing is also intelligently preserved if a sentence ends at +the boundary of a macro line, e.g., +.Pp +.D1 \&Xr mandoc 1 \. +.D1 \&Fl T \&Ns \&Cm ascii \. .Sh MANUAL STRUCTURE A well-formed .Nm @@ -303,15 +311,18 @@ and .Sx \&Os macros, is required for every document. .Pp -The first section (sections are denoted by +The first section (sections are denoted by .Sx \&Sh ) must be the NAME section, consisting of at least one .Sx \&Nm followed by .Sx \&Nd . .Pp -Following that, convention dictates specifying at least the SYNOPSIS and -DESCRIPTION sections, although this varies between manual sections. +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 @@ -320,30 +331,27 @@ file: \&.Dd $\&Mdocdate$ \&.Dt mdoc 7 \&.Os -\&. \&.Sh NAME \&.Nm foo \&.Nd a description goes here -\&.\e\*q The next is for sections 2 & 3 only. +\&.\e\*q The next is for sections 2, 3, & 9 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 The next is for sections 1 & 8 only. +\&.\e\*q .Sh EXIT STATUS \&.\e\*q .Sh EXAMPLES \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. \&.\e\*q .Sh DIAGNOSTICS @@ -361,12 +369,12 @@ utility processes files ... .Pp The sections in a .Nm -document are conventionally ordered as they appear above. Sections -should be composed as follows: +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: +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 @@ -379,22 +387,24 @@ The 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: +assumed to be a function in a section 2, 3, or 9 manual. +The syntax for this is as follows: .Bd -literal -offset indent \&.Lb libarm .Ed .Pp See -.Sx \&Lb -for details. -. +.Sx \&Lb . .It Em SYNOPSIS Documents the utility invocation syntax, function call syntax, or device -configuration. +configuration. .Pp For the first, utilities (sections 1, 6, and 8), this is generally structured as follows: @@ -425,11 +435,49 @@ And for the third, configurations (section 4): \&.Cd \*qit* at isa? port 0x4e\*q .Ed .Pp -Manuals not in these sections generally don't need a +Manuals not in these sections generally don't need a .Em SYNOPSIS . -. +.Pp +Some macros are displayed differently in the +.Em SYNOPSIS +section, particularly +.Sx \&Nm , +.Sx \&Cd , +.Sx \&Fd , +.Sx \&Fn , +.Sx \&Fo , +.Sx \&In , +.Sx \&Vt , +and +.Sx \&Ft . +All of these macros are output on their own line. +If two such dissimilar macros are pair-wise 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 \&Sx , +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 command), such as: @@ -440,125 +488,113 @@ The arguments are as follows: 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 . -. +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. +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.). +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 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 EXAMPLES -Example usages. This often contains snippets of well-formed, -well-tested invocations. Make doubly sure that your examples work -properly! -. +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. +Documents error conditions. +This is most useful in section 4 manuals. Historically, this section was used in place of .Em EXIT STATUS for manuals in sections 1, 6, and 8; however, this practise is discouraged. .Pp See -.Sx \&Bl No \-diag . -. +.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. +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 +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 \&. , -at the beginning of the line. An arbitrary amount of whitespace may -sit between the control character and the macro name. Thus, the -following are equivalent: +at the beginning of the line. +An arbitrary amount of whitespace may sit between the control character +and the macro name. +Thus, the following are equivalent: .Bd -literal -offset indent \&.Pp \&.\ \ \ \&Pp .Ed -. .Pp -The syntax of a macro depends on its classification. In this section, +The syntax of a macro depends on its classification. +In this section, .Sq \-arg refers to macro arguments, which may be followed by zero or more .Sq parm @@ -567,33 +603,30 @@ parameters; opens the scope of a macro; and if specified, .Sq \&Yc closes it out. -. .Pp The .Em Callable column indicates that the macro may be called subsequent to the initial -line-macro. If a macro is not callable, then its invocation after the -initial line macro is interpreted as opaque text, such that +line-macro. +If a macro is not callable, then its invocation after the initial line +macro is interpreted as opaque text, such that .Sq \&.Fl \&Sh produces .Sq Fl \&Sh . -. .Pp The .Em Parsable column indicates whether the macro may be followed by further -(ostensibly callable) macros. If a macro is not parsable, subsequent -macro invocations on the line will be interpreted as opaque text. -. +(ostensibly callable) macros. +If a macro is not parsable, subsequent macro invocations on the line +will be interpreted as opaque text. .Pp The .Em Scope column, if applicable, describes closure rules. -. -. .Ss Block full-explicit -Multi-line scope closed by an explicit closing macro. All macros -contains bodies; only +Multi-line scope closed by an explicit closing macro. +All macros contains bodies; only .Sx \&Bf contains a head. .Bd -literal -offset indent @@ -601,7 +634,6 @@ contains a head. \(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 @@ -614,8 +646,6 @@ contains a head. .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 Multi-line scope closed by end-of-file or implicitly by another macro. All macros have bodies; some @@ -629,26 +659,34 @@ All macros have bodies; some don't have heads; only one .Po .Sx \&It Fl column -.Pc +.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 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 +Like block full-explicit, but also with single-line scope. +Each has at least a body and, in limited circumstances, a head .Po .Sx \&Fo , .Sx \&Eo @@ -663,7 +701,6 @@ and/or tail \&.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 @@ -692,8 +729,6 @@ and/or tail .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 Like block full-implicit, but with single-line scope closed by .Sx Reserved Characters @@ -701,7 +736,6 @@ or end of line. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB .Ed -. .Pp .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent .It Em Macro Ta Em Callable Ta Em Parsable @@ -716,15 +750,24 @@ or end of line. .It Sx \&Ql Ta Yes Ta Yes .It Sx \&Qq Ta Yes Ta Yes .It Sx \&Sq Ta Yes Ta Yes +.It Sx \&Vt Ta Yes Ta Yes .El -. -. +.Pp +Note that the +.Sx \&Vt +macro is a +.Sx Block partial-implicit +only when invoked as the first macro +in a +.Em SYNOPSIS +section line, else it is +.Sx In-line . .Ss In-line Closed by .Sx Reserved Characters , -end of line, fixed argument lengths, and/or subsequent macros. In-line -macros have only text children. If a number (or inequality) of -arguments is +end of line, fixed argument lengths, and/or subsequent macros. +In-line macros have only text children. +If a number (or inequality) of arguments is .Pq n , then the macro accepts an arbitrary number of arguments. .Bd -literal -offset indent @@ -734,7 +777,6 @@ then the macro accepts an arbitrary number of arguments. \&.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 @@ -797,7 +839,7 @@ then the macro accepts an arbitrary number of arguments. .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 \&Pf Ta Yes 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 @@ -809,31 +851,30 @@ then the macro accepts an arbitrary number of arguments. .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 \&Xr Ta Yes Ta Yes Ta >0 .It Sx \&br Ta \&No Ta \&No Ta 0 .It Sx \&sp Ta \&No Ta \&No Ta 1 -.El -. -. +.El .Sh REFERENCE This section is a canonical reference of all macros, arranged -alphabetically. For the scoping of individual macros, see +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 +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 @@ -842,84 +883,73 @@ block. .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 .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 +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. -. +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. -. +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 -. +.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 +Author name. +This macro may alternatively accepts the following arguments, although +these may not be specified along with a parameter: +.Pp +.Bl -tag -width "-nosplitX" -offset indent -compact .It Fl split Renders a line break before each author listing. .It Fl nosplit @@ -927,57 +957,55 @@ The opposite of .Fl split . .El .Pp -In the AUTHORS section, the default is not to split the first author +In the +.Em 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 +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 +will cause the first listing also to be split. +If not in the +.Em 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 +.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 +are re-set when entering the +.Em AUTHORS +section, so if one specifies .Sx \&An Fl nosplit -in the general document body, it must be re-specified in the AUTHORS +in the general document body, it must be re-specified in the +.Em AUTHORS section. -. .Ss \&Ao -Begins a block enclosed by angled brackets. Does not have any head -arguments. +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 +.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac .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 -. +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 angled brackets. .Pp Examples: -.Bd -literal -offset indent -\&.Fl -key= Ns Aq Ar val -.Ed +.D1 \&.Fl -key= \&Ns \&Aq \&Ar val .Pp .Em Remarks : this macro is often abused for rendering URIs, which should instead use @@ -991,22 +1019,21 @@ statements, which should use .Pp See also .Sx \&Ao . -. .Ss \&Ar -Command arguments. If an argument is not provided, the string +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 -. +.D1 \&.Fl o \&Ns \&Ar file1 +.D1 \&.Ar +.D1 \&.Ar arg1 , arg2 . .Ss \&At -Formats an AT&T version. Accepts at most one parameter: -.Bl -tag -width 12n -offset indent +Formats an AT&T version. +Accepts at most one parameter: +.Pp +.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact .It Cm v[1-7] | 32v A version of .At . @@ -1018,10 +1045,8 @@ A system version of Note that these parameters do not begin with a hyphen. .Pp Examples: -.Bd -literal -offset indent -\&.At -\&.At V.1 -.Ed +.D1 \&.At +.D1 \&.At V.1 .Pp See also .Sx \&Bsx , @@ -1032,17 +1057,25 @@ See also .Sx \&Ox , and .Sx \&Ux . -. .Ss \&Bc Closes 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. +Begins a display block. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Bd +.Fl type +.Op Fl offset Ar width +.Op Fl compact +.Ed +.Pp +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: @@ -1060,11 +1093,12 @@ Alias for Centre-justify each line. .El .Pp -The type must be provided first. Secondary arguments are as follows: +The type must be provided first. +Secondary arguments are as follows: .Bl -tag -width 12n -offset indent -.It Fl offset Ar width +.It Fl offset Ar val Offset by the value of -.Ar width , +.Ar val , which is interpreted as one of the following, specified in order: .Bl -item .It @@ -1075,14 +1109,14 @@ the width of standard indentation; twice .Ar indent ; .Ar left , -which has no effect ; +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 +As a precalculated width for a named macro. +The most popular is the imaginary macro .Ar \&Ds , which resolves to .Ar 6n . @@ -1093,16 +1127,9 @@ As a scaling unit following the syntax described in 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 . +If not provided an argument, it will be 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. .El .Pp Examples: @@ -1116,31 +1143,198 @@ See also .Sx \&D1 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 , +and +.Sx \&Sy . .Ss \&Bk +Begins a collection of macros or text not breaking the line. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Bk Fl words +.Pp +Subsequent arguments are ignored. +The +.Fl words +argument is required. +.Pp +Each line within a keep block is kept intact, so 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. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Bl +.Fl type +.Op Fl width Ar val +.Op Fl offset Ar val +.Op Fl compact +.Op HEAD ... +.Ed +.Pp +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 +.Sx \&It +macro, which consists of a head and optional body (depending on the list +type). +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 +.Fl width +argument varies the width of list bodies' left-margins. +.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 +.Sx Scaling Widths +or literal text. +If the initial macro of a +.Fl column +list is not an +.Sx \&It , +an +.Sx \&It +context spanning each line is implied until an +.Sx \&It +line macro is encountered, at which point list bodies are 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. +.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. +.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. +.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. +.It Fl hyphen +Synonym for +.Fl dash . +.It Fl inset +List bodies follow the list head. +The +.Fl width +argument is ignored. +.It Fl item +This produces blocks of text. +The head of list entries must be empty. +The +.Fl width +argument is ignored. +.It Fl ohang +List bodies are positioned on the line following the head. +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 +.Fl width +argument. +.El +.Pp +See also +.Sx \&It . .Ss \&Bo -Begins a block enclosed by square brackets. Does not have any head -arguments. +Begins 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 +\&.Dv BUFSIZ \&Bc .Ed .Pp See also .Sx \&Bq . -. .Ss \&Bq -Encloses its arguments in square brackets. +Encloses its arguments in square brackets. .Pp Examples: -.Bd -literal -offset indent -\&.Bq 1 , Dv BUFSIZ -.Ed +.D1 \&.Bq 1 , \&Dv BUFSIZ .Pp .Em Remarks : this macro is sometimes abused to emulate optional arguments for @@ -1152,45 +1346,38 @@ and .Pp See also .Sx \&Bo . -. .Ss \&Brc Closes 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. Does not have any head -arguments. +Begins 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 +\&.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 +.D1 \&.Brq 1 , ... , \&Va n .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 +.D1 \&.Bsx 1.0 +.D1 \&.Bsx .Pp See also .Sx \&At , @@ -1201,20 +1388,16 @@ See also .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 +.D1 \&.Bx 4.4 +.D1 \&.Bx .Pp See also .Sx \&At , @@ -1225,64 +1408,64 @@ See also .Sx \&Ox , and .Sx \&Ux . -. .Ss \&Cd -Configuration declaration (suggested for use only in section four -manuals). This denotes strings accepted by +Configuration declaration. +This denotes strings accepted by .Xr config 8 . .Pp Examples: -.Bd -literal -offset indent -\&.Cd device le0 at scode? -.Ed +.D1 \&.Cd device le0 at scode? .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. -. +declarations. +This practise is discouraged. .Ss \&Cm -Command modifiers. Useful when specifying configuration options or -keys. +Command modifiers. +Useful when specifying configuration options or keys. .Pp Examples: -.Bd -literal -offset indent -\&.Cm ControlPath -\&.Cm ControlMaster -.Ed +.D1 \&.Cm ControlPath +.D1 \&.Cm ControlMaster .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. +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 +.D1 \&.D1 \&Fl abcdefgh .Pp See also .Sx \&Bd and .Sx \&Dl . -. .Ss \&Db +Start a debugging context. +This macro is parsed, but generally ignored. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Db Cm on | off .Ss \&Dc Closes 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 +Document date. +This is the mandatory first macro of any .Nm -manual. Its calling syntax is as follows: +manual. +Its syntax is as follows: .Pp -.D1 \. Ns Sx \&Dd Cm date +.D1 Pf \. Sx \&Dd Cm date .Pp -The +The .Cm date field may be either .Ar $\&Mdocdate$ , @@ -1293,69 +1476,84 @@ or instead a valid canonical date as specified by 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 +.D1 \&.Dd $\&Mdocdate$ +.D1 \&.Dd $\&Mdocdate: July 21 2007$ +.D1 \&.Dd July 21, 2007 .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. +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 +.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. +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 +.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 +.Bd -literal -offset indent -compact \&.Dq April is the cruellest month \e(em T.S. Eliot .Ed .Pp See also +.Sx \&Qq , +.Sx \&Sq , +and .Sx \&Do . -. .Ss \&Dt -Document title. This is the mandatory second macro of any +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 +file. +Its syntax is as follows: +.Bd -ragged -offset indent +.Pf \. Sx \&Dt +.Oo +.Cm title +.Oo +.Cm section +.Op Cm volume | arch +.Oc +.Oc +.Ed .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. +The document's title (name), defaulting to +.Dq UNKNOWN +if unspecified. +It should be capitalised. .It Cm section -The manual section. This may be one of +The manual section. +This may be one of .Ar 1 .Pq utilities , .Ar 2 @@ -1389,8 +1587,9 @@ The manual section. This may be one of or .Ar paper .Pq paper . -It is also required and should correspond to the manual's filename -suffix. +It should correspond to the manual's filename suffix and defaults to +.Dq 1 +if unspecified. .It Cm volume This overrides the volume inferred from .Ar section . @@ -1421,10 +1620,13 @@ or .Ar CON .Pq contributed manuals . .It Cm arch -This specifies a specific relevant architecture. If +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 +subsequent that. +It, too, is optional. +It must be one of .Ar alpha , .Ar amd64 , .Ar amiga , @@ -1437,6 +1639,7 @@ subsequent that. It, too, is optional. It must be one of .Ar hppa64 , .Ar i386 , .Ar landisk , +.Ar loongson , .Ar luna88k , .Ar mac68k , .Ar macppc , @@ -1455,39 +1658,30 @@ or .El .Pp Examples: -.Bd -literal -offset indent -\&.Dt FOO 1 -\&.Dt FOO 4 KM -\&.Dt FOO 9 i386 -\&.Dt FOO 9 KM i386 -.Ed +.D1 \&.Dt FOO 1 +.D1 \&.Dt FOO 4 KM +.D1 \&.Dt FOO 9 i386 .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 +.D1 \&.Dv BUFSIZ +.D1 \&.Dv STDOUT_FILENO .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 +.D1 \&.Dx 2.4.1 +.D1 \&.Dx .Pp See also .Sx \&At , @@ -1498,77 +1692,239 @@ See also .Sx \&Ox , and .Sx \&Ux . -. .Ss \&Ec +Close a scope started by +.Sx \&Eo . +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ec Op Cm TERM +.Pp +The +.Cm 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 +Ends a font mode context started by +.Sx \&Bf . .Ss \&Ek +Ends a keep context started by +.Sx \&Bk . .Ss \&El +Ends a list context started by +.Sx \&Bl . +.Pp +See also +.Sx \&Bl +and +.Sx \&It . .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. +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 -. +.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. .Ss \&Eo +An arbitrary enclosure. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Eo Op Cm TERM +.Pp +The +.Cm TERM +argument is used as the enclosure head, for example, specifying \e(lq +will emulate +.Sx \&Do . .Ss \&Er -Error constants (suggested for use only in section two manuals). +Display error constants. .Pp Examples: -.Bd -literal -offset indent -\&.Er EPERM -\&.Er ENOENT -.Ed +.D1 \&.Er EPERM +.D1 \&.Er ENOENT .Pp 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 . .Pp Examples: -.Bd -literal -offset indent -\&.Ev DISPLAY -\&.Ev PATH -.Ed -. +.D1 \&.Ev DISPLAY +.D1 \&.Ev PATH .Ss \&Ex -Inserts text regarding a utility's exit values. This macro must have -first the +Inserts text regarding a utility's exit value. +This macro must consist of the .Fl std -argument specified, then an optional +argument followed by an optional .Ar utility . If .Ar utility is not provided, the document's name as stipulated in .Sx \&Nm is provided. +.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. +Furthermore, if the following macro is another +.Sx \&Fa , +the last argument will also have a trailing comma. +.Pp +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 +Ends a function context started by +.Sx \&Fo . .Ss \&Fd +Historically used to document include files. +This usage has been deprecated in favour of +.Sx \&In . +Do not use this macro. +.Pp +See also +.Sx MANUAL STRUCTURE +and +.Sx \&In . .Ss \&Fl +Command-line flag. +Used when listing arguments to command-line utilities. +Prints a fixed-width hyphen +.Sq \- +directly followed by each argument. +If no arguments are provided, a hyphen is printed followed by a space. +If the argument is a macro, a hyphen is prefixed to the subsequent macro +output. +.Pp +Examples: +.D1 \&.Fl a b c +.D1 \&.Fl \&Pf a b +.D1 \&.Fl +.D1 \&.Op \&Fl o \&Ns \&Ar file +.Pp +See also +.Sx \&Cm . .Ss \&Fn +A function name. +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 +.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 "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 -.Ss \&Fr +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 \&Fc , +and +.Sx \&Ft . .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 if no argument is provided. .Pp Examples: -.Bd -literal -offset indent -\&.Fx 7.1 -\&.Fx -.Ed +.D1 \&.Fx 7.1 +.D1 \&.Fx .Pp See also .Sx \&At , @@ -1579,43 +1935,277 @@ See also .Sx \&Ox , 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 No Fl literal +or +.Sx \&D1 +is preferred for displaying code; the +.Sx \&Ic +macro is used when referring to specific instructions. .Ss \&In +An +.Dq include +file. +In the +.Em SYNOPSIS +section (only if invoked as the line macro), the first argument is +preceded by +.Dq #include , +the arguments is enclosed in angled braces. +.Pp +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. +.Pp +Lists +of type +.Fl hang , +.Fl ohang , +.Fl inset , +and +.Fl diag +have the following syntax: +.Pp +.D1 Pf \. Sx \&It Cm args +.Pp +Lists of type +.Fl bullet , +.Fl dash , +.Fl enum , +.Fl hyphen +and +.Fl item +have the following syntax: +.Pp +.D1 Pf \. Sx \&It +.Pp +with subsequent lines interpreted within the scope of the +.Sx \&It +until either a closing +.Sx \&El +or another +.Sx \&It . +.Pp +The +.Fl tag +list has the following syntax: +.Pp +.D1 Pf \. Sx \&It Op Cm args +.Pp +Subsequent lines are interpreted as with +.Fl bullet +and family. +The line arguments correspond to the list's left-hand side; body +arguments correspond to the list's contents. +.Pp +The +.Fl column +list is the most complicated. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&It Op Cm args +.Pp +The +.Cm args +are phrases, a mix of macros and text corresponding to a line column, +delimited by tabs or the special +.Sq \&Ta +pseudo-macro. +Lines subsequent the +.Sx \&It +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 +.Sx \&It +line itself. +Subsequent this, only the +.Sq \&Ta +pseudo-macro may be used to delimit phrases. +Furthermore, note that quoted sections propagate over tab-delimited +phrases on an +.Sx \&It , +for example, +.Pp +.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&; +.Pp +will preserve the semicolon whitespace except for the last. +.Pp +See also +.Sx \&Bl . .Ss \&Lb +Specify a library. +The syntax is as follows: +.Pp +.D1 Pf \. Sx \&Lb Cm library +.Pp +The +.Cm library +parameter may be a system library, such as +.Cm libz +or +.Cm libpam , +in which case a small library description is printed next to the linker +invocation; or a custom library, in which case the library name is +printed in quotes. +This is most commonly used in the +.Em SYNOPSIS +section as described in +.Sx MANUAL STRUCTURE . +.Pp +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: +Format a hyperlink. +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: -.Bd -literal -offset indent -\&.Lk http://bsd.lv "The BSD.lv Project" -\&.Lk http://bsd.lv -.Ed +.D1 \&.Lk http://bsd.lv "The BSD.lv Project" +.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 +.Dq mailto: +hyperlink. +Its syntax is as follows: +.Pp +.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 no argument is provided. .Pp Examples: -.Bd -literal -offset indent -\&.Nx 5.01 -\&.Nx -.Ed +.D1 \&.Nx 5.01 +.D1 \&.Nx .Pp See also .Sx \&At , @@ -1626,51 +2216,68 @@ See also .Sx \&Ox , and .Sx \&Ux . -. .Ss \&Oc +Closes 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 +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 .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. +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 +.D1 \&.Os +.D1 \&.Os KTH/CSC/TCS +.D1 \&.Os BSD 4.3 .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 +.D1 \&.Ox 4.5 +.D1 \&.Ox .Pp See also .Sx \&At , @@ -1681,28 +2288,79 @@ See also .Sx \&Nx , 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 .Sx \&Rs -block. Does not have any tail arguments. -. +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 +block. +Does not have any head arguments. +The block macro may only contain .Sx \&%A , .Sx \&%B , .Sx \&%C , @@ -1715,12 +2373,13 @@ contain .Sx \&%Q , .Sx \&%R , .Sx \&%T , +.Sx \&%U , and .Sx \&%V child macros (at least one must be specified). .Pp Examples: -.Bd -literal -offset indent +.Bd -literal -offset indent -compact \&.Rs \&.%A J. E. Hopcroft \&.%A J. D. Ullman @@ -1736,26 +2395,210 @@ If an 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. .Ss \&Ux -Format the UNIX name. Accepts no argument. +Format the UNIX name. +Accepts no argument. .Pp Examples: -.Bd -literal -offset indent -\&.Ux -.Ed +.D1 \&.Ux .Pp See also .Sx \&At , @@ -1766,50 +2609,197 @@ See also .Sx \&Nx , 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 +.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 +.Em SYNOPSIS +section, else it accepts ordinary +.Sx In-line +syntax. +.Pp +Note that this should not be confused with +.Sx \&Ft , +which is used for function return types. +.Pp +Examples: +.D1 \&.Vt unsigned char +.D1 \&.Vt extern const char * const sys_signame[] \&; +.Pp +See also +.Sx MANUAL STRUCTURE +and +.Sx \&Va . .Ss \&Xc +Close a scope opened by +.Sx \&Xo . .Ss \&Xo +Open an extension scope. +This macro originally existed to extend the 9-argument limit of troff; +since this limit has been lifted, the macro has been deprecated. .Ss \&Xr +Link to another manual +.Pq Qq cross-reference . +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Xr Cm name section +.Pp +The +.Cm name +and +.Cm section +are the name and section of the linked manual. +If +.Cm section +is followed by non-punctuation, an +.Sx \&Ns +is inserted into the token stream. +This behaviour is for compatibility with +.Xr groff 1 . +.Pp +Examples: +.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 with other roff implementations, at -this time limited to -.Xr groff 1 . +This section documents compatibility between mandoc and other other +troff implementations, at this time limited to GNU troff +.Pq Qq groff . The term .Qq historic groff -refers to those versions before the +refers to groff versions before the .Pa doc.tmac file re-write .Pq somewhere between 1.15 and 1.19 . -. +.Pp +Heirloom troff, the other significant troff implementation accepting +\-mdoc, is similar to historic groff. .Pp .Bl -dash -compact .It -Negative scaling units are now truncated to zero instead of creating -interesting conditions, such as with -.Sq \&sp -1i . +The \es (font size), \em (font colour), and \eM (font filling colour) +font decoration escapes are all discarded in mandoc. +.It +Old groff fails to assert a newline before +.Sx \&Bd Fl ragged compact . +.It +groff behaves inconsistently when encountering +.Pf non- Sx \&Fa +children of +.Sx \&Fo +regarding spacing between arguments. +In mandoc, this is not the case: each argument is consistently followed +by a single space and the trailing +.Sq \&) +suppresses prior spacing. +.It +groff behaves inconsistently when encountering +.Sx \&Ft +and +.Sx \&Fn +in the +.Em SYNOPSIS : +at times newline(s) are suppressed depending on whether a prior +.Sx \&Fn +has been invoked. +In mandoc, this is not the case. +See +.Sx \&Ft +and +.Sx \&Fn +for the normalised behaviour. +.It +Historic groff does not break before an +.Sx \&Fn +when not invoked as the line macro in the +.Em SYNOPSIS +section. +.It +Historic groff formats the +.Sx \&In +badly: trailing arguments are trashed and +.Em SYNOPSIS +is not specially treated. +.It +groff does not accept the +.Sq \&Ta +pseudo-macro as a line macro. +mandoc does. +.It +The comment syntax +.Sq \e\." +is no longer accepted. +.It +In groff, the +.Sx \&Pa +macro does not format its arguments when used in the FILES section under +certain list types. +mandoc does. +.It +Historic groff does not print a dash for empty +.Sx \&Fl +arguments. +mandoc and newer groff implementations do. +.It +groff behaves irregularly when specifying +.Sq \ef +.Sx Text Decoration +within line-macro scopes. +mandoc follows a consistent system. +.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. .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. +standalone double-quote in formatted output. +This idiosyncratic behaviour is not applicable in mandoc. .It -Display types -.Sx \&Bd Fl center +Display offsets +.Sx \&Bd +.Fl offset Ar center and -.Fl right -are aliases for -.Fl left . -The +.Fl offset Ar right +are disregarded in mandoc. +Furthermore, troff specifies a .Fl file Ar file -argument is ignored. Since text is not right-justified, +argument that is not supported in mandoc. +Lastly, since text is not right-justified in mandoc (or even groff), .Fl ragged and .Fl filled @@ -1818,19 +2808,14 @@ are aliases, as are and .Fl unfilled . .It -Blocks of whitespace are stripped from both macro and free-form text -lines (except when in literal mode), while groff would retain whitespace -in free-form text lines. -.It -Historic groff has many un-callable macros. Most of these (excluding -some block-level macros) are now callable, conforming to the -non-historic groff version. +Historic groff has many un-callable macros. +Most of these (excluding some block-level macros) are now callable. .It The vertical bar .Sq \(ba made historic groff .Qq go orbital -but is a proper delimiter in this implementation. +but has been a proper delimiter since then. .It .Sx \&It Fl nested is assumed for all lists (it wasn't in historic groff): any list may be @@ -1841,89 +2826,29 @@ lists will restart the sequence only for the sub-list. Some manuals use .Sx \&Li incorrectly by following it with a reserved character and expecting the -delimiter to render. This is not supported. +delimiter to render. +This is not supported in mandoc. .It In groff, the -.Sx \&Fo -macro only produces the first parameter. This is no longer the case. +.Sx \&Cd , +.Sx \&Er , +.Sx \&Ex , +and +.Sx \&Rv +macros were stipulated only to occur in certain manual sections. +mandoc does not have these restrictions. +.It +Newer groff and mandoc print +.Qq AT&T UNIX +prior to unknown arguments of +.Sx \&At ; +older groff did nothing. .El -. -. .Sh SEE ALSO .Xr mandoc 1 , .Xr mandoc_char 7 -. -. .Sh AUTHORS The .Nm reference was written by -.An Kristaps Dzonsons Aq kristaps@kth.se . -.\" -.\" XXX: this really isn't the place for these caveats. -.\" . -.\" . -.\" .Sh CAVEATS -.\" There are many ambiguous parts of mdoc. -.\" . -.\" .Pp -.\" .Bl -dash -compact -.\" .It -.\" .Sq \&Fa -.\" should be -.\" .Sq \&Va -.\" as function arguments are variables. -.\" .It -.\" .Sq \&Ft -.\" should be -.\" .Sq \&Vt -.\" as function return types are still types. Furthermore, the -.\" .Sq \&Ft -.\" should be removed and -.\" .Sq \&Fo , -.\" which ostensibly follows it, should follow the same convention as -.\" .Sq \&Va . -.\" .It -.\" .Sq \&Va -.\" should formalise that only one or two arguments are acceptable: a -.\" variable name and optional, preceding type. -.\" .It -.\" .Sq \&Fd -.\" is ambiguous. It's commonly used to indicate an include file in the -.\" synopsis section. -.\" .Sq \&In -.\" should be used, instead. -.\" .It -.\" Only the -.\" .Sq \-literal -.\" argument to -.\" .Sq \&Bd -.\" makes sense. The remaining ones should be removed. -.\" .It -.\" The -.\" .Sq \&Xo -.\" and -.\" .Sq \&Xc -.\" macros should be deprecated. -.\" .It -.\" The -.\" .Sq \&Dt -.\" macro lacks clarity. It should be absolutely clear which title will -.\" render when formatting the manual page. -.\" .It -.\" A -.\" .Sq \&Lx -.\" should be provided for Linux (\(`a la -.\" .Sq \&Ox , -.\" .Sq \&Nx -.\" etc.). -.\" .It -.\" There's no way to refer to references in -.\" .Sq \&Rs/Re -.\" blocks. -.\" .It -.\" The \-split and \-nosplit dictates via -.\" .Sq \&An -.\" are re-set when entering and leaving the AUTHORS section. -.\" .El -.\" . +.An Kristaps Dzonsons Aq kristaps@bsd.lv .