Locale support. I'm checking this in to clean up fall-out in-tree, but

[mandoc.git] / mandoc.1

diff --git a/mandoc.1 b/mandoc.1
index b28b2d4ea6f53783b7a24051321b596601834441..de4b970d6b79d84a387dcf23e4eef1fefb334c9b 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.1,v 1.77 2010/08/20 01:02:07 schwarze Exp $
+.\"    $Id: mandoc.1,v 1.87 2011/05/17 22:32:45 kristaps Exp $

 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"


@@ -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: August 20 2010 $
+.Dd $Mdocdate: May 17 2011 $

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


@@ -158,14 +158,19 @@ utility accepts the following
 .Fl T
 arguments, which correspond to output modes:
 .Bl -tag -width Ds
 .Fl T
 arguments, which correspond to output modes:
 .Bl -tag -width Ds

+.It Fl T Ns Cm locale
+This option encodes output characters using the current
+.Xr locale 1
+configuration.
+See
+.Sx Locale Output .

 .It Fl T Ns Cm ascii
 .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
 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
 See
 .Sx HTML Output .
 .It Fl T Ns Cm lint


@@ -183,13 +188,23 @@ See
 .It Fl T Ns Cm tree
 Produce an indented parse tree.
 .It Fl T Ns Cm xhtml
 .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.
 See
 .Sx XHTML Output .
 .El
 .Pp
 If multiple input files are specified, these will be processed by the
 corresponding filter in-order.

+.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 ,


@@ -210,6 +225,9 @@ Emboldened characters are rendered as
 The special characters documented in
 .Xr mandoc_char 7
 are rendered best-effort in an ASCII equivalent.
 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.
 .Pp
 Output width is limited to 78 visible columns unless literal input lines
 exceed this limit.


@@ -228,16 +246,14 @@ Output produced by
 .Fl T Ns Cm html
 conforms to HTML-4.01 strict.
 .Pp
 .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
 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
 .Pp
 Special characters are rendered in decimal-encoded UTF-8.
 .Pp


@@ -376,14 +392,14 @@ output mode implies
 .Sh EXAMPLES
 To page manuals to the terminal:
 .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
 .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 check over a large set of manuals:
 .Pp


@@ -391,7 +407,7 @@ To check over a large set of manuals:
 .Pp
 To produce a series of PostScript manuals for A4 paper:
 .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
 .Sh DIAGNOSTICS
 Standard error messages reporting parsing errors are prefixed by
 .Pp


@@ -453,8 +469,8 @@ The
 .Nm
 utility may also print messages related to invalid command line arguments
 or operating system errors, for example when memory is exhausted or
 .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
 .Sh COMPATIBILITY
 This section summarises
 .Nm


@@ -463,6 +479,13 @@ Each input and output format is separately noted.
 .Ss ASCII Compatibility
 .Bl -bullet -compact
 .It
 .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
 The
 .Sq \&Bd \-literal
 and


@@ -473,7 +496,7 @@ in
 .Fl T Ns Cm ascii
 are synonyms, as are \-filled and \-ragged.
 .It
 .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
 .Sq \&Pa
 .Xr mdoc 7
 macro does not underline when scoped under an


@@ -498,8 +521,6 @@ macro in
 has no effect.
 .It
 Words aren't hyphenated.
 has no effect.
 .It
 Words aren't hyphenated.

-.It
-Sentences are unilaterally monospaced.

 .El
 .Ss HTML/XHTML Compatibility
 .Bl -bullet -compact
 .El
 .Ss HTML/XHTML Compatibility
 .Bl -bullet -compact


@@ -532,24 +553,18 @@ and
 lists render similarly.
 .El
 .Sh SEE ALSO
 lists render similarly.
 .El
 .Sh SEE ALSO

+.Xr eqn 7 ,

 .Xr man 7 ,
 .Xr mandoc_char 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
 .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
 In
 .Fl T Ns Cm html
 and


@@ -574,12 +589,6 @@ and
 and cause them to forget the formatting of the prior next-line scope.
 .Pp
 The
 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.
 .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.