'\"!  tbl | mmdoc
'\"macro stdmacro
.if n .pH g1.gencat @(#)gencat	40.4 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} gencat 1 "" "\&"
.if \nX=1 .ds x} gencat 1 ""
.if \nX=2 .ds x} gencat 1 "" "\&"
.if \nX=3 .ds x} gencat "" "" "\&"
.TH \*(x}
.SH "NAME"
.br
\f4gencat\f1 \- generate a formatted message catalogue
.SH "SYNOPSIS"
\f4gencat\f1
\f1[\f4-m\f1]
.I catfile
.I msgfile
\ .\|.\|.
.SH "DESCRIPTION"
.br
The
\f4gencat\f1
utility
merges the message text source file(s) 
msgfile 
into a formatted message database 
\f2catfile\f1.  
The database
\f2catfile\f1
will be created if it does not already exist.  
If 
\f2catfile\f1
does exist
its messages will be included in the new 
\f2catfile\f1.
If set and message numbers collide, 
the new message-text defined in
\f2msgfile\f1
will replace the old message text currently contained in
\f2catfile\f1.
The message text source file (or set of files) input to
\f4gencat\f1
can contain either set and message numbers or simply
message numbers, in which case the set \f4NL_SETD\fP [see \f4nl_types\fP(5)]
is assumed.
.PP
The format of a message text source file is defined as follows.
Note that the fields of a message text source line are separated 
by a single ASCII space or tab character.
Any other ASCII spaces or tabs are considered as being part
of the subsequent field.
.TP 5
\f4$set  n comment\fP
.br
Where \f2n\f1 specifies the set identifier of the 
following messages until the next 
\f4$set\f1,
\f4$delset\f1
or end-of-file appears.  
\f2n\f1 must be  a number in the range (1\-{\f4NL_SETMAX\f1}). 
Set identifiers 
within a single source file need not be contiguous.  
Any string following the set identifier is treated as a comment.
If no
\f4$set\f1
directive is specified in a message text source file, all messages
will be located in 
the default message set
\f4NL_SETD\f1.
.P
.TP 5
\f4$delset  n comment\f1
.br
Deletes message set 
\f2n\f1
from an 
existing message catalogue.
Any string following the set number is treated as a comment.
.P
(Note:  if \f2n\f1 is not a valid set it is ignored.)
.P
.TP 5
\f4$ comment\f1
.br
A line beginning with a dollar symbol $ followed by an ASCII space or
tab character is treated as a comment.  
.TP 5
\f4m message-text\f1
.br
The 
\f2m\f1
denotes the message identifier, 
which is a number in the range (1-{\f4NL_MSGMAX\f1}). 
The
message-text 
is stored in the message catalogue 
with the set identifier 
specified by the last
\f4$set \f1
directive, and with message identifier
\f2m\f1.
If the 
message-text 
is empty, 
and an ASCII space or tab field separator is present, an empty string is
stored in the message catalogue.  If a message source line has a
message number, but neither a field separator nor 
message-text ,
the existing message with that number (if any) is deleted from the
catalogue.
Message identifiers 
need not be contiguous.
The length of
message-text 
must be in the range (0\-{\f4NL_TEXTMAX\f1}).
.P
.TP 5
\f4$quote c\f1
.br
This line specifies an optional quote character
\f2c\f1,
which can be used to surround
message-text 
so that trailing spaces or null (empty) messages are visible in a 
message source line.
By default, or if an empty
\f4$quote\f1
directive is supplied, no quoting of
message-text 
will be recognized.
.P
Empty lines in a message text source file are ignored. 
.P
.br
.ne 15
Text strings can contain the special characters and 
escape sequences defined in the following table:
.TS
center box;
a a a
a ap-1 a.
Description	Symbol	Sequence
_
newline	NL(LF)	\en
horizontal tab	HT	\et
vertical tab	VT	\ev
backspace	BS	\eb
carriage return	CR	\er
form feed	FF	\ef
backslash	\e	\e\e
bit pattern	ddd	\eddd
.TE
.P
The escape sequence 
\f4\eddd\f1
consists of backslash followed by 1, 2 or 3 octal digits, 
which are taken to specify the value of the desired character.  
If the character following a backslash is not one of those specified, 
the backslash is ignored.  
.P
Backslash followed by an ASCII newline character is also used 
to continue a string on the following line.  
Thus, the following two lines describe a single message string:
.br
.P
.DS I
.ft 4
.nf
    1 This line continues \e
    to the next line
.fi
.ft 1
.DE
.P
which is equivalent to:
.P
.br
.DS I
.ft 4
.nf
    1 This line continues to the next line
.fi
.ft 1
.DE
.P
.SH "  NOTES"
.sp
This version of gencat is built upon the 
\f4mkmsgs\f1
utility. The gencat database
comprises of two files \f2catfile\f4.m\fP which is an 
\f4mkmsgs\f1
format catalogue and
the file 
.I catfile
which contains the information required to translate
an set and message number into a simple message number which can be used
in a call to \f4gettxt\fP. 
.sp
Using \f4gettxt\f1 constrains the catalogues to be located in a subdirectory
under \f4/usr/lib/locale\f1. This restriction is lifted by placing only a symbolic
link to the catalogue in the directory \f4/usr/lib/locale/Xopen/LC_MESSAGES\fP
when the catalogue is opened. It is this link that \fPgettxt\f1 uses when 
attempting to access the catalogue. The link is removed when the catalogue is closed
but occasionally as applications exit abnormally without closing catlogues
redundant symbolic links will be left in the directory. 
.sp
For compatibility with previous version of \f4gencat\fP released in a number
of specialized internationalization products, the \f4-m\f1 option is supplied.
This option will cause gencat to build a single file 
.I catfile 
which is compatible
with the format catalogues produced by the earlier versions. The retrieval
routines detect the type of catalogue they are using and will act
appropriately.
.sp
.SH "SEE ALSO"
\f4mkmsgs\f1(1)
.br
\f4catopen\f1(3C),
\f4catgets\f1(3C),
\f4catclose\f1(3C),
\f4gettxt\f1(3C),
\f4nl_types\f1(5) in the \f2Programmer's Reference Manual\fP.
.P
