=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.8 retrieving revision 1.40 diff -u -p -r1.8 -r1.40 --- mandoc/man.7 2009/04/05 16:34:22 1.8 +++ mandoc/man.7 2009/10/24 05:45:04 1.40 @@ -1,49 +1,52 @@ -.\" $Id: man.7,v 1.8 2009/04/05 16:34:22 kristaps Exp $ +.\" $Id: man.7,v 1.40 2009/10/24 05:45:04 kristaps Exp $ .\" -.\" Copyright (c) 2009 Kristaps Dzonsons +.\" Copyright (c) 2009 Kristaps Dzonsons .\" .\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the -.\" above copyright notice and this permission notice appear in all -.\" copies. +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. .\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL -.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED -.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE -.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL -.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR -.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER -.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR -.\" PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: April 5 2009 $ -.Dt man 7 +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: October 24 2009 $ +.Dt MAN 7 .Os -.\" SECTION +. +. .Sh NAME .Nm man .Nd man language reference -.\" SECTION +. +. .Sh DESCRIPTION The .Nm man -language was historically used to format +language was historically used to format .Ux -manuals. This reference document describes the syntax and structure of -this language. +manuals. This reference document describes its syntax, structure, and +usage. +. .Pp -.Em \&Do not -use +.Bf -emphasis +Do not use .Nm -to write your manuals. Use the +to write your manuals. +.Ef +Use the .Xr mdoc 7 language, instead. -.\" PARAGRAPH +. .Pp An .Nm document follows simple rules: lines beginning with the control -character +character .Sq \&. are parsed for macros. Other lines are interpreted within the scope of prior macros: @@ -51,19 +54,19 @@ prior macros: \&.SH Macro lines change control state. Other lines are interpreted within the current state. .Ed -.\" SECTION +. +. .Sh INPUT ENCODING .Nm -documents may contain only graphable 7-bit ASCII characters and the -space character -.Sq \ . -All manuals must have +documents may contain only graphable 7-bit ASCII characters, the +space character, and the tabs character. All manuals must have .Ux -.Sq \en -line termination. +line termination. +. .Pp Blank lines are acceptable; where found, the output will assert a vertical space. +. .Pp The .Sq \ec @@ -71,135 +74,521 @@ escape is common in historical .Nm documents; if encountered at the end of a word, it ensures that the subsequent word isn't off-set by whitespace. -.\" SUB-SECTION +. +. +.Ss Comments +Text following a +.Sq \e\*" , +whether in a macro or free-form text line, is ignored to the end of +line. A macro line with only a control character and comment escape, +.Sq \&.\e" , +is also ignored. Macro lines with only a control charater and +optionally whitespace are stripped from input. +. +. .Ss Special Characters -Special character sequences begin with the escape character +Special characters may occur in both macro and free-form lines. +Sequences begin with the escape character .Sq \e -followed by either an open-parenthesis +followed by either an open-parenthesis .Sq \&( for two-character sequences; an open-bracket .Sq \&[ for n-character sequences (terminated at a close-bracket .Sq \&] ) ; -or a single one-character sequence. +or a single one-character sequence. See +.Xr mandoc_char 7 +for a complete list. Examples include +.Sq \e(em +.Pq em-dash +and +.Sq \ee +.Pq back-slash . +. +. +.Ss Text Decoration +Terms may be text-decorated using the +.Sq \ef +escape followed by an indicator: B (bold), I, (italic), or P and R +(Roman, or reset). +. +. +.Ss Whitespace +Unless specifically escaped, consecutive blocks of whitespace are pruned +from input. These are later re-added, if applicable, by a front-end +utility such as +.Xr mandoc 1 . +. +.Ss Scaling Widths +Many macros support scaled widths for their arguments, such as +stipulating a two-inch paragraph indentation with the following: +.Bd -literal -offset indent +\&.HP 2i +.Ed +. .Pp -Characters may alternatively be escaped by a slash-asterisk, -.Sq \e* , -with the same combinations as described above. This form is deprecated. -.\" SECTION -.Sh STRUCTURE +The syntax for scaled widths is +.Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? , +where a decimal must be preceded or proceeded by at least one digit. +Negative numbers, while accepted, are truncated to zero. The following +scaling units are accepted: +. +.Pp +.Bl -tag -width Ds -offset indent -compact +.It c +centimetre +.It i +inch +.It P +pica (~1/6 inch) +.It p +point (~1/72 inch) +.It f +synonym for +.Sq u +.It v +default vertical span +.It m +width of rendered +.Sq m +.Pq em +character +.It n +width of rendered +.Sq n +.Pq en +character +.It u +default horizontal span +.It M +mini-em (~1/100 em) +.El +.Pp +Using anything other than +.Sq m , +.Sq n , +.Sq u , +or +.Sq v +is necessarily non-portable across output media. See +.Sx COMPATIBILITY . +. +.Pp +If a scaling unit is not provided, the numerical value is interpreted +under the default rules of +.Sq v +for vertical spaces and +.Sq u +for horizontal ones. +.Em Note : +this differs from +.Xr mdoc 7 , +which, if a unit is not provided, will instead interpret the string as +literal text. +. +. +.Sh MANUAL STRUCTURE +Each +.Nm +document must contain contains at least the +.Sx \&TH +macro describing the document's section and title. It may occur +anywhere in the document, although conventionally, it appears as the +first macro. +. +.Pp +Beyond +.Sx \&TH , +at least one macro or text node must appear in the document. Documents +are generally structured as follows: +.Bd -literal -offset indent +\&.TH FOO 1 "13 Aug 2009" +\&. +\&.SH NAME +\efBfoo\efR \e(en a description goes here +\&.\e\*q The next is for sections 2 & 3 only. +\&.\e\*q .SH LIBRARY +\&. +\&.SH SYNOPSIS +\efBfoo\efR [\efB\e-options\efR] arguments... +\&. +\&.SH DESCRIPTION +The \efBfoo\efR utility processes files... +\&. +\&.\e\*q .SH IMPLEMENTATION NOTES +\&.\e\*q The next is for sections 1 & 8 only. +\&.\e\*q .SH EXIT STATUS +\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q .SH RETURN VALUES +\&.\e\*q The next is for sections 1, 6, 7, & 8 only. +\&.\e\*q .SH ENVIRONMENT +\&.\e\*q .SH FILES +\&.\e\*q .SH EXAMPLES +\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. +\&.\e\*q .SH DIAGNOSTICS +\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q .SH ERRORS +\&.\e\*q .SH SEE ALSO +\&.\e\*q \efBbar\efR(1) +\&.\e\*q .SH STANDARDS +\&.\e\*q .SH HISTORY +\&.\e\*q .SH AUTHORS +\&.\e\*q .SH CAVEATS +\&.\e\*q .SH BUGS +\&.\e\*q .SH SECURITY CONSIDERATIONS +.Ed +. +. +.Sh MACRO SYNTAX Macros are one to three three characters in length and begin with a control character , .Sq \&. , at the beginning of the line. An arbitrary amount of whitespace may -sit between the control character and the macro name. Thus, -.Sq \&.PP -and -.Sq \&.\ \ \ \&PP -are equivalent. -.Pp -All -.Nm -macros follow the same structural rules: +sit between the control character and the macro name. Thus, the +following are equivalent: .Bd -literal -offset indent -\&.YO \(lBbody...\(rB +\&.PP +\&.\ \ \ PP .Ed +. .Pp The -.Dq body -consists of zero or more arguments to the macro. -.Pp .Nm -has a primitive notion of multi-line scope for the following macros: -.Sq \&.TM , -.Sq \&.SM , -.Sq \&.SB , -.Sq \&.BI , -.Sq \&.IB , -.Sq \&.BR , -.Sq \&.RB , -.Sq \&.R , -.Sq \&.B , -.Sq \&.I , -.Sq \&.IR -and -.Sq \&.RI . -When these macros are invoked without arguments, the subsequent line is -considered a continuation of the macro. Thus: -.Bd -literal -offset indent -\&.RI +macros are classified by scope: line scope or block scope. Line +macros are only scoped to the current line (and, in some situations, +the subsequent line). Block macros are scoped to the current line and +subsequent lines until closed by another block macro. +. +. +.Ss Line Macros +Line macros are generally scoped to the current line, with the body +consisting of zero or more arguments. If a macro is scoped to the next +line and the line arguments are empty, the next line is used instead, +else the general syntax is used. Thus: +.Bd -literal -offset indent +\&.I foo .Ed +. .Pp -is equivalent to -.Sq \&.RI foo . -If two consecutive lines exhibit the latter behaviour, -an error is raised. Thus, the following is not acceptable: -.Bd -literal -offset indent -\&.RI -\&.I -Hello, world. +is equivalent to +.Sq \&.I foo . +If next-line macros are invoked consecutively, only the last is used. +If a next-line macro is proceded by a block macro, it is ignored. +.Bd -literal -offset indent +\&.YO \(lBbody...\(rB +\(lBbody...\(rB .Ed +. .Pp +.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" +.It Em Macro Ta Em Arguments Ta Em Scope +.It Sx \&B Ta n Ta next-line +.It Sx \&BI Ta n Ta current +.It Sx \&BR Ta n Ta current +.It Sx \&DT Ta 0 Ta current +.It Sx \&I Ta n Ta next-line +.It Sx \&IB Ta n Ta current +.It Sx \&IR Ta n Ta current +.It Sx \&PD Ta n Ta current +.It Sx \&R Ta n Ta next-line +.It Sx \&RB Ta n Ta current +.It Sx \&RI Ta n Ta current +.It Sx \&SB Ta n Ta next-line +.It Sx \&SM Ta n Ta next-line +.It Sx \&TH Ta >1, <6 Ta current +.It Sx \&UC Ta n Ta current +.It Sx \&br Ta 0 Ta current +.It Sx \&fi Ta 0 Ta current +.It Sx \&i Ta n Ta current +.It Sx \&na Ta 0 Ta current +.It Sx \&nf Ta 0 Ta current +.It Sx \&r Ta 0 Ta current +.It Sx \&sp Ta 1 Ta current +.El +. +.Pp The -.Sq \&.TP -macro is similar, but does not need an empty argument line to trigger -the behaviour. -.\" PARAGRAPH -.Sh MACROS -This section contains a complete list of all -.Nm -macros and corresponding number of arguments. +.Sx \&PD , +.Sx \&RS , +.Sx \&RE , +.Sx \&UC , +.Sx \&br , +.Sx \&fi , +.Sx \&i , +.Sx \&na , +.Sx \&nf , +.Sx \&r , +and +.Sx \&sp +macros should not be used. They're included for compatibility. +. +. +.Ss Block Macros +Block macros are comprised of a head and body. Like for in-line macros, +the head is scoped to the current line and, in one circumstance, the +next line; the body is scoped to subsequent lines and is closed out by a +subsequent block macro invocation. +.Bd -literal -offset indent +\&.YO \(lBhead...\(rB +\(lBhead...\(rB +\(lBbody...\(rB +.Ed +. .Pp -.Bl -column "MacroX" "Arguments" -compact -offset indent -.It Em Macro Ta Em Arguments -.It \&.TH Ta >1, <6 -.It \&.SH Ta >0 -.It \&.SS Ta >0 -.It \&.TP Ta n -.It \&.LP Ta 0 -.It \&.PP Ta 0 -.It \&.P Ta 0 -.It \&.IP Ta <3 -.It \&.HP Ta <2 -.It \&.SM Ta n -.It \&.SB Ta n -.It \&.BI Ta n -.It \&.IB Ta n -.It \&.BR Ta n -.It \&.RB Ta n -.It \&.R Ta n -.It \&.B Ta n -.It \&.I Ta n -.It \&.IR Ta n -.It \&.RI Ta n +The closure of body scope may be to the section, where a macro is closed +by +.Sx \&SH ; +sub-section, closed by a section or +.Sx \&SS ; +part, closed by a section, sub-section, or +.Sx \&RE ; +or paragraph, closed by a section, sub-section, part, +.Sx \&HP , +.Sx \&IP , +.Sx \&LP , +.Sx \&P , +.Sx \&PP , +or +.Sx \&TP . +No closure refers to an explicit block closing macro. +. +.Pp +.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent +.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope +.It Sx \&HP Ta <2 Ta current Ta paragraph +.It Sx \&IP Ta <3 Ta current Ta paragraph +.It Sx \&LP Ta 0 Ta current Ta paragraph +.It Sx \&P Ta 0 Ta current Ta paragraph +.It Sx \&PP Ta 0 Ta current Ta paragraph +.It Sx \&RE Ta 0 Ta current Ta none +.It Sx \&RS Ta 1 Ta current Ta part +.It Sx \&SH Ta >0 Ta next-line Ta section +.It Sx \&SS Ta >0 Ta next-line Ta sub-section +.It Sx \&TP Ta n Ta next-line Ta paragraph .El +. .Pp -Although not historically part of the -.Nm -system, the following macros are also supported: +If a block macro is next-line scoped, it may only be followed by in-line +macros (excluding +.Sx \&DT , +.Sx \&PD , +.Sx \&TH , +.Sx \&UC , +.Sx \&br , +.Sx \&na , +.Sx \&sp , +.Sx \&nf , +and +.Sx \&fi ) . +. +. +.Sh REFERENCE +This section is a canonical reference to all macros, arranged +alphabetically. For the scoping of individual macros, see +.Sx MACRO SYNTAX . +. +.Ss \&B +Text is rendered in bold face. +.Ss \&BI +Text is rendered alternately in bold face and italic. Thus, +.Sq .BI this word and that +causes +.Sq this +and +.Sq and +to render in bold face, while +.Sq word +and +.Sq that +render in italics. Whitespace between arguments is omitted in output. +.Ss \&BR +Text is rendered alternately in bold face and roman (the default font). +Whitespace between arguments is omitted in output. +.Ss \&DT +Has no effect. Included for compatibility. +.Ss \&HP +Begin a paragraph whose initial output line is left-justified, but +subsequent output lines are indented, with the following syntax: +.Bd -literal -offset indent +\&.HP [width] +.Ed +. .Pp -.Bl -column "MacroX" "Arguments" -compact -offset indent -.It Em Macro Ta Em Arguments -.It \&.br Ta 0 -.It \&.i Ta n -.El +If scaling width +.Va width +is specified, it's saved for later paragraph left-margins; if +unspecified, the saved or default width is used. +.Ss \&I +Text is rendered in italics. +.Ss \&IB +Text is rendered alternately in italics and bold face. Whitespace +between arguments is omitted in output. +.Ss \&IP +Begin a paragraph with the following syntax: +.Bd -literal -offset indent +\&.IP [head [width]] +.Ed +. .Pp -These follow the same calling conventions as the above -.Nm -macros. -.\" SECTION +This follows the behaviour of the +.Sx \&TP +except for the macro syntax (all arguments on the line, instead of +having next-line scope). If +.Va width +is specified, it's saved for later paragraph left-margins; if +unspecified, the saved or default width is used. +.Ss \&IR +Text is rendered alternately in italics and roman (the default font). +Whitespace between arguments is omitted in output. +.Ss \&LP +Begin an undecorated paragraph. The scope of a paragraph is closed by a +subsequent paragraph, sub-section, section, or end of file. The saved +paragraph left-margin width is re-set to the default. +.Ss \&P +Synonym for +.Sx \&LP . +.Ss \&PP +Synonym for +.Sx \&LP . +.Ss \&R +Text is rendered in roman (the default font). +.Ss \&RB +Text is rendered alternately in roman (the default font) and bold face. +Whitespace between arguments is omitted in output. +.Ss \&RE +Explicitly close out the scope of a prior +.Sx \&RS . +.Ss \&RI +Text is rendered alternately in roman (the default font) and italics. +Whitespace between arguments is omitted in output. +.Ss \&RS +Begin a part setting the left margin. The left margin controls the +offset, following an initial indentation, to un-indented text such as +that of +.Sx \&PP . +A scaling width may be specified as following: +.Bd -literal -offset indent +\&.RS [width] +.Ed +. +.Pp +If +.Va width +is not specified, the saved or default width is used. +.Ss \&SB +Text is rendered in small size (one point smaller than the default font) +bold face. +.Ss \&SH +Begin a section. The scope of a section is only closed by another +section or the end of file. The paragraph left-margin width is re-set +to the default. +.Ss \&SM +Text is rendered in small size (one point smaller than the default +font). +.Ss \&SS +Begin a sub-section. The scope of a sub-section is closed by a +subsequent sub-section, section, or end of file. The paragraph +left-margin width is re-set to the default. +.Ss \&TH +Sets the title of the manual page with the following syntax: +.Bd -literal -offset indent +\&.TH title section [date [source [volume]]] +.Ed +. +.Pp +At least the +.Va title +and +.Va section +arguments must be provided. The +.Va date +argument should be formatted as +.Qq %b [%d] %Y +format, described in +.Xr strptime 3 . +The +.Va source +string specifies the organisation providing the utility. The +.Va volume +replaces the default rendered volume as dictated by the manual section. +.Ss \&TP +Begin a paragraph where the head, if exceeding the indentation width, is +followed by a newline; if not, the body follows on the same line after a +buffer to the indentation width. Subsequent output lines are indented. +. +.Pp +The indentation scaling width may be set as follows: +.Bd -literal -offset indent +\&.TP [width] +.Ed +. +.Pp +If +.Va width +is specified, it's saved for later paragraph left-margins; if +unspecified, the saved or default width is used. +.Ss \&PD +Has no effect. Included for compatibility. +.Ss \&UC +Has no effect. Included for compatibility. +.Ss \&br +Breaks the current line. Consecutive invocations have no further effect. +.Ss \&fi +End literal mode begun by +.Sx \&nf . +.Ss \&i +Italicise arguments. If no arguments are specified, all subsequent text +is italicised. +.Ss \&na +Don't align to the right margin. +.Ss \&nf +Begin literal mode: all subsequent free-form lines have their end of +line boundaries preserved. May be ended by +.Sx \&fi . +.Ss \&r +Fonts and styles (bold face, italics) reset to roman (default font). +.Ss \&sp +Insert n spaces, where n is the macro's positive numeric argument. If +0, this is equivalent to the +.Sx \&br +macro. +. +. +.Sh COMPATIBILITY +This section documents compatibility with other roff implementations, at +this time limited to +.Xr groff 1 . +.Bl -hyphen +.It +In quoted literals, groff allowed pair-wise double-quotes to produce a +standalone double-quote in formatted output. This idiosyncratic +behaviour is no longer applicable. +.It +The +.Sq sp +macro does not accept negative numbers. +.It +Blocks of whitespace are stripped from both macro and free-form text +lines (except when in literal mode), while groff would retain whitespace +in free-form text lines. +.El +. +. .Sh SEE ALSO .Xr mandoc 1 , .Xr mandoc_char 7 -.\" SECTION +. +. .Sh AUTHORS The .Nm -utility was written by -.An Kristaps Dzonsons Aq kristaps@openbsd.org . -.\" SECTION +reference was written by +.An Kristaps Dzonsons Aq kristaps@kth.se . +. +. .Sh CAVEATS Do not use this language. Use .Xr mdoc 7 , instead. +.