./_Man_SunOS_4.1.3_html/html8/installtxt.8.html

Manual page for INSTALLTXT(8)

installtxt, gencat - create a message archive

SYNOPSIS

/usr/etc/installtxt [[-]d|c|r|t|x|i [ ouvs ]] ] message-archive... [ source-message-file ]

/usr/etc/gencat catfile msgfile...

DESCRIPTION

installtxt converts each source-message-file into a binary format message archive. At the same time, if necessary, installtxt maintains groups of files (member files) combined into a single message archive. installtxt is normally used to create and update message archives used by the run-time message handling facility gettext.3

gencat performs the same function as installtxt, but supports the X/Open catalog source format.

installtxt creates the message archive in message-archive. If the message archive does not exist, it is created by the -c option. source-message-file contains source versions of the target strings. On successful completion of an update operation of installtxt, the message archive will have been updated with details of the formatted version of each source-message-file. If message-archive does not contain the full pathname of the run-time location of the message catalog, it will have to be moved to the appropriate locale directory before applications using the archive are activated.

gencat merges the message text source files ( msgfile...) into a formatted message catalog catfile. catfile is created if it does not already exist. If catfile does exist, its messages are included in the new catfile. If set and message numbers collide, the new message-text defined in msgfile will replace the old message text currently contained in catfile. The output formats of both message_archive and catfile are the same. However it should be noted that on a per-application basis, it is not intended that the output forms of these two utilities should be mixed, and the consequence of doing so is undefined.

OPTIONS

The following options and modifiers apply to installtxt only. For installtxt you must indicate only one of: c, d, r, t, or, x, which may be followed by one or more Modifiers, o, u, or , v.

The options are:

c: Create. The member file called source-message-file is being made for the first time in the message archive. It should not exist already.
d: Delete the named member files from message archive. Note that individual messages can be deleted by entering an empty value after the message-id selecting the message to be deleted. With the v option these deletions are notified on the standard output.
r: Replace the named member files in the message archive. This allows the existing message archive to be merged with new versions of messages. No new message will be added to the message archive unless each message-tag in the source-message-file is unique in the active domain. If the member file contains a message-tag that is not unique within the active domain, installtxt will fail and the contents of the active message archive will not be altered.
t: Table of contents. Produces a list on the standard output of all member files in message_archive.
x: Extract. If no names are given, all member files in the message archive are extracted into the current directory; if names are given, only those files are extracted. In neither case does x alter the message archive. The extracted member files will be returned in their original source format. It is possible for the -x option to lose comments that were contained in the original source message file. In addition, overlong lines may be escaped (using \n) at a point that is different from the original source, although the end result will logically be the same string.

Modifiers

o: Old date. When member files are extracted with the x option, set the ``last modified'' date to the date recorded in the message archive.
u: Update. Replace only those member files that have changed since they were put in the message archive. Used with the r option.
v: Verbose. When used with the c, r, or d option, give a file-by-file description of the creation of a new message archive file from the old version and the constituent member files. When used with x, give a file-by-file description of the extraction of message archive member files. When used with t, print information about the size and creation date of the message archive, as well as a count of the number of target strings in the message-archive.

USAGE

source-message-file consists of one or more lines of text, with each line containing either a comment, a directive or a text line. The format of a comment line is:

            "$ %s", comment

A line beginning with a dollar sign ($), followed by a blank character streated as a comment line. The format of directives is:

            "$%s %s", control-type, value

Directives should be directly preceded by a dollar sign ($), and followed by an optional value. There is one blank character between the directive and its value. The following directives are recognized:

$separator c: This directive specifies an optional separator character that will subsequently be used in the following text lines to separate the message identifier from the target string. There is one blank character between separator and the separator character itself. If this line is absent then the default separator is the blank character. Only the first occurrence of this character on one text line will be interpreted, for example:

     $separator :
     12345:Bonjour: Mon ami

: would declare the message identifier to be 12345, the target string would contain the second ":".
$domain domain: This directive states that all following target strings are contained within a domain of the object message file as described by domain. domain can be any string of up to {PATH_MAX} bytes in length.
$quote c: This directive specifies an optional quote character c, which can be used to surround both message_string and message_identifier . By default, or if an empty $quote directive is supplied, no quoting of message_string will be recognized. If the $quote directive is given then all message strings must contain pairs of quotes, although quotes around the message_identifier are still optional after the directive.

The format of the text line is:

"%s%s%s", message_identifier, separator_character, message_string

Each line defines a message identifier and a target string pair.

Empty lines in a source text file are ignored. If a message_identifier starts with a dollar ($) character, then that dollar character must be escaped with a backslash (\$). Any other form of input line syntax is illegal and will cause installtxt to exit with the error value.

Message strings and message identifiers can contain the special characters and escape sequences as defined in the following table:

Description       Symbol
newline           \n
tab               \t
vertical-tab      \v
backspace         \b
carriage-return   \r
form-feed         \f
backslash         \\
bit pattern       \ddd

The escape sequence \ddd consists of backslash followed by 1, 2 or 3 octal digits, which are used to specify the value of the desired character. If message_identifier contains the separator character then it must be escaped with a backslash (\) character. If the character following a backslash is not one of those specified, the effect is unspecified.

Backslash, \, followed by a NEWLINE character is used to continue an individual string on the following line. Both message_identifier and message_string may be continued over lines in this way. message_string is stored in object_file in an implementation specific way. If message_string is empty, and separator is present, a null string is stored in object_file.

msgfile must be in the X/Open gencat format.

EXAMPLES

# /bin/sh script      
# The following creates a message archive in the file messages.general
installtxt -cv messages.general input
#

FILES

/etc/locale/LC_MESSAGES/locale/domain: standard private location for message archive/catalog in locale locale and domain domain
/usr/share/lib/locale/LC_MESSAGES: standard shared location for message archive/catalog in locale locale and domain domain