531 lines
11 KiB
Groff
531 lines
11 KiB
Groff
.\" $Id: mandoc.1,v 1.63 2010/06/11 07:15:42 kristaps Exp $
|
|
.\"
|
|
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" 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 11 2010 $
|
|
.Dt MANDOC 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mandoc
|
|
.Nd format and display UNIX manuals
|
|
.Sh SYNOPSIS
|
|
.Nm mandoc
|
|
.Op Fl V
|
|
.Op Fl f Ns Ar option
|
|
.Op Fl m Ns Ar format
|
|
.Op Fl O Ns Ar option
|
|
.Op Fl T Ns Ar output
|
|
.Op Fl W Ns Ar err
|
|
.Op Ar file...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility formats
|
|
.Ux
|
|
manual pages for display.
|
|
The arguments are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Fl f Ns Ar option
|
|
Comma-separated compiler options.
|
|
See
|
|
.Sx Compiler Options
|
|
for details.
|
|
.It Fl m Ns Ar format
|
|
Input format.
|
|
See
|
|
.Sx Input Formats
|
|
for available formats.
|
|
Defaults to
|
|
.Fl m Ns Cm andoc .
|
|
.It Fl O Ns Ar option
|
|
Comma-separated output options.
|
|
See
|
|
.Sx Output Options
|
|
for details.
|
|
.It Fl T Ns Ar output
|
|
Output format.
|
|
See
|
|
.Sx Output Formats
|
|
for available formats.
|
|
Defaults to
|
|
.Fl T Ns Cm ascii .
|
|
.It Fl V
|
|
Print version and exit.
|
|
.It Fl W Ns Ar err
|
|
Comma-separated warning options.
|
|
Use
|
|
.Fl W Ns Cm all
|
|
to print warnings,
|
|
.Fl W Ns Cm error
|
|
for warnings to be considered errors and cause utility
|
|
termination.
|
|
Multiple
|
|
.Fl W
|
|
arguments may be comma-separated, such as
|
|
.Fl W Ns Cm error , Ns Cm all .
|
|
.It Ar file
|
|
Read input from zero or more files.
|
|
If unspecified, reads from stdin.
|
|
If multiple files are specified,
|
|
.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.
|
|
.Pp
|
|
.Ex -std mandoc
|
|
.Ss Input Formats
|
|
The
|
|
.Nm
|
|
utility accepts
|
|
.Xr mdoc 7
|
|
and
|
|
.Xr man 7
|
|
input with
|
|
.Fl m Ns Cm doc
|
|
and
|
|
.Fl m Ns Cm an ,
|
|
respectively.
|
|
The
|
|
.Xr mdoc 7
|
|
format is
|
|
.Em strongly
|
|
recommended;
|
|
.Xr man 7
|
|
should only be used for legacy manuals.
|
|
.Pp
|
|
A third option,
|
|
.Fl m Ns Cm andoc ,
|
|
which is also the default, determines encoding on-the-fly: if the first
|
|
non-comment macro is
|
|
.Sq \&Dd
|
|
or
|
|
.Sq \&Dt ,
|
|
the
|
|
.Xr mdoc 7
|
|
parser is used; otherwise, the
|
|
.Xr man 7
|
|
parser is used.
|
|
.Pp
|
|
If multiple
|
|
files are specified with
|
|
.Fl m Ns Cm andoc ,
|
|
each has its file-type determined this way.
|
|
If multiple files are
|
|
specified and
|
|
.Fl m Ns Cm doc
|
|
or
|
|
.Fl m Ns Cm an
|
|
is specified, then this format is used exclusively.
|
|
.Ss Output Formats
|
|
The
|
|
.Nm
|
|
utility accepts the following
|
|
.Fl T
|
|
arguments (see
|
|
.Sx OUTPUT ) :
|
|
.Bl -tag -width Ds
|
|
.It Fl T Ns Cm ascii
|
|
Produce 7-bit ASCII output, backspace-encoded for bold and underline
|
|
styles.
|
|
This is the default.
|
|
See
|
|
.Sx ASCII Output .
|
|
.It Fl T Ns Cm html
|
|
Produce strict HTML-4.01 output, with a sane default style.
|
|
See
|
|
.Sx HTML Output .
|
|
.It Fl T Ns Cm lint
|
|
Parse only: produce no output.
|
|
Implies
|
|
.Fl W Ns Cm all
|
|
and
|
|
.Fl f Ns Cm strict .
|
|
.It Fl T Ns Cm ps
|
|
Produce PostScript output.
|
|
See
|
|
.Sx PostScript Output .
|
|
.It Fl T Ns Cm tree
|
|
Produce an indented parse tree.
|
|
.It Fl T Ns Cm xhtml
|
|
Produce strict XHTML-1.0 output, with a sane default style.
|
|
See
|
|
.Sx XHTML Output .
|
|
.El
|
|
.Pp
|
|
If multiple input files are specified, these will be processed by the
|
|
corresponding filter in-order.
|
|
.Ss Compiler Options
|
|
Default compiler behaviour may be overridden with the
|
|
.Fl f
|
|
flag.
|
|
.Bl -tag -width Ds
|
|
.It Fl f Ns Cm ign-errors
|
|
When parsing multiple files, don't halt when one errors out.
|
|
Useful with
|
|
.Fl T Ns Cm lint
|
|
over a large set of manuals passed on the command line.
|
|
.It Fl f Ns Cm ign-escape
|
|
Ignore invalid escape sequences.
|
|
This is the default, but the option can be used to override an earlier
|
|
.Fl f Ns Cm strict .
|
|
.It Fl f Ns Cm ign-scope
|
|
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 Cm no-ign-escape
|
|
Do not ignore invalid escape sequences.
|
|
.It Fl f Ns Cm no-ign-macro
|
|
Do not ignore unknown macros at the start of input lines.
|
|
.It Fl f Ns Cm strict
|
|
Implies
|
|
.Fl f Ns Cm no-ign-escape
|
|
and
|
|
.Fl f Ns Cm no-ign-macro .
|
|
.El
|
|
.Ss Output Options
|
|
The
|
|
.Fl T Ns Ar html
|
|
and
|
|
.Fl T Ns Ar xhtml
|
|
modes accept the following output options:
|
|
.Bl -tag -width Ds
|
|
.It Fl O Ns Cm includes Ns = Ns Ar fmt
|
|
The string
|
|
.Ar fmt ,
|
|
for example,
|
|
.Ar ../src/%I.html ,
|
|
is used as a template for linked header files (usually via the
|
|
.Sq \&In
|
|
macro).
|
|
Instances of
|
|
.Sq \&%I
|
|
are replaced with the include filename.
|
|
The default is not to present a
|
|
hyperlink.
|
|
.It Fl O Ns Cm man Ns = Ns Ar fmt
|
|
The string
|
|
.Ar fmt ,
|
|
for example,
|
|
.Ar ../html%S/%N.%S.html ,
|
|
is used as a template for linked manuals (usually via the
|
|
.Sq \&Xr
|
|
macro).
|
|
Instances of
|
|
.Sq \&%N
|
|
and
|
|
.Sq %S
|
|
are replaced with the linked manual's name and section, respectively.
|
|
If no section is included, section 1 is assumed.
|
|
The default is not to
|
|
present a hyperlink.
|
|
.It Fl O Ns Cm style Ns = Ns Ar style.css
|
|
The file
|
|
.Ar style.css
|
|
is used for an external style-sheet.
|
|
This must be a valid absolute or
|
|
relative URI.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fl T Ns Ar ascii
|
|
mode accepts the following output option:
|
|
.Bl -tag -width Ds
|
|
.It Fl O Ns Cm width Ns = Ns Ar width
|
|
The output width is set to
|
|
.Ar width ,
|
|
which will normalise to \(>=60.
|
|
.El
|
|
.Sh OUTPUT
|
|
This section documents output details of
|
|
.Nm .
|
|
In general, output conforms to the traditional manual style of a header,
|
|
a body composed of sections and sub-sections, and a footer.
|
|
.Pp
|
|
The text style of output characters (non-macro characters, punctuation,
|
|
and white-space) is dictated by context.
|
|
.Pp
|
|
White-space is generally stripped from input.
|
|
This can be changed with
|
|
character escapes (specified in
|
|
.Xr mandoc_char 7 )
|
|
or literal modes (specified in
|
|
.Xr mdoc 7
|
|
and
|
|
.Xr man 7 ) .
|
|
.Pp
|
|
If non-macro punctuation is set apart from words, such as in the phrase
|
|
.Dq to be \&, or not to be ,
|
|
it's processed by
|
|
.Nm ,
|
|
regardless of output format, according to the following rules: opening
|
|
punctuation
|
|
.Po
|
|
.Sq \&( ,
|
|
.Sq \&[ ,
|
|
and
|
|
.Sq \&{
|
|
.Pc
|
|
is not followed by a space; closing punctuation
|
|
.Po
|
|
.Sq \&. ,
|
|
.Sq \&, ,
|
|
.Sq \&; ,
|
|
.Sq \&: ,
|
|
.Sq \&? ,
|
|
.Sq \&! ,
|
|
.Sq \&) ,
|
|
.Sq \&]
|
|
and
|
|
.Sq \&}
|
|
.Pc
|
|
is not preceded by white-space.
|
|
.Pp
|
|
If the input is
|
|
.Xr mdoc 7 ,
|
|
however, these rules are also applied to macro arguments when appropriate.
|
|
.Ss ASCII Output
|
|
Output produced by
|
|
.Fl T Ns Cm ascii ,
|
|
which is the default, is rendered in standard 7-bit ASCII documented in
|
|
.Xr ascii 7 .
|
|
.Pp
|
|
Font styles are applied by using back-spaced encoding such that an
|
|
underlined character
|
|
.Sq c
|
|
is rendered as
|
|
.Sq _ Ns \e[bs] Ns c ,
|
|
where
|
|
.Sq \e[bs]
|
|
is the back-space character number 8.
|
|
Emboldened characters are rendered as
|
|
.Sq c Ns \e[bs] Ns c .
|
|
.Pp
|
|
The special characters documented in
|
|
.Xr mandoc_char 7
|
|
are rendered best-effort in an ASCII equivalent.
|
|
.Pp
|
|
Output width is limited to 78 visible columns unless literal input lines
|
|
exceed this limit.
|
|
.Ss HTML Output
|
|
Output produced by
|
|
.Fl T Ns Cm html
|
|
conforms to HTML-4.01 strict.
|
|
.Pp
|
|
Font styles and page structure are applied using CSS2.
|
|
By default, no font style is applied to any text,
|
|
although CSS2 is hard-coded to format
|
|
the basic structure of output.
|
|
.Pp
|
|
The
|
|
.Pa example.style.css
|
|
file documents the range of styles applied to output and, if used, will
|
|
cause rendered documents to appear as they do in
|
|
.Fl T Ns Cm ascii .
|
|
.Pp
|
|
Special characters are rendered in decimal-encoded UTF-8.
|
|
.Ss PostScript Output
|
|
PostScript Level 2 pages may be generated by
|
|
.Fl T Ns Cm ps .
|
|
Output pages are US-letter sized (215.9 x 279.4 mm) and rendered in
|
|
fixed, 10-point Courier font.
|
|
.Ss XHTML Output
|
|
Output produced by
|
|
.Fl T Ns Cm xhtml
|
|
conforms to XHTML-1.0 strict.
|
|
.Pp
|
|
See
|
|
.Sx HTML Output
|
|
for details; beyond generating XHTML tags instead of HTML tags, these
|
|
output modes are identical.
|
|
.Sh EXAMPLES
|
|
To page manuals to the terminal:
|
|
.Pp
|
|
.D1 $ mandoc \-Wall,error \-fstrict mandoc.1 2\*(Gt&1 | less
|
|
.D1 $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
|
|
.Pp
|
|
To produce HTML manuals with
|
|
.Ar style.css
|
|
as the style-sheet:
|
|
.Pp
|
|
.D1 $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
|
|
.Pp
|
|
To check over a large set of manuals:
|
|
.Pp
|
|
.Dl $ mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
|
|
.Sh COMPATIBILITY
|
|
This section summarises
|
|
.Nm
|
|
compatibility with
|
|
.Xr groff 1 .
|
|
Each input and output format is separately noted.
|
|
.Ss ASCII Compatibility
|
|
.Bl -bullet -compact
|
|
.It
|
|
The
|
|
.Sq \e~
|
|
special character doesn't produce expected behaviour in
|
|
.Fl T Ns Cm ascii .
|
|
.It
|
|
The
|
|
.Sq \&Bd \-literal
|
|
and
|
|
.Sq \&Bd \-unfilled
|
|
macros of
|
|
.Xr mdoc 7
|
|
in
|
|
.Fl T Ns Cm ascii
|
|
are synonyms, as are \-filled and \-ragged.
|
|
.It
|
|
In
|
|
.Xr groff 1 ,
|
|
the
|
|
.Sq \&Pa
|
|
.Xr mdoc 7
|
|
macro does not underline when scoped under an
|
|
.Sq \&It
|
|
in the FILES section.
|
|
This behaves correctly in
|
|
.Nm .
|
|
.It
|
|
A list or display following the
|
|
.Sq \&Ss
|
|
.Xr mdoc 7
|
|
macro in
|
|
.Fl T Ns Cm ascii
|
|
does not assert a prior vertical break, just as it doesn't with
|
|
.Sq \&Sh .
|
|
.It
|
|
The
|
|
.Sq \&na
|
|
.Xr man 7
|
|
macro in
|
|
.Fl T Ns Cm ascii
|
|
has no effect.
|
|
.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 are reduced to a single space;
|
|
.Xr groff 1
|
|
retains spaces.
|
|
.It
|
|
Sentences are unilaterally monospaced.
|
|
.El
|
|
.Ss HTML/XHTML Compatibility
|
|
.Bl -bullet -compact
|
|
.It
|
|
The
|
|
.Sq \efP
|
|
escape will revert the font to the previous
|
|
.Sq \ef
|
|
escape, not to the last rendered decoration, which is now dictated by
|
|
CSS instead of hard-coded.
|
|
It also will not span past the current scope,
|
|
for the same reason.
|
|
Note that in
|
|
.Sx ASCII Output
|
|
mode, this will work fine.
|
|
.It
|
|
The
|
|
.Xr mdoc 7
|
|
.Sq \&Bl \-hang
|
|
and
|
|
.Sq \&Bl \-tag
|
|
list types render similarly (no break following overreached left-hand
|
|
side) due to the expressive constraints of HTML.
|
|
.It
|
|
The
|
|
.Xr man 7
|
|
.Sq IP
|
|
and
|
|
.Sq TP
|
|
lists render similarly.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr man 7 ,
|
|
.Xr mandoc_char 7 ,
|
|
.Xr mdoc 7
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
utility was written by
|
|
.An Kristaps Dzonsons Aq kristaps@bsd.lv .
|
|
.Sh CAVEATS
|
|
The
|
|
.Fl T Ns Cm html
|
|
and
|
|
.Fl T Ns Cm xhtml
|
|
CSS2 styling used for
|
|
.Fl m Ns Cm doc
|
|
input lists does not render properly in older browsers, such as Internet
|
|
Explorer 6 and earlier.
|
|
.Pp
|
|
In
|
|
.Fl T Ns Cm html
|
|
and
|
|
.Fl T Ns Cm xhtml ,
|
|
the maximum size of an element attribute is determined by
|
|
.Dv BUFSIZ ,
|
|
which is usually 1024 bytes.
|
|
Be aware of this when setting long link
|
|
formats such as
|
|
.Fl O Ns Cm style Ns = Ns Ar really/long/link .
|
|
.Pp
|
|
The
|
|
.Fl T Ns Cm html
|
|
and
|
|
.Fl T Ns Cm xhtml
|
|
output modes don't render the
|
|
.Sq \es
|
|
font size escape documented in
|
|
.Xr mdoc 7
|
|
and
|
|
.Xr man 7 .
|
|
.Pp
|
|
Nesting elements within next-line element scopes of
|
|
.Fl m Ns Cm an ,
|
|
such as
|
|
.Sq br
|
|
within an empty
|
|
.Sq B ,
|
|
will confuse
|
|
.Fl T Ns Cm html
|
|
and
|
|
.Fl T Ns Cm xhtml
|
|
and cause them to forget the formatting of the prior next-line scope.
|
|
.Pp
|
|
The
|
|
.Sq i
|
|
macro in
|
|
.Fl m Ns Cm an
|
|
should italicise all subsequent text if a line argument is not provided.
|
|
This behaviour is not implemented.
|
|
The
|
|
.Sq \(aq
|
|
control character is an alias for the standard macro control character
|
|
and does not emit a line-break as stipulated in GNU troff.
|