=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.2 retrieving revision 1.21 diff -u -p -r1.2 -r1.21 --- mandoc/man.7 2009/03/26 09:55:39 1.2 +++ mandoc/man.7 2009/07/27 12:35:53 1.21 @@ -1,23 +1,21 @@ -.\" $Id: man.7,v 1.2 2009/03/26 09:55:39 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 26 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 -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,87 +43,159 @@ 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: -.Bd -literal -offset XXX +.Bd -literal -offset indent \&.SH Macro lines change control state. Other lines are interpreted within the current state. .Ed -.\" PARAGRAPH -.Pp -Macros are character sequences whose structural rules are described -later in this document. .\" SECTION .Sh INPUT ENCODING .Nm -documents may contain only graphable 7-bit ASCII characters and the -space character -.Sq \ . -All manuals must have -.Sq \en -line termination. +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 also assert a +Blank lines are acceptable; where found, the output will assert a vertical space. +.Pp +The +.Sq \ec +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. +.\" 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. -.Pp -The -.Xr mdoc 7 -contains a table of all available escapes. +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 \&. +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 +.Sq \&.PP and .Sq \&.\ \ \ \&PP are equivalent. .Pp -All follow the same -structural rules: -.Bd -literal -offset XXXX -\&.Yo \(lBbody...\(rB +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. -.\" PARAGRAPH +.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 +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. +.\" SECTION .Sh MACROS -This section contains a complete list of all +This section contains a complete list of all .Nm -macros, arranged alphabetically, with the number of arguments. +macros and corresponding number of arguments. .Pp -.Bl -column "MacroX" "Arguments" -compact -offset XXXX +.Bl -column "MacroX" "Arguments" -compact -offset indent .It Em Macro Ta Em Arguments -.It \&.TH Ta >0 -.It \&.SH Ta n -.It \&.SS Ta n +.It \&.TH Ta >1, <6 +.It \&.SH Ta >0 +.It \&.SS Ta >0 .It \&.TP Ta n -.It \&.LP Ta n -.It \&.PP Ta n -.It \&.P Ta n -.It \&.IP Ta n -.It \&.HP 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 @@ -136,16 +206,37 @@ macros, arranged alphabetically, with the number of ar .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 +.Sh COMPATIBILITY +See +.Xr mdoc 7 +for groff compatibility notes. +.\" SECTION .Sh SEE ALSO -.Xr mandoc 1 +.Xr mandoc 1 , +.Xr mandoc_char 7 .\" SECTION .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