-.\" $Id: mandoc.1,v 1.89 2011/05/30 07:24:15 kristaps Exp $
+.\" $Id: mandoc.1,v 1.101 2012/05/27 17:48:57 schwarze Exp $
.\"
-.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2012 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
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: May 30 2011 $
+.Dd $Mdocdate: May 27 2012 $
.Dt MANDOC 1
.Os
.Sh NAME
.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
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
+.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
.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
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.
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
.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
.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 ,
.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 ,
.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 ,
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 legancy 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
.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
-.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
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
The
.Nm
utility was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .
.Sh CAVEATS
In
.Fl T Ns Cm html
git.ckatri.com / mandoc.git / blobdiff