=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.5 retrieving revision 1.19 diff -u -p -r1.5 -r1.19 --- mandoc/man.7 2009/03/26 23:01:26 1.5 +++ mandoc/man.7 2009/07/14 15:56:44 1.19 @@ -1,23 +1,21 @@ -.\" $Id: man.7,v 1.5 2009/03/26 23:01:26 kristaps Exp $ +.\" $Id: man.7,v 1.19 2009/07/14 15:56:44 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 14 2009 $ +.Dt MAN 7 .Os .\" SECTION .Sh NAME @@ -29,15 +27,15 @@ The .Nm man 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 Em +Do not use .Nm -to write your manuals. Use the +to write your manuals. +.Ef +Use the .Xr mdoc 7 language, instead. .\" PARAGRAPH @@ -56,12 +54,9 @@ 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. .Pp Blank lines are acceptable; where found, the output will assert a @@ -74,6 +69,16 @@ 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 +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. +.\" SUB-SECTION .Ss Special Characters Special character sequences begin with the escape character .Sq \e @@ -87,13 +92,33 @@ 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. +with the same combinations as described above. .Pp -The -.Xr mdoc 7 -contains a table of all available escapes. +Terms may also be text-decorated using the +.Sq \ef +escape followed by a text-decoration letter: 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 \&. , @@ -138,7 +163,7 @@ foo .Ed .Pp is equivalent to -.Sq \&.RI foo . +.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 @@ -151,7 +176,7 @@ 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 .Nm @@ -180,15 +205,35 @@ 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 1 , +.Xr mandoc_char 7 .\" SECTION .Sh AUTHORS The .Nm utility was written by -.An Kristaps Dzonsons Aq kristaps@openbsd.org . +.An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION .Sh CAVEATS Do not use this language. Use