Ugly fix for `Bl' or `Bd' causing badness when nested in `Bl -hang' lists.

[mandoc.git] / man.7

diff --git a/man.7 b/man.7
index 5cca8277b9aeb2f44cd18da55897e38750ec9161..91f469c76983c499b289d62fd0a2f25b1997ed7f 100644 (file)
--- a/man.7
+++ b/man.7
@@ -1,4 +1,4 @@
-.\"    $Id: man.7,v 1.15 2009/06/22 13:09:17 kristaps Exp $
+.\"    $Id: man.7,v 1.20 2009/07/20 13:45:11 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 22 2009 $
+.Dd $Mdocdate: July 20 2009 $

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


@@ -25,15 +25,17 @@
 .Sh DESCRIPTION
 The
 .Nm man
 .Sh DESCRIPTION
 The
 .Nm man

-language was historically used to format 
+language was historically used to format

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


@@ -41,7 +43,7 @@ language, instead.
 An
 .Nm
 document follows simple rules:  lines beginning with the control
 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:
 .Sq \&.
 are parsed for macros.  Other lines are interpreted within the scope of
 prior macros:


@@ -53,14 +55,9 @@ 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.  
+line termination.

 .Pp
 Blank lines are acceptable; where found, the output will assert a
 vertical space.
 .Pp
 Blank lines are acceptable; where found, the output will assert a
 vertical space.


@@ -74,8 +71,8 @@ subsequent word isn't off-set by whitespace.
 .\" SUB-SECTION
 .Ss Comments
 Anything following a
 .\" SUB-SECTION
 .Ss Comments
 Anything following a

-.Sq \e" 
-delimiter is considered a comment (unless the 
+.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 \e
 itself has been escaped) and is ignored to the end of line.
 Furthermore, a macro line with only a control character


@@ -85,7 +82,7 @@ optionally followed by whitespace, is ignored.
 .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

-followed by either an open-parenthesis 
+followed by either an open-parenthesis

 .Sq \&(
 for two-character sequences; an open-bracket
 .Sq \&[
 .Sq \&(
 for two-character sequences; an open-bracket
 .Sq \&[


@@ -95,7 +92,31 @@ 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
+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
 .\" SECTION
 .Sh SYNTAX
 Macros are one to three three characters in length and begin with a


@@ -108,11 +129,11 @@ and
 .Sq \&.\ \ \ \&PP
 are equivalent.
 .Pp
 .Sq \&.\ \ \ \&PP
 are equivalent.
 .Pp

-All 
+All

 .Nm
 macros follow the same structural rules:
 .Bd -literal -offset indent
 .Nm
 macros follow the same structural rules:
 .Bd -literal -offset indent

-\&.YO \(lBbody...\(rB 
+\&.YO \(lBbody...\(rB

 .Ed
 .Pp
 The
 .Ed
 .Pp
 The


@@ -120,7 +141,7 @@ The
 consists of zero or more arguments to the macro.
 .Pp
 .Nm
 consists of zero or more arguments to the macro.
 .Pp
 .Nm

-has a primitive notion of multi-line scope for the following macros: 
+has a primitive notion of multi-line scope for the following macros:

 .Sq \&.TM ,
 .Sq \&.SM ,
 .Sq \&.SB ,
 .Sq \&.TM ,
 .Sq \&.SM ,
 .Sq \&.SB ,


@@ -131,23 +152,23 @@ has a primitive notion of multi-line scope for the following macros:
 .Sq \&.R ,
 .Sq \&.B ,
 .Sq \&.I ,
 .Sq \&.R ,
 .Sq \&.B ,
 .Sq \&.I ,

-.Sq \&.IR 
+.Sq \&.IR

 and
 .Sq \&.RI .
 When these macros are invoked without arguments, the subsequent line is
 considered a continuation of the macro.  Thus:
 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 
+.Bd -literal -offset indent
+\&.RI

 foo
 .Ed
 .Pp
 foo
 .Ed
 .Pp

-is equivalent to 
+is equivalent to

 .Sq \&.RI foo .
 If two consecutive lines exhibit the latter behaviour,
 an error is raised.  Thus, the following is not acceptable:
 .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 
+.Bd -literal -offset indent
+\&.RI
+\&.I

 Hello, world.
 .Ed
 .Pp
 Hello, world.
 .Ed
 .Pp


@@ -156,21 +177,8 @@ The
 macro is similar, but does not need an empty argument line to trigger
 the behaviour.
 .\" SECTION
 macro is similar, but does not need an empty argument line to trigger
 the behaviour.
 .\" 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 MACROS
 .Sh MACROS

-This section contains a complete list of all 
+This section contains a complete list of all

 .Nm
 macros and corresponding number of arguments.
 .Pp
 .Nm
 macros and corresponding number of arguments.
 .Pp


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


@@ -219,7 +232,7 @@ macros.
 .Sh AUTHORS
 The
 .Nm
 .Sh AUTHORS
 The
 .Nm

-utility was written by 
+utility was written by

 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh CAVEATS
 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh CAVEATS