=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.11 retrieving revision 1.31 diff -u -p -r1.11 -r1.31 --- mandoc/man.7 2009/06/10 20:18:43 1.11 +++ mandoc/man.7 2009/08/20 11:51:07 1.31 @@ -1,4 +1,4 @@ -.\" $Id: man.7,v 1.11 2009/06/10 20:18:43 kristaps Exp $ +.\" $Id: man.7,v 1.31 2009/08/20 11:51:07 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -14,190 +14,502 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 10 2009 $ +.Dd $Mdocdate: August 20 2009 $ .Dt MAN 7 .Os -.\" SECTION +. +. .Sh NAME -.Nm man -.Nd man language reference -.\" SECTION +. Nm man +. Nd man language reference +. +. .Sh DESCRIPTION The -.Nm man -language was historically used to format -.Ux -manuals. This reference document describes the syntax and structure of -this language. -.Pp -.Em \&Do not -use -.Nm -to write your manuals. Use the -.Xr mdoc 7 +. Nm man +language was historically used to format +. Ux +manuals. This reference document describes its syntax, structure, and +usage. +. Pp +. Bf -emphasis +Do not use +. Nm +to write your manuals. +. Ef +Use the +. Xr mdoc 7 language, instead. -.\" PARAGRAPH -.Pp +. Pp An -.Nm +. Nm document follows simple rules: lines beginning with the control -character -.Sq \&. +character +. Sq \&. are parsed for macros. Other lines are interpreted within the scope of prior macros: -.Bd -literal -offset indent +. Bd -literal -offset indent \&.SH Macro lines change control state. Other lines are interpreted within the current state. -.Ed -.\" SECTION +. Ed +. +. .Sh INPUT ENCODING -.Nm -documents may contain only graphable 7-bit ASCII characters and the -space character -.Sq \ . -All manuals must have -.Ux -.Sq \en -line termination. -.Pp +. Nm +documents may contain only graphable 7-bit ASCII characters, the +space character, and the tabs character. All manuals must have +. Ux +line termination. +. Pp Blank lines are acceptable; where found, the output will assert a vertical space. -.Pp +. Pp The -.Sq \ec +. Sq \ec escape is common in historical -.Nm +. 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 Special Characters -Special character sequences begin with the escape character -.Sq \e -followed by either an open-parenthesis -.Sq \&( +. +. +. 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 characters may occur in both macro and free-form lines. +Sequences begin with the escape character +. Sq \e +followed by either an open-parenthesis +. Sq \&( for two-character sequences; an open-bracket -.Sq \&[ +. Sq \&[ for n-character sequences (terminated at a close-bracket -.Sq \&] ) ; -or a single one-character sequence. -.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 +. Sq \&] ) ; +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 . +. +. +.Sh MANUAL STRUCTURE +Each +. Nm +document must contain contains at least the +. Sq 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 +. Sq 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 +\&. +\&.SH SYNOPSIS +\efBfoo\efR [\efB\e-options\efR] arguments... +\&. +\&.SH DESCRIPTION +The \efBfoo\efR utility does... +\&. +\&.\e\*q .SH RETURN VALUES +\&.\e\*q .SH ENVIRONMENT +\&.\e\*q .SH FILES +\&.\e\*q .SH EXAMPLES +\&.\e\*q .SH DIAGNOSTICS +\&.\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 +. Ed +. +. +.Sh MACRO SYNTAX Macros are one to three three characters in length and begin with a control character , -.Sq \&. , +. 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 +. Sq .PP and -.Sq \&.\ \ \ \&PP +. Sq \&.\ \ \ PP are equivalent. -.Pp -All -.Nm -macros follow the same structural rules: -.Bd -literal -offset indent -\&.YO \(lBbody...\(rB -.Ed -.Pp +. 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 +. Nm +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. -.Ed -.Pp -The -.Sq \&.TP -macro is similar, but does not need an empty argument line to trigger -the behaviour. +. Ed +. Pp +is equivalent to +. Sq \&.I foo . .\" PARAGRAPH -.Sh MACROS -This section contains a complete list of all -.Nm -macros and corresponding number of arguments. -.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 -.El -.Pp -Although not historically part of the -.Nm -system, the following macros are also supported: -.Pp -.Bl -column "MacroX" "Arguments" -compact -offset indent -.It Em Macro Ta Em Arguments -.It \&.br Ta 0 -.It \&.i Ta n -.El -.Pp -These follow the same calling conventions as the above -.Nm -macros. -.\" SECTION +Consecutive next-line scope invocations are disallowed. +. Bd -literal -offset indent +\&.YO \(lBbody...\(rB +\(lBbody...\(rB +. Ed +. Pp +It is considered an error when next-line scope is open at the end of +file. +. Pp +. Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" +. It Em Macro Ta Em Arguments Ta Em Scope +. It B Ta n Ta next-line +. It BI Ta n Ta current +. It BR Ta n Ta current +. It DT Ta 0 Ta current +. It I Ta n Ta next-line +. It IB Ta n Ta current +. It IR Ta n Ta current +. It R Ta n Ta next-line +. It RB Ta n Ta current +. It RI Ta n Ta current +. It SB Ta n Ta next-line +. It SM Ta n Ta next-line +. It TH Ta >1, <6 Ta current +. It br Ta 0 Ta current +. It fi Ta 0 Ta current +. It i Ta n Ta current +. It na Ta 0 Ta current +. It nf Ta 0 Ta current +. It r Ta 0 Ta current +. It sp Ta 1 Ta current +. El +. Pp +The +. Sq RS , +. Sq RE , +. Sq br , +. Sq fi , +. Sq i , +. Sq na , +. Sq nf , +. Sq r , +and +. Sq sp +macros aren't historically part of +. Nm +and 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 +The closure of body scope may be to the section, where a macro is closed +by +. Sq SH ; +sub-section, closed by a section or +. Sq SS ; +part, closed by a section, sub-section, or +. Sq RE ; +or paragraph, closed by a section, sub-section, part, +. Sq HP , +. Sq IP , +. Sq LP , +. Sq P , +. Sq PP , +or +. Sq TP . +No closure refers to an explicit block closing macro. +. Pp +It is considered an error when part or next-line scope is open at the +end of file. +. 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 HP Ta <2 Ta current Ta paragraph +. It IP Ta <3 Ta current Ta paragraph +. It LP Ta 0 Ta current Ta paragraph +. It P Ta 0 Ta current Ta paragraph +. It PP Ta 0 Ta current Ta paragraph +. It RE Ta 0 Ta current Ta none +. It RS Ta 1 Ta current Ta part +. It SH Ta >0 Ta current Ta section +. It SS Ta >0 Ta current Ta sub-section +. It TP Ta n Ta next-line Ta paragraph +. El +. Pp +If a block macro is next-line scoped, it may only be followed by in-line +macros (excluding +. Sq DT , +. Sq TH , +. Sq br , +. Sq na , +. Sq sp , +. Sq nf , +and +. Sq 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 Definitions +In this reference, a numerical width may be either a standalone natural +number (such as 3, 4, 10, etc.) or a natural number followed by a width +multiplier +. Qq n , +corresponding to the width of the formatted letter n, or +. Qq m , +corresponding to the width of the formatted letter m. The latter is the +default, if unspecified. Thus, +. Bd -literal -offset indent +\&.HP 12n +. Ed +. Pp +indicates an offset of 12 +. Qq n +. Ns -sized +letters. +. +. +. Ss Macro Reference +. Bl -tag -width Ds +. It B +Text is rendered in bold face. +. It 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. +. It BR +Text is rendered alternately in bold face and roman (the default font). +Whitespace between arguments is omitted in output. +. It DT +Re-set the tab spacing to 0.5 inches. +. It 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 +If +. Va width +is specified, it's saved for later paragraph left-margins; if +unspecified, the saved or default width is used. +. It I +Text is rendered in italics. +. It IB +Text is rendered alternately in italics and bold face. Whitespace +between arguments is omitted in output. +. It IP +Begin a paragraph with the following syntax: +. Bd -literal -offset indent +\&.IP [head [width]] +. Ed +. Pp +This follows the behaviour of the +. Sq 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. +. It IR +Text is rendered alternately in italics and roman (the default font). +Whitespace between arguments is omitted in output. +. It LP, P, PP +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. +. It R +Text is rendered in roman (the default font). +. It RB +Text is rendered alternately in roman (the default font) and bold face. +Whitespace between arguments is omitted in output. +. It RE +Explicitly close out the scope of a prior +. Sq RS . +. It RI +Text is rendered alternately in roman (the default font) and italics. +Whitespace between arguments is omitted in output. +. It 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 +. Sq PP . +The 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. +. It SB +Text is rendered in small size (one point smaller than the default font) +bold face. +. It 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. +. It SM +Text is rendered in small size (one point smaller than the default +font). +. It 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. +. It 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. +. It 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 width may be set as follows: +. Bd -literal -offset indent +\&.TP [width] +. Ed +. Pp +Where +. Va width +must be a properly-formed numeric width. If +. Va width +is specified, it's saved for later paragraph left-margins; if +unspecified, the saved or default width is used. +. It br +Breaks the current line. Consecutive invocations have no further effect. +. It fi +End literal mode begun by +. Sq nf . +. It i +Italicise arguments. If no arguments are specified, all subsequent text +is italicised. +. It na +Don't alignment the right margin. +. It nf +Begin literal mode: all subsequent free-form lines have their end of +line boundaries preserved. May be ended by +. Sq fi . +. It r +Fonts and styles (bold face, italics) reset to roman (default font). +. It sp +Insert n spaces, where n is the macro's positive numeric argument. If +0, this is equivalent to the +. Sq br +macro. +. El +. +. +.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 +. Xr mandoc 1 , +. Xr mandoc_char 7 +. +. .Sh AUTHORS The -.Nm -utility was written by -.An Kristaps Dzonsons Aq kristaps@openbsd.org . -.\" SECTION +. Nm +reference was written by +. An Kristaps Dzonsons Aq kristaps@kth.se . +. +. .Sh CAVEATS Do not use this language. Use -.Xr mdoc 7 , +. Xr mdoc 7 , instead. +.