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