Annotation of src/usr.bin/mklocale/mklocale.1, Revision 1.1
1.1 ! espie 1: .\" $NetBSD: mklocale.1,v 1.13 2004/01/24 17:03:26 wiz Exp $
! 2: .\" FreeBSD: src/usr.bin/mklocale/mklocale.1,v 1.6 1999/09/20 09:15:21 phantom Exp
! 3: .\"
! 4: .\" Copyright (c) 1993, 1994
! 5: .\" The Regents of the University of California. All rights reserved.
! 6: .\"
! 7: .\" This code is derived from software contributed to Berkeley by
! 8: .\" Paul Borman at Krystal Technologies.
! 9: .\"
! 10: .\" Redistribution and use in source and binary forms, with or without
! 11: .\" modification, are permitted provided that the following conditions
! 12: .\" are met:
! 13: .\" 1. Redistributions of source code must retain the above copyright
! 14: .\" notice, this list of conditions and the following disclaimer.
! 15: .\" 2. Redistributions in binary form must reproduce the above copyright
! 16: .\" notice, this list of conditions and the following disclaimer in the
! 17: .\" documentation and/or other materials provided with the distribution.
! 18: .\" 3. Neither the name of the University nor the names of its contributors
! 19: .\" may be used to endorse or promote products derived from this software
! 20: .\" without specific prior written permission.
! 21: .\"
! 22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
! 23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
! 26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 32: .\" SUCH DAMAGE.
! 33: .\"
! 34: .\" @(#)mklocale.1 8.2 (Berkeley) 4/18/94
! 35: .\"
! 36: .Dd April 18, 1994
! 37: .Dt MKLOCALE 1
! 38: .Os
! 39: .Sh NAME
! 40: .Nm mklocale
! 41: .Nd make LC_CTYPE locale files
! 42: .Sh SYNOPSIS
! 43: .Nm mklocale
! 44: .Op Fl d
! 45: \*[Lt]
! 46: .Ar src-file
! 47: \*[Gt]
! 48: .Ar language/LC_CTYPE
! 49: .Nm mklocale
! 50: .Op Fl d
! 51: .Fl o
! 52: .Ar language/LC_CTYPE
! 53: .Ar src-file
! 54: .Sh DESCRIPTION
! 55: The
! 56: .Nm mklocale
! 57: utility reads an
! 58: .Dv LC_CTYPE
! 59: source file from standard input and produces an
! 60: .Dv LC_CTYPE
! 61: binary file on standard output suitable for placement in
! 62: .Pa /usr/share/locale/\*[Lt]language\*[Gt]/LC_CTYPE .
! 63: .Pp
! 64: The format of
! 65: .Ar src-file
! 66: is quite simple.
! 67: It consists of a series of lines which start with a keyword and have
! 68: associated data following.
! 69: C style comments are used
! 70: to place comments in the file.
! 71: .Pp
! 72: Following options are available:
! 73: .Bl -tag -width XXX
! 74: .It Fl d
! 75: Turns on debugging messages.
! 76: .It Fl o
! 77: Specify output file.
! 78: .El
! 79: .Pp
! 80: Besides the keywords which will be listed below,
! 81: the following are valid tokens in
! 82: .Ar src-file :
! 83: .Bl -tag -width literal
! 84: .It Dv RUNE
! 85: A
! 86: .Dv RUNE
! 87: may be any of the following:
! 88: .Bl -tag -width 0x[0-9a-z]*
! 89: .It Ar 'x'
! 90: The ASCII character
! 91: .Ar x .
! 92: .It Ar '\ex'
! 93: The ANSI C character
! 94: .Ar \ex
! 95: where
! 96: .Ar \ex
! 97: is one of
! 98: .Dv \ea ,
! 99: .Dv \eb ,
! 100: .Dv \ef ,
! 101: .Dv \en ,
! 102: .Dv \er ,
! 103: .Dv \et ,
! 104: or
! 105: .Dv \ev .
! 106: .It Ar 0x[0-9a-z]*
! 107: A hexadecimal number representing a rune code.
! 108: .It Ar 0[0-7]*
! 109: An octal number representing a rune code.
! 110: .It Ar [1-9][0-9]*
! 111: A decimal number representing a rune code.
! 112: .El
! 113: .It Dv STRING
! 114: A string enclosed in double quotes (").
! 115: .It Dv THRU
! 116: Either
! 117: .Dv ...
! 118: or
! 119: .Dv - .
! 120: Used to indicate ranges.
! 121: .It Ar literal
! 122: The follow characters are taken literally:
! 123: .Bl -tag -width "\*[Lt]\|\|(\|\|["
! 124: .It Dv "\*[Lt]\|(\|["
! 125: Used to start a mapping.
! 126: All are equivalent.
! 127: .It Dv "\*[Gt]\|\^)\|]"
! 128: Used to end a mapping.
! 129: All are equivalent.
! 130: .It Dv :
! 131: Used as a delimiter in mappings.
! 132: .El
! 133: .El
! 134: .Pp
! 135: Key words which should only appear once are:
! 136: .Bl -tag -width PHONOGRAM
! 137: .It Dv ENCODING
! 138: Followed by a
! 139: .Dv STRING
! 140: which indicates the encoding mechanism to be used for this locale.
! 141: The current encodings are:
! 142: .Bl -tag -width NONE
! 143: .It Dv NONE
! 144: No translation and the default.
! 145: .It Dv UTF2
! 146: .Dv "Universal character set Transformation Format"
! 147: adopted from
! 148: .Nm "Plan 9 from Bell Labs" .
! 149: .It Dv EUC
! 150: .Dv EUC
! 151: encoding as used by several
! 152: vendors of
! 153: .Ux
! 154: systems.
! 155: .El
! 156: .It Dv VARIABLE
! 157: This keyword must be followed by a single tab or space character,
! 158: after which encoding specific data is placed.
! 159: Currently only the
! 160: .Dv "EUC"
! 161: encoding requires variable data.
! 162: .\" See
! 163: .\" .Xr euc 4
! 164: .\" for further details.
! 165: .It Dv INVALID
! 166: A single
! 167: .Dv RUNE
! 168: follows and is used as the invalid rune for this locale.
! 169: .El
! 170: .Pp
! 171: The following keywords may appear multiple times and have the following
! 172: format for data:
! 173: .in +.5i
! 174: .Bl -tag -width "XXRUNE1 THRU RUNEn : RUNE2XX"
! 175: .It Aq Dv RUNE1 RUNE2
! 176: .Dv RUNE1
! 177: is mapped to
! 178: .Dv RUNE2 .
! 179: .It Aq Dv RUNE1 THRU RUNEn : RUNE2
! 180: Runes
! 181: .Dv RUNE1
! 182: through
! 183: .Dv RUNEn
! 184: are mapped to
! 185: .Dv RUNE2
! 186: through
! 187: .Dv RUNE2
! 188: + n-1.
! 189: .El
! 190: .in -.5i
! 191: .Bl -tag -width PHONOGRAM
! 192: .It Dv MAPLOWER
! 193: Defines the tolower mappings.
! 194: .Dv RUNE2
! 195: is the lower case representation of
! 196: .Dv RUNE1 .
! 197: .It Dv MAPUPPER
! 198: Defines the toupper mappings.
! 199: .Dv RUNE2
! 200: is the upper case representation of
! 201: .Dv RUNE1 .
! 202: .It Dv TODIGIT
! 203: Defines a map from runes to their digit value.
! 204: .Dv RUNE2
! 205: is the integer value represented by
! 206: .Dv RUNE1 .
! 207: For example, the ASCII character
! 208: .Sq 0
! 209: would map to the decimal value 0.
! 210: Only values up to 255 are allowed.
! 211: .El
! 212: .Pp
! 213: The following keywords may appear multiple times and have the following
! 214: format for data:
! 215: .Bl -tag -width "RUNE1 THRU RUNEn"
! 216: .It Dv RUNE
! 217: This rune has the property defined by the keyword.
! 218: .It Dv "RUNE1 THRU RUNEn"
! 219: All the runes between and including
! 220: .Dv RUNE1
! 221: and
! 222: .Dv RUNEn
! 223: have the property defined by the keyword.
! 224: .El
! 225: .Bl -tag -width PHONOGRAM
! 226: .It Dv ALPHA
! 227: Defines runes which are alphabetic, printable, and graphic.
! 228: .It Dv CONTROL
! 229: Defines runes which are control characters.
! 230: .It Dv DIGIT
! 231: Defines runes which are decimal digits, printable, and graphic.
! 232: .It Dv GRAPH
! 233: Defines runes which are graphic and printable.
! 234: .It Dv LOWER
! 235: Defines runes which are lower case, printable, and graphic.
! 236: .It Dv PUNCT
! 237: Defines runes which are punctuation, printable, and graphic.
! 238: .It Dv SPACE
! 239: Defines runes which are spaces.
! 240: .It Dv UPPER
! 241: Defines runes which are upper case, printable, and graphic.
! 242: .It Dv XDIGIT
! 243: Defines runes which are hexadecimal digits, printable, and graphic.
! 244: .It Dv BLANK
! 245: Defines runes which are blank.
! 246: .It Dv PRINT
! 247: Defines runes which are printable.
! 248: .It Dv IDEOGRAM
! 249: Defines runes which are ideograms, printable, and graphic.
! 250: .It Dv SPECIAL
! 251: Defines runes which are special characters, printable, and graphic.
! 252: .It Dv PHONOGRAM
! 253: Defines runes which are phonograms, printable, and graphic.
! 254: .It Dv SWIDTHn
! 255: Defines runes with specific glyph width.
! 256: .Ar n
! 257: takes 0 to 3.
! 258: .It Dv CHARSET
! 259: Controls character set for subsequent runes.
! 260: .\" To support
! 261: .\" .Xr iso2022 4
! 262: .\" locale definitions.
! 263: .El
! 264: .Sh SEE ALSO
! 265: .\"Xr colldef 1 ,
! 266: .Xr setlocale 3 ,
! 267: .\" .Xr euc 4 ,
! 268: .\" .Xr utf8 4
! 269: .Xr nls 7
! 270: .Sh HISTORY
! 271: The
! 272: .Nm mklocale
! 273: utility first appeared in
! 274: .Bx 4.4 .
! 275: .Sh BUGS
! 276: The
! 277: .Nm mklocale
! 278: utility is overly simplistic.
! 279: .Pp
! 280: We should switch to
! 281: .Nm localedef
! 282: and its file format, which is more standard.