path: root/usr/src/man/man1/msggen.1

'\" te
.\" Copyright (c) 2000-2007 AT&T Knowledge Ventures
.\" To view license terms, see http://www.opensource.org/licenses/cpl1.0.txt
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc.
.TH MSGGEN 1 "Oct 9, 2007"
.SH NAME
msggen \- generate a machine independent formatted message catalog
.SH SYNOPSIS
.LP
.nf
\fBmsggen\fR [\fB-fls\fR] \fIcatfile\fR [\fImsgfile\fR]
.fi

.SH DESCRIPTION
.sp
.LP
\fBmsggen\fR merges the message text source file \fImsgfile\fR into a machine
independent formatted message catalog \fIcatfile\fR. The file \fIcatfile\fR is
created if it does not already exist. If \fIcatfile\fR does exist, its messages
are included in the new \fIcatfile\fR. If set and message numbers collide, the
new message text defined in \fImsgfile\fR replaces the old message text
currently contained in \fIcatfile\fR.
.sp
.LP
Non-ASCII characters must be UTF-8 encoded. \fBiconv\fR(1) can be used to
convert to/from UTF-8.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.br
.na
\fB\fB--format\fR\fR
.ad
.RS 12n
List the \fBprintf\fR(3C) format signature for each message in \fIcatfile\fR. A
format signature is one line containing one character for each format
specification:
.sp
.ne 2
.na
\fB\fBc\fR\fR
.ad
.RS 5n
char
.RE

.sp
.ne 2
.na
\fB\fBd\fR\fR
.ad
.RS 5n
double
.RE

.sp
.ne 2
.na
\fB\fBD\fR\fR
.ad
.RS 5n
long double
.RE

.sp
.ne 2
.na
\fB\fBf\fR\fR
.ad
.RS 5n
float
.RE

.sp
.ne 2
.na
\fB\fBh\fR\fR
.ad
.RS 5n
short
.RE

.sp
.ne 2
.na
\fB\fBi\fR\fR
.ad
.RS 5n
int
.RE

.sp
.ne 2
.na
\fB\fBj\fR\fR
.ad
.RS 5n
long long
.RE

.sp
.ne 2
.na
\fB\fBl\fR\fR
.ad
.RS 5n
long
.RE

.sp
.ne 2
.na
\fB\fBp\fR\fR
.ad
.RS 5n
void*
.RE

.sp
.ne 2
.na
\fB\fBs\fR\fR
.ad
.RS 5n
string
.RE

.sp
.ne 2
.na
\fB\fBt\fR\fR
.ad
.RS 5n
ptrdiff_t
.RE

.sp
.ne 2
.na
\fB\fBz\fR\fR
.ad
.RS 5n
size_t
.RE

.sp
.ne 2
.na
\fB\fB?\fR\fR
.ad
.RS 5n
unknown
.RE

.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.br
.na
\fB\fB--list\fR\fR
.ad
.RS 12n
List \fIcatfile\fR in UTF-8 msgfile form.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.br
.na
\fB\fB--set\fR\fR
.ad
.RS 12n
Convert the \fIcatfile\fR to a message set number and print the number on the
standard output.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIcatfile\fR\fR
.ad
.RS 11n
Machine independent formatted message catalog file.
.RE

.sp
.ne 2
.na
\fB\fImsgfile\fR\fR
.ad
.RS 11n
Message text source file.
.RE

.SH USAGE
.sp
.LP
Message text source files are in \fBgencat\fR(1) format, defined as follows.
The fields of a message text source line are separated by a single blank
character. Any other blank characters are considered to be part of the
subsequent field. The \fBNL_*\fR constants are defined in one or both of
\fB<limits.h>\fR and \fB<nl_types.h>\fR\&.
.sp
.ne 2
.na
\fB\fB$\fR \fIcomment\fR\fR
.ad
.sp .6
.RS 4n
A line beginning with a \fB$\fR followed by a blank character is treated as a
comment.
.RE

.sp
.ne 2
.na
\fB\fB$delset\fR \fIn comment\fR\fR
.ad
.sp .6
.RS 4n
This line deletes message set \fIn\fR from an existing message catalog. \fIn\fR
denotes the set number \fB[1, NL_SETMAX]\fR. Any text following the set number
is treated as a comment.
.RE

.sp
.ne 2
.na
\fB\fB$quote\fR \fIc\fR\fR
.ad
.sp .6
.RS 4n
This line specifies an optional quote character \fIc\fR, which can be used to
surround message-text so that trailing spaces or empty messages are visible in
a message source line. By default, or if an empty \fB$quote\fR directive is
supplied, no quoting of message-text is recognized.
.RE

.sp
.ne 2
.na
\fB\fB$set\fR \fIn comment\fR\fR
.ad
.sp .6
.RS 4n
This line specifies the set identifier of the following messages until the next
\fB$set\fR or end-of-file (\fBEOF\fR) appears. \fIn\fR denotes the set
identifier, which is defined as a number in the range \fB[1, NL_SETMAX]\fR. Set
numbers need not be contiguous. Any text following the set identifier is
treated as a comment. If no \fB$set\fR directive is specified in a message text
source file, all messages are located in message set 1.
.RE

.sp
.ne 2
.na
\fB\fB$translation\fR \fIidentification YYYY-MM-DD\fR\fB[,...]\fR\fR
.ad
.sp .6
.RS 4n
Append translation information to the message catalog header. Only the newest
date for a given identification is retained in the catalog. Multiple
translation lines are combined into a single, comma-separated list.
.RE

.sp
.ne 2
.na
\fB\fBm\fR \fImessage-text\fR\fR
.ad
.sp .6
.RS 4n
\fBm\fR denotes the message identifier, which is defined as a number in the
range \fB[1, NL_MSGMAX]\fR. The message-text is stored in the message catalogue
with the set identifier specified by the last \fB$set\fR directive, and with
message identifier \fBm\fR. If the message-text is empty, and a blank character
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. There are no
\fImessage-text\fR length restrictions.
.RE

.SH EXIT STATUS
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
One or more specified jobs does not exist.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBmsggen\fR
.sp
.LP
The following example generates a message catalog \fBxxx\fR from the message
file \fBxxx.msg\fR:

.sp
.in +2
.nf
example% msggen xxx xxx.msg
.fi
.in -2
.sp

.SH AUTHORS
.sp
.LP
Glenn Fowler, \fBgsf@research.att.com\fR
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Volatile
.TE

.SH SEE ALSO
.sp
.LP
.BR gencat (1),
.BR iconv (1),
.BR msgcc (1),
.BR printf (3C),
.BR attributes (7)