=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.6 retrieving revision 1.21 diff -u -p -r1.6 -r1.21 --- mandoc/man.7 2009/03/27 14:56:15 1.6 +++ mandoc/man.7 2009/07/27 12:35:53 1.21 @@ -1,23 +1,21 @@ -.\" $Id: man.7,v 1.6 2009/03/27 14:56:15 kristaps Exp $ +.\" $Id: man.7,v 1.21 2009/07/27 12:35:53 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: March 27 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: July 27 2009 $ +.Dt MAN 7 .Os .\" SECTION .Sh NAME @@ -27,17 +25,17 @@ .Sh DESCRIPTION The .Nm man -language was historically used to format +language was historically used to format .Ux -manuals. In this reference document, we describe the syntax and -structure of the -.Nm -language. +manuals. This reference document describes its syntax, structure, and +usage. .Pp -.Em \&Do not ever -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 @@ -45,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: @@ -56,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. @@ -74,22 +69,59 @@ 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. +.\" 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. -.Pp -Characters may alternatively be escaped by a slash-asterisk, -.Sq \e* , -with the same combinations as described above. This form is deprecated. +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 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 the +.Sq \&.TH , +at least one macro or text node must appear in the document. +.\" SECTION +.Sh SYNTAX Macros are one to three three characters in length and begin with a control character , .Sq \&. , @@ -100,11 +132,11 @@ and .Sq \&.\ \ \ \&PP are equivalent. .Pp -All +All .Nm macros follow the same structural rules: .Bd -literal -offset indent -\&.YO \(lBbody...\(rB +\&.YO \(lBbody...\(rB .Ed .Pp The @@ -112,7 +144,7 @@ The consists of zero or more arguments to the macro. .Pp .Nm -has a primitive notion of multi-line scope for the following macros: +has a primitive notion of multi-line scope for the following macros: .Sq \&.TM , .Sq \&.SM , .Sq \&.SB , @@ -123,23 +155,23 @@ has a primitive notion of multi-line scope for the fol .Sq \&.R , .Sq \&.B , .Sq \&.I , -.Sq \&.IR +.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 +.Bd -literal -offset indent +\&.RI foo .Ed .Pp -is equivalent to -.Sq \&.RI foo . +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 +.Bd -literal -offset indent +\&.RI +\&.I Hello, world. .Ed .Pp @@ -147,9 +179,9 @@ The .Sq \&.TP macro is similar, but does not need an empty argument line to trigger the behaviour. -.\" PARAGRAPH +.\" SECTION .Sh MACROS -This section contains a complete list of all +This section contains a complete list of all .Nm macros and corresponding number of arguments. .Pp @@ -176,7 +208,26 @@ macros and corresponding number of arguments. .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 +.Sh COMPATIBILITY +See +.Xr mdoc 7 +for groff compatibility notes. +.\" SECTION .Sh SEE ALSO .Xr mandoc 1 , .Xr mandoc_char 7 @@ -184,8 +235,8 @@ macros and corresponding number of arguments. .Sh AUTHORS The .Nm -utility was written by -.An Kristaps Dzonsons Aq kristaps@openbsd.org . +utility was written by +.An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION .Sh CAVEATS Do not use this language. Use