=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.14 retrieving revision 1.21 diff -u -p -r1.14 -r1.21 --- mandoc/man.7 2009/06/18 10:32:00 1.14 +++ mandoc/man.7 2009/07/27 12:35:53 1.21 @@ -1,4 +1,4 @@ -.\" $Id: man.7,v 1.14 2009/06/18 10:32:00 kristaps Exp $ +.\" $Id: man.7,v 1.21 2009/07/27 12:35:53 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 18 2009 $ +.Dd $Mdocdate: July 27 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: @@ -53,14 +55,9 @@ Other lines are interpreted within the current state. .Sh INPUT ENCODING .Nm documents may contain only graphable 7-bit ASCII characters, the -space character -.Sq \ , -and tabs -.Sq \et . -All manuals must have +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. @@ -73,31 +70,58 @@ documents; if encountered at the end of a word, it ens subsequent word isn't off-set by whitespace. .\" SUB-SECTION .Ss Comments -Anything following a -.Sq \e" -delimiter is considered a comment (unless the -.Sq \e -itself has been escaped) and is ignored to the end of line. -Furthermore, a macro line with only a control character -.Sq \. , -optionally followed by whitespace, is ignored. +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 \&. , @@ -108,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 @@ -120,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 , @@ -131,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 +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 @@ -155,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 @@ -199,6 +223,11 @@ 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 @@ -206,7 +235,7 @@ macros. .Sh AUTHORS The .Nm -utility was written by +utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION .Sh CAVEATS