adv_cmds/gencat/gencat.1

   1 .\"     $OpenBSD: gencat.1,v 1.3 1997/06/11 15:39:54 kstailey Exp $
   2 .\"
   3 .\" Copyright (c) 1997 Ken Stailey
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. The name of the author may not be used to endorse or promote products
  14 .\"    derived from this software without specific prior written permission
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD: src/usr.bin/gencat/gencat.1,v 1.9 2001/11/23 14:37:27 dd Exp $
  28 .\"
  29 .Dd June 11, 1997
  30 .Dt GENCAT 1
  31 .Os
  32 .Sh NAME
  33 .Nm gencat
  34 .Nd NLS catalog compiler
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Ar "output-file"
  38 .Ar "input-files..."
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 utility merges the text NLS input files
  43 .Ar "input-files..."
  44 into a formatted message catalog file
  45 .Ar "output-file" .
  46 The file
  47 .Ar "output-file"
  48 will be created if it does not already exist.  If
  49 .Ar "output-file"
  50 does exist, its messages will be included in the new
  51 .Ar "output-file" .
  52 If set and message numbers collide, the new message text defined in
  53 .Ar "input-files..."
  54 will replace the old message text currently contained in
  55 .Ar "output-file" .
  56 .Sh INPUT FILES
  57 The format of a message text source file is defined below.  Note that
  58 the fields of a message text source line are separated by a single space
  59 character: any other space characters are considered to be part of the
  60 field contents.
  61 .Pp
  62 .Bl -tag -width 3n
  63 .It Li $set Ar n comment
  64 This line specifies the set identifier of the following messages until
  65 the next
  66 .Li $set
  67 or end-of-file appears.  The argument
  68 .Ar n
  69 is the set identifier which is defined as a number in the range
  70 [1, (NL_SETMAX)].  Set identifiers must occur in ascending order within
  71 a single source file, but need not be contiguous.  Any string following
  72 a space following the set identifier is treated as a comment.  If no
  73 .Li $set
  74 directive  is specified in a given source file, all messages will
  75 be located in the default message set NL_SETD.
  76 .It Li $del Ar n comment
  77 This line deletes messages from set
  78 .Ar n
  79 from a message catalog.  The
  80 .Ar n
  81 specifies a set number.  Any string following a space following the set
  82 number is treated as a comment.
  83 .It Li $ Ar comment
  84 A line beginning with
  85 .Li $
  86 followed by a space is treated as a comment.
  87 .It Ar m message-text
  88 A message line consists of a message identifier
  89 .Ar m
  90 in the range [1, (NL_MSGMAX)].  The
  91 .Ar message-text
  92 is stored in the message catalog with the set identifier specified by
  93 the last
  94 .Li $set
  95 directive, and the message identifier
  96 .Ar m .
  97 If the
  98 .Ar message-text
  99 is empty, and there is a space character following the message identifier,
 100 an empty string is stored in the message catalog.  If the
 101 .Ar message-text
 102 is empty, and if there is no space character following the message
 103 identifier, then the existing message in the current set with the
 104 specified message identifier is deleted from the catalog.  Message
 105 identifiers must be in ascending order within a single set, but
 106 need not be contiguous.  The
 107 .Ar message-text
 108 length must be in the range [0, (NL_TEXTMAX)].
 109 .It Li $quote Ar c
 110 This line specifies an optional quote character
 111 .Ar c
 112 which can be used to surround
 113 .Ar message-text
 114 so that trailing space or empty messages are visible in message
 115 source files.  By default, or if an empty
 116 .Li $quote
 117 directive is specified, no quoting of
 118 .Ar message-text
 119 will be recognized.
 120 .El
 121 .Pp
 122 Empty lines in message source files are ignored.  The effect of lines
 123 beginning with any character other than those described above is
 124 undefined.
 125 .Pp
 126 Text strings can contain the following special characters and escape
 127 sequences.  In addition, if a quote character is defined, it may be
 128 escaped as well to embed a literal quote character.
 129 .Pp
 130 .Bl -tag -width "\eooo" -offset indent -compact
 131 .It Li \en
 132 line feed
 133 .It Li \et
 134 horizontal tab
 135 .It Li \ev
 136 vertical tab
 137 .It Li \eb
 138 backspace
 139 .It Li \er
 140 carriage return
 141 .It Li \ef
 142 form feed
 143 .It Li \e\e
 144 backslash
 145 .It Li \eooo
 146 octal number in the range [000, 377]
 147 .El
 148 .Pp
 149 A backslash character immediately before the end of the line in a file
 150 is used to continue the line onto the next line, e.g.:
 151 .Pp
 152 .Dl 1 This line is continued \e
 153 .Dl on this line.
 154 .Pp
 155 If the character following the backslash is not one of those specified,
 156 the backslash is ignored.
 157 .Sh DIAGNOSTICS
 158 .Ex -std
 159 .Sh SEE ALSO
 160 .Xr catclose 3 ,
 161 .Xr catgets 3 ,
 162 .Xr catopen 3
 163 .Sh STANDARDS
 164 The
 165 .Nm
 166 utility is compliant with the
 167 .St -xpg4
 168 standard.
 169 .Sh AUTHORS
 170 .An -nosplit
 171 This manual page was originally written by
 172 .An Ken Stailey
 173 and later revised by
 174 .An Terry Lambert .
 175 .Sh BUGS
 176 A message catalog file created from a blank input file cannot be revised;
 177 it must be deleted and recreated.