=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.99 retrieving revision 1.121 diff -u -p -r1.99 -r1.121 --- mandoc/mdoc.7 2010/05/12 08:41:17 1.99 +++ mandoc/mdoc.7 2010/06/06 22:25:56 1.121 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.99 2010/05/12 08:41:17 kristaps Exp $ +.\" $Id: mdoc.7,v 1.121 2010/06/06 22:25:56 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -14,7 +14,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: May 12 2010 $ +.Dd $Mdocdate: June 6 2010 $ .Dt MDOC 7 .Os .Sh NAME @@ -33,7 +33,7 @@ section describes compatibility with other troff \-mdo .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 @@ -101,9 +101,11 @@ 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 @@ -118,14 +120,16 @@ escape followed by an indicator: B (bold), I, (italic) .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 +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 +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. @@ -174,7 +178,8 @@ 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 @@ -187,14 +192,14 @@ trailing spaces are stripped from input (unless in a l 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. +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" , @@ -203,7 +208,8 @@ 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" @@ -213,16 +219,18 @@ 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 @@ -246,8 +254,8 @@ stipulating a two-inch list indentation with the follo 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 @@ -285,8 +293,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 @@ -317,18 +343,15 @@ 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 @@ -358,12 +381,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 @@ -383,8 +406,8 @@ 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 @@ -449,14 +472,14 @@ Print verbose information. .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. +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 . @@ -467,28 +490,30 @@ Documents any usages of environment variables, e.g., 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 +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 +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 @@ -503,15 +528,16 @@ Documents error handling in sections 2, 3, and 9. 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 @@ -539,15 +565,17 @@ Documents any security precautions that operators shou 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 @@ -560,8 +588,9 @@ closes it out. 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 . @@ -569,15 +598,16 @@ produces 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 @@ -625,8 +655,8 @@ has multiple heads. .It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss .El .Ss Block partial-explicit -Like block full-explicit, but also with single-line scope. Each -has at least a body and, in limited circumstances, a head +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 @@ -698,14 +728,16 @@ Note that the macro is a .Sx Block partial-implicit only when invoked as the first macro -in a SYNOPSIS section line, else it is +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 @@ -795,7 +827,8 @@ then the macro accepts an arbitrary number of argument .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 @@ -876,8 +909,9 @@ Examples: .D1 \&.Ad [0,$] .D1 \&.Ad 0x00000000 .Ss \&An -Author name. This macro may alternatively accepts the following -arguments, although these may not be specified along with a parameter: +Author name. +This macro may alternatively accepts the following arguments, although +these may not be specified along with a parameter: .Bl -tag -width 12n -offset indent .It Fl split Renders a line break before each author listing. @@ -888,10 +922,11 @@ The opposite of .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 +interspersed by other macros or text, are split. +Thus, specifying .Fl split -will cause the first listing also to be split. If not in the AUTHORS -section, the default is not to split. +will cause the first listing also to be split. +If not in the AUTHORS section, the default is not to split. .Pp Examples: .D1 \&.An -nosplit @@ -907,8 +942,8 @@ are re-set when entering the AUTHORS section, so if on in the general document body, it must be re-specified in the AUTHORS section. .Ss \&Ao -Begins a block enclosed by angled brackets. Does not have any head -arguments. +Begins a block enclosed by angled brackets. +Does not have any head arguments. .Pp Examples: .D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac @@ -916,9 +951,9 @@ Examples: See also .Sx \&Aq . .Ss \&Ap -Inserts an apostrophe without any surrounding white-space. This is -generally used as a grammatic device when referring to the verb form of -a function: +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 @@ -941,7 +976,8 @@ statements, which should use 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 @@ -950,7 +986,8 @@ Examples: .D1 \&.Ar .D1 \&.Ar arg1 , arg2 . .Ss \&At -Formats an AT&T version. Accepts at most one parameter: +Formats an AT&T version. +Accepts at most one parameter: .Bl -tag -width 12n -offset indent .It Cm v[1-7] | 32v A version of @@ -980,10 +1017,11 @@ Closes a .Sx \&Bo block. Does not have any tail arguments. .Ss \&Bd -Begins a display block. A display is collection of macros or text which -may be collectively offset or justified in a manner different from that -of the enclosing context. By default, the block is preceded by a -vertical space. +Begins a display block. +A display is collection of macros or text which may be collectively +offset or justified in a manner different from that +of the enclosing context. +By default, the block is preceded by a vertical space. .Pp Each display is associated with a type, which must be one of the following arguments: @@ -1001,7 +1039,8 @@ 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 Offset by the value of @@ -1022,8 +1061,8 @@ 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 . @@ -1060,63 +1099,115 @@ and .Ss \&Bf .Ss \&Bk .Ss \&Bl -.\" Begins a list composed of one or more list entries. A list entry is -.\" specified by the -.\" .Sx \&It -.\" macro, which consists of a head and optional body. By default, a list -.\" is preceded by a blank line. A list must specify one of the following -.\" list types: -.\" .Bl -tag -width 12n -.\" .It Fl bullet -.\" A list offset by a bullet. The head of list entries must be empty. -.\" List entry bodies are justified after the bullet. -.\" .It Fl column -.\" A columnated list. The number of columns is specified as arguments to -.\" the -.\" .Sx \&Bl -.\" macro (the deprecated form of following the invocation of -.\" .Fl column -.\" is also accepted). Arguments dictate the width of columns specified in -.\" list entries. List entry bodies must be left empty. Columns specified -.\" in the list entry head are justified to their position in the sequence -.\" of columns. -.\" .It Fl dash -.\" A list offset by a dash (hyphen). The head of list entries must be -.\" empty. List entry bodies are justified past the dash. -.\" .It Fl diag -.\" Like -.\" .Fl inset -.\" lists, but with additional formatting to the head. -.\" .It Fl enum -.\" A list offset by a number indicating list entry position. The head of -.\" list entries must be empty. List entry bodies are justified past the -.\" enumeration. -.\" .It Fl hang -.\" Like -.\" .Fl tag , -.\" but instead of list bodies justifying to the head on the first line, -.\" they trail the head text. -.\" .It Fl hyphen -.\" Synonym for -.\" .Fl dash . -.\" .It Fl inset -.\" Like -.\" .Fl tag , -.\" but list entry bodies aren't justified. -.\" .It Fl item -.\" An un-justified list. This produces blocks of text. -.\" .It Fl ohang -.\" List bodies are placed on the line following the head. -.\" .It Fl tag -.\" A list offset by list entry heads. List entry bodies are justified -.\" after the head. -.\" .El -.\" .Pp -.\" More... -.\" . +Begins a list composed of one or more list entries. +A list is associated with a type, which is a required argument. +Other arguments are +.Fl width , +defined per-type as accepting a literal or +.Sx Scaling Widths +value; +.Fl offset , +also accepting a literal or +.Sx Scaling Widths +value setting the list's global offset; and +.Fl compact , +suppressing the default vertical space printed before each list entry. +A list entry is specified by the +.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 @@ -1147,8 +1238,8 @@ Closes a .Sx \&Bro block. Does not have any tail arguments. .Ss \&Bro -Begins a block enclosed by curly braces. Does not have any head -arguments. +Begins a block enclosed by curly braces. +Does not have any head arguments. .Pp Examples: .Bd -literal -offset indent @@ -1204,7 +1295,8 @@ See also and .Sx \&Ux . .Ss \&Cd -Configuration declaration. This denotes strings accepted by +Configuration declaration. +This denotes strings accepted by .Xr config 8 . .Pp Examples: @@ -1214,10 +1306,11 @@ Examples: this macro is commonly abused by using quoted literals to retain white-space 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: .D1 \&.Cm ControlPath @@ -1226,8 +1319,10 @@ Examples: 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: .D1 \&.D1 \&Fl abcdefgh @@ -1237,16 +1332,23 @@ See also 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. .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 .Cm date @@ -1268,8 +1370,10 @@ See also 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: .D1 \&.Dl % mandoc mdoc.7 | less @@ -1299,19 +1403,32 @@ Examples: See also .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: +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 -.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch -.Pp Its arguments are as follows: .Bl -tag -width Ds -offset Ds .It Cm title -The document's title (name). This should be capitalised and is -required. +The document's title (name), defaulting to +.Qq 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 @@ -1345,8 +1462,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 +.Qq 1 +if unspecified. .It Cm volume This overrides the volume inferred from .Ar section . @@ -1377,10 +1495,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 , @@ -1415,7 +1536,6 @@ Examples: .D1 \&.Dt FOO 1 .D1 \&.Dt FOO 4 KM .D1 \&.Dt FOO 9 i386 -.D1 \&.Dt FOO 9 KM i386 .Pp See also .Sx \&Dd @@ -1452,10 +1572,17 @@ and .Ss \&Ef .Ss \&Ek .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: .D1 \&.Em Warnings! @@ -1480,8 +1607,8 @@ Examples: .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 values. +This macro must have first the .Fl std argument specified, then an optional .Ar utility . @@ -1491,15 +1618,54 @@ is not provided, the document's name as stipulated in .Sx \&Nm is provided. .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 .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 \&In . .Ss \&Fl -Command-line flag. Used when listing arguments to command-line -utilities. Prints a fixed-width hyphen +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. +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 @@ -1510,9 +1676,106 @@ Examples: 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 +If invoked in the +.Em SYNOPSIS +section, vertical space is asserted before and after the macro. +In all cases, the function arguments are surrounded in parenthesis and +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 \&Fa , +.Sx \&Fo , +.Sx \&Fc , +and +.Sx \&Ft . .Ss \&Fo +Begin a function block. +This is a multi-line version of +.Sx \&Fn . +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Fo Cm funcname +.Pp +Invocations usually occur in the following context: +.Bd -ragged -offset indent +.Pf \. Sx \&Ft Cm functype +.br +.Pf \. Sx \&Fo Cm funcname +.br +.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname +.br +\.\.\. +.br +.Pf \. Sx \&Fc +.Ed +.Pp +In the +.Em SYNOPSIS +section, a +.Sx \&Fo +block is surrounded by vertical space unless +.Sx \&Ft +is the prior macro, in which case it is preceded by only a newline. +.Pp +A +.Sx \&Fo +scope is closed by +.Pp +See also +.Sx \&Fa , +.Sx \&Fc , +and +.Sx \&Fn . +.Sx \&Fc . .Ss \&Fr .Ss \&Ft +A function type. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Ft Cm functype +.Pp +If invoked before a +.Sx \&Fo +or +.Sx \&Fn +in the +.Em SYNOPSIS +section, a line-break will follow. +Furthermore, if invoked in the +.Em SYNOPSIS +section, it will assert vertical space prior to its arguments. +.Pp +Examples: +.D1 \&.Ft int +.Bd -literal -offset indent -compact +\&.Ft functype +\&.Fn funcname +.Ed +.Pp +See also +.Sx \&Fo , +.Sx \&Fc , +and +.Sx \&Fn . .Ss \&Fx Format the FreeBSD version provided as an argument, or a default value if no argument is provided. @@ -1533,13 +1796,130 @@ and .Ss \&Hf .Ss \&Ic .Ss \&In +An +.Qq include +file. +In the +.Em SYNOPSIS +section (only if invoked as the line macro), the first argument is +preceded by +.Qq #include , +the arguments is enclosed in angled braces, and a newline is asserted. +In all other invocations, only angled braces will enclose the argument. +.Pp +Examples +.D1 \&.In sys/types .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 propogate over tab-delimited +phrases on an +.Sx \&It , +for example, +.Pp +.D1 .It \(dqcol1 ; 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 .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: .D1 \&.Lk http://bsd.lv "The BSD.lv Project" @@ -1550,6 +1930,15 @@ See also .Ss \&Lp .Ss \&Ms .Ss \&Mt +Format a +.Qq mailto: +hyperlink. +Its syntax is as follows: +.Pp +.D1 Pf \. Sx \&Mt Cm address +.Pp +Examples: +.D1 \&.Mt discuss@manpages.bsd.lv .Ss \&Nd .Ss \&Nm .Ss \&No @@ -1575,18 +1964,20 @@ and .Ss \&Oo .Ss \&Op .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: .D1 \&.Os @@ -1632,12 +2023,14 @@ and .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 , @@ -1650,6 +2043,7 @@ contain .Sx \&%Q , .Sx \&%R , .Sx \&%T , +.Sx \&%U , and .Sx \&%V child macros (at least one must be specified). @@ -1683,8 +2077,11 @@ line. .Ss \&Sy .Ss \&Tn .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: .D1 \&.Ux @@ -1700,9 +2097,10 @@ and .Sx \&Ox . .Ss \&Va .Ss \&Vt -A variable type. This is also used for indicating global variables in the -SYNOPSIS section, in which case a variable name is also specified. Note that -it accepts +A variable type. +This is also used for indicating global variables in the SYNOPSIS +section, in which case a variable name is also specified. +Note that it accepts .Sx Block partial-implicit syntax when invoked as the first macro in the SYNOPSIS section, else it accepts ordinary @@ -1715,7 +2113,7 @@ which is used for function return types. .Pp Examples: .D1 \&.Vt unsigned char -.D1 \&.Vt extern const char * const sys_signame[] ; +.D1 \&.Vt extern const char * const sys_signame[] \&; .Pp See also .Sx \&Ft @@ -1725,31 +2123,32 @@ 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. +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 calling syntax is +Its syntax is as follows: .Pp -.D1 \. Ns Sx \&Xr Cm name section +.D1 Pf \. Sx \&Xr Cm name section .Pp The .Cm name and .Cm section -are the name and section of the linked manual. If +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 +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 \&; .D1 \&.Xr mandoc 1 \&Ns s behaviour .Ss \&br .Ss \&sp @@ -1769,6 +2168,49 @@ Heirloom troff, the other significant troff implementa .Pp .Bl -dash -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 dependong 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. @@ -1776,25 +2218,29 @@ is no longer accepted. In groff, the .Sx \&Pa macro does not format its arguments when used in the FILES section under -certain list types. mandoc does. +certain list types. +mandoc does. .It Historic groff does not print a dash for empty .Sx \&Fl -arguments. mandoc and newer groff implementations do. +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. +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 +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 not applicable in mandoc. +standalone double-quote in formatted output. +This idiosyncratic behaviour is not applicable in mandoc. .It Display types .Sx \&Bd @@ -1805,8 +2251,8 @@ are aliases for .Fl left in manodc. Furthermore, the .Fl file Ar file -argument is ignored. Lastly, since text is not right-justified in -mandoc (or even groff), +argument is ignored. +Lastly, since text is not right-justified in mandoc (or even groff), .Fl ragged and .Fl filled @@ -1815,8 +2261,8 @@ are aliases, as are and .Fl unfilled . .It -Historic groff has many un-callable macros. Most of these (excluding -some block-level macros) are now callable. +Historic groff has many un-callable macros. +Most of these (excluding some block-level macros) are now callable. .It The vertical bar .Sq \(ba @@ -1833,20 +2279,23 @@ 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 in mandoc. +delimiter to render. +This is not supported in mandoc. .It In groff, the -.Sx \&Fo -macro only produces the first parameter. This is not the case in -mandoc. -.It -In groff, the .Sx \&Cd , .Sx \&Er , +.Sx \&Ex , and -.Sx \&Ex -macros were stipulated only to occur in certain manual sections. mandoc -does not have these restrictions. +.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 ,