[apple/icu.git] / icuSources / tools / makeconv / makeconv.1.in

.\" Hey, Emacs! This is -*-nroff-*- you know...
.\"
.\" makeconv.1: manual page for the makeconv utility
.\"
.\" Copyright (C) 2000-2002 IBM, Inc. and others.
.\"
.\" Manual page by Yves Arrouye <yves@realnames.com>.
.\"
.TH MAKECONV 1 "16 April 2002" "ICU MANPAGE" "ICU @VERSION@ Manual"
.SH NAME
.B makeconv
\- compile a converter table
.SH SYNOPSIS
.B makeconv
[
.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
]
[
.BR "\-c\fP, \fB\-\-copyright"
]
[
.BR "\-v\fP, \fB\-\-verbose"
]
[
.BI "\-d\fP, \fB\-\-destdir" " destination"
]
.IR convertertable " .\|.\|."
.SH DESCRIPTION
.B makeconv
converts the ICU converter table
.I convertertable
into a binary file. The binary file has the same base name as
.I convertertable
but has a
.B .cnv
extension (instead of the typical
.B .ucm
extension of the
.I convertertable
file).
This binary file can then be read directly by ICU, or used by
.BR pkgdata (1)
for incorporation into a larger archive or library.
.PP
The
.I convertertable
must be in the ICU ucm (Unicode Codepage Mapping) format in order to
be understood by
.BR makeconv .
The ICU ucm format is similar to the IBM NLTC upmap/tpmap/rpmap files.
Comments in the
.I convertable
are handled as follows. If a comment (starting with a `#' sign) that
is after some text does contain the fallback indicator `|' then only
the text starting with the `#' sign, and ending before the `|' sign,
is ignored.
Otherwise, or if the comment is the first thing on the line,
the comment runs up to the end of the line. This special
handling of comments is to accomodate the practice of putting fallback
information in comments in the strict IBM NLTC ucmap format.
.PP
Note that new converters will be automatically found by ICU after their
installation in ICU's data directory. They do not need to
be listed in the
.BR convrtrs.txt (5)
converters aliases file in order to be available to applications using ICU.
They do need to be listed there if one wants to give them aliases, or
tags, though.
.SH OPTIONS
.TP
.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
Print help about usage and exit.
.TP
.BR "\-c\fP, \fB\-\-copyright"
Include a copyright notice in the binary data.
.TP
.BR "\-v\fP, \fB\-\-verbose"
Display extra informative messages during execution.
.TP
.BI "\-d\fP, \fB\-\-destdir" " destination"
Set the destination directory to
.IR destination .
The default destination directory is specified by the environment variable
.BR ICU_DATA .
.SH CAVEATS
If an existing converter table is changed and recompiled using
.BR makeconv ,
the resulting binary file must be packaged in the same way that it was
packaged initially. For example, if converters were grouped together in
an archive or a library with
.BR pkgdata (1),
then the archive or library must be rebuilt with the new binary file.
A standalone binary converter file will not take precedence over a
packaged one.
.SH ENVIRONMENT
.TP 10
.B ICU_DATA
Specifies the directory containing ICU data. Defaults to
.BR @thepkgicudatadir@/@PACKAGE@/@VERSION@/ .
Some tools in ICU depend on the presence of the trailing slash. It is thus
important to make sure that it is present if
.B ICU_DATA
is set.
.SH VERSION
@VERSION@
.SH COPYRIGHT
Copyright (C) 2000 IBM, Inc. and others.
.SH SEE ALSO
.BR convrtrs.txt (5) 
.br
.BR pkgdata (1)
Commit	Line	Data
b75a7d8f A	1	.\" Hey, Emacs! This is --nroff-- you know...
	2	.\"
	3	.\" makeconv.1: manual page for the makeconv utility
	4	.\"
	5	.\" Copyright (C) 2000-2002 IBM, Inc. and others.
	6	.\"
	7	.\" Manual page by Yves Arrouye <yves@realnames.com>.
	8	.\"
	9	.TH MAKECONV 1 "16 April 2002" "ICU MANPAGE" "ICU @VERSION@ Manual"
	10	.SH NAME
	11	.B makeconv
	12	\- compile a converter table
	13	.SH SYNOPSIS
	14	.B makeconv
	15	[
	16	.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
	17	]
	18	[
	19	.BR "\-c\fP, \fB\-\-copyright"
	20	]
	21	[
	22	.BR "\-v\fP, \fB\-\-verbose"
	23	]
	24	[
	25	.BI "\-d\fP, \fB\-\-destdir" " destination"
	26	]
	27	.IR convertertable " .\\|.\\|."
	28	.SH DESCRIPTION
	29	.B makeconv
	30	converts the ICU converter table
	31	.I convertertable
	32	into a binary file. The binary file has the same base name as
	33	.I convertertable
	34	but has a
	35	.B .cnv
	36	extension (instead of the typical
	37	.B .ucm
	38	extension of the
	39	.I convertertable
	40	file).
	41	This binary file can then be read directly by ICU, or used by
	42	.BR pkgdata (1)
	43	for incorporation into a larger archive or library.
	44	.PP
	45	The
	46	.I convertertable
	47	must be in the ICU ucm (Unicode Codepage Mapping) format in order to
	48	be understood by
	49	.BR makeconv .
	50	The ICU ucm format is similar to the IBM NLTC upmap/tpmap/rpmap files.
	51	Comments in the
	52	.I convertable
	53	are handled as follows. If a comment (starting with a `#' sign) that
	54	is after some text does contain the fallback indicator `\|' then only
	55	the text starting with the `#' sign, and ending before the `\|' sign,
	56	is ignored.
	57	Otherwise, or if the comment is the first thing on the line,
	58	the comment runs up to the end of the line. This special
	59	handling of comments is to accomodate the practice of putting fallback
	60	information in comments in the strict IBM NLTC ucmap format.
	61	.PP
	62	Note that new converters will be automatically found by ICU after their
	63	installation in ICU's data directory. They do not need to
	64	be listed in the
65	.BR convrtrs.txt (5)
66	converters aliases file in order to be available to applications using ICU.
67	They do need to be listed there if one wants to give them aliases, or
68	tags, though.
69	.SH OPTIONS
70	.TP
71	.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
72	Print help about usage and exit.
73	.TP
74	.BR "\-c\fP, \fB\-\-copyright"
75	Include a copyright notice in the binary data.
76	.TP
77	.BR "\-v\fP, \fB\-\-verbose"
78	Display extra informative messages during execution.
79	.TP
80	.BI "\-d\fP, \fB\-\-destdir" " destination"
81	Set the destination directory to
82	.IR destination .
83	The default destination directory is specified by the environment variable
84	.BR ICU_DATA .
85	.SH CAVEATS
86	If an existing converter table is changed and recompiled using
87	.BR makeconv ,
88	the resulting binary file must be packaged in the same way that it was
89	packaged initially. For example, if converters were grouped together in
90	an archive or a library with
91	.BR pkgdata (1),
92	then the archive or library must be rebuilt with the new binary file.
93	A standalone binary converter file will not take precedence over a
94	packaged one.
95	.SH ENVIRONMENT
96	.TP 10
97	.B ICU_DATA
98	Specifies the directory containing ICU data. Defaults to
99	.BR @thepkgicudatadir@/@PACKAGE@/@VERSION@/ .
100	Some tools in ICU depend on the presence of the trailing slash. It is thus
101	important to make sure that it is present if
102	.B ICU_DATA
103	is set.
104	.SH VERSION
105	@VERSION@
106	.SH COPYRIGHT
107	Copyright (C) 2000 IBM, Inc. and others.
108	.SH SEE ALSO
109	.BR convrtrs.txt (5)
110	.br
111	.BR pkgdata (1)
112