usr.bin/gencat/gencat.1

   1 .\" $NetBSD: gencat.1,v 1.13 2011/12/29 16:41:38 christos 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 December 29, 2011
  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 .Op Ar msgfile|- ...
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 utility generates a formatted message catalog
  46 .Ar catfile
  47 from stdin or one or more message source text files
  48 .Ar msgfile .
  49 The file
  50 .Ar catfile
  51 is created if it does not already exist.
  52 If
  53 .Ar catfile
  54 does exist, its messages are included in the new
  55 .Ar catfile .
  56 The new message text defined in
  57 .Ar msgfile
  58 replaces the old message text currently in
  59 .Ar catfile
  60 when the set and message numbers match.
  61 .Pp
  62 The generated message catalog contains message
  63 strings that will be retrieved using the
  64 .Xr catgets 3
  65 library call.
  66 These messages are dynamically loaded by the
  67 Native Language Support (NLS) library at run time.
  68 Error messages are grouped into sets, and a program can load a
  69 particular set depending on which type, or language, of messages
  70 is desired.
  71 .Ss Message Text Source File Format
  72 The message text source files are text files in the format described below.
  73 Note that the fields of a message text source line are separated by
  74 space or tab characters.
  75 .\" XXX Required by POSIX; the code must be fixed first.  Above line should be
  76 .\" a single space or tab character;
  77 .\" any other space or tab characters are considered to be part of the
  78 .\" field contents.
  79 .Bl -tag -width 3n
  80 .It Li $set Ar n comment
  81 Determines the set identifier to be used for all subsequent messages
  82 until the next
  83 .Li $set
  84 or end-of-file.
  85 The
  86 .Ar n
  87 is the set identifier which is defined as a number in the range
  88 .Bo 1 ,
  89 .Dv NL_SETMAX Bc .
  90 Set identifiers within a single source file need not be contiguous.
  91 Any string following the set identifier is treated as a comment.
  92 If no
  93 .Li $set
  94 directive is specified in a message text source file,
  95 all messages will be located in the default message set
  96 .Dv NL_SETD .
  97 .It Li $delset Ar n comment
  98 Removes message set
  99 .Ar n
 100 from the catalog.
 101 The
 102 .Ar n
 103 is a set identifier in the range
 104 .Bo 1 ,
 105 .Dv NL_SETMAX Bc .
 106 If a message set was created earlier in the
 107 current file, or in a file previously read by the
 108 .Nm
 109 command, this directive will remove it.
 110 Any string following the set identifier is treated as a comment.
 111 .It Li $ Ar comment
 112 A line beginning with
 113 .Li $
 114 followed by a space or tab character is treated as a comment.
 115 .It Ar m message-text
 116 A message line consists of a message identifier
 117 .Ar m
 118 in the range
 119 .Bo 1 ,
 120 .Dv NL_MSGMAX Bc
 121 and the
 122 .Ar message-text .
 123 The
 124 .Ar message-text
 125 is read until the end of the line or a quote character
 126 (if one is specified).
 127 The
 128 .Ar message-text
 129 is stored in the message catalog with
 130 the set identifier specified by the last
 131 .Li $set
 132 directive, and the message identifier
 133 .Ar m .
 134 If the
 135 .Ar message-text
 136 is empty and there is a space or tab character
 137 following the message identifier,
 138 an empty string is stored in the message catalog.
 139 If no
 140 .Ar message-text
 141 is provided,
 142 and if there is no space or tab character following the message
 143 identifier,
 144 the message with the message identifier
 145 .Ar m
 146 in the current set is removed from the catalog.
 147 Message identifiers need not be contiguous within a single set.
 148 The length of
 149 .Ar message-text
 150 must be in the range
 151 .Bo 0 ,
 152 .Dv NL_TEXTMAX Bc .
 153 .It Li $quote Ar c
 154 Sets an optional quote character to be used around the
 155 .Ar message-text .
 156 The quote character
 157 .Ar c
 158 may be any character other than white space.
 159 If this is specified, then messages must begin and end with the
 160 quote character.
 161 .\" XXX Remove next sentence when code is fixed for POSIX conformance.
 162 This is useful when messages must contain leading white space.
 163 .\" XXX Replacement when above is removed.
 164 .\" This is useful to make leading and trailing spaces or empty
 165 .\" messages visible.
 166 By default no quote character is used.
 167 If an empty
 168 .Li $quote
 169 directive is specified, then the current quote character is unset.
 170 .El
 171 .Pp
 172 Empty lines
 173 .\" XXX Remove next line when the code is fixed for POSIX conformance.
 174 and leading blanks
 175 in a message text source file are ignored.
 176 Any line beginning with any character other than those
 177 described above is ignored as a syntax error.
 178 .Pp
 179 Text message strings may contain any characters and
 180 the following special characters and escape sequences.
 181 .Pp
 182 .Bl -column -offset indent ".Sy carriage return" ".Sy Symbol" ".Sy Sequence"
 183 .It Sy Description Ta Sy Symbol Ta Sy Sequence
 184 .It newline Ta NL(LF) Ta Li \en
 185 .It horizontal tab Ta HT Ta Li \et
 186 .It vertical tab Ta VT Ta Li \ev
 187 .It backspace Ta BS Ta Li \eb
 188 .It carriage return Ta CR Ta Li \er
 189 .It form feed Ta FF Ta Li \ef
 190 .It backslash Ta \e Ta Li \e\e
 191 .It bit pattern Ta ddd Ta Li \eddd
 192 .El
 193 .Pp
 194 A bit pattern,
 195 .Li \eddd ,
 196 consists of a backslash followed by
 197 one, two, or three octal digits representing the value of the character.
 198 The current quote character, if defined, may be escaped with a backslash
 199 to generate the quote character.
 200 Any character following the backslash ('\e') other than those specified
 201 is ignored.
 202 .Pp
 203 A backslash at the end of the line continues the message onto the next line.
 204 The following two lines are an example of such a message:
 205 .Pp
 206 .Dl 1 This message continues \e
 207 .D1 on the next line
 208 .Pp
 209 Producing the following message:
 210 .Pp
 211 .Dl 1 This message continues on the next line
 212 .Sh EXIT STATUS
 213 .Ex -std
 214 .Sh SEE ALSO
 215 .Xr catclose 3 ,
 216 .Xr catgets 3 ,
 217 .Xr catopen 3 ,
 218 .Xr nls 7
 219 .\" XXX Close but not quite; add when code is fixed.
 220 .\".Sh STANDARDS
 221 .\"The
 222 .\".Nm
 223 .\"utility is compliant with the
 224 .\".St -p1003.1-2004
 225 .\"standard.
 226 .Sh AUTHORS
 227 The Native Language Support (NLS) message catalog facility was
 228 contributed by
 229 .An J.T. Conklin
 230 .Aq jtc@NetBSD.org .
 231 This page was originally written by
 232 .An Kee Hinckley
 233 .Aq nazgul@somewhere.com .