-.\" $Id: mandoc.1,v 1.77 2010/08/20 01:02:07 schwarze Exp $
+.\" $Id: mandoc.1,v 1.88 2011/05/20 15:51:18 kristaps Exp $
.\"
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" 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 20 2010 $
+.Dd $Mdocdate: May 20 2011 $
.Dt MANDOC 1
.Os
.Sh NAME
.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
+.Xr UTF-8 Output .
+.It Fl T Ns Cm locale
+Encode output using the current
+.Xr locale 1 .
+See
+.Sx Locale Output .
.It Fl T Ns Cm ascii
-Produce 7-bit ASCII output, backspace-encoded for bold and underline
-styles.
+Produce 7-bit ASCII output.
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.
+Produce strict CSS1/HTML-4.01 output.
See
.Sx HTML Output .
.It Fl T Ns Cm lint
.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.
+Produce strict CSS1/XHTML-1.0 output.
See
.Sx XHTML Output .
.El
.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 ,
The special characters documented in
.Xr mandoc_char 7
are rendered best-effort in an ASCII equivalent.
+If no equivalent is found,
+.Sq \&?
+is used instead.
.Pp
Output width is limited to 78 visible columns unless literal input lines
exceed this limit.
.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 .
+file documents style-sheet classes available for customising output.
+If a style-sheet is not specified with
+.Fl O Ns Ar style ,
+.Fl T Ns Cm html
+defaults to simple output readable in any graphical or text-based web
+browser.
.Pp
Special characters are rendered in decimal-encoded UTF-8.
.Pp
.Sh EXAMPLES
To page manuals to the terminal:
.Pp
-.D1 $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
-.D1 $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
+.Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
+.Dl $ 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
+.Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
.Pp
To check over a large set of manuals:
.Pp
.Pp
To produce a series of PostScript manuals for A4 paper:
.Pp
-.D1 $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
+.Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
.Sh DIAGNOSTICS
Standard error messages reporting parsing errors are prefixed by
.Pp
.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.
+input files cannot be read.
+Such messages do not carry the prefix described above.
.Sh COMPATIBILITY
This section summarises
.Nm
.Ss ASCII Compatibility
.Bl -bullet -compact
.It
+Unrenderable unicode codepoints specified with
+.Sq \e[uNNNN]
+escapes are printed as
+.Sq \&?
+in mandoc.
+In GNU troff, these raise an error.
+.It
The
.Sq \&Bd \-literal
and
.Fl T Ns Cm ascii
are synonyms, as are \-filled and \-ragged.
.It
-In GNU troff, the
+In historic GNU troff, the
.Sq \&Pa
.Xr mdoc 7
macro does not underline when scoped under an
has no effect.
.It
Words aren't hyphenated.
-.It
-Sentences are unilaterally monospaced.
.El
.Ss HTML/XHTML Compatibility
.Bl -bullet -compact
lists render similarly.
.El
.Sh SEE ALSO
+.Xr eqn 7 ,
.Xr man 7 ,
.Xr mandoc_char 7 ,
-.Xr mdoc 7
+.Xr mdoc 7 ,
+.Xr roff 7 ,
+.Xr tbl 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
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.
git.ckatri.com / mandoc.git / blobdiff