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: src/usr.bin/colldef/colldef.1,v 1.8.2.6 2003/02/24 23:04:38 trhodes Exp $
  27 .\" $DragonFly: src/usr.bin/colldef/colldef.1,v 1.3 2006/02/17 19:38:58 swildner Exp $
  28 .\"
  29 .Dd January 27, 1995
  30 .Dt COLLDEF 1
  31 .Os
  32 .Sh NAME
  33 .Nm colldef
  34 .Nd convert collation sequence source definition
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Op Fl I Ar map_dir
  38 .Op Fl o Ar out_file
  39 .Op Ar filename
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 utility converts a collation sequence source definition
  44 into a format usable by the
  45 .Fn strxfrm
  46 and
  47 .Fn strcoll
  48 functions.
  49 It is used to define the many ways in which
  50 strings can be ordered and collated.
  51 .Fn strxfrm
  52 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 .Fn strcoll
  62 transforms its arguments and does a
  63 comparison.
  64 .Pp
  65 The
  66 .Nm
  67 utility reads the collation sequence source definition
  68 from the standard input and stores the converted definition in filename.
  69 The output file produced contains the
  70 database with collating sequence information in a form
  71 usable by system commands and routines.
  72 .Pp
  73 Options list:
  74 .Bl -tag -width 4n
  75 .It Fl I Ar map_dir
  76 This option set directory name where
  77 .Ar charmap
  78 files can be found, current directory by default.
  79 .It Fl o Ar out_file
  80 This option set output file name,
  81 .Ar LC_COLLATE
  82 by default.
  83 .El
  84 .Pp
  85 The collation sequence definition specifies a set of collating elements and
  86 the rules defining how strings containing these should be ordered.
  87 This is most useful for different language definitions.
  88 .Pp
  89 The specification file can consist of three statements:
  90 .Ar charmap ,
  91 .Ar substitute
  92 and
  93 .Ar order .
  94 .Pp
  95 Of these, only the
  96 .Ar order
  97 statement is required.
  98 When
  99 .Ar charmap
 100 or
 101 .Ar substitute
 102 is
 103 supplied, these statements must be ordered as above.
 104 Any
 105 statements after the order statement are ignored.
 106 .Pp
 107 Lines in the specification file beginning with a
 108 .Ar #
 109 are
 110 treated as comments and are ignored.
 111 Blank lines are also
 112 ignored.
 113 .Pp
 114 .Ar charmap charmapfile
 115 .Pp
 116 .Ar charmap
 117 defines where a mapping of the character
 118 and collating element symbols to the actual
 119 character encoding can be found.
 120 .Pp
 121 The format of
 122 .Ar charmapfile
 123 is shown below.
 124 Symbol
 125 names are separated from their values by TAB or
 126 SPACE characters. symbol-value can be specified in
 127 a hexadecimal (\ex\fI??\fR) or octal (\e\fI???\fR)
 128 representation, and can be only one character in length.
 129 .Bd -literal
 130 .Ar symbol-name1 symbol-value1
 131 .Ar symbol-name2 symbol-value2
 132 .Ar ...
 133 .Ed
 134 .Pp
 135 The
 136 .Ar charmap
 137 statement is optional.
 138 .Pp
 139 .Ar substitute
 140 \fIsymbol\fR
 141 .Ar with
 142 "\fIrepl_string\fR"
 143 .Pp
 144 The
 145 .Ar substitute
 146 statement substitutes the character
 147 .Ar symbol
 148 with the string
 149 .Ar repl_string .
 150 Symbol names cannot be specified in
 151 .Ar repl_string
 152 field.
 153 The
 154 .Ar substitute
 155 statement is optional.
 156 .Pp
 157 .Ar order order_list
 158 .Pp
 159 .Ar order_list
 160 is a list of symbols, separated by semi colons, that defines the
 161 collating sequence.
 162 The
 163 special symbol
 164 .Ar ...
 165 specifies, in a short-hand
 166 form, symbols that are sequential in machine code
 167 order.
 168 .Pp
 169 An order list element
 170 can be represented in any one of the following
 171 ways:
 172 .Bl -bullet
 173 .It
 174 The symbol itself (for example,
 175 .Ar a
 176 for the lower-case letter
 177 .Ar a )
 178 .It
 179 The symbol in octal representation (for example,
 180 .Ar \e141
 181 for the letter
 182 .Ar a )
 183 .It
 184 The symbol in hexadecimal representation (for example,
 185 .Ar \ex61
 186 for the letter
 187 .Ar a )
 188 .It
 189 The symbol name as defined in the
 190 .Ar charmap
 191 file (for example,
 192 .Ar <letterA>
 193 for
 194 .Ar letterA \e023
 195 record in
 196 .Ar charmapfile ) .
 197 If character map name have
 198 .Ar >
 199 character, it must be escaped as
 200 .Ar /> ,
 201 single
 202 .Ar /
 203 must be escaped as
 204 .Ar // .
 205 .It
 206 Symbols
 207 .Ar \ea ,
 208 .Ar \eb ,
 209 .Ar \ef ,
 210 .Ar \en ,
 211 .Ar \er ,
 212 .Ar \ev
 213 are permitted in its usual C-language meaning
 214 .It
 215 The symbol chain (for example:
 216 .Ar abc ,
 217 .Ar <letterA><letterB>c ,
 218 .Ar \exf1b\exf2 )
 219 .It
 220 The symbol range (for example,
 221 .Ar a;...;z )
 222 .It
 223 Comma-separated symbols, ranges and chains enclosed in parenthesis (for example
 224 .Ar \&(
 225 .Ar sym1 ,
 226 .Ar sym2 ,
 227 .Ar ...
 228 .Ar \&) )
 229 are assigned the
 230 same primary ordering but different secondary
 231 ordering.
 232 .It
 233 Comma-separated symbols, ranges and chains enclosed in curly brackets (for example
 234 .Ar \&{
 235 .Ar sym1 ,
 236 .Ar sym2 ,
 237 .Ar ...
 238 .Ar \&} )
 239 are assigned the same primary ordering only.
 240 .El
 241 .Pp
 242 The backslash character
 243 .Ar \e
 244 is used for continuation.
 245 In this case, no characters are permitted
 246 after the backslash character.
 247 .Sh FILES
 248 .Bl -tag -width ".Pa /usr/share/locale/<language>/LC_COLLATE" -compact
 249 .It Pa /usr/share/locale/<language>/LC_COLLATE
 250 standard shared location  for  collation  orders
 251 under the locale locale
 252 .El
 253 .Sh DIAGNOSTICS
 254 The
 255 .Nm
 256 utility exits with the following values:
 257 .Bl -tag -width indent
 258 .It Li 0
 259 No errors were found and the output was successfully created.
 260 .It Li !=0
 261 Errors were found.
 262 .El
 263 .Sh SEE ALSO
 264 .Xr mklocale 1 ,
 265 .Xr setlocale 3 ,
 266 .Xr strcoll 3 ,
 267 .Xr strxfrm 3