usr.bin/gencat/gencat.1

   1 .\" $NetBSD: gencat.1,v 1.11 2008/11/04 03:14:46 ginsbach Exp $
   2 .\"
   3 .\" Copyright (c) 2007 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Kee Hinckley and Brian Ginsbach.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" Written by Kee Hinckley <nazgul@somewhere.com>
  31 .\"
  32 .Dd November 4, 2008
  33 .Dt GENCAT 1
  34 .Os
  35 .Sh NAME
  36 .Nm gencat
  37 .Nd generates a Native Language Support (NLS) message catalog file
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Ar catfile
  41 .Ar msgfile
  42 .Op Ar msgfile ...
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility generates a formatted message catalog
  47 .Ar catfile
  48 from one or more message source text files
  49 .Ar msgfile .
  50 The file
  51 .Ar catfile
  52 is created if it does not already exist.
  53 If
  54 .Ar catfile
  55 does exist, its messages are included in the new
  56 .Ar catfile .
  57 The new message text defined in
  58 .Ar msgfile
  59 replaces the old message text currently in
  60 .Ar catfile
  61 when the set and message numbers match.
  62 .Pp
  63 The generated message catalog contains message
  64 strings that will be retrieved using the
  65 .Xr catgets 3
  66 library call.
  67 These messages are dynamically loaded by the
  68 Native Language Support (NLS) library at run time.
  69 Error messages are grouped into sets, and a program can load a
  70 particular set depending on which type, or language, of messages
  71 is desired.
  72 .Ss Message Text Source File Format
  73 The message text source files are text files in the format described below.
  74 Note that the fields of a message text source line are separated by
  75 space or tab characters.
  76 .\" XXX Required by POSIX; the code must be fixed first.  Above line should be
  77 .\" a single space or tab character;
  78 .\" any other space or tab characters are considered to be part of the
  79 .\" field contents.
  80 .Bl -tag -width 3n
  81 .It Li $set Ar n comment
  82 Determines the set identifier to be used for all subsequent messages
  83 until the next
  84 .Li $set
  85 or end-of-file.
  86 The
  87 .Ar n
  88 is the set identifier which is defined as a number in the range
  89 .Bo 1 ,
  90 .Dv NL_SETMAX Bc .
  91 Set identifiers within a single source file need not be contiguous.
  92 Any string following the set identifier is treated as a comment.
  93 If no
  94 .Li $set
  95 directive is specified in a message text source file,
  96 all messages will be located in the default message set
  97 .Dv NL_SETD .
  98 .It Li $delset Ar n comment
  99 Removes message set
 100 .Ar n
 101 from the catalog.
 102 The
 103 .Ar n
 104 is a set identifier in the range
 105 .Bo 1 ,
 106 .Dv NL_SETMAX Bc .
 107 If a message set was created earlier in the
 108 current file, or in a file previously read by the
 109 .Nm
 110 command, this directive will remove it.
 111 Any string following the set identifier is treated as a comment.
 112 .It Li $ Ar comment
 113 A line beginning with
 114 .Li $
 115 followed by a space or tab character is treated as a comment.
 116 .It Ar m message-text
 117 A message line consists of a message identifier
 118 .Ar m
 119 in the range
 120 .Bo 1 ,
 121 .Dv NL_MSGMAX Bc
 122 and the
 123 .Ar message-text .
 124 The
 125 .Ar message-text
 126 is read until the end of the line or a quote character
 127 (if one is specified).
 128 The
 129 .Ar message-text
 130 is stored in the message catalog with
 131 the set identifier specified by the last
 132 .Li $set
 133 directive, and the message identifier
 134 .Ar m .
 135 If the
 136 .Ar message-text
 137 is empty and there is a space or tab character
 138 following the message identifier,
 139 an empty string is stored in the message catalog.
 140 If no
 141 .Ar message-text
 142 is provided,
 143 and if there is no space or tab character following the message
 144 identifier,
 145 the message with the message identifier
 146 .Ar m
 147 in the current set is removed from the catalog.
 148 Message identifiers need not be contiguous within a single set.
 149 The length of
 150 .Ar message-text
 151 must be in the range
 152 .Bo 0 ,
 153 .Dv NL_TEXTMAX Bc .
 154 .It Li $quote Ar c
 155 Sets an optional quote character to be used around the
 156 .Ar message-text .
 157 The quote character
 158 .Ar c
 159 may be any character other than white space.
 160 If this is specified, then messages must begin and end with the
 161 quote character.
 162 .\" XXX Remove next sentence when code is fixed for POSIX conformance.
 163 This is useful when messages must contain leading white space.
 164 .\" XXX Replacement when above is removed.
 165 .\" This is useful to make leading and trailing spaces or empty
 166 .\" messages visible.
 167 By default no quote character is used.
 168 If an empty
 169 .Li $quote
 170 directive is specified, then the current quote character is unset.
 171 .El
 172 .Pp
 173 Empty lines
 174 .\" XXX Remove next line when the code is fixed for POSIX conformance.
 175 and leading blanks
 176 in a message text source file are ignored.
 177 Any line beginning with any character other than those
 178 described above is ignored as a syntax error.
 179 .Pp
 180 Text message strings may contain any characters and
 181 the following special characters and escape sequences.
 182 .Pp
 183 .Bl -column -offset indent ".Sy carriage return" ".Sy Symbol" ".Sy Sequence"
 184 .It Sy Description Ta Sy Symbol Ta Sy Sequence
 185 .It newline Ta NL(LF) Ta Li \en
 186 .It horizontal tab Ta HT Ta Li \et
 187 .It vertical tab Ta VT Ta Li \ev
 188 .It backspace Ta BS Ta Li \eb
 189 .It carriage return Ta CR Ta Li \er
 190 .It form feed Ta FF Ta Li \ef
 191 .It backslash Ta \e Ta Li \e\e
 192 .It bit pattern Ta ddd Ta Li \eddd
 193 .El
 194 .Pp
 195 A bit pattern,
 196 .Li \eddd ,
 197 consists of a backslash followed by
 198 one, two, or three octal digits representing the value of the character.
 199 The current quote character, if defined, may be escaped with a backslash
 200 to generate the quote character.
 201 Any character following the backslash ('\e') other than those specified
 202 is ignored.
 203 .Pp
 204 A backslash at the end of the line continues the message onto the next line.
 205 The following two lines are an example of such a message:
 206 .Pp
 207 .Dl 1 This message continues \e
 208 .D1 on the next line
 209 .Pp
 210 Producing the following message:
 211 .Pp
 212 .Dl 1 This message continues on the next line
 213 .Sh EXIT STATUS
 214 .Ex -std
 215 .Sh SEE ALSO
 216 .Xr catclose 3 ,
 217 .Xr catgets 3 ,
 218 .Xr catopen 3 ,
 219 .Xr nls 7
 220 .\" XXX Close but not quite; add when code is fixed.
 221 .\".Sh STANDARDS
 222 .\"The
 223 .\".Nm
 224 .\"utility is compliant with the
 225 .\".St -p1003.1-2004
 226 .\"standard.
 227 .Sh AUTHORS
 228 The Native Language Support (NLS) message catalog facility was
 229 contributed by
 230 .An J.T. Conklin
 231 .Aq jtc@NetBSD.org .
 232 This page was originally written by
 233 .An Kee Hinckley
 234 .Aq nazgul@somewhere.com .