=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.11 retrieving revision 1.24 diff -u -p -r1.11 -r1.24 --- mandoc/man.7 2009/06/10 20:18:43 1.11 +++ mandoc/man.7 2009/08/13 12:31:50 1.24 @@ -1,4 +1,4 @@ -.\" $Id: man.7,v 1.11 2009/06/10 20:18:43 kristaps Exp $ +.\" $Id: man.7,v 1.24 2009/08/13 12:31:50 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: June 10 2009 $ +.Dd $Mdocdate: August 13 2009 $ .Dt MAN 7 .Os .\" SECTION @@ -25,15 +25,17 @@ .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 @@ -41,7 +43,7 @@ language, instead. 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: @@ -52,13 +54,10 @@ Other lines are interpreted within the current state. .\" 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. @@ -70,22 +69,87 @@ escape is common in historical 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. +.\" SUB-SECTION .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 . +.\" SUB-SECTION---------------------- +.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). +.\" SUB-SECTION---------------------- +.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 . +.\" SECTION +.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 -Characters may alternatively be escaped by a slash-asterisk, -.Sq \e* , -with the same combinations as described above. This form is deprecated. +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 +foo \e- 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 .\" SECTION -.Sh STRUCTURE +.Sh MACRO SYNTAX Macros are one to three three characters in length and begin with a control character , .Sq \&. , @@ -96,97 +160,231 @@ and .Sq \&.\ \ \ \&PP are equivalent. .Pp -All -.Nm -macros follow the same structural rules: -.Bd -literal -offset indent -\&.YO \(lBbody...\(rB -.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-scoped +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. +.\" SUBSECTION +.Ss Line Macros +Line-macros are scoped to the current line, with the body consisting of +zero or more arguments. If a macro is next-line scoped and the line +arguments are empty, the next line is used instead. Thus: +.Bd -literal -offset indent +\&.RI foo .Ed +.\" PARAGRAPH .Pp -is equivalent to +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. +.\" PARAGRAPH +Consecutive next-line invocations are disallowed. +.Bd -literal -offset indent +\&.YO \(lBbody...\(rB +\(lBbody...\(rB .Ed -.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. .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 +.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 \&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 +.\" PARAGRAPH .Pp -Although not historically part of the +The lower-case +.Sq \&br , +.Sq \&fi , +.Sq \&i , +.Sq \&na , +.Sq \&nf , +.Sq \&r , +and +.Sq \&sp +macros aren't historically part of .Nm -system, the following macros are also supported: +and should not be used. They're included for compatibility. +.\" SUBSECTION +.Ss Block Macros +Block macros are comprised of a head and body. 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 +.\" PARAGRAPH .Pp -.Bl -column "MacroX" "Arguments" -compact -offset indent -.It Em Macro Ta Em Arguments -.It \&.br Ta 0 -.It \&.i Ta n +If a block macro is next-line scoped, it may only be followed by in-line +macros (excluding +.Sq na , +.Sq sp , +.Sq nf , +.Sq fi , +and +.Sq TH ) . +.\" PARAGRAPH +.Pp +.Bl -column "MacroX" "Arguments" "ScopeXXXX" -compact -offset indent +.It Em Macro Ta Em Arguments Ta Em Scope +.It \&HP Ta <2 Ta current +.It \&IP Ta <3 Ta current +.It \&LP Ta 0 Ta current +.It \&P Ta 0 Ta current +.It \&PP Ta 0 Ta current +.It \&SH Ta >0 Ta current +.It \&SS Ta >0 Ta current +.It \&TP Ta n Ta next-line .El +.\" SECTION +.Sh REFERENCE +This section is a canonical reference to all macros, arranged +alphabetically. For the scoping of individual macros, see +.Sx MACRO SYNTAX . +.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 \&HP +Begin a paragraph whose initial output line is left-justified, but +subsequent output lines are indented. +.\" TODO. +.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 +.\" TODO. +.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. +.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 \&RI +Text is rendered alternately in roman (the default font) and italics. +Whitespace between arguments is omitted in output. +.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. +.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. +.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 -These follow the same calling conventions as the above -.Nm -macros. +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 point, is +followed by a newline; if not, the body follows on the same line after a +buffer to the indentation point. Subsequent output lines are indented. +.It \&br +Breaks the current line. Consecutive invocations have no further effect. +.\" TODO. +.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 +No alignment to 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 .\" SECTION +.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 +.\" SECTION .Sh SEE ALSO .Xr mandoc 1 , .Xr mandoc_char 7 @@ -194,8 +392,8 @@ macros. .Sh AUTHORS The .Nm -utility was written by -.An Kristaps Dzonsons Aq kristaps@openbsd.org . +reference was written by +.An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION .Sh CAVEATS Do not use this language. Use