Fixed STRUCTURE repeat (schwarze@openbsd.org).

[mandoc.git] / mandoc.1

diff --git a/mandoc.1 b/mandoc.1
index 3d1dc3cd245f698d1a857280e4544330f225ab00..b0fb6de17908550c085cc068b95e68627c07ab90 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.1,v 1.19 2009/06/15 09:35:16 kristaps Exp $
+.\"    $Id: mandoc.1,v 1.22 2009/06/22 12:04:05 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 15 2009 $
+.Dd $Mdocdate: June 22 2009 $

 .Dt MANDOC 1
 .Os
 .\" SECTION
 .Dt MANDOC 1
 .Os
 .\" SECTION


@@ -98,19 +98,19 @@ were provided.
 .Pp
 .Ex -std mandoc
 .\" SUB-SECTION
 .Pp
 .Ex -std mandoc
 .\" SUB-SECTION

-.Ss Punctuation
+.Ss Punctuation and Spacing

 If punctuation is set apart from words, such as in the phrase
 .Dq to be \&, or not to be ,
 it's processed by
 .Nm
 If punctuation is set apart from words, such as in the phrase
 .Dq to be \&, or not to be ,
 it's processed by
 .Nm

-according to the following rules.  Opening punctuation
+according to the following rules:  opening punctuation

 .Po
 .Sq \&( , 
 .Sq \&[ , 
 and
 .Sq \&{
 .Pc 
 .Po
 .Sq \&( , 
 .Sq \&[ , 
 and
 .Sq \&{
 .Pc 

-is not followed by a space. Closing punctuation
+is not followed by a space; closing punctuation

 .Po
 .Sq \&. , 
 .Sq \&, , 
 .Po
 .Sq \&. , 
 .Sq \&, , 


@@ -128,6 +128,15 @@ is not preceded by whitespace.
 If the input is
 .Xr mdoc 7 ,
 these rules are also applied to macro arguments when appropriate.
 If the input is
 .Xr mdoc 7 ,
 these rules are also applied to macro arguments when appropriate.

+.Pp
+White-space, in non-literal (normal) mode, is stripped from input and
+replaced on output by a single space.  Thus, if you wish to preserve
+multiple spaces, they must be space-escaped
+.Sq \e\  .
+or used in a literal display mode, e.g., 
+.Sq \&.Bd \-literal 
+in 
+.Xr mdoc 7 .

 .\" SUB-SECTION
 .Ss Input Formats
 The
 .\" SUB-SECTION
 .Ss Input Formats
 The


@@ -210,16 +219,18 @@ flag.
 When rewinding the scope of a block macro, forces the compiler to ignore
 scope violations.  This can seriously mangle the resulting tree.
 .Pq mdoc only
 When rewinding the scope of a block macro, forces the compiler to ignore
 scope violations.  This can seriously mangle the resulting tree.
 .Pq mdoc only

-.It Fl f Ns Ar ign-escape
-Ignore invalid escape sequences.
-.It Fl f Ns Ar ign-macro
-Ignore unknown macros at the start of input lines (default for 
-.Xr man 7
-parsing).
+.It Fl f Ns Ar no-ign-escape
+Don't ignore invalid escape sequences.

 .It Fl f Ns Ar no-ign-macro
 .It Fl f Ns Ar no-ign-macro

-Do not ignore unknown macros at the start of input lines (default for 
-.Xr mdoc 7
-parsing).
+Do not ignore unknown macros at the start of input lines.
+.It Fl f Ns Ar no-ign-chars
+Do not ignore disallowed characters.
+.It Fl f Ns Ar strict
+Implies 
+.Fl f Ns Ar no-ign-escape ,
+.Fl f Ns Ar no-ign-macro 
+and
+.Fl f Ns Ar no-ign-chars . 

 .El
 .\" PARAGRAPH
 .Pp
 .El
 .\" PARAGRAPH
 .Pp


@@ -228,22 +239,47 @@ As with the
 flag, multiple
 .Fl f
 options may be grouped and delimited with a comma.  Using
 flag, multiple
 .Fl f
 options may be grouped and delimited with a comma.  Using

-.Fl f Ns Ar ign-scope,ign-escape ,
-for example, will try to ignore scope and character-escape errors.
+.Fl f Ns Ar ign-scope,no-ign-escape ,
+for example, will try to ignore scope and not ignore character-escape
+errors.

 .\" SECTION
 .Sh EXAMPLES
 To page manuals to the terminal:
 .\" PARAGRAPH
 .Pp
 .\" SECTION
 .Sh EXAMPLES
 To page manuals to the terminal:
 .\" PARAGRAPH
 .Pp

-.D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
-.Pp
+.D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less

 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
 .\" SECTION
 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
 .\" SECTION

+.Sh COMPATIBILITY
+This section summarises 
+.Nm
+compatibility with 
+.Xr groff 1 .
+.Pp
+.Bl -bullet -compact
+.It 
+A list or display following
+.Sq \&.Ss
+does not assert a prior vertical break, just as it doesn't with
+.Sq \&.Sh .
+.It
+The \-literal and \-unfilled 
+.Sq \&.Bd
+displays types are synonyms, as are \-filled and \-ragged.
+.It
+Words aren't hyphenated.
+.It
+In normal mode (not a literal block), blocks of spaces aren't preserved,
+so double spaces following sentence closure 
+.Pq Qq French spacing
+are reduced to a single space.
+.El
+.\" SECTION

 .Sh SEE ALSO
 .Xr mandoc_char 7 ,
 .Xr mdoc 7 ,
 .Xr man 7
 .Sh SEE ALSO
 .Xr mandoc_char 7 ,
 .Xr mdoc 7 ,
 .Xr man 7

-.\" 
+.\" SECTION

 .Sh AUTHORS
 The
 .Nm
 .Sh AUTHORS
 The
 .Nm


@@ -253,37 +289,7 @@ utility was written by
 .Sh CAVEATS
 The 
 .Nm
 .Sh CAVEATS
 The 
 .Nm

-utility in
-.Fl T Ns Ar ascii
-mode doesn't yet know how to display the following:
-.Pp
-.Bl -bullet -compact
-.It
-The \-hang 
-.Sq \&.Bl
-list is not yet supported.
-.El
+utility doesn't yet know how to display \-hang lists.

 .Pp
 Other macros still aren't supported by virtue of nobody complaining
 .Pp
 Other macros still aren't supported by virtue of nobody complaining

-about their absence.  Please report any omissions: this is a work in
-progress.
-.Pp
-The following list documents differences between traditional
-.Xr nroff 1
-output and
-.Nm :
-.Pp
-.Bl -bullet -compact
-.It 
-A list of display following
-.Sq \&.Ss
-does not assert a prior vertical break, just as it doesn't with
-.Sq \&.Sh .
-.It
-Special characters don't follow the current font style.
-.\" LIST-ITEM
-.It
-The \-literal and \-unfilled 
-.Sq \&.Bd
-displays types are synonyms, as are \-filled and \-ragged.
-.El
+about their absence.