.TH 2UTF 1 "14 April 1998" Linux "User Manuals"
.SH NAME
2UTF, fromUTF \- translates char-sets to/from 
.BR unicode (7),
decodes MIME messages
.SH SYNOPSIS
.RB [ 2UTF | fromUTF ]
.RI [ options ] " " [ charmap_file_or_alias ]
.BI < input " >" output
.SH DESCRIPTION
.LP
.B 	2UTF
is a filter which converts char-sets to
.BR unicode (7)
(UCS - Universal Character Set) and reverse if
possible. It can also display char-maps,
console font and a range of
.BR unicode (7)
glyphs in
.BR utf\-8 (7)
encoding.
It gets char-map for single-byte char-sets from
.B locales
or
.B wg15-locale
package database, from tables found at
.B ftp://ftp.unicode.org/
or other similar files with user defined format.
It can invoke external filters specified in configuration file.
.PD 0
.PP
.I 	charmap_file_or_alias
is pathname, alias or filename for the file with char-map definition.
Alias or filename
is converted to uppercase. Aliases specified in
.B locales
char-maps
are cached in special file if directory/file permissions allow this.
If exact match for alias or filename isn't found,
.I *alias*
or
.I *filename*
glob pattern is used (except for aliases found in configuration file).
.PP
.B 	\-
(hyphen-minus) and
.B _
(low line, spacing underscore) characters in aliases are ignored.
.PP
	When invoked without char-map specified a mail message is assumed
on standard input. I do
.I not
provide any warranty and recommend you to backup your mail if you use
.B
2UTF
as automatic mail filter. See
.I procmailrc
file in
.I examples
subdirectory. It should handle common
text and multi-part types, MIME style encrypted and not 8-bit headers. Everything
is converted to
.BR utf\-8 (7)
encoding.
Messages with MIME style
.BR pgp (1)
signatures should be passed untouched.
.PD 1
.SH OPTIONS
.TP
.B \-\-
stops option checking for the rest of the command line.
.TP
.B \-2 "" \-\-UCS\-2 "" \-\-ucs\-2
output (input if
.B \-\-reverse
specified) 2 byte wide characters.
.TP
.B \-4 "" \-\-UCS\-4 "" \-\-ucs\-4
output (input if
.B \-\-reverse
specified) 4 byte wide characters.
.TP
.B \-8 "" \-\-UTF\-8 "" \-\-utf\-8
.B (default)
output (input if
.B \-\-reverse
specified) multi-byte
.BR utf\-8 (7)
characters.
.TP
.BI \-c FILENAME " " " "  \-\-charmap\-file= FILENAME 
the alternative way to specify filename or pathname for char-map file.
.TP
.B \-C "" \-\-create\-aliases
rescans all available char-map files and (re)creates aliases file.
You should have write permission for this file.
.TP
\fB\-d\fR[\fIN\fR] \fB\-\-debug\fR[\fB=\fIN\fR]\fP
Outputs debugging info to stderr. Implies
.BR --verbose .
.I N
is debug level from 1 to 9. Default is 1.
.TP
\fB\-f\fR[\fIFORMAT\fR]  \fB\-\-format\fR[\fB=\fIFORMAT\fR]\fP
.BR sscanf (3)
format string for reading char-map file. If not specified the default format as output by
.B 2UTF \-h
(used by char-maps from
.B WG15
locales) is assumed. Aliases specified in locale char-map files are recognized.
Lines beginning with
.B %
or
.B #
and lines not matching format
are ignored. In case of duplicated lines the last line takes precedence.
" 0x%x 0x%X "
.BR sscanf (3)
format string is always assumed
for char-map files ending in
.IR .TXT ,
.I .X
or
.IR .x .
This corresponds to char-maps you can get from
.BR ftp://ftp.unicode.org.
.TP
.B \-o "" \-\-forward
.B (default)
converts *to* 
.BR unicode (7)
if invoked as
.BR 2UTF,
and tries convert *from*
.BR unicode (7)
if invoked as
.BR fromUTF.
.TP
.B \-H "" \-\-HTML \-\-html
This aplies to approximations when converting from
.BR unicode (7).
Special HTML characters appearing after approximations are changed
to &lt; &gt; &quot; and &amp;.
.TP
.B \-h "" \-? "" \-\-? "" \-\-help "" \-help
Prints the program's version number, default parameters,
and a short usage message to the program's standard error output and exits.
.TP
.B \-hp "" \-\-help=pathnames
Prints pathnames for configuration file, default compiled-in directories for
char-map files, actually used directories for char-map files,
pathname for aliases cache.
.TP
.B \-l "" \-\-list-charmaps
Lists char-maps and aliases currently in aliases database, then exits.
This includes only char-maps usable by
.BR 2UTF . 
.TP
.B \-r "" \-\-reverse
tries convert back *from*
.BR unicode (7)
if invoked as
.BR 2UTF,
and converts *to* 
.BR unicode (7)
if invoked as
.BR fromUTF.
.TP
.B \-W "" \-\-show\-charmap
outputs table of char-map characters in
.BR utf\-8 (7)
encoding. 
.B .
(period) is substituted for 0x0000-0x001F and 0x007F.
.B ?
(question mark) is substituted for undefined characters.
.TP
.B \-S "" \-\-spit\-glyphs
outputs table of characters in
.BR utf\-8 (7)
encoding at F000-F1FF
.BR unicode (7)
private use area. This corresponds to current console font in Linux.
.TP
\fB\-S\fR[\fImin\fR]\fR[\fB\-\fR]\fR[\fImax\fR]  \fB\-\-spit\-glyphs\fB=\fR[\fImin\fR]\fR[\fB\-\fR]\fR[\fImax\fR]
outputs table of characters in
.BR utf\-8 (7)
encoding at given range.
.I min
and
.I max
is
.BR unicode (7)
hex numbers from 0 to 7FFFFFFF.
.I min
defaults to 0.
.I max
defaults to
.I min
+ 511 if
.B \-
is present.
.TP
.B \-s "" \-\-switch\-to\-UTF\-8
tries to switch to
.BR utf\-8 (7)
mode by writing <ESC>%G to the program's standard error output. Use
.B echo -ne '\\\033%@'
to switch back if required. This is Linux console escape sequences.
.TP
\fB\-u\fR[\fIX\fR] \fB\-\-unknown\-char\fR[\fB=\fIX\fR]\fP
substitute
.I X
for unknown single byte characters and errors.
If
.I X
isn't specified the default
character as output by
.B 2UTF \-h
is assumed.
.I X
can be a single character, hex (0x80), octal (0200) or
decimal (128) number. This can be usefull when translating
to single-byte encoding.
.TP
.B \-v "" \-\-verbose
verbose mode.
.TP
.B \-V "" \-\-version
shows program's version and some copyright information.
.PP
	Rightmost option or alias takes precedence. Long options may be abbreviated. Short options may be grouped.
.LP
Default
.BR unicode (7)
character for errors and unknown characters is 0xFFFD.
Approximations can be performed if conversion is from Unicode to single-byte
char-sets. US-ASCII strings up to 4 bytes length is substituted for characters
undefined in the output charset. These strings are defined at the compile time.
.SH EXAMPLES
.PP
	To view ISO_8859-3:1988 document use:
.PP
.BI "2UTF --verbose --switch-to-UTF-8 8859-3 <" document " | less -r"
.PP
	To translate from CP1257 to BALTIC (ISO-IR-179) use:
.PP
.BI "2UTF -2 1257 <" cp1257_file " | fromUTF -2 baltic >" baltic_charset_file
.PP
	To call a BBS using 869 "code page" use:
.PP
.B minicom -l -t linux |2UTF --switch-to-UTF-8 IBM869
.PP
	See also
.I examples
subdirectory.
.SH FILES
There can be self-explanatory configuration file
.IR 2UTF.config .
It is searched in /usr/local/etc/, /usr/etc/, /etc/ or other directories
defined at compile time. It can specify directory names for char-map files
and external filters for conversion to and from multi-byte char-sets and
encodings.

.SH "SEE ALSO"
.BR 2UTF (1),
.BR unicode (7),
.BR utf\-8 (7),
.BR tcs (1),
.B recode
info page
.PP
.B Yudit
editor and converter at
.B http://sunsite.unc.edu/pub/Linux/Incoming
or
.B http://sunsite.unc.edu/pub/Linux/apps/editors/X/
.PP
.B ftp://ftp.cnd.org/pub/ifcss.org/software/unix/convert/
.PP
.RB ` trans '
program at
.B ftp://ftp.funet.fi/pub/doc/charsets/
.PP
.BR console_codes (4),
.BR charsets (4)
.PP
Look at
.B ftp://dkuug.dk/i18n/WG15-collection/charmaps/
and
.B ftp://ftp.unicode.org/
for char-map files.
.SH BUG REPORTS
.PD 0
.PP
	Bug reports, comments and suggestions please send to:
./" .RS
.PP
.B Ricardas Cepas <rch@pub.osf.lt>
or
.B <rch@WriteMe.Com>
.PD 1
.SH BUGS
.PD 0
.PP
Due to the
.BR popen (3)
bug in Linux libc inexistent commands in configuration file are not detected.
So please check configuration file by hand.
.PP
Transformation from UTF-8 can be slow.
.PP
If char-map files you are using are incomplete characters can be lost.
.PP
Reverse transformation is not perfect.
.PP
See also
.I TODO
file.
.PP
Please use at
.B your own risk.

.SH COPYING
	This program (including this man page) is distributed under
.B BSD style license
(see
.I BSD_style_license
file in the documentation directory)
or
.B GNU General Public License V2
except
.IR hdr.h ", " plan9.h " and " utf.c
files (if used) from
.BR tcs (1),
public domain code from
.I mimedecode.c
file. Copyright statements should be
keeped unchanged.
.PP
	For the copyright information see file
.IR copyright .