.\" $NetBSD: src/usr.bin/gencat/gencat.1,v 1.8 2003/05/02 08:35:42 gmcgarry Exp $
.\"
.\" Written by Kee Hinckley <nazgul@somewhere.com>
.\"
.Dd April 29, 1999
.Dt GENCAT 1
.Os
.Sh NAME
.Nm gencat
.Nd generates a Native Language Support (NLS) message catalog file
.Sh SYNOPSIS
.Nm
.Ar catalog-file
.Ar message-file
.Op Ar message-file ...
.Sh DESCRIPTION
The
.Nm
command reads one or more files containing message strings that will
be displayed using the
.Xr catgets 3
library call.
From these files it generates a message catalog which
is loaded dynamically by the Native Language Support (NLS) library at run time.
.Pp
The message description files are text files in the format described below.
.Pp
The message catalog file is a binary file.
If it already exists, it will be truncated when
.Nm
is run.
.Pp
Error messages are grouped into sets, and a program can load a
particular set depending on which type, or language, of messages
is desired.
.Sh MESSAGE FILE FORMAT
Empty lines and leading blanks are ignored.
.Bl -tag -width "NN message"
.It Em "$set NN"
Determines the set to be used for all subsequent messages.
.Ar "NN"
is an integer greater than 0.
.It Em "$delset NN"
Removes a set from the catalog.
.Ar "NN"
is an integer greater than 0.
.Pp
If a set was created earlier in the
current file, or in a file previously read by the
.Nm
command, this command will remove it.
.It Em "$quote C"
Sets a quote character to be used around the messages.
.Ar "C"
may be any character other than white space.
.Pp
If this is specified, then messages must begin and end with the
quote character.
By default no quote character is used.
If none is specified, then the current quote character is unset.
This is useful when messages must contain leading white space.
.It Em "NN message"
Defines a message.
.Ar "NN"
is an integer greater than 0.
.Pp
The message is read until the end of the line or a quote character (if one is
specified).
If no message is provided, the message with the number
.Ar "NN"
is removed from the catalog.
If no "set" has been created, this command generates an error.
.El
.Pp
Messages may contain any characters, however the "\\"
is special as an escape character, where the following instances
are allowed:
.Bd -literal -offset indent
\&\\\\	Generates a single backslash.
\&\\n	Generates a newline (as defined by the C compiler).
\&\\t	Generates a tab (as defined by the C compiler).
\&\\v	Generates a vertical tab (as defined by the C compiler).
\&\\b	Generates a backspace (as defined by the C compiler).
\&\\r	Generates a carriage return (as defined by the C compiler).
\&\\f	Generates a form feed (as defined by the C compiler).
\&\\NNN	Generates the character corresponding to the specified
	octal number.
\&\\EOL	A backslash at the end of line continues the message onto
	the next line.
\&\\quote	A backslash preceding the current quote character generates
	the quote character.
.Ed
.Sh SEE ALSO
.Xr catclose 3 ,
.Xr catgets 3 ,
.Xr catopen 3 ,
.Xr nls 7
.Sh AUTHORS
.An -nosplit
The Native Language Support (NLS) message catalog facility was
contributed by
.An J.T. Conklin
.Aq jtc@NetBSD.org .
This page was written by
.An Kee Hinckley
.Aq nazgul@somewhere.com .