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