Annotation of mandoc/preconv.1, Revision 1.2
1.2 ! kristaps 1: .\" $Id: preconv.1,v 1.1 2011/05/26 12:01:14 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.2 ! kristaps 17: .Dd $Mdocdate: May 26 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.
41: Its arguments are as follows:
42: .Bl -tag -width Ds
43: .It Fl D Ar enc
44: The default encoding.
45: This is case-insensitive.
46: See
47: .Sx Algorithm
48: and
49: .Sx Encodings .
50: .It Fl e Ar enc
51: The document's encoding.
52: This is case-insensitive.
53: See
54: .Sx Algorithm
55: and
56: .Sx Encodings .
57: .It Ar file
58: The input file.
59: .El
60: .Pp
61: If
62: .Ar file
63: is not provided,
64: .Nm
65: accepts standard input.
66: Output is written to standard output.
67: Unicode characters in the ASCII range are printed as regular ASCII
68: characters; those above this range are printed using the
69: .Sq \e[uNNNN]
70: format documented in
71: .Xr mandoc_char 7 .
72: .Pp
73: If input bytes are improperly formed in the current encoding, they're
74: passed unmodified to standard output.
75: .Ss Encodings
76: The
77: .Nm
78: utility accepts the
79: .Ar utf\-8 ,
80: .Ar us\-ascii ,
81: and
82: .Ar latin\-1
83: encodings as arguments to
84: .Fl D Ar enc
85: or
86: .Fl e Ar enc .
87: .Ss Algorithm
88: An encoding is chosen according to the following steps:
89: .Bl -enum
90: .It
91: From the argument passed to
92: .Fl e Ar enc .
93: .It
94: If a BOM exists, utf\-8 encoding is selected.
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
101: .\" .Sh IMPLEMENTATION NOTES
102: .\" Not used in OpenBSD.
103: .\" .Sh RETURN VALUES
104: .\" For sections 2, 3, & 9 only.
105: .\" .Sh ENVIRONMENT
106: .\" For sections 1, 6, 7, & 8 only.
107: .\" .Sh FILES
108: .Sh EXIT STATUS
109: .Ex -std
110: .\" .Sh EXAMPLES
111: .\" .Sh DIAGNOSTICS
112: .\" For sections 1, 4, 6, 7, & 8 only.
113: .\" .Sh ERRORS
114: .\" For sections 2, 3, & 9 only.
115: .Sh SEE ALSO
116: .Xr mandoc 1 ,
117: .Xr mandoc_char 7
118: .Sh STANDARDS
119: The
120: .Nm
121: utility references the US-ASCII character set standard, ANSI_X3.4\-1968;
122: the Latin\-1 character set standard, ISO/IEC 8859\-1:1998; the UTF\-8
123: character set standard; and UCS (Unicode), ISO/IEC 10646.
124: .Sh HISTORY
125: The
126: .Nm
127: utility first appeared in the GNU troff
128: .Pq Dq groff
129: system in December 2005, authored by Tomohiro Kubota and Werner
130: Lemberg.
131: The implementation that is part of the
132: .Xr mandoc 1
133: utility appeared in May 2011.
134: .Sh AUTHORS
135: The
136: .Nm
137: utility was written by
138: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
139: .\" .Sh CAVEATS
140: .\" .Sh BUGS
141: .\" .Sh SECURITY CONSIDERATIONS
142: .\" Not used in OpenBSD.
CVSweb