Lint-check (removed unused variable).

[mandoc.git] / man.7

diff --git a/man.7 b/man.7
index e9dd35d918a570562d164b129cc0ce4e511bd6de..d99cf7218f01725173eaec9fcf75a902f13df3b5 100644 (file)
--- a/man.7
+++ b/man.7
@@ -1,4 +1,4 @@
-.\"    $Id: man.7,v 1.12 2009/06/11 07:26:35 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 11 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


@@ -52,12 +54,9 @@ Other lines are interpreted within the current state.
 .\" SECTION
 .Sh INPUT ENCODING
 .Nm
 .\" 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
 .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


@@ -70,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
 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
 .Ss Special Characters
 Special character sequences begin with the escape character
 .Sq \e


@@ -83,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 \&. ,


@@ -143,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


@@ -187,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