.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "EOCONV 1"
.TH EOCONV 1 2024-05-02 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
eoconv \- Convert text files between various Esperanto encodings
.SH USAGE
.IX Header "USAGE"
eoconv [\-q] \-\-from=\fIencoding\fR \-\-to=\fIencoding\fR [\fIfile\fR ...]
.PP
.Vb 4
\& Options:
\&   \-\-from       specify input encoding (see below)
\&   \-\-to         specify output encoding (see below)
\&   \-q, \-\-quiet  suppress warnings
\&
\&   \-\-help       detailed help message
\&   \-\-man        full documentation
\&   \-\-version    display version information
\&
\& Valid encodings:
\&   post\-h post\-H post\-x post\-X post\-caret pre\-caret latex
\&   html\-hex html\-dec iso\-8859\-3 utf\-7 utf\-8 utf\-16 utf\-32
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBeoconv\fR will read the given input files (or stdin if no files are
specified) containing Esperanto text in the encoding specified by
\&\fB\-\-from\fR, and then output it in the encoding specified by \fB\-\-to\fR.
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-\-from=\fR\fIencoding\fR 17
.IX Item "--from=encoding"
Specify character encoding for input
.IP \fB\-\-to=\fR\fIencoding\fR 17
.IX Item "--to=encoding"
Specify character encoding for output
.IP "\fB\-q\fR \fB\-\-quiet\fR" 17
.IX Item "-q --quiet"
Suppress non-essential warning messages
.IP "\fB\-?\fR \fB\-\-help\fR" 17
.IX Item "-? --help"
Print a brief help message and exit.
.IP \fB\-\-man\fR 17
.IX Item "--man"
Print the manual page and exit.
.IP \fB\-\-version\fR 17
.IX Item "--version"
Print version information and exit.
.SS "CHARACTER ENCODINGS"
.IX Subsection "CHARACTER ENCODINGS"
.IP \fIpost-h\fR 17
.IX Item "post-h"
ASCII postfix h notation
.IP \fIpost-H\fR 17
.IX Item "post-H"
ASCII postfix H notation
.IP \fIpost-x\fR 17
.IX Item "post-x"
ASCII postfix x notation
.IP \fIpost-X\fR 17
.IX Item "post-X"
ASCII postfix X notation
.IP \fIpost-caret\fR 17
.IX Item "post-caret"
ASCII postfix caret (^) notation
.IP \fIpre-caret\fR 17
.IX Item "pre-caret"
ASCII prefix caret (^) notation
.IP "\fIlatex\fR, \fILaTeX\fR" 17
.IX Item "latex, LaTeX"
ASCII LaTeX sequences
.IP "\fIhtml-hex\fR, \fIHTML-hex\fR" 17
.IX Item "html-hex, HTML-hex"
ASCII HTML hexadecimal entities
.IP "\fIhtml-dec\fR, \fIHTML-dec\fR" 17
.IX Item "html-dec, HTML-dec"
ASCII HTML decimal entities
.IP "\fIiso\-8859\-3\fR, \fIISO\-8859\-3\fR, \fIlatin3\fR, \fIlatin\-3\fR, \fILatin3\fR, \fILatin\-3\fR" 17
.IX Item "iso-8859-3, ISO-8859-3, latin3, latin-3, Latin3, Latin-3"
ISO\-8859\-3
.IP "\fIutf\-7\fR, \fIUTF\-7\fR, \fIutf7\fR, \fIUTF7\fR" 17
.IX Item "utf-7, UTF-7, utf7, UTF7"
Unicode UTF\-7
.IP "\fIutf\-8\fR, \fIUTF\-8\fR, \fIutf8\fR, \fIUTF8\fR" 17
.IX Item "utf-8, UTF-8, utf8, UTF8"
Unicode UTF\-8
.IP "\fIutf\-16\fR, \fIUTF\-16\fR, \fIutf16\fR, \fIUTF16\fR" 17
.IX Item "utf-16, UTF-16, utf16, UTF16"
Unicode UTF\-16
.IP "\fIutf\-32\fR, \fIUTF\-32\fR, \fIutf32\fR, \fIUTF32\fR" 17
.IX Item "utf-32, UTF-32, utf32, UTF32"
Unicode UTF\-32
.SH "ESPERANTO ORTHOGRAPHY"
.IX Header "ESPERANTO ORTHOGRAPHY"
Esperanto is written in an alphabet of 28 letters.  However, only 22
of these letters can be found in the standard ASCII character set.
The remaining six \-\- `c', `g', `h', `j', and `s' with circumflex, and
`u' with breve \-\- are not available in ASCII; neither are they among
the characters available in the common 8\-bit ISO\-8859\-1 character
encoding.  Therefore, while the six special Esperanto characters pose
no problem for handwritten texts, they were impossible to represent on
standard typewriters, and are somewhat problematic even on modern-day
computers.  Various encoding systems have been developed to represent
Esperanto text in printed and typed text.
.SS "POSTFIX-h NOTATION"
.IX Subsection "POSTFIX-h NOTATION"
This was the solution proposed by the creator of Esperanto,
L. L. Zamenhof.  He recommended using `u' for `u\-breve' and appending
an `h' to a letter to indicate that it should have a circumflex.
However, the letters `u' and `h' are already part of the Esperanto
alphabet, so using them for another purpose invites ambiguity and
mispronunciation.  It also makes conversion of Esperanto text to
postfix-h notation `lossy' or one-way; it is generally not possible to
convert from postfix-h notation via automated means.  This notation
suffers from the additional drawback that the text cannot be sorted
with standard rules for ASCII text.
.SS "POSTFIX-H NOTATION"
.IX Subsection "POSTFIX-H NOTATION"
This is the same as postfix-h notation, except that `H' is used
instead of `h' following a capital letter.
.SS "POSTFIX-x NOTATION"
.IX Subsection "POSTFIX-x NOTATION"
This is the most common ASCII notation encountered today.  It involves
appending an `x' to a letter to indicate that it should have an accent
(be it circumflex or breve).  Since `x' is not a letter in the
Esperanto alphabet, no ambiguity results.  However, ASCII sorting
algorithms still fail with postfix-x text.
.SS "POSTFIX-X NOTATION"
.IX Subsection "POSTFIX-X NOTATION"
This is the same as postfix-x notation, except that `X' is used
instead of `x' following a capital letter.
.SS "PREFIX\- AND POSTFIX-CARET NOTATION"
.IX Subsection "PREFIX- AND POSTFIX-CARET NOTATION"
Two slightly less popular ASCII encodings are to prepend or append a
caret (`^') to a letter to indicate that it should have an accent.
.SS "ISO\-8859\-3 (LATIN\-3)"
.IX Subsection "ISO-8859-3 (LATIN-3)"
ISO 8859\-3, also known as Latin\-3 or South European, is an 8\-bit
character encoding for Esperanto.  High-bit characters are used to
encode the accented Esperanto letters.  ISO\-8859\-3 can also be used
for encoding English, Finnish, German, Italian, Latin, Maltese,
Turkish, and Portuguese, making it useful for texts which mix
Esperanto with one or more of these languages.
.SS "UNICODE (ISO/IEC 10646)"
.IX Subsection "UNICODE (ISO/IEC 10646)"
Unicode is a standard for matching every character of every human
language to a specific code.  The mapping methods are known as Unicode
Transformation Formats (UTF). Among them are UTF\-32, UTF\-16, UTF\-8 and
UTF\-7, where the numbers indicate the number of bits in one unit.
.SS "LaTeX SEQUENCES"
.IX Subsection "LaTeX SEQUENCES"
The popular LaTeX typesetting package is capable of representing
virtually any accented character.  Note that conversion from LaTeX
sequences assumes that characters to be accented are enclosed in
braces \-\- for example, `\e^{C}' will be recognized as `C' with
circumflex, but `\e^C' will not be.
.SS "HTML ENTITIES"
.IX Subsection "HTML ENTITIES"
Unicode codes for Esperanto characters can be escaped in HTML
documents by using HTML entities.  The codes can be represented in
either decimal (base\-10) or hexadecimal (base\-16) notation; the two
are functionally equivalent.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
Because the postfix-h and postfix-H notations are inherently
ambiguous, conversion from postfix-h or \-H text is unlikely to result
in coherent text.  Use at your own risk, and carefully proofread the
results.
.PP
Report bugs to <psychonaut@nothingisreal.com>.
.SH AUTHOR
.IX Header "AUTHOR"
Tristan Miller <psychonaut@nothingisreal.com>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBcharsets\fR\|(7), \fBascii\fR\|(7), \fBiso_8859\-3\fR\|(7), \fBunicode\fR\|(7), \fButf\-8\fR\|(7), \fBlatex\fR\|(1)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (C) 2004\-2016 Tristan Miller.
.PP
Permission is granted to make and distribute verbatim or modified
copies of this manual provided the copyright notice and this
permission notice are preserved on all copies.