1 .\" $Id: preconv.1,v 1.5 2011/08/18 08:58:44 kristaps Exp $
3 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .Dd $Mdocdate: August 18 2011 $
22 .Nd recode multibyte UNIX manuals
31 utility recodes multibyte
36 or other troff system supporting the
41 Its arguments are as follows:
46 The document's encoding.
55 accepts standard input.
60 The recoded input is written to standard output: Unicode characters in
61 the ASCII range are printed as regular ASCII characters, while those
62 above this range are printed using the
67 If input bytes are improperly formed in the current encoding, they're
68 passed unmodified to standard output.
69 For some encodings, such as UTF-8, unrecoverable input sequences will
72 to stop processing and exit.
74 An encoding is chosen according to the following steps:
77 From the argument passed to
80 If a BOM exists, UTF\-8 encoding is selected.
82 From the coding tags parsed from
84 on the first two lines of input.
85 A file variable is an input line of the form
87 .Dl \%.\e\(dq -*- key: val [; key: val ]* -*-
89 A coding tag variable is where
95 is the name of the encoding.
96 A typical file variable with a coding tag is
98 .Dl \%.\e\(dq -*- mode: troff; coding: utf-8 -*-
100 From the argument passed to
103 If all else fails, Latin\-1 is used.
108 utility recognises the UTF\-8, us\-ascii, and latin\-1 encodings as
113 arguments, or as coding tags.
114 Encodings are matched case-insensitively.
115 .\" .Sh IMPLEMENTATION NOTES
116 .\" Not used in OpenBSD.
117 .\" .Sh RETURN VALUES
118 .\" For sections 2, 3, & 9 only.
120 .\" For sections 1, 6, 7, & 8 only.
125 Explicitly page a UTF\-8 manual
127 in the current locale:
129 .Dl $ preconv \-e utf\-8 foo.1 | mandoc -Tlocale | less
131 .\" For sections 1, 4, 6, 7, & 8 only.
133 .\" For sections 2, 3, & 9 only.
140 utility references the US-ASCII character set standard, ANSI_X3.4\-1968;
141 the Latin\-1 character set standard, ISO/IEC 8859\-1:1998; the UTF\-8
142 character set standard; and UCS (Unicode), ISO/IEC 10646.
146 utility first appeared in the GNU troff
148 system in December 2005, authored by Tomohiro Kubota and Werner
150 The implementation that is part of the
152 utility appeared in May 2011.
156 utility was written by
157 .An Kristaps Dzonsons ,
158 .Mt kristaps@bsd.lv .
161 .\" .Sh SECURITY CONSIDERATIONS
162 .\" Not used in OpenBSD.