scuffed-code/icu4c/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 IBM, Inc. and others.
.\"
.\" Manual page by Yves Arrouye <yves@realnames.com>.
.\"
.TH CONVRTRS.TXT 5 "12 October 2000" "ICU MANPAGE" "ICU @VERSION@ Manual"
.SH NAME
.B convrtrs.txt
\- ICU converters aliases file
.br
.B cnvalias.dat
\- 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 (8)
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 important: if a given name appears multiple times, the last one prevails.
Names of converters and aliases are compared without considering case; the
dash, underscore, and space characters 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 ::= { converter | comment }
converter ::= name [ tags ] { alias } [ comment ]
alias ::= name [ tags ]
tags ::= '{' { name } '}'
comment ::= '#' \fIanything\fP
.fi
.RE
.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.
Note that tags do not need to be declared, they are collected as they
appear.
Names appropriate for a given standard can be retrieved
programmatically by using the
.BR ucnv_getStandardName (3)
function.
.SH CAVEATS
The
.B convrtrs.txt
file is not directly read by ICU. It must be transformed into a binary
file by
.BR gencnval (5)
first. Also, depending on the way ICU was packaged, even the resulting
.B cnvalias.dat
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 IBM, Inc. and others.
.SH SEE ALSO
.BR gencnval (8),
.BR pkgdata (8)