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