source/tools/gencnval/convrtrs.txt.5.in

.\" Hey, Emacs! This is -*-nroff-*- you know...
.\"
.\" convrtrs.txt.5: manual page for the convrtrs.txt file
.\"
.\" Copyright (C) 2000-2002 IBM, Inc. and others.
.\"
.\" Manual page by Yves Arrouye <yves@realnames.com>.
.\"
.TH CONVRTRS.TXT 5 "22 July 2002" "ICU MANPAGE" "ICU @VERSION@ Manual"
.SH NAME
.B convrtrs.txt
\- ICU converters aliases file
.br
.B cnvalias.icu
\- binary ICU converters aliases file
.SH DESCRIPTION
The file
.B convrtrs.txt
lists the names of the converters that ICU can handle, along with
their known aliases. ICU can open a converter given either its real name or
any of its aliases.
.B convrtrs.txt
is read by
.BR gencnval (1)
in order to generate the binary data that ICU uses to represent the converters
aliases information.
.PP
Each converter and its aliases are described on a separate lines; fields
on each line are separated by white space. The order of records in
.B convrtrs.txt
is significant: if a given name appears multiple times, the last one prevails.
Names of converters and aliases are compared without considering case; the
characters dash (U+002D HYPHEN-MINUS), underscore (U+005F LOW LINE), and
space (U+0020 SPACE) are also ignored during comparison
(even though spaces cannot be used in
.B convrtrs.txt
since white space is significant as a field delimiter).
Thus the names
.BR UTF-8 ,
.BR utf_8 ,
and
.BR "Utf 8"
are equivalent converters names.
.PP
The format of
.B convrtrs.txt
can be described by the following BNF grammar:
.PP
.RS
.nf
converters ::= tags { converter }
converter ::= name [ tags ] { alias }
alias ::= name [ tags ]
tags ::= '{' { tag } '}'
tag ::= standard{*}
comment ::= '#' \fIanything\fP
.fi
.RE
.PP
Line continuation and comment sytax are similar to the GNU make syntax.
Any lines beginning with whitespace (e.g. U+0020 SPACE or U+0009 HORIZONTAL
TABULATION) are presumed to be a continuation of the previous line.
.PP
The file must start with a list of recognized tags. These tags are used to
get the correct converter implementation based on the defined standard tag.
For instance, Shift-JIS on an IBM platform may be different from Shift-JIS
on a Windows platform.
.PP
A
.I name
can use any character other than white space and the '{' and '#' delimiters.
In practice, names are usually restricted to the set of uppercase and
lowercase latin letters plus arabic digits, the dash, the underscore,
and the colon characters. It is recommended to follow this convention
when naming new converters or their aliases.
.PP
A
.I comment
starts with the pound character '#' and ends with the current
line. Comments are ignored.
.PP
The
.I name
of a given
.I converter
must match its algorithmic name if the converter is algorithmic, or
its file name if the converter is table-driven. The table for the
converter
.B ibm-912
for example, is expected to be in the
.B ibm-912.cnv
file.
An
.I alias
has no such restriction, as aliases are just arbitrary names
associated to a given converter.
.PP
The presence of a
.I tag
after a converter or alias name means that this name is associated to
a given standard set of names. Two well-known such standards are the
.B MIME
and
.B IANA
registries of names. The default ICU
.B convrtrs.txt
file already uses these tags.
These tags must be declared at the beginning of the file.
Names appropriate for a given standard can be retrieved
programmatically by using the ucnv_getStandardName() or the
ucnv_openStandardNames() function. The asterisk (U+002A) is
used to note which standard name is the default, and the
preceding alias is returned by ucnv_getStandardName(). A standard
tag may have multiple aliases recognized by the same standard for
the same converter name.
.SH CAVEATS
The
.B convrtrs.txt
file is not directly read by ICU. It must be transformed into a binary
file by
.BR gencnval (1)
first. Also, depending on the way ICU was packaged, even the resulting
.B cnvalias.icu
file may not be read by ICU. Please refer to the ICU manual for more
information on which files are effectively read by ICU at runtime, and
how to produce them.
.SH COPYRIGHT
Copyright (C) 2000-2002 IBM, Inc. and others.
.SH SEE ALSO
.BR gencnval (1),
.BR pkgdata (1)