=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.135 retrieving revision 1.201 diff -u -p -r1.135 -r1.201 --- mandoc/mdoc.7 2010/07/16 21:09:39 1.135 +++ mandoc/mdoc.7 2011/08/17 22:20:14 1.201 @@ -1,6 +1,6 @@ -.\" $Id: mdoc.7,v 1.135 2010/07/16 21:09:39 kristaps Exp $ +.\" $Id: mdoc.7,v 1.201 2011/08/17 22:20:14 kristaps Exp $ .\" -.\" Copyright (c) 2009, 2010 Kristaps Dzonsons +.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2010 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -15,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: July 16 2010 $ +.Dd $Mdocdate: August 17 2011 $ .Dt MDOC 7 .Os .Sh NAME @@ -27,73 +27,64 @@ 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 for +.Nm +formatting is +.Xr mandoc 1 ; +the .Sx COMPATIBILITY -section describes compatibility with other troff \-mdoc implementations. +section describes compatibility with other implementations. .Pp An .Nm document follows simple rules: lines beginning with the control character -.Sq \. -are parsed for macros. Other lines are interpreted within the scope of -prior macros: +.Sq \&. +are parsed for macros. +Lines not beginning with the control character 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. +Text lines are interpreted within the current state. .Ed .Sh LANGUAGE SYNTAX .Nm documents may contain only graphable 7-bit ASCII characters, the space -character, and, in certain circumstances, the tab character. All -manuals must have -.Ux -line terminators. +character, and, in certain circumstances, the tab character. +The back-space character +.Sq \e +indicates the start of an escape sequence for +.Sx Comments , +.Sx Predefined Strings , +and +.Sx Special Characters . .Ss Comments -Text following a +Text following an escaped double-quote .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\*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: +whether in a macro or text line, is ignored to the end of +line. +A macro line beginning with a control character and comment escape +.Sq \&.\e\*q +is also ignored. +Furthermore, +macro lines with only a control character and optional trailing +whitespace are +stripped from input. .Pp -.Bl -tag -width Ds -offset indent -compact -.It \&. -.Pq period -.It \&, -.Pq comma -.It \&: -.Pq colon -.It \&; -.Pq semicolon -.It \&( -.Pq left-parenthesis -.It \&) -.Pq right-parenthesis -.It \&[ -.Pq left-bracket -.It \&] -.Pq right-bracket -.It \&? -.Pq question -.It \&! -.Pq exclamation -.It \&| -.Pq vertical bar -.El -.Pp -Use of reserved characters is described in -.Sx MACRO SYNTAX . -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. +Examples: +.Bd -literal -offset indent -compact +\&.\e\*q This is a comment line. +\&.\e\*q The next line is ignored: +\&. +\&.Em Emphasis \e\*q This is also a comment. +.Ed .Ss Special Characters -Special characters may occur in both macro and free-form lines. +Special characters are used to encode special glyphs and are rendered +differently across output media. +They may occur in both macro and text lines. Sequences begin with the escape character .Sq \e followed by either an open-parenthesis @@ -102,73 +93,53 @@ 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. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It \e(em +em dash +.It \ee +backslash +.El +.Pp See .Xr mandoc_char 7 for a complete list. -Examples include -.Sq \e(em -.Pq em-dash -and -.Sq \ee -.Pq back-slash . .Ss Text Decoration Terms may be text-decorated using the .Sq \ef -escape followed by an indicator: B (bold), I, (italic), 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, +escape followed by an indicator: B (bold), I (italic), R (regular), or P +(revert to previous mode). +A numerical representation 3, 2, or 1 (bold, italic, and regular, 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 +If a macro opens a font scope after calling +.Sq \ef , +such as with +.Sx \&Bf , +the .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. +mode will be restored upon exiting the +.Sx \&Bf +scope. .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: +Examples: +.Bl -tag -width Ds -offset indent -compact +.It \efBbold\efR +write in bold, then switch to regular +.It \efIitalic\efP +write in italic, then return to previous +.El .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 +Text decoration is .Em not recommended for .Nm , which encourages semantic annotation. .Ss Predefined Strings -Historically, -.Xr groff 1 -also defined a set of package-specific -.Dq predefined strings , -which, like +Predefined strings, like .Sx Special Characters , -mark special output characters and strings by way of input codes. +mark special output glyphs. Predefined strings are escaped with the slash-asterisk, .Sq \e* : single-character @@ -177,85 +148,79 @@ two-character .Sq \e*(XX , and N-character .Sq \e*[N] . -See -.Xr mandoc_char 7 -for a complete list. -Examples include -.Sq \e*(Am -.Pq ampersand -and -.Sq \e*(Ba -.Pq vertical bar . +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It \e*(Am +ampersand +.It \e*(Ba +vertical bar +.El +.Pp +These strings are set using +.Xr roff 7 , +although +.Nm +consists of several pre-set escapes listed in +.Xr mandoc_char 7 . .Ss Whitespace 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 text lines, whitespace is preserved within a line. 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. .Pp -This produces tokens -.Sq a" , -.Sq b c , -.Sq de , -and -.Sq fg" . -Note that any quoted term, be it argument or macro, is indiscriminately -considered literal text. -Thus, the following produces -.Sq \&Em a : -.Bd -literal -offset indent -\&.Em "Em a" -.Ed +Unescaped trailing spaces are stripped from text line input unless in a +literal context. +In general, trailing whitespace on any input line is discouraged for +reasons of portability. +In the rare case that a blank character is needed at the end of an +input line, it may be forced by +.Sq \e\ \e& . .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: +Blank text lines, which may include whitespace, are only permitted +within literal contexts. +If the first character of a text line is a space, that line is printed +with a leading newline. +.Ss Quotation +Macro arguments may be quoted with double-quotes; in this case, +whitespace within the quotes is retained as part of the argument. +For example, .Pp -.D1 Cm Month Day , Year +.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq" .Pp -The -.Cm Day -value is an optionally zero-padded numeral. -The -.Cm Month -value is the full month name. -The -.Cm Year -value is the full four-digit year. +renders as +.Sq Fn strlen "const char *s" , +while .Pp -Reduced form dates are broken-down canonical form dates: +.D1 Pf \. \&Fn strlen "const char *s" .Pp -.D1 Cm Month , Year -.D1 Cm Year +would produce +.Sq Fn strlen const char *s . .Pp -Some examples of valid dates follow: +A quoted argument begins with a double-quote preceded by whitespace. +The next double-quote not pairwise adjacent to another double-quote +terminates the literal, regardless of surrounding whitespace. .Pp -.D1 "May, 2009" Pq reduced form -.D1 "2009" Pq reduced form -.D1 "May 20, 2009" Pq canonical form -.Ss Scaling Widths -Many macros support scaled widths for their arguments, such as -stipulating a two-inch list indentation with the following: +In unquoted arguments, space characters can alternatively be included +by preceding them with a backslash +.Pq Sq \e\~ , +but quoting is usually better for clarity. +.Pp +Note that any quoted text, even if it would cause a macro invocation +when unquoted, is considered literal text. +Thus, the following produces +.Sq Op "Fl a" : .Bd -literal -offset indent -\&.Bl -tag -width 2i +\&.Op "Fl a" .Ed .Pp -The syntax for scaled widths is +In text lines, quotes are regarded as opaque text. +.Ss Scaling Widths +Many macros support scaled widths for their arguments. +The syntax for a scaled width 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. +.Pp The following scaling units are accepted: .Pp .Bl -tag -width Ds -offset indent -compact @@ -297,35 +262,51 @@ or is necessarily non-portable across output media. See .Sx COMPATIBILITY . +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It \&.Bl -tag -width 2i +two-inch tagged list indentation +.Pq see Sx \&Bl +.It \&.sp 2v +two vertical spaces +.Pq see Sx \&sp +.El .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 +Sentences should terminate at the end of an input line. +By doing this, a formatter 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 \&) , +delimiters +.Po +.Sq \&) , .Sq \&] , .Sq \&' , -.Sq \&" ) . +.Sq \&" +.Pc . .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. .Pp -.D1 \&Xr mandoc 1 \. -.D1 \&Fl T \&Ns \&Cm ascii \. +Examples: +.Bd -literal -offset indent -compact +Do not end sentences mid-line like this. Instead, +end a sentence like this. +A macro would end like this: +\&.Xr mandoc 1 \&. +.Ed .Sh MANUAL STRUCTURE A well-formed .Nm document consists of a document prologue followed by one or more sections. .Pp -The prologue, which consists of (in order) the +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 ) @@ -342,18 +323,20 @@ sections, although this varies between manual sections .Pp The following is a well-formed skeleton .Nm -file: +file for a utility +.Qq progname : .Bd -literal -offset indent \&.Dd $\&Mdocdate$ -\&.Dt mdoc 7 +\&.Dt PROGNAME section \&.Os \&.Sh NAME -\&.Nm foo -\&.Nd a description goes here -\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.Nm progname +\&.Nd one line about what it does \&.\e\*q .Sh LIBRARY +\&.\e\*q For sections 2, 3, & 9 only. +\&.\e\*q Not used in OpenBSD. \&.Sh SYNOPSIS -\&.Nm foo +\&.Nm progname \&.Op Fl options \&.Ar \&.Sh DESCRIPTION @@ -361,18 +344,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 @@ -381,23 +365,28 @@ 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 +Multiple +.Sq \&Nm +names should be separated by commas. +.Pp The .Sx \&Nm macro(s) must precede the @@ -425,26 +414,36 @@ configuration. For the first, utilities (sections 1, 6, and 8), this is generally structured as follows: .Bd -literal -offset indent -\&.Nm foo +\&.Nm bar \&.Op Fl v \&.Op Fl o Ar file \&.Op Ar -\&.Nm bar +\&.Nm foo \&.Op Fl v \&.Op Fl o Ar file \&.Op Ar .Ed .Pp +Commands should be ordered alphabetically. +.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 *" \&.Fn bar "const char *src" .Ed .Pp +Ordering of +.Sx \&In , +.Sx \&Vt , +.Sx \&Fn , +and +.Sx \&Fo +macros should follow C header-file conventions. +.Pp And for the third, configurations (section 4): .Bd -literal -offset indent \&.Cd \*qit* at isa? port 0x2e\*q @@ -466,8 +465,8 @@ section, particularly .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 +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 @@ -488,14 +487,20 @@ with the text immediately following the .Sx \&Nm macro, up to the next .Sx \&Nm , -.Sx \&Sx , +.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 -.Em NAME . -It usually contains a break-down of the options (if documenting a +This begins with an expansion of the brief, one line description in +.Em NAME : +.Bd -literal -offset indent +The +\&.Nm +utility does this, that, and the other. +.Ed +.Pp +It usually follows with a breakdown of the options (if documenting a command), such as: .Bd -literal -offset indent The arguments are as follows: @@ -506,36 +511,50 @@ Print verbose information. .Ed .Pp Manuals not documenting a command won't include the above fragment. +.Pp +Since the +.Em DESCRIPTION +section usually contains most of the text of a manual, longer manuals +often use the +.Sx \&Ss +macro to form subsections. +In very long manuals, the +.Em DESCRIPTION +may be split into multiple sections, each started by an +.Sx \&Sh +macro followed by a non-standard section name, and each having +several subsections, like in the present +.Nm +manual. .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 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. @@ -545,7 +564,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. @@ -568,7 +587,13 @@ This section should exist for most manuals. Cross-references should conventionally be ordered first by section, then alphabetically. .Pp +References to other documentation concerning the topic of the manual page, +for example authoritative books or journal articles, may also be +provided in this section. +.Pp See +.Sx \&Rs +and .Sx \&Xr . .It Em STANDARDS References any standards implemented or used. @@ -579,26 +604,26 @@ 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 it was first implemented, +and when it was ported to or reimplemented for the operating system at hand. .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 @@ -622,20 +647,32 @@ 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 +column indicates that the macro may also be called by passing its name +as an argument to another macro. +For example, +.Sq \&.Op \&Fl O \&Ar file +produces +.Sq Op Fl O Ar file . +To prevent a macro call and render the macro name literally, +escape it by prepending a zero-width space, +.Sq \e& . +For example, +.Sq \&Op \e&Fl O +produces +.Sq Op \&Fl O . +If a macro is not callable but its name appears as an argument +to another macro, it is interpreted as opaque text. +For example, .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. +.Em Parsed +column indicates whether the macro may call other macros by receiving +their names as arguments. +If a macro is not parsed but the name of another macro appears +as an argument, it is interpreted as opaque text. .Pp The .Em Scope @@ -644,15 +681,18 @@ column, if applicable, describes closure rules. Multi-line scope closed by an explicit closing macro. All macros contains bodies; only .Sx \&Bf -contains a head. +and +.Pq optionally +.Sx \&Bl +contain a head. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \(lBbody...\(rB \&.Yc .Ed .Pp -.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX" -.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope +.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 @@ -674,7 +714,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 @@ -682,13 +724,13 @@ 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 -.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 +.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 Yes Ta closed by Sx \&Sh +.It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss .El .Pp Note that the @@ -718,8 +760,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 @@ -746,15 +788,14 @@ and/or tail .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 -or end of line. +Like block full-implicit, but with single-line scope closed by the +end of the 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 +.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 @@ -778,24 +819,38 @@ in a .Em SYNOPSIS section line, else it is .Sx In-line . +.Ss Special block macro +The +.Sx \&Ta +macro can only be used below +.Sx \&It +in +.Sx \&Bl Fl column +lists. +It delimits blocks representing table cells; +these blocks have bodies, but no heads. +.Pp +.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 \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It +.El .Ss In-line -Closed by -.Sx Reserved Characters , -end of line, fixed argument lengths, and/or subsequent macros. +Closed by the end of the line, fixed argument lengths, +and/or subsequent macros. In-line macros have only text children. If a number (or inequality) of arguments is .Pq n , then the macro accepts an arbitrary number of arguments. .Bd -literal -offset indent -\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb +\&.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 @@ -810,8 +865,8 @@ then the macro accepts an arbitrary number of argument .It Sx \&%T Ta \&No Ta \&No Ta >0 .It Sx \&%U Ta \&No Ta \&No Ta >0 .It Sx \&%V Ta \&No Ta \&No Ta >0 -.It Sx \&Ad Ta Yes Ta Yes Ta n -.It Sx \&An Ta Yes Ta Yes Ta n +.It Sx \&Ad Ta Yes Ta Yes Ta >0 +.It Sx \&An Ta Yes Ta Yes Ta >0 .It Sx \&Ap Ta Yes Ta Yes Ta 0 .It Sx \&Ar Ta Yes Ta Yes Ta n .It Sx \&At Ta Yes Ta Yes Ta 1 @@ -819,31 +874,31 @@ then the macro accepts an arbitrary number of argument .It Sx \&Bt Ta \&No Ta \&No Ta 0 .It Sx \&Bx Ta Yes Ta Yes Ta n .It Sx \&Cd Ta Yes Ta Yes Ta >0 -.It Sx \&Cm Ta Yes Ta Yes Ta n +.It Sx \&Cm Ta Yes Ta Yes Ta >0 .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 \&Dv Ta Yes Ta Yes Ta >0 .It Sx \&Dx Ta Yes Ta Yes Ta n .It Sx \&Em Ta Yes Ta Yes Ta >0 .It Sx \&En Ta \&No Ta \&No Ta 0 .It Sx \&Er Ta Yes Ta Yes Ta >0 .It Sx \&Es Ta \&No Ta \&No Ta 0 -.It Sx \&Ev Ta Yes Ta Yes Ta n +.It Sx \&Ev Ta Yes Ta Yes Ta >0 .It Sx \&Ex Ta \&No Ta \&No Ta n -.It Sx \&Fa Ta Yes Ta Yes Ta n +.It Sx \&Fa Ta Yes Ta Yes Ta >0 .It Sx \&Fd Ta \&No Ta \&No Ta >0 .It Sx \&Fl Ta Yes Ta Yes Ta n .It Sx \&Fn Ta Yes Ta Yes Ta >0 .It Sx \&Fr Ta \&No Ta \&No Ta n -.It Sx \&Ft Ta Yes Ta Yes Ta n +.It Sx \&Ft Ta Yes Ta Yes Ta >0 .It Sx \&Fx Ta Yes Ta Yes Ta n .It Sx \&Hf Ta \&No Ta \&No Ta n .It Sx \&Ic Ta Yes Ta Yes Ta >0 -.It Sx \&In Ta \&No Ta \&No Ta n +.It Sx \&In Ta \&No Ta \&No Ta 1 .It Sx \&Lb Ta \&No Ta \&No Ta 1 -.It Sx \&Li Ta Yes Ta Yes Ta n -.It Sx \&Lk Ta Yes Ta Yes Ta n +.It Sx \&Li Ta Yes Ta Yes Ta >0 +.It Sx \&Lk Ta Yes Ta Yes Ta >0 .It Sx \&Lp Ta \&No Ta \&No Ta 0 .It Sx \&Ms Ta Yes Ta Yes Ta >0 .It Sx \&Mt Ta Yes Ta Yes Ta >0 @@ -871,6 +926,90 @@ then the macro accepts an arbitrary number of argument .It Sx \&br Ta \&No Ta \&No Ta 0 .It Sx \&sp Ta \&No Ta \&No Ta 1 .El +.Ss Delimiters +When a macro argument consists of one single input character +considered as a delimiter, the argument gets special handling. +This does not apply when delimiters appear in arguments containing +more than one character. +Consequently, to prevent special handling and just handle it +like any other argument, a delimiter can be escaped by prepending +a zero-width space +.Pq Sq \e& . +In text lines, delimiters never need escaping, but may be used +as normal punctuation. +.Pp +For many macros, when the leading arguments are opening delimiters, +these delimiters are put before the macro scope, +and when the trailing arguments are closing delimiters, +these delimiters are put after the macro scope. +For example, +.Pp +.D1 Pf \. \&Aq "( [ word ] ) ." +.Pp +renders as: +.Pp +.D1 Aq ( [ word ] ) . +.Pp +Opening delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&( +left parenthesis +.It \&[ +left bracket +.El +.Pp +Closing delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&. +period +.It \&, +comma +.It \&: +colon +.It \&; +semicolon +.It \&) +right parenthesis +.It \&] +right bracket +.It \&? +question mark +.It \&! +exclamation mark +.El +.Pp +Note that even a period preceded by a backslash +.Pq Sq \e.\& +gets this special handling; use +.Sq \e&. +to prevent that. +.Pp +Many in-line macros interrupt their scope when they encounter +delimiters, and resume their scope when more arguments follow that +are not delimiters. +For example, +.Pp +.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" +.Pp +renders as: +.Pp +.D1 Fl a ( b | c \*(Ba d ) e +.Pp +This applies to both opening and closing delimiters, +and also to the middle delimiter: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&| +vertical bar +.El +.Pp +As a special case, the predefined string \e*(Ba is handled and rendered +in the same way as a plain +.Sq \&| +character. +Using this predefined string is not recommended in new manuals. .Sh REFERENCE This section is a canonical reference of all macros, arranged alphabetically. @@ -879,29 +1018,30 @@ 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 -.Sx Dates . +block. +Recommended formats of arguments are +.Ar month day , year +or just +.Ar year . .Ss \&%I Publisher or issuer name of an .Sx \&Rs @@ -925,7 +1065,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 @@ -935,8 +1076,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 @@ -944,70 +1086,71 @@ 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 +.Dl \&.Ad [0,$] +.Dl \&.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 +Can be used both for the authors of the program, function, or driver +documented in the manual, or for the authors of the manual itself. +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. +.Dl \&.An -nosplit +.Dl \&.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: -.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac +.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac .Pp See also .Sx \&Aq . .Ss \&Ap -Inserts an apostrophe without any surrounding white-space. +Inserts an apostrophe without any surrounding whitespace. This is generally used as a grammatical device when referring to the verb -form of a function: -.Bd -literal -offset indent -\&.Fn execve Ap d -.Ed +form of a function. +.Pp +Examples: +.Dl \&.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 +.Dl \&.Fl -key= \&Ns \&Aq \&Ar val .Pp .Em Remarks : this macro is often abused for rendering URIs, which should instead use @@ -1024,30 +1167,42 @@ 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: -.D1 \&.Fl o \&Ns \&Ar file1 -.D1 \&.Ar -.D1 \&.Ar arg1 , arg2 . +.Dl ".Fl o Ar file" +.Dl ".Ar" +.Dl ".Ar arg1 , arg2 ." +.Pp +The arguments to the +.Sx \&Ar +macro are names and placeholders for command arguments; +for fixed strings to be passed verbatim as arguments, use +.Sx \&Fl +or +.Sx \&Cm . .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 III +.At III . .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 -.D1 \&.At V.1 +.Dl \&.At +.Dl \&.At III +.Dl \&.At V.1 .Pp See also .Sx \&Bsx , @@ -1059,82 +1214,100 @@ 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. +Begin a display block. Its syntax is as follows: .Bd -ragged -offset indent .Pf \. Sx \&Bd -.Fl type +.Fl Ns Ar 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. +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 text lines. +By default, a display 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. +The +.Ar type +must be one of the following: +.Bl -tag -width 13n -offset indent +.It Fl centered +Produce one output line from each input line, and 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. +Change the positions of line breaks to fill each line, and left- and +right-justify the resulting block. .It Fl literal -Alias for -.Fl unfilled . -.It Fl centered -Centre-justify each line. +Produce one output line from each input line, +and do not justify the block at all. +Preserve white space as it appears in the input. +Always use a constant-width font. +Use this for displaying source code. +.It Fl ragged +Change the positions of line breaks to fill each line, and left-justify +the resulting block. +.It Fl unfilled +The same as +.Fl literal , +but using the same font as for normal text, which is a variable width font +if supported by the output device. .El .Pp -The type must be provided first. -Secondary arguments are as follows: -.Bl -tag -width 12n -offset indent -.It Fl offset Ar val -Offset by the value of -.Ar val , -which is interpreted as one of the following, specified in order: +The +.Ar type +must be provided first. +Additional arguments may follow: +.Bl -tag -width 13n -offset indent +.It Fl offset Ar width +Indent the display by the +.Ar width , +which may be one of the following: .Bl -item .It -As one of the pre-defined strings -.Ar indent , -the width of standard indentation; -.Ar indent-two , +One of the pre-defined strings +.Cm indent , +the width of a standard indentation (six constant width characters); +.Cm indent-two , twice -.Ar indent ; -.Ar left , +.Cm indent ; +.Cm left , which has no effect; -.Ar right , -which justifies to the right margin; and -.Ar center , +.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 not provided an argument, it will be ignored. +When the argument is missing, +.Fl offset +is ignored. .It Fl compact -Do not assert a vertical space before 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 @@ -1161,7 +1334,7 @@ and argument are equivalent, as are .Fl symbolic and -.Cm \&Sy, +.Cm \&Sy , and .Fl literal and @@ -1175,21 +1348,23 @@ is encountered. See also .Sx \&Li , .Sx \&Ef , +.Sx \&Em , and .Sx \&Sy . .Ss \&Bk -Begins a collection of macros or text not breaking the line. -Its syntax is as follows: +For each macro, keep its output together on the same output line, +until the end of the macro or the end of the input line is reached, +whichever comes first. +Line breaks in text lines are unaffected. +The syntax is as follows: .Pp .D1 Pf \. Sx \&Bk Fl words .Pp -Subsequent arguments are ignored. The .Fl words -argument is required. +argument is required; additional arguments are ignored. .Pp -Each line within a keep block is kept intact, so the following example -will not break within each +The following example will not break within each .Sx \&Op macro line: .Bd -literal -offset indent @@ -1202,128 +1377,142 @@ macro line: 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: +Begin a list. +Lists consist of items specified using the +.Sx \&It +macro, containing a head or a body or both. +The list syntax is as follows: .Bd -ragged -offset indent .Pf \. Sx \&Bl -.Fl type +.Fl Ns Ar 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 +The list +.Ar type +is mandatory and must be specified first. +The +.Fl width +and +.Fl offset +arguments accept .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). +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 -line macro is encountered, at which point list bodies are interpreted as +contexts spanning one input line each are implied until an +.Sx \&It +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. +Most often used in the +.Em DIAGNOSTICS +section with error constants in the item heads. .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. +No item heads can be specified. +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 +Lists may be nested within lists and displays. +Nesting of +.Fl column +and +.Fl enum +lists may not be portable. +.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 @@ -1334,7 +1523,7 @@ See also Encloses its arguments in square brackets. .Pp Examples: -.D1 \&.Bq 1 , \&Dv BUFSIZ +.Dl \&.Bq 1 , \&Dv BUFSIZ .Pp .Em Remarks : this macro is sometimes abused to emulate optional arguments for @@ -1347,15 +1536,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 @@ -1366,7 +1556,7 @@ See also Encloses its arguments in curly braces. .Pp Examples: -.D1 \&.Brq 1 , ... , \&Va n +.Dl \&.Brq 1 , ... , \&Va n .Pp See also .Sx \&Bro . @@ -1375,8 +1565,8 @@ Format the BSD/OS version provided as an argument, or no argument is provided. .Pp Examples: -.D1 \&.Bsx 1.0 -.D1 \&.Bsx +.Dl \&.Bsx 1.0 +.Dl \&.Bsx .Pp See also .Sx \&At , @@ -1395,8 +1585,9 @@ Format the BSD version provided as an argument, or a d argument is provided. .Pp Examples: -.D1 \&.Bx 4.4 -.D1 \&.Bx +.Dl \&.Bx 4.3 Tahoe +.Dl \&.Bx 4.4 +.Dl \&.Bx .Pp See also .Sx \&At , @@ -1408,29 +1599,33 @@ See also and .Sx \&Ux . .Ss \&Cd -Configuration declaration. +Kernel configuration declaration. This denotes strings accepted by .Xr config 8 . +It is most often used in section 4 manual pages. .Pp Examples: -.D1 \&.Cd device le0 at scode? +.Dl \&.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. .Ss \&Cm Command modifiers. -Useful when specifying configuration options or keys. +Typically used for fixed strings passed as arguments, unless +.Sx \&Fl +is more appropriate. +Also useful when specifying configuration options or keys. .Pp Examples: -.D1 \&.Cm ControlPath -.D1 \&.Cm ControlMaster -.Pp -See also -.Sx \&Fl . +.Dl ".Nm mt Fl f Ar device Cm rewind" +.Dl ".Nm ps Fl o Cm pid , Ns Cm command" +.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" +.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa" +.Dl ".Cm LogLevel Dv DEBUG" .Ss \&D1 One-line indented display. This is formatted by the default rules and is useful for simple indented @@ -1438,22 +1633,25 @@ statements. It is followed by a newline. .Pp Examples: -.D1 \&.D1 \&Fl abcdefgh +.Dl \&.D1 \&Fl abcdefgh .Pp See also .Sx \&Bd and .Sx \&Dl . .Ss \&Db -Start a debugging context. -This macro is parsed, but generally ignored. +Switch debugging mode. Its syntax is as follows: .Pp .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 @@ -1461,22 +1659,41 @@ This is the mandatory first macro of any manual. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Dd Cm date +.D1 Pf \. Sx \&Dd Ar month day , year .Pp The -.Cm date -field may be either -.Ar $\&Mdocdate$ , -which signifies the current manual revision date dictated by +.Ar month +is the full English month name, the +.Ar day +is an optionally zero-padded numeral, and the +.Ar year +is the full four-digit year. +.Pp +Other arguments are not portable; the +.Xr mandoc 1 +utility handles them as follows: +.Bl -dash -offset 3n -compact +.It +To have the date automatically filled in by the +.Ox +version of .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. +the special string +.Dq $\&Mdocdate$ +can be given as an argument. +.It +A few alternative date formats are accepted as well +and converted to the standard form. +.It +If a date string cannot be parsed, it is used verbatim. +.It +If no date string is given, the current date is used. +.El .Pp Examples: -.D1 \&.Dd $\&Mdocdate$ -.D1 \&.Dd $\&Mdocdate: July 21 2007$ -.D1 \&.Dd July 21, 2007 +.Dl \&.Dd $\&Mdocdate$ +.Dl \&.Dd $\&Mdocdate: July 21 2007$ +.Dl \&.Dd July 21, 2007 .Pp See also .Sx \&Dt @@ -1489,23 +1706,30 @@ invocations. It is followed by a newline. .Pp Examples: -.D1 \&.Dl % mandoc mdoc.7 | less +.Dl \&.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 @@ -1514,6 +1738,9 @@ Examples: .Ed .Pp See also +.Sx \&Qq , +.Sx \&Sq , +and .Sx \&Do . .Ss \&Dt Document title. @@ -1524,22 +1751,22 @@ Its syntax is as follows: .Bd -ragged -offset indent .Pf \. Sx \&Dt .Oo -.Cm title +.Ar title .Oo -.Cm section -.Op Cm volume | arch +.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 @@ -1576,9 +1803,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 @@ -1607,10 +1834,10 @@ This field is optional, and if specified, must be one 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. @@ -1631,6 +1858,7 @@ It must be one of .Ar luna88k , .Ar mac68k , .Ar macppc , +.Ar mips64 , .Ar mvme68k , .Ar mvme88k , .Ar mvmeppc , @@ -1646,30 +1874,37 @@ or .El .Pp Examples: -.D1 \&.Dt FOO 1 -.D1 \&.Dt FOO 4 KM -.D1 \&.Dt FOO 9 i386 +.Dl \&.Dt FOO 1 +.Dl \&.Dt FOO 4 KM +.Dl \&.Dt FOO 9 i386 .Pp See also .Sx \&Dd and .Sx \&Os . .Ss \&Dv -Defined variables such as preprocessor constants. +Defined variables such as preprocessor constants, constant symbols, +enumeration values, and so on. .Pp Examples: -.D1 \&.Dv BUFSIZ -.D1 \&.Dv STDOUT_FILENO +.Dl \&.Dv NULL +.Dl \&.Dv BUFSIZ +.Dl \&.Dv STDOUT_FILENO .Pp See also -.Sx \&Er . +.Sx \&Er +and +.Sx \&Ev +for special-purpose constants and +.Sx \&Va +for variable symbols. .Ss \&Dx Format the DragonFly BSD version provided as an argument, or a default value if no argument is provided. .Pp Examples: -.D1 \&.Dx 2.4.1 -.D1 \&.Dx +.Dl \&.Dx 2.4.1 +.Dl \&.Dx .Pp See also .Sx \&At , @@ -1685,10 +1920,10 @@ Close a scope started by .Sx \&Eo . Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ec Op Cm TERM +.D1 Pf \. Sx \&Ec Op Ar TERM .Pp The -.Cm TERM +.Ar TERM argument is used as the enclosure tail, for example, specifying \e(rq will emulate .Sx \&Dc . @@ -1696,13 +1931,13 @@ will emulate End a display context started by .Sx \&Bd . .Ss \&Ef -Ends a font mode context started by +End a font mode context started by .Sx \&Bf . .Ss \&Ek -Ends a keep context started by +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 @@ -1710,35 +1945,50 @@ See also and .Sx \&It . .Ss \&Em -Denotes text that should be emphasised. +Denotes text that should be +.Em emphasised . Note that this is a presentation term and should not be used for stylistically decorating technical terms. +Depending on the output device, this is usually represented +using an italic font or underlined characters. .Pp Examples: -.D1 \&.Em Warnings! -.D1 \&.Em Remarks : +.Dl \&.Em Warnings! +.Dl \&.Em Remarks : +.Pp +See also +.Sx \&Bf , +.Sx \&Li , +.Sx \&No , +and +.Sx \&Sy . .Ss \&En -This macro is obsolete and not implemented. +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 Cm TERM +.D1 Pf \. Sx \&Eo Op Ar TERM .Pp The -.Cm TERM +.Ar TERM argument is used as the enclosure head, for example, specifying \e(lq will emulate .Sx \&Do . .Ss \&Er -Display error constants. +Error constants for definitions of the +.Va errno +libc global variable. +This is most often used in section 2 and 3 manual pages. .Pp Examples: -.D1 \&.Er EPERM -.D1 \&.Er ENOENT +.Dl \&.Er EPERM +.Dl \&.Er ENOENT .Pp See also -.Sx \&Dv . +.Sx \&Dv +for general constants. .Ss \&Es This macro is obsolete and not implemented. .Ss \&Ev @@ -1746,19 +1996,31 @@ Environmental variables such as those specified in .Xr environ 7 . .Pp Examples: -.D1 \&.Ev DISPLAY -.D1 \&.Ev PATH +.Dl \&.Ev DISPLAY +.Dl \&.Ev PATH +.Pp +See also +.Sx \&Dv +for general constants. .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 . +Insert a standard sentence regarding command exit values of 0 on success +and >0 on failure. +This is most often used in section 1, 6, and 8 manual pages. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ex Fl std Op Ar utility ... +.Pp If .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. +Multiple +.Ar utility +arguments are treated as separate utilities. +.Pp +See also +.Sx \&Rv . .Ss \&Fa Function argument. Its syntax is as follows: @@ -1784,14 +2046,14 @@ Furthermore, if the following macro is another 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 +.Dl \&.Fa \(dqconst char *p\(dq +.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq +.Dl \&.Fa foo .Pp See also .Sx \&Fo . .Ss \&Fc -Ends a function context started by +End a function context started by .Sx \&Fo . .Ss \&Fd Historically used to document include files. @@ -1804,7 +2066,7 @@ See also and .Sx \&In . .Ss \&Fl -Command-line flag. +Command-line flag or option. Used when listing arguments to command-line utilities. Prints a fixed-width hyphen .Sq \- @@ -1814,10 +2076,11 @@ If the argument is a macro, a hyphen is prefixed to th output. .Pp Examples: -.D1 \&.Fl a b c -.D1 \&.Fl \&Pf a b -.D1 \&.Fl -.D1 \&.Op \&Fl o \&Ns \&Ar file +.Dl ".Fl R Op Fl H | L | P" +.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" +.Dl ".Fl type Cm d Fl name Pa CVS" +.Dl ".Fl Ar signal_number" +.Dl ".Fl o Fl" .Pp See also .Sx \&Cm . @@ -1826,26 +2089,35 @@ 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 +.Op Ar functype +.Ar funcname +.Op Oo Ar argtype Oc Ar argname .Ed .Pp Function arguments are surrounded in parenthesis and are delimited by commas. If no arguments are specified, blank parenthesis are output. +In the +.Em SYNOPSIS +section, this macro starts a new output line, +and a blank line is automatically inserted between function definitions. .Pp Examples: -.D1 \&.Fn "int funcname" "int arg0" "int arg1" -.D1 \&.Fn funcname "int arg0" -.D1 \&.Fn funcname arg0 +.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q +.Dl \&.Fn funcname \*qint arg0\*q +.Dl \&.Fn funcname arg0 +.Pp .Bd -literal -offset indent -compact \&.Ft functype \&.Fn funcname .Ed .Pp +When referring to a function documented in another manual page, use +.Sx \&Xr +instead. See also -.Sx MANUAL STRUCTURE +.Sx MANUAL STRUCTURE , +.Sx \&Fo , and .Sx \&Ft . .Ss \&Fo @@ -1854,17 +2126,17 @@ This is a multi-line version of .Sx \&Fn . Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Fo Cm funcname +.D1 Pf \. Sx \&Fo Ar funcname .Pp Invocations usually occur in the following context: .Bd -ragged -offset indent -.Pf \. Sx \&Ft Cm functype +.Pf \. Sx \&Ft Ar functype .br -.Pf \. Sx \&Fo Cm funcname +.Pf \. Sx \&Fo Ar funcname .br -.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname +.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname .br -\.\.\. +\&.\.\. .br .Pf \. Sx \&Fc .Ed @@ -1872,20 +2144,34 @@ Invocations usually occur in the following context: A .Sx \&Fo scope is closed by +.Sx \&Fc . .Pp See also .Sx MANUAL STRUCTURE , .Sx \&Fa , .Sx \&Fc , and +.Sx \&Ft . +.Ss \&Fr +This macro is obsolete and not implemented in +.Xr mandoc 1 . +.Pp +It was used to show function return values. +The syntax was: +.Pp +.Dl Pf . Sx \&Fr Ar value .Ss \&Ft A function type. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ft Cm functype +.D1 Pf \. Sx \&Ft Ar functype .Pp +In the +.Em SYNOPSIS +section, a new output line is started after this macro. +.Pp Examples: -.D1 \&.Ft int +.Dl \&.Ft int .Bd -literal -offset indent -compact \&.Ft functype \&.Fn funcname @@ -1897,12 +2183,14 @@ See also 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: -.D1 \&.Fx 7.1 -.D1 \&.Fx +.Dl \&.Fx 7.1 +.Dl \&.Fx .Pp See also .Sx \&At , @@ -1914,7 +2202,13 @@ See also and .Sx \&Ux . .Ss \&Hf -This macro is obsolete and not implemented. +This macro is not implemented in +.Xr mandoc 1 . +.Pp +It was used to include the contents of a (header) file literally. +The syntax was: +.Pp +.Dl Pf . Sx \&Hf Ar filename .Ss \&Ic Designate an internal or interactive command. This is similar to @@ -1922,11 +2216,12 @@ This is similar to but used for instructions rather than values. .Pp Examples: -.D1 \&.Ic hash -.D1 \&.Ic alias +.Dl \&.Ic :wq +.Dl \&.Ic hash +.Dl \&.Ic alias .Pp Note that using -.Sx \&Bd No Fl literal +.Sx \&Bd Fl literal or .Sx \&D1 is preferred for displaying code; the @@ -1934,17 +2229,19 @@ is preferred for displaying code; the macro is used when referring to specific instructions. .Ss \&In An -.Qq include +.Dq include file. -In the +When invoked as the first macro on an input line 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. +section, the argument is displayed in angle brackets +and preceded by +.Dq #include , +and a blank line is inserted in front if there is a preceding +function declaration. +This is most often used in section 2, 3, and 9 manual pages. .Pp Examples: -.D1 \&.In sys/types +.Dl \&.In sys/types.h .Pp See also .Sx MANUAL STRUCTURE . @@ -1961,7 +2258,7 @@ and .Fl diag have the following syntax: .Pp -.D1 Pf \. Sx \&It Cm args +.D1 Pf \. Sx \&It Ar args .Pp Lists of type .Fl bullet , @@ -1998,33 +2295,29 @@ The list is the most complicated. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&It Op Cm args +.D1 Pf \. Sx \&It Ar cell Op Ar cell ... +.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... .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 +The arguments consist of one or more lines of text and macros +representing a complete table line. +Cells within the line are delimited by tabs or by the special +.Sx \&Ta +block macro. +The tab cell delimiter may only be used within 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 +line itself; on following lines, only the +.Sx \&Ta +macro can be used to delimit cells, and +.Sx \&Ta +is only recognized as a macro when called by other macros, +not as the first macro on a line. +.Pp +Note that quoted strings may span tab-delimited cells on an .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, +line. +For example, .Pp -.D1 .It \(dqcol1 ; col2 ;\(dq \&; +.Dl .It \(dqcol1 ; col2 ;\(dq \&; .Pp will preserve the semicolon whitespace except for the last. .Pp @@ -2034,10 +2327,10 @@ See also Specify a library. The syntax is as follows: .Pp -.D1 Pf \. Sx \&Lb Cm library +.D1 Pf \. Sx \&Lb Ar library .Pp The -.Cm library +.Ar library parameter may be a system library, such as .Cm libz or @@ -2051,21 +2344,33 @@ section as described in .Sx MANUAL STRUCTURE . .Pp Examples: -.D1 \&.Lb libz -.D1 \&.Lb mdoc +.Dl \&.Lb libz +.Dl \&.Lb mdoc .Ss \&Li -Denotes text that should be in a literal font mode. +Denotes text that should be in a +.Li literal +font mode. Note that this is a presentation term and should not be used for stylistically decorating technical terms. +.Pp +On terminal output devices, this is often indistinguishable from +normal text. +.Pp +See also +.Sx \&Bf , +.Sx \&Em , +.Sx \&No , +and +.Sx \&Sy . .Ss \&Lk Format a hyperlink. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Lk Cm uri Op Cm name +.D1 Pf \. Sx \&Lk Ar uri Op Ar name .Pp Examples: -.D1 \&.Lk http://bsd.lv "The BSD.lv Project" -.D1 \&.Lk http://bsd.lv +.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q +.Dl \&.Lk http://bsd.lv .Pp See also .Sx \&Mt . @@ -2073,18 +2378,26 @@ See also Synonym for .Sx \&Pp . .Ss \&Ms +Display a mathematical symbol. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ms Ar symbol +.Pp +Examples: +.Dl \&.Ms sigma +.Dl \&.Ms aleph .Ss \&Mt Format a -.Qq mailto: +.Dq mailto: hyperlink. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Mt Cm address +.D1 Pf \. Sx \&Mt Ar address .Pp Examples: -.D1 \&.Mt discuss@manpages.bsd.lv +.Dl \&.Mt discuss@manpages.bsd.lv .Ss \&Nd -A one-line description of the manual's content. +A one line description of the manual's content. This may only be invoked in the .Em SYNOPSIS section subsequent the @@ -2092,8 +2405,8 @@ section subsequent the macro. .Pp Examples: -.D1 \&.Sx \&Nd mdoc language reference -.D1 \&.Sx \&Nd format and display UNIX manuals +.Dl Pf . Sx \&Nd mdoc language reference +.Dl Pf . Sx \&Nd format and display UNIX manuals .Pp The .Sx \&Nd @@ -2145,20 +2458,58 @@ macro rather than .Sx \&Nm to mark up the name of the manual page. .Ss \&No -A -.Qq noop -macro used to terminate prior macro contexts. +Normal text. +Closes the scope of any preceding in-line macro. +When used after physical formatting macros like +.Sx \&Em +or +.Sx \&Sy , +switches back to the standard font face and weight. +Can also be used to embed plain text strings in macro lines +using semantic annotation macros. .Pp Examples: -.D1 \&.Sx \&Fl ab \&No cd \&Fl ef +.Dl ".Em italic , Sy bold , No and roman" +.Pp +.Bd -literal -offset indent -compact +\&.Sm off +\&.Cm :C No / Ar pattern No / Ar replacement No / +\&.Sm on +.Ed +.Pp +See also +.Sx \&Em , +.Sx \&Li , +and +.Sx \&Sy . .Ss \&Ns +Suppress a space between the output of the preceding macro +and the following text or macro. +Following invocation, input is interpreted as normal text +just like after an +.Sx \&No +macro. +.Pp +This has no effect when invoked at the start of a macro line. +.Pp +Examples: +.Dl ".Ar name Ns = Ns Ar value" +.Dl ".Cm :M Ns Ar pattern" +.Dl ".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: -.D1 \&.Nx 5.01 -.D1 \&.Nx +.Dl \&.Nx 5.01 +.Dl \&.Nx .Pp See also .Sx \&At , @@ -2170,7 +2521,7 @@ See also and .Sx \&Ux . .Ss \&Oc -Closes multi-line +Close multi-line .Sx \&Oo context. .Ss \&Oo @@ -2178,19 +2529,21 @@ Multi-line version of .Sx \&Op . .Pp Examples: -.Bd -literal -offset indent +.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. +Optional part of a command line. Prints the argument(s) in brackets. +This is most often used in the +.Em SYNOPSIS +section of section 1 and 8 manual pages. .Pp Examples: -.D1 \&.Op \&Fl a \&Ar b -.D1 \&.Op \&Ar a | b +.Dl \&.Op \&Fl a \&Ar b +.Dl \&.Op \&Ar a | b .Pp See also .Sx \&Oo . @@ -2202,35 +2555,40 @@ any file. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Os Op Cm system +.D1 Pf \. Sx \&Os Op Ar system Op Ar version .Pp The optional -.Cm system +.Ar system parameter specifies the relevant operating system or environment. Left unspecified, it defaults to the local operating system version. This is the suggested form. .Pp Examples: -.D1 \&.Os -.D1 \&.Os KTH/CSC/TCS -.D1 \&.Os BSD 4.3 +.Dl \&.Os +.Dl \&.Os KTH/CSC/TCS +.Dl \&.Os BSD 4.3 .Pp See also .Sx \&Dd and .Sx \&Dt . .Ss \&Ot -Unknown usage. +This macro is obsolete and not implemented in +.Xr mandoc 1 . .Pp -.Em Remarks : -this macro has been deprecated. +Historical +.Xr mdoc 7 +packages described it as +.Dq "old function type (FORTRAN)" . .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: -.D1 \&.Ox 4.5 -.D1 \&.Ox +.Dl \&.Ox 4.5 +.Dl \&.Ox .Pp See also .Sx \&At , @@ -2242,11 +2600,14 @@ See also and .Sx \&Ux . .Ss \&Pa -A file-system path. +An absolute or relative file system path, or a file or directory name. +If an argument is not provided, the character +.Sq \(ti +is used as a default. .Pp Examples: -.D1 \&.Pa /usr/bin/mandoc -.D1 \&.Pa /usr/share/man/man7/mdoc.7 +.Dl \&.Pa /usr/bin/mandoc +.Dl \&.Pa /usr/share/man/man7/mdoc.7 .Pp See also .Sx \&Lk . @@ -2254,19 +2615,25 @@ See also Close parenthesised context opened by .Sx \&Po . .Ss \&Pf -Removes the space -.Pq Qq prefix -between its arguments. +Removes the space between its argument +.Pq Dq prefix +and the following macro. Its syntax is as follows: .Pp -.D1 Pf \. \&Pf Cm prefix suffix +.D1 .Pf Ar prefix macro arguments ... .Pp -The -.Cm suffix -argument may be a macro. +This is equivalent to: .Pp +.D1 .No Ar prefix No \&Ns Ar macro arguments ... +.Pp Examples: -.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix +.Dl ".Pf $ Ar variable_name" +.Dl ".Pf 0x Ar hex_digits" +.Pp +See also +.Sx \&Ns +and +.Sx \&Sm . .Ss \&Po Multi-line version of .Sx \&Pq . @@ -2274,22 +2641,54 @@ Multi-line version of Break a paragraph. This will assert vertical space between prior and subsequent macros and/or text. +.Pp +Paragraph breaks are not needed before or after +.Sx \&Sh +or +.Sx \&Ss +macros or before displays +.Pq Sx \&Bd +or lists +.Pq Sx \&Bl +unless the +.Fl compact +flag is given. .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 +.Qq 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. @@ -2329,8 +2728,46 @@ block is used within a SEE ALSO section, a vertical sp before the rendered output, else the block continues on the current line. .Ss \&Rv +Insert a standard sentence regarding a function call's return value of 0 +on success and \-1 on error, with the +.Va errno +libc global variable set on error. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Rv Fl std Op Ar function ... +.Pp +If +.Ar function +is not specified, the document's name set by +.Sx \&Nm +is used. +Multiple +.Ar function +arguments are treated as separate functions. +.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 . +Although this macro is parsed, it should not consist of child node or it +may not be linked with +.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: @@ -2342,15 +2779,180 @@ By default, spacing is 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 +output generated from adjacent macros, but text lines still get normal spacing between words and sentences. .Ss \&So +Multi-line version of +.Sx \&Sq . .Ss \&Sq +Encloses its arguments in +.Sq typewriter +single-quotes. +.Pp +See also +.Sx \&Dq , +.Sx \&Qq , +and +.Sx \&So . .Ss \&Ss +Begin a new subsection. +Unlike with +.Sx \&Sh , +there is no convention for the naming of subsections. +Except +.Em DESCRIPTION , +the conventional sections described in +.Sx MANUAL STRUCTURE +rarely have subsections. +.Pp +Sub-section names should be unique so that they may be keyed by +.Sx \&Sx . +Although this macro is parsed, it should not consist of child node or it +may not be linked with +.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 +.It \-xpg4.3 +.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 subsection in the same manual page. +The referenced section or subsection name must be identical to the +enclosed argument, including whitespace. +.Pp +Examples: +.Dl \&.Sx MANUAL STRUCTURE +.Pp +See also +.Sx \&Sh +and +.Sx \&Ss . .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 \&Em , +.Sx \&Li , +and +.Sx \&No . +.Ss \&Ta +Table cell separator in +.Sx \&Bl Fl column +lists; can only be used below +.Sx \&It . .Ss \&Tn +Format a tradename. +.Pp +Since this macro is often implemented to use a small caps font, +it has historically been used for acronyms (like ASCII) as well. +Such usage is not recommended because it would use the same macro +sometimes for semantical annotation, sometimes for physical formatting. +.Pp +Examples: +.Dl \&.Tn IBM .Ss \&Ud Prints out .Dq currently under development. @@ -2359,7 +2961,7 @@ Format the UNIX name. Accepts no argument. .Pp Examples: -.D1 \&.Ux +.Dl \&.Ux .Pp See also .Sx \&At , @@ -2374,8 +2976,8 @@ and A variable name. .Pp Examples: -.D1 \&.Va foo -.D1 \&.Va const char *bar ; +.Dl \&.Va foo +.Dl \&.Va const char *bar ; .Ss \&Vt A variable type. This is also used for indicating global variables in the @@ -2383,19 +2985,22 @@ This is also used for indicating global variables in t 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 +syntax when invoked as the first macro on an input line in the .Em SYNOPSIS section, else it accepts ordinary .Sx In-line syntax. +In the former case, this macro starts a new output line, +and a blank line is inserted in front if there is a preceding +function definition or include directive. .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[] \&; +.Dl \&.Vt unsigned char +.Dl \&.Vt extern const char * const sys_signame[] \&; .Pp See also .Sx MANUAL STRUCTURE @@ -2405,255 +3010,263 @@ and 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. +Extend the header of an +.Sx \&It +macro or the body of a partial-implicit block macro +beyond the end of the input line. +This macro originally existed to work around the 9-argument limit +of historic +.Xr roff 7 . .Ss \&Xr Link to another manual .Pq Qq cross-reference . Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Xr Cm name section +.D1 Pf \. Sx \&Xr Ar name section .Pp The -.Cm name +.Ar name and -.Cm section +.Ar section are the name and section of the linked manual. If -.Cm section +.Ar section 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 \&Ns s behaviour +.Dl \&.Xr mandoc 1 +.Dl \&.Xr mandoc 1 \&; +.Dl \&.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 Ar height +.Pp +The +.Ar 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 .Pq Qq groff . The term .Qq historic groff -refers to groff versions before the +refers to groff versions before 1.17, +which featured a significant update of the .Pa doc.tmac -file re-write -.Pq somewhere between 1.15 and 1.19 . +file. .Pp 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 -Old groff fails to assert a newline before -.Sx \&Bd Fl ragged compact . +Display macros +.Po +.Sx \&Bd , +.Sx \&Dl , +and +.Sx \&D1 +.Pc +may not be nested. +\*[hist] .It -groff behaves inconsistently when encountering -.Pf non- Sx \&Fa -children of +.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 \&Bl 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 +with non-standard arguments behaves very strangely. +When there are three arguments, they are printed verbatim. +Any other number of arguments is replaced by the current date, +but without any arguments the string +.Dq Epoch +is printed. +.It +.Sx \&Fl +does not print a dash for an empty argument. +\*[hist] +.It +.Sx \&Fn +does not start a new line unless invoked as the line macro in the +.Em SYNOPSIS +section. +\*[hist] +.It .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. +with +.Pf non- Sx \&Fa +children causes inconsistent spacing between arguments. +In mandoc, a single space is always inserted between arguments. .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 +.Em SYNOPSIS +causes inconsistent vertical spacing, 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. +for the normalised behaviour in mandoc. .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. +ignores additional arguments and is not treated specially in the +.Em SYNOPSIS . +\*[hist] .It -groff does not accept the -.Sq \&Ta -pseudo-macro as a line macro. -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 -The comment syntax -.Sq \e." -is no longer accepted. +.Sx \&Li +followed by a delimiter is incorrectly used in some manuals +instead of properly quoting that character, which sometimes works with +historic groff. .It -In groff, the +.Sx \&Lk +only accepts a single link-name argument; the remainder is misformatted. +.It .Sx \&Pa -macro does not format its arguments when used in the FILES section under +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. +.Sx \&Ta +can only be called by other macros, but not at the beginning of a line. .It -groff behaves irregularly when specifying +.Sx \&%C +is not implemented. +.It +Historic groff only allows up to eight or nine arguments per macro input +line, depending on the exact situation. +Providing more arguments causes garbled output. +The number of arguments on one input line is not limited with mandoc. +.It +Historic groff has many un-callable macros. +Most of these (excluding some block-level macros) are callable +in new groff and mandoc. +.It +.Sq \(ba +(vertical bar) is not fully supported as a delimiter. +\*[hist] +.It .Sq \ef +.Pq font face +and +.Sq \ef +.Pq font family face .Sx Text Decoration -within line-macro scopes. -mandoc follows a consistent system. +escapes behave irregularly when specified within line-macro scopes. .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. +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 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 \&Bd +.Fl file Ar file . .It -Display offsets .Sx \&Bd .Fl offset Ar center and -.Fl offset Ar right -are disregarded in mandoc. -Furthermore, troff specifies a -.Fl file Ar file -argument that is not supported in mandoc. -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 . +.Fl offset Ar right . +Groff does not implement centered and flush-right rendering either, +but produces large indentations. .It -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 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 -nested and -.Fl enum -lists will restart the sequence only for the sub-list. -.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. -.It -In groff, the -.Sx \&Cd , -.Sx \&Er , -.Sx \&Ex , +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 -.Sx \&Rv -macros were stipulated only to occur in certain manual sections. -mandoc does not have these restrictions. +.Sq \es +.Pq text size +escape sequences are all discarded in mandoc. .It -Newer groff and mandoc print -.Qq AT&T UNIX -prior to unknown arguments of -.Sx \&At ; -older groff did nothing. +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 +.Xr eqn 7 , +.Xr man 7 , +.Xr mandoc_char 7 , +.Xr roff 7 , +.Xr tbl 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 -.\" .