Annotation of mandoc/preconv.1, Revision 1.7
1.7 ! schwarze 1: .\" $Id: preconv.1,v 1.6 2011/12/25 19:35:44 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4: .\"
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.
8: .\"
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.
16: .\"
1.7 ! schwarze 17: .Dd $Mdocdate: December 25 2011 $
1.1 kristaps 18: .Dt PRECONV 1
19: .Os
20: .Sh NAME
21: .Nm preconv
1.2 kristaps 22: .Nd recode multibyte UNIX manuals
1.1 kristaps 23: .Sh SYNOPSIS
24: .Nm preconv
25: .Op Fl D Ar enc
26: .Op Fl e Ar enc
27: .Op Ar file
28: .Sh DESCRIPTION
29: The
30: .Nm
31: utility recodes multibyte
32: .Ux
33: manual files into
34: .Xr mandoc 1
1.2 kristaps 35: .Po
36: or other troff system supporting the
37: .Sq \e[uNNNN]
38: escape sequence
39: .Pc
1.1 kristaps 40: input.
1.6 kristaps 41: .Pp
42: By default, it parses from standard output, determining encoding as
43: described in
44: .Sx Algorithm .
45: .Pp
1.1 kristaps 46: Its arguments are as follows:
47: .Bl -tag -width Ds
48: .It Fl D Ar enc
49: The default encoding.
50: .It Fl e Ar enc
51: The document's encoding.
52: .It Ar file
53: The input file.
54: .El
1.3 kristaps 55: .Pp
56: The recoded input is written to standard output: Unicode characters in
57: the ASCII range are printed as regular ASCII characters, while those
58: above this range are printed using the
1.1 kristaps 59: .Sq \e[uNNNN]
60: format documented in
61: .Xr mandoc_char 7 .
62: .Pp
63: If input bytes are improperly formed in the current encoding, they're
64: passed unmodified to standard output.
1.3 kristaps 65: For some encodings, such as UTF-8, unrecoverable input sequences will
66: cause
1.1 kristaps 67: .Nm
1.3 kristaps 68: to stop processing and exit.
1.1 kristaps 69: .Ss Algorithm
70: An encoding is chosen according to the following steps:
71: .Bl -enum
72: .It
73: From the argument passed to
74: .Fl e Ar enc .
75: .It
1.3 kristaps 76: If a BOM exists, UTF\-8 encoding is selected.
77: .It
78: From the coding tags parsed from
79: .Qq File Variables
80: on the first two lines of input.
81: A file variable is an input line of the form
82: .Pp
83: .Dl \%.\e\(dq -*- key: val [; key: val ]* -*-
84: .Pp
1.4 kristaps 85: A coding tag variable is where
1.3 kristaps 86: .Cm key
87: is
88: .Qq coding
89: and
90: .Cm val
91: is the name of the encoding.
1.4 kristaps 92: A typical file variable with a coding tag is
1.3 kristaps 93: .Pp
94: .Dl \%.\e\(dq -*- mode: troff; coding: utf-8 -*-
1.1 kristaps 95: .It
96: From the argument passed to
97: .Fl D Ar enc .
98: .It
99: If all else fails, Latin\-1 is used.
100: .El
1.3 kristaps 101: .Pp
102: The
103: .Nm
104: utility recognises the UTF\-8, us\-ascii, and latin\-1 encodings as
105: passed to the
106: .Fl e
107: and
108: .Fl D
109: arguments, or as coding tags.
110: Encodings are matched case-insensitively.
1.1 kristaps 111: .\" .Sh IMPLEMENTATION NOTES
112: .\" Not used in OpenBSD.
113: .\" .Sh RETURN VALUES
114: .\" For sections 2, 3, & 9 only.
115: .\" .Sh ENVIRONMENT
116: .\" For sections 1, 6, 7, & 8 only.
117: .\" .Sh FILES
118: .Sh EXIT STATUS
119: .Ex -std
1.3 kristaps 120: .Sh EXAMPLES
121: Explicitly page a UTF\-8 manual
122: .Pa foo.1
123: in the current locale:
124: .Pp
125: .Dl $ preconv \-e utf\-8 foo.1 | mandoc -Tlocale | less
1.1 kristaps 126: .\" .Sh DIAGNOSTICS
127: .\" For sections 1, 4, 6, 7, & 8 only.
128: .\" .Sh ERRORS
129: .\" For sections 2, 3, & 9 only.
130: .Sh SEE ALSO
131: .Xr mandoc 1 ,
132: .Xr mandoc_char 7
133: .Sh STANDARDS
134: The
135: .Nm
136: utility references the US-ASCII character set standard, ANSI_X3.4\-1968;
137: the Latin\-1 character set standard, ISO/IEC 8859\-1:1998; the UTF\-8
138: character set standard; and UCS (Unicode), ISO/IEC 10646.
139: .Sh HISTORY
140: The
141: .Nm
142: utility first appeared in the GNU troff
143: .Pq Dq groff
144: system in December 2005, authored by Tomohiro Kubota and Werner
145: Lemberg.
146: The implementation that is part of the
147: .Xr mandoc 1
148: utility appeared in May 2011.
149: .Sh AUTHORS
150: The
151: .Nm
152: utility was written by
1.7 ! schwarze 153: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.1 kristaps 154: .\" .Sh CAVEATS
155: .\" .Sh BUGS
156: .\" .Sh SECURITY CONSIDERATIONS
157: .\" Not used in OpenBSD.
CVSweb