Modernised comment handling: text following \" is thrown away before

[mandoc.git] / man.7

diff --git a/man.7 b/man.7
index f85d690cbe2b37b3b311bbd407a84c7eea12b562..fa473867a37806edd413098f260726710cf2d912 100644 (file)
--- a/man.7
+++ b/man.7
@@ -1,23 +1,21 @@
-.\" $Id: man.7,v 1.3 2009/03/26 14:38:11 kristaps Exp $
+.\"    $Id: man.7,v 1.13 2009/06/16 19:13:28 kristaps Exp $

 .\"
 .\"

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

 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\"
 .\" 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: June 16 2009 $
+.Dt MAN 7

 .Os
 .\" SECTION
 .Sh NAME
 .Os
 .\" SECTION
 .Sh NAME


@@ -29,10 +27,8 @@ The
 .Nm man
 language was historically used to format 
 .Ux
 .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 the syntax and structure of
+this language.

 .Pp
 .Em \&Do not
 use 
 .Pp
 .Em \&Do not
 use 


@@ -49,14 +45,10 @@ character
 .Sq \&.
 are parsed for macros.  Other lines are interpreted within the scope of
 prior macros:
 .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
 \&.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
 .\" SECTION
 .Sh INPUT ENCODING
 .Nm


@@ -64,11 +56,29 @@ documents may contain only graphable 7-bit ASCII characters and the
 space character
 .Sq \  .
 All manuals must have
 space character
 .Sq \  .
 All manuals must have

+.Ux

 .Sq \en
 line termination.  
 .Pp
 .Sq \en
 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.
 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
+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
 .\" SUB-SECTION
 .Ss Special Characters
 Special character sequences begin with the escape character


@@ -84,48 +94,82 @@ or a single one-character sequence.
 Characters may alternatively be escaped by a slash-asterisk,
 .Sq \e* ,
 with the same combinations as described above.  This form is deprecated.  
 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.

 .\" SECTION
 .Sh STRUCTURE
 Macros are one to three three characters in length and begin with a
 .\" SECTION
 .Sh STRUCTURE
 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,
 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
 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.
 .Ed
 .Pp
 The
 .Dq body
 consists of zero or more arguments to the macro.

+.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.

 .\" PARAGRAPH
 .Sh MACROS
 This section contains a complete list of all 
 .Nm
 .\" PARAGRAPH
 .Sh MACROS
 This section contains a complete list of all 
 .Nm

-macros, arranged alphabetically, with the number of arguments.
+macros and corresponding number of arguments.

 .Pp
 .Pp

-.Bl -column "MacroX" "Arguments" -compact -offset XXXX
+.Bl -column "MacroX" "Arguments" -compact -offset indent

 .It Em Macro Ta Em Arguments
 .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 \&.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
 .It \&.SM    Ta    n
 .It \&.SB    Ta    n
 .It \&.BI    Ta    n


@@ -138,15 +182,30 @@ macros, arranged alphabetically, with the number of arguments.
 .It \&.IR    Ta    n
 .It \&.RI    Ta    n
 .El
 .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 SEE ALSO
 .\" SECTION
 .Sh SEE ALSO

-.Xr mandoc 1
+.Xr mandoc 1 ,
+.Xr mandoc_char 7

 .\" SECTION
 .Sh AUTHORS
 The
 .Nm
 utility was written by 
 .\" 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
 .\" SECTION
 .Sh CAVEATS
 Do not use this language.  Use