Annotation of src/usr.bin/gencat/gencat.1, Revision 1.15
1.15 ! jmc 1: .\" $OpenBSD: gencat.1,v 1.14 2009/01/04 18:42:32 sobrado 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.15 ! jmc 27: .\" $Id: gencat.1,v 1.14 2009/01/04 18:42:32 sobrado Exp $
1.1 kstailey 28: .\"
1.14 sobrado 29: .Dd $Mdocdate: January 4 2009 $
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.5 deraadt 61: .Pp
62: .Bl -tag -width
63: .It Li $set Ar n comment
64: This line specifies the set identifier of the following messages until
65: the next
66: .Li $set
1.9 aaron 67: or end-of-file appears.
68: The argument
1.5 deraadt 69: .Ar n
70: is the set identifier which is defined as a number in the range
1.9 aaron 71: .Bo 1 ,
72: .Dv NL_SETMAX Bc .
73: Set identifiers must occur in ascending order within
74: a single source file, but need not be contiguous.
75: Any string following
76: a space following the set identifier is treated as a comment.
77: If no
1.5 deraadt 78: .Li $set
1.9 aaron 79: directive is specified in a given source file, all messages will
80: be located in the default message set
81: .Dv NL_SETD .
1.5 deraadt 82: .It Li $del Ar n comment
83: This line deletes messages from set
84: .Ar n
1.9 aaron 85: from a message catalog.
86: The
1.5 deraadt 87: .Ar n
1.9 aaron 88: specifies a set number.
89: Any string following a space following the set
1.5 deraadt 90: number is treated as a comment.
91: .It Li $ Ar comment
92: A line beginning with
93: .Li $
94: followed by a space is treated as a comment.
95: .It Ar m message-text
96: A message line consists of a message identifier
97: .Ar m
1.9 aaron 98: in the range
99: .Bo 1 ,
100: .Dv NL_MSGMAX Bc .
101: The
1.5 deraadt 102: .Ar message-text
103: is stored in the message catalog with the set identifier specified by
104: the last
105: .Li $set
106: directive, and the message identifier
107: .Ar m .
108: If the
109: .Ar message-text
110: is empty, and there is a space character following the message identifier,
1.9 aaron 111: an empty string is stored in the message catalog.
112: If the
1.5 deraadt 113: .Ar message-text
114: is empty, and if there is no space character following the message
115: identifier, then the existing message in the current set with the
1.9 aaron 116: specified message identifier is deleted from the catalog.
117: Message identifiers must be in ascending order within a single set, but
118: need not be contiguous.
119: The
1.5 deraadt 120: .Ar message-text
1.9 aaron 121: length must be in the range
122: .Bo 0 ,
123: .Dv NL_TEXTMAX Bc .
1.5 deraadt 124: .It Li $quote Ar c
125: This line specifies an optional quote character
126: .Ar c
127: which can be used to surround
128: .Ar message-text
129: so that trailing space or empty messages are visible in message
1.9 aaron 130: source files.
131: By default, or if an empty
1.5 deraadt 132: .Li $quote
133: directive is specified, no quoting of
134: .Ar message-text
135: will be recognized.
136: .El
137: .Pp
1.9 aaron 138: Empty lines in message source files are ignored.
139: The effect of lines beginning with any character other than those
140: described above is undefined.
1.5 deraadt 141: .Pp
142: Text strings can contain the following special characters and escape
1.9 aaron 143: sequences.
144: In addition, if a quote character is defined, it may be
1.5 deraadt 145: escaped as well to embed a literal quote character.
146: .Pp
1.9 aaron 147: .Bl -tag -width Ds -offset indent -compact
1.5 deraadt 148: .It Li \en
149: line feed
150: .It Li \et
151: horizontal tab
152: .It Li \ev
153: vertical tab
154: .It Li \eb
155: backspace
156: .It Li \er
157: carriage return
158: .It Li \ef
159: form feed
160: .It Li \e\e
161: backslash
162: .It Li \eooo
163: octal number in the range [000, 377]
164: .El
165: .Pp
166: A backslash character immediately before the end of the line in a file
1.9 aaron 167: is used to continue the line onto the next line, e.g.,
1.5 deraadt 168: .Pp
169: .Dl 1 This line is continued \e
170: .Dl on this line.
171: .Pp
172: If the character following the backslash is not one of those specified,
173: the backslash is ignored.
1.1 kstailey 174: .Pp
1.13 sobrado 175: .Ex -std gencat
1.1 kstailey 176: .Sh SEE ALSO
177: .Xr catclose 3 ,
178: .Xr catgets 3 ,
179: .Xr catopen 3
180: .Sh STANDARDS
181: The
1.5 deraadt 182: .Nm
183: utility is compliant with the
1.15 ! jmc 184: .St -p1003.1-2008
! 185: specification.
1.10 aaron 186: .Sh AUTHORS
1.11 jaredy 187: .An -nosplit
1.5 deraadt 188: This manual page by
189: .An Ken Stailey
190: updated and revised by
191: .An Terry Lambert .
192: .Sh BUGS
193: A message catalog file created from a blank input file can not be revised;
194: it must be deleted and recreated.