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