Annotation of src/usr.bin/gencat/gencat.1, Revision 1.20
1.20 ! jmc 1: .\" $OpenBSD: gencat.1,v 1.19 2014/03/20 15:39:41 jmc Exp $
1.1 kstailey 2: .\"
3: .\" Copyright (c) 1997 Ken Stailey
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: .\" 3. The name of the author may not be used to endorse or promote products
14: .\" derived from this software without specific prior written permission
15: .\"
16: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19: .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26: .\"
1.20 ! jmc 27: .\" $Id: gencat.1,v 1.19 2014/03/20 15:39:41 jmc Exp $
1.1 kstailey 28: .\"
1.20 ! jmc 29: .Dd $Mdocdate: March 20 2014 $
1.1 kstailey 30: .Dt GENCAT 1
31: .Os
32: .Sh NAME
33: .Nm gencat
34: .Nd NLS catalog compiler
35: .Sh SYNOPSIS
1.7 aaron 36: .Nm gencat
1.14 sobrado 37: .Ar catfile msgfile ...
1.1 kstailey 38: .Sh DESCRIPTION
39: The
1.5 deraadt 40: .Nm
1.6 espie 41: utility merges the text NLS (National Language Support) in
1.14 sobrado 42: .Ar msgfile
1.5 deraadt 43: into a formatted message catalog file
1.14 sobrado 44: .Ar catfile .
1.5 deraadt 45: The file
1.14 sobrado 46: .Ar catfile
1.9 aaron 47: will be created if it does not already exist.
48: If
1.14 sobrado 49: .Ar catfile
1.5 deraadt 50: does exist, its messages will be included in the new
1.14 sobrado 51: .Ar catfile .
1.5 deraadt 52: If set and message numbers collide, the new message text defined in
1.14 sobrado 53: .Ar msgfile
1.5 deraadt 54: will replace the old message text currently contained in
1.14 sobrado 55: .Ar catfile .
1.5 deraadt 56: .Sh INPUT FILES
1.9 aaron 57: The format of a message text source file is defined below.
58: Note that the fields of a message text source line are separated by a
59: single space character; any other space characters are considered to be
60: part of the field contents.
1.16 schwarze 61: .Bl -tag -width Ds
1.5 deraadt 62: .It Li $set Ar n comment
63: This line specifies the set identifier of the following messages until
64: the next
65: .Li $set
1.9 aaron 66: or end-of-file appears.
67: The argument
1.5 deraadt 68: .Ar n
69: is the set identifier which is defined as a number in the range
1.9 aaron 70: .Bo 1 ,
71: .Dv NL_SETMAX Bc .
72: Set identifiers must occur in ascending order within
73: a single source file, but need not be contiguous.
74: Any string following
75: a space following the set identifier is treated as a comment.
76: If no
1.5 deraadt 77: .Li $set
1.9 aaron 78: directive is specified in a given source file, all messages will
79: be located in the default message set
80: .Dv NL_SETD .
1.19 jmc 81: .It Li $delset Ar n comment
1.5 deraadt 82: This line deletes messages from set
83: .Ar n
1.9 aaron 84: from a message catalog.
85: The
1.5 deraadt 86: .Ar n
1.9 aaron 87: specifies a set number.
88: Any string following a space following the set
1.5 deraadt 89: number is treated as a comment.
90: .It Li $ Ar comment
91: A line beginning with
92: .Li $
93: followed by a space is treated as a comment.
94: .It Ar m message-text
95: A message line consists of a message identifier
96: .Ar m
1.9 aaron 97: in the range
98: .Bo 1 ,
99: .Dv NL_MSGMAX Bc .
100: The
1.5 deraadt 101: .Ar message-text
102: is stored in the message catalog with the set identifier specified by
103: the last
104: .Li $set
105: directive, and the message identifier
106: .Ar m .
107: If the
108: .Ar message-text
109: is empty, and there is a space character following the message identifier,
1.9 aaron 110: an empty string is stored in the message catalog.
111: If the
1.5 deraadt 112: .Ar message-text
113: is empty, and if there is no space character following the message
114: identifier, then the existing message in the current set with the
1.9 aaron 115: specified message identifier is deleted from the catalog.
116: Message identifiers must be in ascending order within a single set, but
117: need not be contiguous.
118: The
1.5 deraadt 119: .Ar message-text
1.9 aaron 120: length must be in the range
121: .Bo 0 ,
122: .Dv NL_TEXTMAX Bc .
1.5 deraadt 123: .It Li $quote Ar c
124: This line specifies an optional quote character
125: .Ar c
126: which can be used to surround
127: .Ar message-text
128: so that trailing space or empty messages are visible in message
1.9 aaron 129: source files.
130: By default, or if an empty
1.5 deraadt 131: .Li $quote
132: directive is specified, no quoting of
133: .Ar message-text
134: will be recognized.
135: .El
136: .Pp
1.9 aaron 137: Empty lines in message source files are ignored.
138: The effect of lines beginning with any character other than those
139: described above is undefined.
1.5 deraadt 140: .Pp
141: Text strings can contain the following special characters and escape
1.9 aaron 142: sequences.
143: In addition, if a quote character is defined, it may be
1.5 deraadt 144: escaped as well to embed a literal quote character.
145: .Pp
1.9 aaron 146: .Bl -tag -width Ds -offset indent -compact
1.5 deraadt 147: .It Li \en
148: line feed
149: .It Li \et
150: horizontal tab
151: .It Li \ev
152: vertical tab
153: .It Li \eb
154: backspace
155: .It Li \er
156: carriage return
157: .It Li \ef
158: form feed
159: .It Li \e\e
160: backslash
161: .It Li \eooo
162: octal number in the range [000, 377]
163: .El
164: .Pp
165: A backslash character immediately before the end of the line in a file
1.9 aaron 166: is used to continue the line onto the next line, e.g.,
1.5 deraadt 167: .Pp
168: .Dl 1 This line is continued \e
169: .Dl on this line.
170: .Pp
171: If the character following the backslash is not one of those specified,
172: the backslash is ignored.
1.17 jmc 173: .Sh EXIT STATUS
1.13 sobrado 174: .Ex -std gencat
1.1 kstailey 175: .Sh SEE ALSO
176: .Xr catclose 3 ,
177: .Xr catgets 3 ,
178: .Xr catopen 3
179: .Sh STANDARDS
180: The
1.5 deraadt 181: .Nm
182: utility is compliant with the
1.15 jmc 183: .St -p1003.1-2008
184: specification.
1.10 aaron 185: .Sh AUTHORS
1.11 jaredy 186: .An -nosplit
1.5 deraadt 187: This manual page by
188: .An Ken Stailey
189: updated and revised by
190: .An Terry Lambert .
191: .Sh BUGS
1.20 ! jmc 192: A message catalog file created from a blank input file cannot be revised;
1.5 deraadt 193: it must be deleted and recreated.