typo; noticed by jmc@ some time ago

[mandoc.git] / preconv.1

diff --git a/preconv.1 b/preconv.1
index 266cbc7c2cc6151512b42f2495a4f0e2b4de1702..8daee30854d969c1882c524c1d49288f0db2e189 100644 (file)
--- a/preconv.1
+++ b/preconv.1
@@ -1,4 +1,4 @@
-.\"    $Id: preconv.1,v 1.2 2011/05/26 12:14:46 kristaps Exp $
+.\"    $Id: preconv.1,v 1.7 2013/07/13 19:41:16 schwarze Exp $

 .\"
 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\"
 .\" Copyright (c) 2011 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: May 26 2011 $
+.Dd $Mdocdate: July 13 2013 $

 .Dt PRECONV 1
 .Os
 .Sh NAME
 .Dt PRECONV 1
 .Os
 .Sh NAME


@@ -38,52 +38,34 @@ or other troff system supporting the
 escape sequence
 .Pc
 input.
 escape sequence
 .Pc
 input.

+.Pp
+By default, it parses from standard output, determining encoding as
+described in
+.Sx Algorithm .
+.Pp

 Its arguments are as follows:
 .Bl -tag -width Ds
 .It Fl D Ar enc
 The default encoding.
 Its arguments are as follows:
 .Bl -tag -width Ds
 .It Fl D Ar enc
 The default encoding.

-This is case-insensitive.
-See
-.Sx Algorithm
-and
-.Sx Encodings .

 .It Fl e Ar enc
 The document's encoding.
 .It Fl e Ar enc
 The document's encoding.

-This is case-insensitive.
-See
-.Sx Algorithm
-and
-.Sx Encodings .

 .It Ar file
 The input file.
 .El
 .Pp
 .It Ar file
 The input file.
 .El
 .Pp

-If
-.Ar file
-is not provided,
-.Nm
-accepts standard input.
-Output is written to standard output.
-Unicode characters in the ASCII range are printed as regular ASCII
-characters; those above this range are printed using the
+The recoded input is written to standard output: Unicode characters in
+the ASCII range are printed as regular ASCII characters, while those
+above this range are printed using the

 .Sq \e[uNNNN]
 format documented in
 .Xr mandoc_char 7 .
 .Pp
 If input bytes are improperly formed in the current encoding, they're
 passed unmodified to standard output.
 .Sq \e[uNNNN]
 format documented in
 .Xr mandoc_char 7 .
 .Pp
 If input bytes are improperly formed in the current encoding, they're
 passed unmodified to standard output.

-.Ss Encodings
-The
+For some encodings, such as UTF-8, unrecoverable input sequences will
+cause

 .Nm
 .Nm

-utility accepts the
-.Ar utf\-8 ,
-.Ar us\-ascii ,
-and
-.Ar latin\-1
-encodings as arguments to
-.Fl D Ar enc
-or
-.Fl e Ar enc .
+to stop processing and exit.

 .Ss Algorithm
 An encoding is chosen according to the following steps:
 .Bl -enum
 .Ss Algorithm
 An encoding is chosen according to the following steps:
 .Bl -enum


@@ -91,13 +73,41 @@ An encoding is chosen according to the following steps:
 From the argument passed to
 .Fl e Ar enc .
 .It
 From the argument passed to
 .Fl e Ar enc .
 .It

-If a BOM exists, utf\-8 encoding is selected.
+If a BOM exists, UTF\-8 encoding is selected.
+.It
+From the coding tags parsed from
+.Qq File Variables
+on the first two lines of input.
+A file variable is an input line of the form
+.Pp
+.Dl \%.\e\(dq -*- key: val [; key: val ]* -*-
+.Pp
+A coding tag variable is where
+.Cm key
+is
+.Qq coding
+and
+.Cm val
+is the name of the encoding.
+A typical file variable with a coding tag is
+.Pp
+.Dl \%.\e\(dq -*- mode: troff; coding: utf-8 -*-

 .It
 From the argument passed to
 .Fl D Ar enc .
 .It
 If all else fails, Latin\-1 is used.
 .El
 .It
 From the argument passed to
 .Fl D Ar enc .
 .It
 If all else fails, Latin\-1 is used.
 .El

+.Pp
+The
+.Nm
+utility recognises the UTF\-8, us\-ascii, and latin\-1 encodings as
+passed to the
+.Fl e
+and
+.Fl D
+arguments, or as coding tags.
+Encodings are matched case-insensitively.

 .\" .Sh IMPLEMENTATION NOTES
 .\" Not used in OpenBSD.
 .\" .Sh RETURN VALUES
 .\" .Sh IMPLEMENTATION NOTES
 .\" Not used in OpenBSD.
 .\" .Sh RETURN VALUES


@@ -107,7 +117,12 @@ If all else fails, Latin\-1 is used.
 .\" .Sh FILES
 .Sh EXIT STATUS
 .Ex -std
 .\" .Sh FILES
 .Sh EXIT STATUS
 .Ex -std

-.\" .Sh EXAMPLES
+.Sh EXAMPLES
+Explicitly page a UTF\-8 manual
+.Pa foo.1
+in the current locale:
+.Pp
+.Dl $ preconv \-e utf\-8 foo.1 | mandoc -Tlocale | less

 .\" .Sh DIAGNOSTICS
 .\" For sections 1, 4, 6, 7, & 8 only.
 .\" .Sh ERRORS
 .\" .Sh DIAGNOSTICS
 .\" For sections 1, 4, 6, 7, & 8 only.
 .\" .Sh ERRORS


@@ -135,7 +150,7 @@ utility appeared in May 2011.
 The
 .Nm
 utility was written by
 The
 .Nm
 utility was written by

-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

 .\" .Sh CAVEATS
 .\" .Sh BUGS
 .\" .Sh SECURITY CONSIDERATIONS
 .\" .Sh CAVEATS
 .\" .Sh BUGS
 .\" .Sh SECURITY CONSIDERATIONS