Fixed \(bq.

[mandoc.git] / mandoc.1

diff --git a/mandoc.1 b/mandoc.1
index 73c82ce42bff6d752bb513c0336ebef8d68f8e2f..78d5254523311d6e26fd5b35d05bc015ee8c1896 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.1,v 1.20 2009/06/17 19:12:03 kristaps Exp $
+.\"    $Id: mandoc.1,v 1.29 2009/07/26 19:30:50 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 17 2009 $
+.Dd $Mdocdate: July 26 2009 $

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


@@ -34,13 +34,13 @@
 .Sh DESCRIPTION
 The
 .Nm
 .Sh DESCRIPTION
 The
 .Nm

-utility formats 
+utility formats

 .Ux
 manual pages for display.  The arguments are as follows:
 .Bl -tag -width Ds
 .\" ITEM
 .It Fl f Ns Ar option...
 .Ux
 manual pages for display.  The arguments are as follows:
 .Bl -tag -width Ds
 .\" ITEM
 .It Fl f Ns Ar option...

-Override default compiler behaviour.  See 
+Override default compiler behaviour.  See

 .Sx Compiler Options
 for details.
 .\" ITEM
 .Sx Compiler Options
 for details.
 .\" ITEM


@@ -60,16 +60,12 @@ for available formats.  Defaults to
 Print version and exit.
 .\" ITEM
 .It Fl W Ns Ar err...
 Print version and exit.
 .\" ITEM
 .It Fl W Ns Ar err...

-Print warning messages.  May be set to 
+Configure warning messages.  Use

 .Fl W Ns Ar all
 .Fl W Ns Ar all

-for all warnings, 
-.Ar compat
-for groff/troff-compatibility warnings, or
-.Ar syntax
-for syntax warnings.  If
-.Fl W Ns Ar error 
-is specified, warnings are considered errors and cause utility
-termination.  Multiple 
+to print warnings,
+.Fl W Ns Ar error
+for warnings to be considered errors and cause utility
+termination.  Multiple

 .Fl W
 arguments may be comma-separated, such as
 .Fl W Ns Ar error,all .
 .Fl W
 arguments may be comma-separated, such as
 .Fl W Ns Ar error,all .


@@ -83,9 +79,9 @@ will halt with the first failed parse.
 .El
 .\" PARAGRAPH
 .Pp
 .El
 .\" PARAGRAPH
 .Pp

-By default, 
-.Nm 
-reads 
+By default,
+.Nm
+reads

 .Xr mdoc 7
 or
 .Xr man 7
 .Xr mdoc 7
 or
 .Xr man 7


@@ -98,36 +94,45 @@ 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
 .Po

-.Sq \&( , 
-.Sq \&[ , 
+.Sq \&( ,
+.Sq \&[ ,

 and
 .Sq \&{
 and
 .Sq \&{

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

 .Po
 .Po

-.Sq \&. , 
-.Sq \&, , 
-.Sq \&; , 
-.Sq \&: , 
-.Sq \&? , 
-.Sq \&! , 
-.Sq \&) , 
-.Sq \&] 
+.Sq \&. ,
+.Sq \&, ,
+.Sq \&; ,
+.Sq \&: ,
+.Sq \&? ,
+.Sq \&! ,
+.Sq \&) ,
+.Sq \&]

 and
 .Sq \&}
 and
 .Sq \&}

-.Pc 
+.Pc

 is not preceded by whitespace.
 .Pp
 If the input is
 .Xr mdoc 7 ,
 these rules are also applied to macro arguments when appropriate.
 is not preceded by whitespace.
 .Pp
 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


@@ -144,26 +149,26 @@ respectively.  The
 .Xr mdoc 7
 format is
 .Em strongly
 .Xr mdoc 7
 format is
 .Em strongly

-recommended; 
+recommended;

 .Xr man 7
 should only be used for legacy manuals.
 .Pp
 A third option,
 .Fl m Ns Ar andoc ,
 which is also the default, determines encoding on-the-fly: if the first
 .Xr man 7
 should only be used for legacy manuals.
 .Pp
 A third option,
 .Fl m Ns Ar andoc ,
 which is also the default, determines encoding on-the-fly: if the first

-non-comment macro is 
-.Sq \&.Dd
+non-comment macro is
+.Sq \&Dd

 or
 or

-.Sq \&.Dt ,
-the 
+.Sq \&Dt ,
+the

 .Xr mdoc 7
 parser is used; otherwise, the
 .Xr man 7
 parser is used.
 .Pp
 If multiple
 .Xr mdoc 7
 parser is used; otherwise, the
 .Xr man 7
 parser is used.
 .Pp
 If multiple

-files are specified with 
-.Fl m Ns Ar andoc , 
+files are specified with
+.Fl m Ns Ar andoc ,

 each has its file-type determined this way.  If multiple files are
 specified and
 .Fl m Ns Ar doc
 each has its file-type determined this way.  If multiple files are
 specified and
 .Fl m Ns Ar doc


@@ -210,16 +215,22 @@ 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 .
+.It Fl f Ns Ar ign-errors
+Don't halt when encountering parse errors.  Useful with
+.Fl T Ns Ar lint
+over a large set of manuals passed on the command line.

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


@@ -228,37 +239,62 @@ 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
 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less

+.\" PARAGRAPH
+.Pp
+To check over a large set of manuals:
+.\" PARAGRAPH
+.Pp
+.Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`

 .\" SECTION
 .Sh COMPATIBILITY
 .\" SECTION
 .Sh COMPATIBILITY

-This section summarises 
+This section summarises

 .Nm
 .Nm

-compatibility with 
+compatibility with

 .Xr groff 1 .
 .Pp
 .Bl -bullet -compact
 .Xr groff 1 .
 .Pp
 .Bl -bullet -compact

-.It 
+.\" LIST-ITEM
+.It
+The 
+.Sq \e~
+special character doesn't produce expected behaviour.
+.\" LIST-ITEM
+.It
+In 
+.Xr groff 1 ,
+the
+.Sq \&Pa
+macro does not underline when under a
+.Sq \&It .
+This behaves correctly in
+.Nm .
+.\" LIST-ITEM
+.It

 A list or display following
 A list or display following

-.Sq \&.Ss
+.Sq \&Ss

 does not assert a prior vertical break, just as it doesn't with
 does not assert a prior vertical break, just as it doesn't with

-.Sq \&.Sh .
-.\" LIST-ITEM
+.Sq \&Sh .

 .It
 .It

-The \-literal and \-unfilled 
-.Sq \&.Bd
+The \-literal and \-unfilled
+.Sq \&Bd

 displays types are synonyms, as are \-filled and \-ragged.
 .\" LIST-ITEM
 .It
 Words aren't hyphenated.
 displays types are synonyms, as are \-filled and \-ragged.
 .\" LIST-ITEM
 .It
 Words aren't hyphenated.

+.\" LIST-ITEM
+.It
+In normal mode (not a literal block), blocks of spaces aren't preserved,
+so double spaces following sentence closure are reduced to a single space.

 .El
 .\" SECTION
 .Sh SEE ALSO
 .El
 .\" SECTION
 .Sh SEE ALSO


@@ -269,13 +305,5 @@ Words aren't hyphenated.
 .Sh AUTHORS
 The
 .Nm
 .Sh AUTHORS
 The
 .Nm

-utility was written by 
+utility was written by

 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .An Kristaps Dzonsons Aq kristaps@kth.se .

-.\" SECTION
-.Sh CAVEATS
-The 
-.Nm
-utility doesn't yet know how to display \-hang lists.
-.Pp
-Other macros still aren't supported by virtue of nobody complaining
-about their absence.