mandoc: Simpler description of output formats, shortening the manual

mandoc: Simpler description of output formats, shortening the manual

[schwarze]

Log Message:
-----------
Simpler description of output formats, shortening the manual page by 15 lines.
Avoid the double redirection from -Tutf8 via -Tlocale to -Tascii.
Add LC_CTYPE to the ENVIRONMENT section.
While here, also correct a few inaccuracies and tweak some wordings.
Triggered by a question from Laura Morales <lauretas at mail dot com>.

Modified Files:
--------------
    mandoc:
        mandoc.1

Revision Data
-------------
Index: mandoc.1
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.1,v
retrieving revision 1.223
retrieving revision 1.224
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.223 -r1.224
--- mandoc.1
+++ mandoc.1
@@ -34,9 +34,7 @@
 .Sh DESCRIPTION
 The
 .Nm
-utility formats
-.Ux
-manual pages for display.
+utility formats manual pages for display.
 .Pp
 By default,
 .Nm
@@ -132,13 +130,32 @@ With other arguments,
 is silently ignored.
 .It Fl O Ar options
 Comma-separated output options.
+See the descriptions of the individual output formats for supported
+.Ar options .
 .It Fl T Ar output
-Output format.
-See
-.Sx Output Formats
-for available formats.
-Defaults to
-.Fl T Cm locale .
+Select the output format.
+Supported values for the
+.Ar output
+argument are
+.Cm ascii ,
+.Cm html ,
+the default of
+.Cm locale ,
+.Cm man ,
+.Cm markdown ,
+.Cm pdf ,
+.Cm ps ,
+.Cm tree ,
+and
+.Cm utf8 .
+.Pp
+The special
+.Fl T Cm lint
+mode only parses the input and produces no output.
+It implies
+.Fl W Cm all
+and redirects parser messages, which usually appear on standard
+error output, to standard output.
 .It Fl W Ar level
 Specify the minimum message
 .Ar level
@@ -196,11 +213,11 @@ and
 are requested, they can be joined with a comma, for example
 .Fl W Cm error , Ns Cm stop .
 .It Ar file
-Read input from zero or more files.
-If unspecified, reads from stdin.
-If multiple files are specified,
+Read from the given input file.
+If multiple files are specified, they are processed in the given order.
+If unspecified,
 .Nm
-will halt with the first failed parse.
+reads from standard input.
 .El
 .Pp
 The options
@@ -220,69 +237,14 @@ manual.
 The options
 .Fl fkl
 are mutually exclusive and override each other.
-.Ss Output Formats
-The
-.Nm
-utility accepts the following
-.Fl T
-arguments, which correspond to output modes:
-.Bl -tag -width "-T markdown"
-.It Fl T Cm ascii
-Produce 7-bit ASCII output.
-See
-.Sx ASCII Output .
-.It Fl T Cm html
-Produce HTML5, CSS1, and MathML output.
-See
-.Sx HTML Output .
-.It Fl T Cm lint
-Parse only: produce no output.
-Implies
-.Fl W Cm all
-and redirects parser messages, which usually appear
-on standard error output, to standard output.
-.It Fl T Cm locale
-Encode output using the current locale.
-This is the default.
-See
-.Sx Locale Output .
-.It Fl T Cm man
-Produce
-.Xr man 7
-format output.
-See
-.Sx Man Output .
-.It Fl T Cm markdown
-Produce output in
-.Sy markdown
-format.
-See
-.Sx Markdown Output .
-.It Fl T Cm pdf
-Produce PDF output.
-See
-.Sx PDF Output .
-.It Fl T Cm ps
-Produce PostScript output.
-See
-.Sx PostScript Output .
-.It Fl T Cm tree
-Produce an indented parse tree.
-See
-.Sx Syntax tree output .
-.It Fl T Cm utf8
-Encode output in the UTF\-8 multi-byte format.
-See
-.Sx UTF\-8 Output .
-.El
-.Pp
-If multiple input files are specified, these will be processed by the
-corresponding filter in-order.
 .Ss ASCII Output
-Output produced by
+Use
 .Fl T Cm ascii
-is rendered in standard 7-bit ASCII documented in
-.Xr ascii 7 .
+to force text output in 7-bit ASCII character encoding documented in the
+.Xr ascii 7
+manual page, ignoring the
+.Xr locale 1
+set in the environment.
 .Pp
 Font styles are applied by using back-spaced encoding such that an
 underlined character
@@ -356,7 +318,8 @@ defaults to simple output (via an embedd
 readable in any graphical or text-based web
 browser.
 .Pp
-Special characters are rendered in decimal-encoded UTF\-8.
+Non-ASCII characters are rendered
+as decimal numeric Unicode character references.
 .Pp
 The following
 .Fl O
@@ -406,19 +369,28 @@ This must be a valid absolute or
 relative URI.
 .El
 .Ss Locale Output
-Locale-depending output encoding is triggered with
+By default,
+.Nm
+automatically selects UTF-8 or ASCII output according to the current
+.Xr locale 1 .
+If any of the environment variables
+.Ev LC_ALL ,
+.Ev LC_CTYPE ,
+or
+.Ev LANG
+are set and the first one that is set
+selects the UTF-8 character encoding, it produces
+.Sx UTF-8 Output ;
+otherwise, it falls back to
+.Sx ASCII Output .
+This output mode can also be selected explicitly with
 .Fl T Cm locale .
-This is the default.
-.Pp
-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 Cm ascii .
-See
-.Sx ASCII Output
-for font style specification and available command-line arguments.
 .Ss Man Output
-Translate input format into
+Use
+.Fl T Cm man
+to translate
+.Xr mdoc 7
+input into
 .Xr man 7
 output format.
 This is useful for distributing manual sources to legacy systems
@@ -426,11 +398,7 @@ 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
+If the input format of a file is
 .Xr man 7 ,
 the input is copied to the output, expanding any
 .Xr roff 7
@@ -442,11 +410,11 @@ level controls which
 .Sx DIAGNOSTICS
 are displayed before copying the input to the output.
 .Ss Markdown Output
-Translate
+Use
+.Fl T Cm markdown
+to translate
 .Xr mdoc 7
-input to the
-.Sy markdown
-format conforming to
+input to the markdown format conforming to
 .Lk http://daringfireball.net/projects/markdown/syntax.text\
  "John Gruber's 2004 specification" .
 The output also almost conforms to the
@@ -517,13 +485,24 @@ If an unknown value is encountered,
 .Ar letter
 is used.
 .El
-.Ss UTF\-8 Output
+.Ss UTF-8 Output
 Use
 .Fl T Cm utf8
-to force a UTF\-8 locale.
+to force text output in UTF-8 multi-byte character encoding,
+ignoring the
+.Xr locale 1
+settings in the environment.
 See
-.Sx Locale Output
-for details and options.
+.Sx ASCII Output
+regarding font styles and
+.Fl O
+arguments.
+.Pp
+On operating systems lacking locale or wide character support, and
+on those where the internal character representation is not UCS-4,
+.Nm
+always falls back to
+.Sx ASCII Output .
 .Ss Syntax tree output
 Use
 .Fl T Cm tree
@@ -592,6 +571,13 @@ Meta data is not available in this case.
 .El
 .Sh ENVIRONMENT
 .Bl -tag -width MANPAGER
+.It Ev LC_CTYPE
+The character encoding
+.Xr locale 1 .
+When
+.Sx Locale Output
+is selected, it decides whether to use ASCII or UTF-8 output format.
+It never affects the interpretation of input files.
 .It Ev MANPAGER
 Any non-empty value of the environment variable
 .Ev MANPAGER
--
 To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv