unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



gencat(1)							    gencat(1)



NAME

  gencat - Creates and modifies	a message catalog

SYNOPSIS

  gencat catalog_file source_file...

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  gencat:  XCU5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

OPERANDS

  catalog_file
      Specifies	the message catalog to be modified or created. You can sub-
      stitute -	(a dash) for this operand to direct command results to the
      standard output rather than to a file.

      [Tru64 UNIX]  The	convention is to include the .cat extension on the
      filename of a message catalog.

  source_file...
      Specifies	the message text source	file, or files,	used to	modify or
      create the message catalog. You can substitute - (a dash)	for this
      operand to direct	gencat to accept message source	data from the stan-
      dard input.

      [Tru64 UNIX]  You	can also omit the source_file operand to direct	gen-
      cat to accept message source data	from the standard input.  This exten-
      sion is supported	only to	ensure backward	compatibility for existing
      scripts.	For new	scripts, it is recommended that	you specify - (a
      dash) for	source_file when you want gencat to accept message source
      data from	the standard input.

      [Tru64 UNIX]  The	convention is to include the .msg extension on the
      filename of a message text source	file.

DESCRIPTION

  The gencat command creates or	modifies a message catalog from	a message
  text source file.

  A message text source	file is	a text file that you create to hold messages
  printed by your program.  You	can use	any text editor	to enter messages
  into the text	source file.  Messages can be grouped into sets, generally to
  represent functional subsets of your program.	 Each message has a numeric
  identifier, which must be unique within its set.  The	message	text source
  file can also	contain	commands recognized by gencat for manipulating sets
  and individual messages.

  [Tru64 UNIX]	Programmers can	use symbolic names rather than numeric con-
  stants to refer to messages within programs.	The gencat utility does	not
  recognize symbolic names, but	the mkcatdefs:

    +  Accepts messages	preceded by a symbolic name and	assigns	a numeric
       value to	each

    +  Creates a header	file that applications can include to map message
       symbols to their	numeric	values

  [Tru64 UNIX]	Therefore, the most convenient way to generate a message
  catalog is to	pass your symbolic constants and associated messages through
  mkcatdefs and	then pass its output to	gencat.

  If a message catalog with the	name catalog_file exists, gencat modifies it
  according to the statements in the message source files. If the catalog
  does not exist, gencat creates the catalog with the name catalog_file.

  You can specify any number of	message	text source files. The gencat command
  processes multiple source files one after the	other in the sequence that
  you specify them.  Each successive source file modifies the catalog. If you
  specify - (a dash) in	place of source_file, the gencat command accepts mes-
  sage source data from	the standard input. Note that you can specify a	-
  (dash) for the catalog file (standard	output), the source file (standard
  input), or both.

  The source_file can contain the following commands.  Each initial keyword
  or number must be followed by	white space.  The gencat utility ignores any
  line beginning with a	space, a tab, or a $ (dollar sign) character followed
  by a space, a	tab, or	a newline character. Thus, you can use these
  sequences to start comments in your source_file.  Blank lines	are also
  ignored.  Finally, you can place comments on the same	line after the $del-
  set, $quote, $len, or	$set commands, because the gencat utility ignores
  anything following the preceding syntax elements.

  message_number text
      Inserts text as a	message	with the identifier message_number.  Numbers
      must be ascending	within each set: you can skip a	number,	but you	can-
      not go back to add a missing number or replace an	existing number	dur-
      ing a gencat session.

      The value	for message_number must	be in the range	1 to NL_MSGMAX,	which
      is defined in the	<&lt;limits.h>&gt; header file.

      If the message text is empty, and	a space	or tab field separator is
      present, an empty	string is stored in the	message	catalog. If a message
      source line has a	message	number,	but neither a field separator nor
      message text, the	existing message within	that number (if	any) is
      deleted from the catalog.

      Refer to the following description of $len for a discussion of the
      length limits that apply to message text.

  $delset set_number [comment]
      Deletes the set of messages indicated by set_number.

      The set_number parameter must be in the range 0 to NL_SETMAX, which is
      defined in the <&lt;limits.h>&gt;	header file.

  $quote character [comment]
      Sets the quote character to character.  See the explanation later	in
      this section.

  $len [max_length] [comment]
      [Tru64 UNIX]  Sets the maximum length allowed for	messages in your
      catalog. If this command is not used, or if you use it without the
      max_length argument, the maximum length is 8192 bytes (the value set by
      NL_TEXTMAX, which	is defined in the <&lt;limits.h>&gt; header file). XCU does
      not include the $len command and specifies that the length of message
      text be in the range 0 to	NL_TEXTMAX.

      [Tru64 UNIX]  If gencat does not encounter a digit immediately follow-
      ing the single nonblank character	separator between $len and its first
      argument,	the command ignores the	rest of	the line. Therefore, if	you
      intend to	include	the optional max_length	parameter, make	sure only one
      space or tab character separates the number from $len.

  $set set_number [comment]
      Indicates	that all messages entered after	this command are placed	in
      the set indicated	by set_number.	You can	change the set by entering
      another $set command.  However, set numbers must be entered in ascend-
      ing order; you cannot go back to a lower-numbered	set during the gencat
      session. If the command is not used, the default set number is the
      value of NL_SETD in the <&lt;nl_types.h>&gt; header file.	 This value is
      vendor-defined.  On this operating system, the NL_SETD value is 1.

      The set_number parameter must be in the range 1 to NL_SETMAX, which is
      defined in the <&lt;limits.h>&gt;	header file.

  A line beginning with	a digit	marks a	message	to be included in the cata-
  log. You can specify any amount of white space between the message ID
  number and the message text; however,	one space or tab character is recom-
  mended when the message text is not delimited	by quotes. When	message	text
  is not quoted, gencat	treats additional white	space as part of the message.
  When message text is quoted, gencat ignores all spaces or tabs between the
  message ID and the first quotation character.

  Escape sequences, like those recognized by the C language, can be used in
  text;	these are listed after the commands. Use a \ (backslash) character to
  continue message text	on the following line.

  The gencat command does not accept symbolic identifiers.

  [Tru64 UNIX]	You must run the mkcatdefs command if you want to use sym-
  bolic	identifiers for	messages in your program.

  The Escape character \ (backslash) can be used to include the	following
  special characters in	the message text:

  \n  Inserts a	newline	(NL or LF).

  \t  Inserts a	horizontal tab (HT).

  \v  Inserts a	vertical tab (VT).

  \b  Performs a backspace function (BS).

  \r  Inserts a	carriage return	(CR).

  \f  Inserts a	form feed (FF).

  \\  Inserts a	backslash (\).

  \ddd
      Inserts the single-byte character	associated with	the octal value
      represented by the octal digits ddd. One,	two, or	three octal digits
      can be specified;	however, you must include leading zeros	if the char-
      acters following the octal digits	are also valid octal digits.  For
      example, the octal value for $ (dollar sign) is 44.  To insert $5.00
      into a message, use \0445.00, not	\445.00, or the	5 will be parsed as
      part of the octal	value.

  \xdd or \xdddd
      [Tru64 UNIX]  Inserts the	character associated with the hexadecimal
      value represented	by the hexadecimal digits. The gencat command inserts
      a	single-byte character when you specify two valid digits	(dd) and a
      double-byte character when you specify four valid	digits (dddd). See
      \ddd for a way to	avoid parsing errors when the hexadecimal value	pre-
      cedes an actual digit.

  You can also include printf()	conversion specifications in messages that
  are printed by the printf() family of	calls in C code	or by the printf com-
  mand in shell	scripts.

  [Tru64 UNIX]	If you display a message from a	shell script with the dspmsg
  command, the only conversion specifications that can be used in the message
  are %s and %n$s.

EXIT STATUS

  On successful	completion, the	gencat command returns 0 (zero); on error,
  the command returns a	value greater than zero. When gencat returns an	error
  value, no action is taken on any commands, and an existing catalog is	left
  unchanged.

ERRORS

  [Tru64 UNIX]	You can	enter the following command to display the messages
  returned by the gencat command:

       % dspcat	msgfac.cat | grep gencat

EXAMPLES

   1.  To use the $set command in a source file	to give	a group	of messages a
       set number, enter:
	    $set 10 Communication Error	Messages

       The message set number is 10.  All messages following the $set command
       are assigned that set number, up	until the next occurrence of a $set
       command.	 (Set numbers must be assigned in ascending order, but need
       not be contiguous.  Large gaps in the number sequence are discouraged
       in order	to increase efficiency and performance.	 There is no perfor-
       mance advantage to using	more than one set number in a catalog.)

       You can include a comment in the	$set command, but it is	not required.

   2.  To use the $delset command to remove all	of the messages	belonging to
       the specified set from a	catalog, enter:
	    $delset 10 Communication Error Messages

       The message set is specified by n. The $delset command must be placed
       in the proper set number	order with respect to any $set commands	in
       the same	source file.  You can include a	comment	in the $delset com-
       mand also.

   3.  Enter the message text and assign message ID numbers as follows:
	    12 "file removed"

       This command assigns the	message	ID number 12 to	the text that follows
       it.

       You must	leave at least one space or tab	character between the message
       ID number and the message text, but you can include more	spaces or
       tabs if you prefer. If you do include more spaces or tabs, they will
       be ignored when message text is quoted and considered part of the text
       when message text is not	quoted.

       Message numbers must be in ascending order within a single message
       set, but	need not be contiguous.

       All text	following the message number is	included as message text, up
       to the end of the line.	If you place the escape	character \
       (backslash) as the last character on the	line, the message text con-
       tinues on the following line.  Consider the following example:


	    This is the	text associated	with \
	    message number 5.

       These two lines define the following single-line	message:


	    This is the	text associated	with message number 5.

   4.  The following example shows the effect of a quote character:


	    $quote "   Use a double quote to delimit message text
	    $set 10	       Message Facility	- Quote	command	messages
	    1 "Use the $quote command to define	a character \
	    \n for delimiting message text" \n
	    2 "You can include the \"quote\" character in a message \n \
	    by placing a \\ (backslash)	in front of it"	\n
	    3 You can include the "quote" character in a message \n \
	    by having another character	as the first nonspace \
	    \n character after the message ID number \n
	    $quote
	    4 You can disable the quote	mechanism by \n	\
	    using the $quote command without \n	a character \
	    after it \n

       In this example,	the $quote command defines the " (double quote)	as
       the quote character. The	quote character	must be	the first nonspace
       character following the message number. Any text	following the next
       occurrence of the quote character is ignored.

       The example also	shows two ways the quote character can be included in
       the message text:

	 +  Place a \ in front of the quote character.

	 +  Use	some other character as	the first nonspace character follow-
	    ing	the message number. This disables the quote character only
	    for	that message.

       The example also	shows the following:

	 +  A \	is still required to split a quoted message across lines.

	 +  To display a \ in a	message, you must place	another	\ in front of
	    it.

	 +  You	can format your	message	with a newline character by using \n.

	 +  If you use the $quote command with no character argument, you
	    disable the	quote mechanism.




ENVIRONMENT VARIABLES

  The following	locale environment variables (see i18n_intro(5)	and
  l10n_intro(5)) affect	gencat operation:

  LANG
      Provides a default value for locale category variables that are not
      set. If any of these variables contains an invalid setting, the gencat
      command behaves as if none of them were defined.

  LC_ALL
      If set to	a non-empty string, overrides values in	all locale variables,
      including	LANG.

  LC_CTYPE
      Determines the locale for	the interpretation in text data	of byte
      sequences	as characters.

  LC_MESSAGES
      Determines the locale used for diagnostic	messages.

  NLSPATH
      Determines the location of message catalogs for the processing of
      LC_MESSAGES.

SEE ALSO

  Commands:  dspcat(1),	dspmsg(1), extract(1), mkcatdefs(1), printf(1),	run-
  cat(1), strextract(1), strmerge(1), trans(1)

  Functions:  catclose(3), catgets(3), catopen(3)

  Files:  patterns(4)

  Others:  i18n_intro(5), l10n_intro(5), iconv_intro(5), standards(5)

  Writing Software for the International Market