Below DIAGNOSTICS, document the SYSERR message level;

[mandoc.git] / mandoc.1

diff --git a/mandoc.1 b/mandoc.1
index de14205c60f2724266dddf7f0a6bc1b249a6317b..745dd504ed61e08fac1d746076dd3faecdb3a79c 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,6 +1,7 @@
-.\"    $Id: mandoc.1,v 1.90 2011/08/18 08:58:43 kristaps Exp $
+.\"    $Id: mandoc.1,v 1.105 2014/06/23 22:03:30 schwarze Exp $

 .\"
 .\"

-.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>

 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above


@@ -14,7 +15,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: August 18 2011 $
+.Dd $Mdocdate: June 23 2014 $

 .Dt MANDOC 1
 .Os
 .Sh NAME
 .Dt MANDOC 1
 .Os
 .Sh NAME


@@ -23,6 +24,9 @@
 .Sh SYNOPSIS
 .Nm mandoc
 .Op Fl V
 .Sh SYNOPSIS
 .Nm mandoc
 .Op Fl V

+.Sm off
+.Op Fl I Cm os Li = Ar name
+.Sm on

 .Op Fl m Ns Ar format
 .Op Fl O Ns Ar option
 .Op Fl T Ns Ar output
 .Op Fl m Ns Ar format
 .Op Fl O Ns Ar option
 .Op Fl T Ns Ar output


@@ -34,8 +38,30 @@ The
 utility formats
 .Ux
 manual pages for display.
 utility formats
 .Ux
 manual pages for display.

+.Pp
+By default,
+.Nm
+reads
+.Xr mdoc 7
+or
+.Xr man 7
+text from stdin, implying
+.Fl m Ns Cm andoc ,
+and produces
+.Fl T Ns Cm ascii
+output.
+.Pp

 The arguments are as follows:
 .Bl -tag -width Ds
 The arguments are as follows:
 .Bl -tag -width Ds

+.Sm off
+.It Fl I Cm os Li = Ar name
+.Sm on
+Override the default operating system
+.Ar name
+for the
+.Xr mdoc 7
+.Sq \&Os
+macro.

 .It Fl m Ns Ar format
 Input format.
 See
 .It Fl m Ns Ar format
 Input format.
 See


@@ -96,18 +122,6 @@ If multiple files are specified,
 .Nm
 will halt with the first failed parse.
 .El
 .Nm
 will halt with the first failed parse.
 .El

-.Pp
-By default,
-.Nm
-reads
-.Xr mdoc 7
-or
-.Xr man 7
-text from stdin, implying
-.Fl m Ns Cm andoc ,
-and produces
-.Fl T Ns Cm ascii
-output.

 .Ss Input Formats
 The
 .Nm
 .Ss Input Formats
 The
 .Nm


@@ -157,15 +171,7 @@ The
 utility accepts the following
 .Fl T
 arguments, which correspond to output modes:
 utility accepts the following
 .Fl T
 arguments, which correspond to output modes:

-.Bl -tag -width Ds
-.It Fl T Ns Cm utf8
-Encode output in the UTF\-8 multi-byte format.
-See
-.Sx UTF\-8 Output .
-.It Fl T Ns Cm locale
-Encode output using the current locale.
-See
-.Sx Locale Output .
+.Bl -tag -width "-Tlocale"

 .It Fl T Ns Cm ascii
 Produce 7-bit ASCII output.
 This is the default.
 .It Fl T Ns Cm ascii
 Produce 7-bit ASCII output.
 This is the default.


@@ -179,6 +185,16 @@ See
 Parse only: produce no output.
 Implies
 .Fl W Ns Cm warning .
 Parse only: produce no output.
 Implies
 .Fl W Ns Cm warning .

+.It Fl T Ns Cm locale
+Encode output using the current locale.
+See
+.Sx Locale Output .
+.It Fl T Ns Cm man
+Produce
+.Xr man 7
+format output.
+See
+.Sx Man Output .

 .It Fl T Ns Cm pdf
 Produce PDF output.
 See
 .It Fl T Ns Cm pdf
 Produce PDF output.
 See


@@ -189,6 +205,10 @@ See
 .Sx PostScript Output .
 .It Fl T Ns Cm tree
 Produce an indented parse tree.
 .Sx PostScript Output .
 .It Fl T Ns Cm tree
 Produce an indented parse tree.

+.It Fl T Ns Cm utf8
+Encode output in the UTF\-8 multi-byte format.
+See
+.Sx UTF\-8 Output .

 .It Fl T Ns Cm xhtml
 Produce strict CSS1/XHTML-1.0 output.
 See
 .It Fl T Ns Cm xhtml
 Produce strict CSS1/XHTML-1.0 output.
 See


@@ -197,23 +217,6 @@ See
 .Pp
 If multiple input files are specified, these will be processed by the
 corresponding filter in-order.
 .Pp
 If multiple input files are specified, these will be processed by the
 corresponding filter in-order.

-.Ss UTF\-8 Output
-Use
-.Fl T Ns Cm utf8
-to force a UTF\-8 locale.
-See
-.Sx Locale Output
-for details and options.
-.Ss Locale Output
-Locale-depending output encoding is triggered with
-.Fl T Ns Cm locale .
-This option is not available on all systems: systems without locale
-support, or those whose internal representation is not natively UCS-4,
-will fall back to
-.Fl T Ns Cm ascii .
-See
-.Sx ASCII Output
-for font style specification and available command-line arguments.

 .Ss ASCII Output
 Output produced by
 .Fl T Ns Cm ascii ,
 .Ss ASCII Output
 Output produced by
 .Fl T Ns Cm ascii ,


@@ -245,6 +248,15 @@ The following
 .Fl O
 arguments are accepted:
 .Bl -tag -width Ds
 .Fl O
 arguments are accepted:
 .Bl -tag -width Ds

+.It Cm indent Ns = Ns Ar indent
+The left margin for normal text is set to
+.Ar indent
+blank characters instead of the default of five for
+.Xr mdoc 7
+and seven for
+.Xr man 7 .
+Increasing this is not recommended; it may result in degraded formatting,
+for example overfull lines or ugly line breaks.

 .It Cm width Ns = Ns Ar width
 The output width is set to
 .Ar width ,
 .It Cm width Ns = Ns Ar width
 The output width is set to
 .Ar width ,


@@ -270,6 +282,21 @@ The following
 .Fl O
 arguments are accepted:
 .Bl -tag -width Ds
 .Fl O
 arguments are accepted:
 .Bl -tag -width Ds

+.It Cm fragment
+Omit the
+.Aq !DOCTYPE
+declaration and the
+.Aq html ,
+.Aq head ,
+and
+.Aq body
+elements and only emit the subtree below the
+.Aq body
+element.
+The
+.Cm style
+argument will be ignored.
+This is useful when embedding manual content within existing documents.

 .It Cm includes Ns = Ns Ar fmt
 The string
 .Ar fmt ,
 .It Cm includes Ns = Ns Ar fmt
 The string
 .Ar fmt ,


@@ -306,6 +333,48 @@ is used for an external style-sheet.
 This must be a valid absolute or
 relative URI.
 .El
 This must be a valid absolute or
 relative URI.
 .El

+.Ss Locale Output
+Locale-depending output encoding is triggered with
+.Fl T Ns Cm locale .
+This option is not available on all systems: systems without locale
+support, or those whose internal representation is not natively UCS-4,
+will fall back to
+.Fl T Ns Cm ascii .
+See
+.Sx ASCII Output
+for font style specification and available command-line arguments.
+.Ss Man Output
+Translate input format into
+.Xr man 7
+output format.
+This is useful for distributing manual sources to legacy systems
+lacking
+.Xr mdoc 7
+formatters.
+.Pp
+If
+.Xr mdoc 7
+is passed as input, it is translated into
+.Xr man 7 .
+If the input format is
+.Xr man 7 ,
+the input is copied to the output, expanding any
+.Xr roff 7
+.Sq so
+requests.
+The parser is also run, and as usual, the
+.Fl W
+level controls which
+.Sx DIAGNOSTICS
+are displayed before copying the input to the output.
+.Ss PDF Output
+PDF-1.1 output may be generated by
+.Fl T Ns Cm pdf .
+See
+.Sx PostScript Output
+for
+.Fl O
+arguments and defaults.

 .Ss PostScript Output
 PostScript
 .Qq Adobe-3.0
 .Ss PostScript Output
 PostScript
 .Qq Adobe-3.0


@@ -340,14 +409,13 @@ If an unknown value is encountered,
 .Ar letter
 is used.
 .El
 .Ar letter
 is used.
 .El

-.Ss PDF Output
-PDF-1.1 output may be generated by
-.Fl T Ns Cm pdf .
+.Ss UTF\-8 Output
+Use
+.Fl T Ns Cm utf8
+to force a UTF\-8 locale.

 See
 See

-.Sx PostScript Output
-for
-.Fl O
-arguments and defaults.
+.Sx Locale Output
+for details and options.

 .Ss XHTML Output
 Output produced by
 .Fl T Ns Cm xhtml
 .Ss XHTML Output
 Output produced by
 .Fl T Ns Cm xhtml


@@ -417,12 +485,20 @@ To check over a large set of manuals:
 To produce a series of PostScript manuals for A4 paper:
 .Pp
 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
 To produce a series of PostScript manuals for A4 paper:
 .Pp
 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps

+.Pp
+Convert a modern
+.Xr mdoc 7
+manual to the older
+.Xr man 7
+format, for use on systems lacking an
+.Xr mdoc 7
+parser:
+.Pp
+.Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man

 .Sh DIAGNOSTICS
 Standard error messages reporting parsing errors are prefixed by
 .Pp
 .Sh DIAGNOSTICS
 Standard error messages reporting parsing errors are prefixed by
 .Pp

-.Sm off
-.D1 Ar file : line : column : \ level :
-.Sm on
+.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level :

 .Pp
 where the fields have the following meanings:
 .Bl -tag -width "column"
 .Pp
 where the fields have the following meanings:
 .Bl -tag -width "column"


@@ -440,8 +516,17 @@ points to the first character of the word.
 The message level, printed in capital letters.
 .El
 .Pp
 The message level, printed in capital letters.
 .El
 .Pp

+The
+.Ar line
+and
+.Ar column
+fields are omitted when meaningless.
+.Pp

 Message levels have the following meanings:
 .Bl -tag -width "warning"
 Message levels have the following meanings:
 .Bl -tag -width "warning"

+.It Cm syserr
+Opening or reading an input file failed, so the parser cannot
+even be started and no output is produced from that input file.

 .It Cm fatal
 The parser is unable to parse a given input file at all.
 No formatted output is produced from that input file.
 .It Cm fatal
 The parser is unable to parse a given input file at all.
 No formatted output is produced from that input file.


@@ -477,9 +562,8 @@ output mode.
 The
 .Nm
 utility may also print messages related to invalid command line arguments
 The
 .Nm
 utility may also print messages related to invalid command line arguments

-or operating system errors, for example when memory is exhausted or
-input files cannot be read.
-Such messages do not carry the prefix described above.
+or operating system errors, for example when memory is exhausted.
+Such messages may not carry the prefix described above.

 .Sh COMPATIBILITY
 This section summarises
 .Nm
 .Sh COMPATIBILITY
 This section summarises
 .Nm


@@ -572,8 +656,7 @@ lists render similarly.
 The
 .Nm
 utility was written by
 The
 .Nm
 utility was written by

-.An Kristaps Dzonsons ,
-.Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

 .Sh CAVEATS
 In
 .Fl T Ns Cm html
 .Sh CAVEATS
 In
 .Fl T Ns Cm html