1c95a5650c01c4650c3260c1fba5b6daa48b5b1e
[dragonfly.git] / usr.bin / colldef / colldef.1
1 .\" Copyright (c) 1995 Alex Tatmanjants <alex@elvisti.kiev.ua>
2 .\"             at Electronni Visti IA, Kiev, Ukraine.
3 .\"                     All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\"    notice, this list of conditions and the following disclaimer in the
12 .\"    documentation and/or other materials provided with the distribution.
13 .\"
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 .\" SUCH DAMAGE.
25 .\"
26 .\" $FreeBSD: head/usr.bin/colldef/colldef.1 213573 2010-10-08 12:40:16Z uqs $
27 .\"
28 .Dd January 27, 1995
29 .Dt COLLDEF 1
30 .Os
31 .Sh NAME
32 .Nm colldef
33 .Nd convert collation sequence source definition
34 .Sh SYNOPSIS
35 .Nm
36 .Op Fl I Ar map_dir
37 .Op Fl o Ar out_file
38 .Op Ar filename
39 .Sh DESCRIPTION
40 The
41 .Nm
42 utility converts a collation sequence source definition
43 into a format usable by the
44 .Fn strxfrm
45 and
46 .Fn strcoll
47 functions.
48 It is used to define the many ways in which
49 strings can be ordered and collated.
50 The
51 .Fn strxfrm
52 function transforms
53 its first argument and places the result in its second
54 argument.
55 The transformed string is such that it can be
56 correctly ordered with other transformed strings by using
57 .Fn strcmp ,
58 .Fn strncmp ,
59 or
60 .Fn memcmp .
61 The
62 .Fn strcoll
63 function transforms its arguments and does a
64 comparison.
65 .Pp
66 The
67 .Nm
68 utility reads the collation sequence source definition
69 from the standard input and stores the converted definition in filename.
70 The output file produced contains the
71 database with collating sequence information in a form
72 usable by system commands and routines.
73 .Pp
74 The following options are available:
75 .Bl -tag -width indent
76 .It Fl I Ar map_dir
77 Set directory name where
78 .Ar charmap
79 files can be found, current directory by default.
80 .It Fl o Ar out_file
81 Set output file name,
82 .Ar LC_COLLATE
83 by default.
84 .El
85 .Pp
86 The collation sequence definition specifies a set of collating elements and
87 the rules defining how strings containing these should be ordered.
88 This is most useful for different language definitions.
89 .Pp
90 The specification file can consist of three statements:
91 .Ar charmap ,
92 .Ar substitute
93 and
94 .Ar order .
95 .Pp
96 Of these, only the
97 .Ar order
98 statement is required.
99 When
100 .Ar charmap
101 or
102 .Ar substitute
103 is
104 supplied, these statements must be ordered as above.
105 Any
106 statements after the order statement are ignored.
107 .Pp
108 Lines in the specification file beginning with a
109 .Ql #
110 are
111 treated as comments and are ignored.
112 Blank lines are also
113 ignored.
114 .Pp
115 .Dl "charmap charmapfile"
116 .Pp
117 .Ar Charmap
118 defines where a mapping of the character
119 and collating element symbols to the actual
120 character encoding can be found.
121 .Pp
122 The format of
123 .Ar charmapfile
124 is shown below.
125 Symbol
126 names are separated from their values by TAB or
127 SPACE characters.
128 Symbol-value can be specified in
129 a hexadecimal (\ex\fI??\fR) or octal (\e\fI???\fR)
130 representation, and can be only one character in length.
131 .Bd -literal -offset indent
132 symbol-name1 symbol-value1
133 symbol-name2 symbol-value2
134 \&...
135 .Ed
136 .Pp
137 Symbol names cannot be specified in
138 .Ar substitute
139 fields.
140 .Pp
141 The
142 .Ar charmap
143 statement is optional.
144 .Bd -literal -offset indent
145 substitute "symbol" with "repl_string"
146 .Ed
147 .Pp
148 The
149 .Ar substitute
150 statement substitutes the character
151 .Ar symbol
152 with the string
153 .Ar repl_string .
154 Symbol names cannot be specified in
155 .Ar repl_string
156 field.
157 The
158 .Ar substitute
159 statement is optional.
160 .Pp
161 .Dl "order order_list"
162 .Pp
163 .Ar Order_list
164 is a list of symbols, separated by semi colons, that defines the
165 collating sequence.
166 The
167 special symbol
168 .Ar ...
169 specifies, in a short-hand
170 form, symbols that are sequential in machine code
171 order.
172 .Pp
173 An order list element
174 can be represented in any one of the following
175 ways:
176 .Bl -bullet
177 .It
178 The symbol itself (for example,
179 .Ar a
180 for the lower-case letter
181 .Ar a ) .
182 .It
183 The symbol in octal representation (for example,
184 .Ar \e141
185 for the letter
186 .Ar a ) .
187 .It
188 The symbol in hexadecimal representation (for example,
189 .Ar \ex61
190 for the letter
191 .Ar a ) .
192 .It
193 The symbol name as defined in the
194 .Ar charmap
195 file (for example,
196 .Ar <letterA>
197 for
198 .Ar letterA \e023
199 record in
200 .Ar charmapfile ) .
201 If character map name have
202 .Ar >
203 character, it must be escaped as
204 .Ar /> ,
205 single
206 .Ar /
207 must be escaped as
208 .Ar // .
209 .It
210 Symbols
211 .Ar \ea ,
212 .Ar \eb ,
213 .Ar \ef ,
214 .Ar \en ,
215 .Ar \er ,
216 .Ar \ev
217 are permitted in its usual C-language meaning.
218 .It
219 The symbol chain (for example:
220 .Ar abc ,
221 .Ar <letterA><letterB>c ,
222 .Ar \exf1b\exf2 )
223 .It
224 The symbol range (for example,
225 .Ar a;...;z ) .
226 .It
227 Comma-separated symbols, ranges and chains enclosed in parenthesis (for example
228 .Ar \&(
229 .Ar sym1 ,
230 .Ar sym2 ,
231 .Ar ...
232 .Ar \&) )
233 are assigned the
234 same primary ordering but different secondary
235 ordering.
236 .It
237 Comma-separated symbols, ranges and chains enclosed in curly brackets (for example
238 .Ar \&{
239 .Ar sym1 ,
240 .Ar sym2 ,
241 .Ar ...
242 .Ar \&} )
243 are assigned the same primary ordering only.
244 .El
245 .Pp
246 The backslash character
247 .Ar \e
248 is used for continuation.
249 In this case, no characters are permitted
250 after the backslash character.
251 .Sh FILES
252 .Bl -tag -width indent
253 .It Pa /usr/share/locale/ Ns Ao Ar language Ac Ns Pa /LC_COLLATE
254 The standard shared location for collation orders
255 under the locale
256 .Aq Ar language .
257 .El
258 .Sh EXIT STATUS
259 The
260 .Nm
261 utility exits with the following values:
262 .Bl -tag -width indent
263 .It Li 0
264 No errors were found and the output was successfully created.
265 .It Li !=0
266 Errors were found.
267 .El
268 .Sh SEE ALSO
269 .Xr mklocale 1 ,
270 .Xr setlocale 3 ,
271 .Xr strcoll 3 ,
272 .Xr strxfrm 3