adv_cmds/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.21 2004/05/19 09:45:46 ru 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 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 .Pp
 132 .Bd -literal -offset indent
 133 symbol-name1 symbol-value1
 134 symbol-name2 symbol-value2
 135 \&...
 136 .Ed
 137 .Pp
 138 Symbol names cannot be specified in
 139 .Ar substitute
 140 fields.
 141 .Pp
 142 The
 143 .Ar charmap
 144 statement is optional.
 145 .Pp
 146 .Bd -literal -offset indent
 147 substitute "symbol" with "repl_string"
 148 .Ed
 149 .Pp
 150 The
 151 .Ar substitute
 152 statement substitutes the character
 153 .Ar symbol
 154 with the string
 155 .Ar repl_string .
 156 Symbol names cannot be specified in
 157 .Ar repl_string
 158 field.
 159 The
 160 .Ar substitute
 161 statement is optional.
 162 .Pp
 163 .Dl "order order_list"
 164 .Pp
 165 .Ar Order_list
 166 is a list of symbols, separated by semi colons, that defines the
 167 collating sequence.
 168 The
 169 special symbol
 170 .Ar ...
 171 specifies, in a short-hand
 172 form, symbols that are sequential in machine code
 173 order.
 174 .Pp
 175 An order list element
 176 can be represented in any one of the following
 177 ways:
 178 .Bl -bullet
 179 .It
 180 The symbol itself (for example,
 181 .Ar a
 182 for the lower-case letter
 183 .Ar a ) .
 184 .It
 185 The symbol in octal representation (for example,
 186 .Ar \e141
 187 for the letter
 188 .Ar a ) .
 189 .It
 190 The symbol in hexadecimal representation (for example,
 191 .Ar \ex61
 192 for the letter
 193 .Ar a ) .
 194 .It
 195 The symbol name as defined in the
 196 .Ar charmap
 197 file (for example,
 198 .Ar <letterA>
 199 for
 200 .Ar letterA \e023
 201 record in
 202 .Ar charmapfile ) .
 203 If character map name have
 204 .Ar >
 205 character, it must be escaped as
 206 .Ar /> ,
 207 single
 208 .Ar /
 209 must be escaped as
 210 .Ar // .
 211 .It
 212 Symbols
 213 .Ar \ea ,
 214 .Ar \eb ,
 215 .Ar \ef ,
 216 .Ar \en ,
 217 .Ar \er ,
 218 .Ar \ev
 219 are permitted in its usual C-language meaning.
 220 .It
 221 The symbol chain (for example:
 222 .Ar abc ,
 223 .Ar <letterA><letterB>c ,
 224 .Ar \exf1b\exf2 )
 225 .It
 226 The symbol range (for example,
 227 .Ar a;...;z ) .
 228 .It
 229 Comma-separated symbols, ranges and chains enclosed in parenthesis (for example
 230 .Ar \&(
 231 .Ar sym1 ,
 232 .Ar sym2 ,
 233 .Ar ...
 234 .Ar \&) )
 235 are assigned the
 236 same primary ordering but different secondary
 237 ordering.
 238 .It
 239 Comma-separated symbols, ranges and chains enclosed in curly brackets (for example
 240 .Ar \&{
 241 .Ar sym1 ,
 242 .Ar sym2 ,
 243 .Ar ...
 244 .Ar \&} )
 245 are assigned the same primary ordering only.
 246 .El
 247 .Pp
 248 The backslash character
 249 .Ar \e
 250 is used for continuation.
 251 In this case, no characters are permitted
 252 after the backslash character.
 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 FILES
 264 .Bl -tag -width indent
 265 .It Pa /usr/share/locale/ Ns Ao Ar language Ac Ns Pa /LC_COLLATE
 266 The standard shared location for collation orders
 267 under the locale
 268 .Aq Ar language .
 269 .El
 270 .Sh SEE ALSO
 271 .Xr mklocale 1 ,
 272 .Xr setlocale 3 ,
 273 .Xr strcoll 3 ,
 274 .Xr strxfrm 3