1.\" $NetBSD: gencat.1,v 1.12 2009/03/09 19:24:32 joerg 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 44The 45.Nm 46utility generates a formatted message catalog 47.Ar catfile 48from one or more message source text files 49.Ar msgfile . 50The file 51.Ar catfile 52is created if it does not already exist. 53If 54.Ar catfile 55does exist, its messages are included in the new 56.Ar catfile . 57The new message text defined in 58.Ar msgfile 59replaces the old message text currently in 60.Ar catfile 61when the set and message numbers match. 62.Pp 63The generated message catalog contains message 64strings that will be retrieved using the 65.Xr catgets 3 66library call. 67These messages are dynamically loaded by the 68Native Language Support (NLS) library at run time. 69Error messages are grouped into sets, and a program can load a 70particular set depending on which type, or language, of messages 71is desired. 72.Ss Message Text Source File Format 73The message text source files are text files in the format described below. 74Note that the fields of a message text source line are separated by 75space 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 82Determines the set identifier to be used for all subsequent messages 83until the next 84.Li $set 85or end-of-file. 86The 87.Ar n 88is the set identifier which is defined as a number in the range 89.Bo 1 , 90.Dv NL_SETMAX Bc . 91Set identifiers within a single source file need not be contiguous. 92Any string following the set identifier is treated as a comment. 93If no 94.Li $set 95directive is specified in a message text source file, 96all messages will be located in the default message set 97.Dv NL_SETD . 98.It Li $delset Ar n comment 99Removes message set 100.Ar n 101from the catalog. 102The 103.Ar n 104is a set identifier in the range 105.Bo 1 , 106.Dv NL_SETMAX Bc . 107If a message set was created earlier in the 108current file, or in a file previously read by the 109.Nm 110command, this directive will remove it. 111Any string following the set identifier is treated as a comment. 112.It Li $ Ar comment 113A line beginning with 114.Li $ 115followed by a space or tab character is treated as a comment. 116.It Ar m message-text 117A message line consists of a message identifier 118.Ar m 119in the range 120.Bo 1 , 121.Dv NL_MSGMAX Bc 122and the 123.Ar message-text . 124The 125.Ar message-text 126is read until the end of the line or a quote character 127(if one is specified). 128The 129.Ar message-text 130is stored in the message catalog with 131the set identifier specified by the last 132.Li $set 133directive, and the message identifier 134.Ar m . 135If the 136.Ar message-text 137is empty and there is a space or tab character 138following the message identifier, 139an empty string is stored in the message catalog. 140If no 141.Ar message-text 142is provided, 143and if there is no space or tab character following the message 144identifier, 145the message with the message identifier 146.Ar m 147in the current set is removed from the catalog. 148Message identifiers need not be contiguous within a single set. 149The length of 150.Ar message-text 151must be in the range 152.Bo 0 , 153.Dv NL_TEXTMAX Bc . 154.It Li $quote Ar c 155Sets an optional quote character to be used around the 156.Ar message-text . 157The quote character 158.Ar c 159may be any character other than white space. 160If this is specified, then messages must begin and end with the 161quote character. 162.\" XXX Remove next sentence when code is fixed for POSIX conformance. 163This 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. 167By default no quote character is used. 168If an empty 169.Li $quote 170directive is specified, then the current quote character is unset. 171.El 172.Pp 173Empty lines 174.\" XXX Remove next line when the code is fixed for POSIX conformance. 175and leading blanks 176in a message text source file are ignored. 177Any line beginning with any character other than those 178described above is ignored as a syntax error. 179.Pp 180Text message strings may contain any characters and 181the 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 195A bit pattern, 196.Li \eddd , 197consists of a backslash followed by 198one, two, or three octal digits representing the value of the character. 199The current quote character, if defined, may be escaped with a backslash 200to generate the quote character. 201Any character following the backslash ('\e') other than those specified 202is ignored. 203.Pp 204A backslash at the end of the line continues the message onto the next line. 205The 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 210Producing 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 228The Native Language Support (NLS) message catalog facility was 229contributed by 230.An J.T. Conklin 231.Aq jtc@NetBSD.org . 232This page was originally written by 233.An Kee Hinckley 234.Aq nazgul@somewhere.com . 235