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