mdocml/dist/preconv.1

.\"	Id: preconv.1,v 1.7 2013/07/13 19:41:16 schwarze Exp
.\"
.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd July 13, 2013
.Dt PRECONV 1
.Os
.Sh NAME
.Nm preconv
.Nd recode multibyte UNIX manuals
.Sh SYNOPSIS
.Nm preconv
.Op Fl D Ar enc
.Op Fl e Ar enc
.Op Ar file
.Sh DESCRIPTION
The
.Nm
utility recodes multibyte
.Ux
manual files into
.Xr mandoc 1
.Po
or other troff system supporting the
.Sq \e[uNNNN]
escape sequence
.Pc
input.
.Pp
By default, it parses from standard output, determining encoding as
described in
.Sx Algorithm .
.Pp
Its arguments are as follows:
.Bl -tag -width Ds
.It Fl D Ar enc
The default encoding.
.It Fl e Ar enc
The document's encoding.
.It Ar file
The input file.
.El
.Pp
The recoded input is written to standard output: Unicode characters in
the ASCII range are printed as regular ASCII characters, while those
above this range are printed using the
.Sq \e[uNNNN]
format documented in
.Xr mandoc_char 7 .
.Pp
If input bytes are improperly formed in the current encoding, they're
passed unmodified to standard output.
For some encodings, such as UTF-8, unrecoverable input sequences will
cause
.Nm
to stop processing and exit.
.Ss Algorithm
An encoding is chosen according to the following steps:
.Bl -enum
.It
From the argument passed to
.Fl e Ar enc .
.It
If a BOM exists, UTF\-8 encoding is selected.
.It
From the coding tags parsed from
.Qq File Variables
on the first two lines of input.
A file variable is an input line of the form
.Pp
.Dl \%.\e\(dq -*- key: val [; key: val ]* -*-
.Pp
A coding tag variable is where
.Cm key
is
.Qq coding
and
.Cm val
is the name of the encoding.
A typical file variable with a coding tag is
.Pp
.Dl \%.\e\(dq -*- mode: troff; coding: utf-8 -*-
.It
From the argument passed to
.Fl D Ar enc .
.It
If all else fails, Latin\-1 is used.
.El
.Pp
The
.Nm
utility recognises the UTF\-8, us\-ascii, and latin\-1 encodings as
passed to the
.Fl e
and
.Fl D
arguments, or as coding tags.
Encodings are matched case-insensitively.
.\" .Sh IMPLEMENTATION NOTES
.\" Not used in OpenBSD.
.\" .Sh RETURN VALUES
.\" For sections 2, 3, & 9 only.
.\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, & 8 only.
.\" .Sh FILES
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Explicitly page a UTF\-8 manual
.Pa foo.1
in the current locale:
.Pp
.Dl $ preconv \-e utf\-8 foo.1 | mandoc -Tlocale | less
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, & 8 only.
.\" .Sh ERRORS
.\" For sections 2, 3, & 9 only.
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr mandoc_char 7
.Sh STANDARDS
The
.Nm
utility references the US-ASCII character set standard, ANSI_X3.4\-1968;
the Latin\-1 character set standard, ISO/IEC 8859\-1:1998; the UTF\-8
character set standard; and UCS (Unicode), ISO/IEC 10646.
.Sh HISTORY
The
.Nm
utility first appeared in the GNU troff
.Pq Dq groff
system in December 2005, authored by Tomohiro Kubota and Werner
Lemberg.
The implementation that is part of the
.Xr mandoc 1
utility appeared in May 2011.
.Sh AUTHORS
The
.Nm
utility was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
.\" .Sh CAVEATS
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS
.\" Not used in OpenBSD.