[apple/icu.git] / icuSources / tools / icupkg / icupkg.8.in

.\" Hey, Emacs! This is -*-nroff-*- you know...
.\"
.\" icupkg.8: manual page for the icupkg utility
.\"
.\" Copyright (C) 2016 and later: Unicode, Inc. and others.
.\" License & terms of use: http://www.unicode.org/copyright.html
.\" Copyright (C) 2000-2006 IBM, Inc. and others.
.\"
.TH ICUPKG 8 "18 August 2006" "ICU MANPAGE" "ICU @VERSION@ Manual"
.SH NAME
.B icupkg
\- extract or modify an ICU
.B .dat
archive
.SH SYNOPSIS
.B icupkg
[
.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
]
[
.BR "\-tl\fP, \fB\-\-type" " l"
|
.BR "\-tb\fP, \fB\-\-type" " b"
|
.BR "\-te\fP, \fB\-\-type" " e"
]
[
.BR "\-c\fP, \fB\-\-copyright"
|
.BI "\-C\fP, \fB\-\-comment" " comment"
]
[
.BI "\-a\fP, \fB\-\-add" " list"
]
[
.BI "\-r\fP, \fB\-\-remove" " list"
]
[
.BI "\-x\fP, \fB\-\-extract" " list"
]
[
.BI "\-l\fP, \fB\-\-list"
]
[
.BI "\-s\fP, \fB\-\-sourcedir" " source"
]
[
.BI "\-d\fP, \fB\-\-destdir" " destination"
]
[
.BI "\-w\fP, \fB\-\-writepkg"
]
[
.BI "\-m\fP, \fB\-\-matchmode" " mode"
]
.IR infilename
[
.BI "outfilename"
]
.SH DESCRIPTION
.B icupkg
reads the input ICU
.B .dat
package file, modify it according to the options,
swap it to the desired platform properties (charset & endianness),
and optionally write the resulting ICU
.B .dat
package to the output file.
Items are removed, then added, then extracted and listed.
An ICU
.B .dat
package is written if items are removed or added,
or if the input and output filenames differ,
or if the
.BR "\-w\fP, \fB\-\-writepkg"
option is set.
.PP
If the input filename is "new" then an empty package is created.
If the output filename is missing, then it is automatically generated
from the input filename. If the input filename ends with an l, b, or e
matching its platform properties, then the output filename will
contain the letter from the
.BI "\-t\fP, \fB\-\-type"
option.
.PP
This tool can also be used to just swap a single ICU data file, replacing the
former icuswap tool. For this mode, provide the infilename (and optional
outfilename) for a non-package ICU data file.
Allowed options include
.BI "\-t\fP, \fB\-w\fP, \fB\-s\fP"
and
.BI \-d
.
The filenames can be absolute, or relative to the source/dest dir paths.
Other options are not allowed in this mode.
.SH OPTIONS
.TP
.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
Print help about usage and exit.
.TP
.BI "\-tl\fP, \fB\-\-type" " l"
Output for little-endian/ASCII charset family.
The output type defaults to the input type.
.TP
.BI "\-tb\fP, \fB\-\-type" " b"
Output for big-endian/ASCII charset family.
The output type defaults to the input type.
.TP
.BI "\-te\fP, \fB\-\-type" " e"
Output for big-endian/EBCDIC charset family.
The output type defaults to the input type.
.TP
.BR \-c\fP, \fB\-\-copyright
Include the ICU copyright notice in the resulting data.
.TP
.BI "\-C\fP, \fB\-\-comment" " comment"
Include the specified
.I comment
in the resulting data instead of the ICU copyright notice. 
.TP
.BI "\-a\fP, \fB\-\-add" " list"
Add items from the
.I list
to the package. The list can be a single filename with a
.B .txt
file extension containing a list of item filenames, or an ICU
.B .dat
package filename.
.TP
.BI "\-r\fP, \fB\-\-remove" " list"
Remove items from the
.I list
from the package. The list can be a single filename with a
.B .txt
file extension containing a list of item filenames, or an ICU
.B .dat
package filename.
.TP
.BI "\-x\fP, \fB\-\-extract" " list"
Extract items from the
.I list
from the package. The list can be a single filename with a
.B .txt
file extension containing a list of item filenames, or an ICU
.B .dat
package filename.
.TP
.BI "\-m\fP, \fB\-\-matchmode" " mode"
Set the matching mode for item names with wildcards.
.TP
.BI "\-s\fP, \fB\-\-sourcedir" " source"
Set the source directory to
.IR source .
The default source directory is the current directory.
.TP
.BI "\-d\fP, \fB\-\-destdir" " destination"
Set the destination directory to
.IR destination .
The default destination directory is the current directory.
.TP
.BI "\-l\fP, \fB\-\-list"
List the package items to stdout (after modifying the package).
.SH LIST FILE SYNTAX
Items are listed on one or more lines and separated by whitespace (space+tab).
Comments begin with
.B #
and are ignored. Empty lines are ignored. Lines where the first non-whitespace
character is one of "%&'()*+,-./:;<=>?_ are also ignored
to reserve for future syntax.
.PP
Items for removal or extraction may contain a single 
.B *
wildcard character. The 
.B *
matches zero or more characters. If
.BI "\-m\fP, \fB\-\-matchmode" " noslash"
is set, then the
.B *
character does not match the
.B /
character.
.PP
Items must be listed relative to the package, and the
.B "\fB\-\-sourcedir"
or the
.B "\fB\-\-destdir"
path will be prepended. The paths are only prepended to item
filenames while adding or extracting items, not to ICU .dat package or list
filenames.
.PP
Paths may contain
.B /
instead of the platform's file separator character and are converted as
appropriate.
.SH AUTHORS
Markus Scherer
.br
George Rhoten
.SH VERSION
1.0
.SH COPYRIGHT
Copyright (C) 2006 IBM, Inc. and others.
.SH SEE ALSO
.BR pkgdata (1)
.BR genrb (1)
Commit	Line	Data
73c04bcf A	1	.\" Hey, Emacs! This is --nroff-- you know...
	2	.\"
	3	.\" icupkg.8: manual page for the icupkg utility
	4	.\"
f3c0d7a5 A	5	.\" Copyright (C) 2016 and later: Unicode, Inc. and others.
f3c0d7a5 A	6	.\" License & terms of use: http://www.unicode.org/copyright.html
73c04bcf A	7	.\" Copyright (C) 2000-2006 IBM, Inc. and others.
	8	.\"
	9	.TH ICUPKG 8 "18 August 2006" "ICU MANPAGE" "ICU @VERSION@ Manual"
	10	.SH NAME
	11	.B icupkg
	12	\- extract or modify an ICU
	13	.B .dat
	14	archive
	15	.SH SYNOPSIS
	16	.B icupkg
	17	[
	18	.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
	19	]
	20	[
	21	.BR "\-tl\fP, \fB\-\-type" " l"
	22	\|
	23	.BR "\-tb\fP, \fB\-\-type" " b"
	24	\|
	25	.BR "\-te\fP, \fB\-\-type" " e"
	26	]
	27	[
	28	.BR "\-c\fP, \fB\-\-copyright"
	29	\|
	30	.BI "\-C\fP, \fB\-\-comment" " comment"
	31	]
	32	[
	33	.BI "\-a\fP, \fB\-\-add" " list"
	34	]
	35	[
	36	.BI "\-r\fP, \fB\-\-remove" " list"
	37	]
	38	[
	39	.BI "\-x\fP, \fB\-\-extract" " list"
	40	]
	41	[
	42	.BI "\-l\fP, \fB\-\-list"
	43	]
	44	[
	45	.BI "\-s\fP, \fB\-\-sourcedir" " source"
	46	]
	47	[
	48	.BI "\-d\fP, \fB\-\-destdir" " destination"
	49	]
	50	[
	51	.BI "\-w\fP, \fB\-\-writepkg"
	52	]
	53	[
	54	.BI "\-m\fP, \fB\-\-matchmode" " mode"
	55	]
	56	.IR infilename
	57	[
	58	.BI "outfilename"
	59	]
	60	.SH DESCRIPTION
	61	.B icupkg
	62	reads the input ICU
	63	.B .dat
	64	package file, modify it according to the options,
	65	swap it to the desired platform properties (charset & endianness),
	66	and optionally write the resulting ICU
	67	.B .dat
	68	package to the output file.
	69	Items are removed, then added, then extracted and listed.
	70	An ICU
71	.B .dat
72	package is written if items are removed or added,
73	or if the input and output filenames differ,
74	or if the
75	.BR "\-w\fP, \fB\-\-writepkg"
76	option is set.
77	.PP
78	If the input filename is "new" then an empty package is created.
79	If the output filename is missing, then it is automatically generated
80	from the input filename. If the input filename ends with an l, b, or e
81	matching its platform properties, then the output filename will
82	contain the letter from the
83	.BI "\-t\fP, \fB\-\-type"
84	option.
85	.PP
86	This tool can also be used to just swap a single ICU data file, replacing the
87	former icuswap tool. For this mode, provide the infilename (and optional
88	outfilename) for a non-package ICU data file.
89	Allowed options include
90	.BI "\-t\fP, \fB\-w\fP, \fB\-s\fP"
91	and
92	.BI \-d
93	.
94	The filenames can be absolute, or relative to the source/dest dir paths.
95	Other options are not allowed in this mode.
96	.SH OPTIONS
97	.TP
98	.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
99	Print help about usage and exit.
100	.TP
101	.BI "\-tl\fP, \fB\-\-type" " l"
102	Output for little-endian/ASCII charset family.
103	The output type defaults to the input type.
104	.TP
105	.BI "\-tb\fP, \fB\-\-type" " b"
106	Output for big-endian/ASCII charset family.
107	The output type defaults to the input type.
108	.TP
109	.BI "\-te\fP, \fB\-\-type" " e"
110	Output for big-endian/EBCDIC charset family.
111	The output type defaults to the input type.
112	.TP
113	.BR \-c\fP, \fB\-\-copyright
114	Include the ICU copyright notice in the resulting data.
115	.TP
116	.BI "\-C\fP, \fB\-\-comment" " comment"
117	Include the specified
118	.I comment
119	in the resulting data instead of the ICU copyright notice.
120	.TP
121	.BI "\-a\fP, \fB\-\-add" " list"
122	Add items from the
123	.I list
124	to the package. The list can be a single filename with a
125	.B .txt
126	file extension containing a list of item filenames, or an ICU
127	.B .dat
128	package filename.
129	.TP
130	.BI "\-r\fP, \fB\-\-remove" " list"
131	Remove items from the
132	.I list
133	from the package. The list can be a single filename with a
134	.B .txt
135	file extension containing a list of item filenames, or an ICU
136	.B .dat
137	package filename.
138	.TP
139	.BI "\-x\fP, \fB\-\-extract" " list"
140	Extract items from the
141	.I list
142	from the package. The list can be a single filename with a
143	.B .txt
144	file extension containing a list of item filenames, or an ICU
145	.B .dat
146	package filename.
147	.TP
148	.BI "\-m\fP, \fB\-\-matchmode" " mode"
149	Set the matching mode for item names with wildcards.
150	.TP
151	.BI "\-s\fP, \fB\-\-sourcedir" " source"
152	Set the source directory to
153	.IR source .
154	The default source directory is the current directory.
155	.TP
156	.BI "\-d\fP, \fB\-\-destdir" " destination"
157	Set the destination directory to
158	.IR destination .
159	The default destination directory is the current directory.
160	.TP
161	.BI "\-l\fP, \fB\-\-list"
162	List the package items to stdout (after modifying the package).
163	.SH LIST FILE SYNTAX
164	Items are listed on one or more lines and separated by whitespace (space+tab).
165	Comments begin with
166	.B #
167	and are ignored. Empty lines are ignored. Lines where the first non-whitespace
168	character is one of "%&'()*+,-./:;<=>?_ are also ignored
169	to reserve for future syntax.
170	.PP
171	Items for removal or extraction may contain a single
172	.B *
173	wildcard character. The
174	.B *
175	matches zero or more characters. If
176	.BI "\-m\fP, \fB\-\-matchmode" " noslash"
177	is set, then the
178	.B *
179	character does not match the
180	.B /
181	character.
182	.PP
183	Items must be listed relative to the package, and the
184	.B "\fB\-\-sourcedir"
185	or the
186	.B "\fB\-\-destdir"
187	path will be prepended. The paths are only prepended to item
188	filenames while adding or extracting items, not to ICU .dat package or list
189	filenames.
190	.PP
191	Paths may contain
192	.B /
193	instead of the platform's file separator character and are converted as
194	appropriate.
195	.SH AUTHORS
196	Markus Scherer
197	.br
198	George Rhoten
199	.SH VERSION
200	1.0
201	.SH COPYRIGHT
202	Copyright (C) 2006 IBM, Inc. and others.
203	.SH SEE ALSO
204	.BR pkgdata (1)
205	.BR genrb (1)
206