Lint-check (removed unused variable).

[mandoc.git] / man.7

diff --git a/man.7 b/man.7
index 42ab6e57ad0f1a45019a30757cdbd54aae19f7dd..d99cf7218f01725173eaec9fcf75a902f13df3b5 100644 (file)
--- a/man.7
+++ b/man.7
@@ -1,4 +1,4 @@
-.\"    $Id: man.7,v 1.14 2009/06/18 10:32:00 kristaps Exp $
+.\"    $Id: man.7,v 1.19 2009/07/14 15:56:44 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"


@@ -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.
 .\"
 .\" 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 14 2009 $

 .Dt MAN 7
 .Os
 .\" SECTION
 .Dt MAN 7
 .Os
 .\" SECTION


@@ -27,13 +27,15 @@ The
 .Nm man
 language was historically used to format 
 .Ux
 .Nm man
 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
 .Pp

-.Em \&Do not
-use 
+.Bf Em
+Do not use 

 .Nm
 .Nm

-to write your manuals.  Use the
+to write your manuals.  
+.Ef
+Use the

 .Xr mdoc 7
 language, instead.
 .\" PARAGRAPH
 .Xr mdoc 7
 language, instead.
 .\" PARAGRAPH


@@ -53,13 +55,8 @@ Other lines are interpreted within the current state.
 .Sh INPUT ENCODING
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the
 .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
 .Ux

-.Sq \en

 line termination.  
 .Pp
 Blank lines are acceptable; where found, the output will assert a
 line termination.  
 .Pp
 Blank lines are acceptable; where found, the output will assert a


@@ -95,9 +92,33 @@ or a single one-character sequence.
 .Pp
 Characters may alternatively be escaped by a slash-asterisk,
 .Sq \e* ,
 .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
+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
 .\" 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 \&. ,
 Macros are one to three three characters in length and begin with a
 control character ,
 .Sq \&. ,


@@ -155,7 +176,7 @@ The
 .Sq \&.TP
 macro is similar, but does not need an empty argument line to trigger
 the behaviour.
 .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
 .Sh MACROS
 This section contains a complete list of all 
 .Nm


@@ -199,6 +220,11 @@ These follow the same calling conventions as the above
 .Nm
 macros.
 .\" SECTION
 .Nm
 macros.
 .\" SECTION

+.Sh COMPATIBILITY
+See
+.Xr mdoc 7
+for groff compatibility notes.
+.\" SECTION

 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr mandoc_char 7
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr mandoc_char 7