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