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