manual/man-db/original/man1/gencat.1

   1 .TH GENCAT 1 "15 August 1994"
   2 .SH NAME
   3 gencat \- generate a message catalog from a set of message files
   4 .SH SYNOPSIS
   5 .B gencat [-new] [-lang C|C++|ANSIC] catfile msgfile [-h <header-file>]
   6 .SH DESCRIPTION
   7 .B gencat
   8 is the software used to compile message files into message
   9 catalogs.  It can also be used to generate a header file from the message files
  10 which can then be included in the original source code.  The benefit of including this
  11 .B gencat
  12 generated header file is that it allows the programmer to use
  13 descriptive names to refer to messages and message sets instead of hard to remember
  14 integer numbers.  However its chief purpose is in compiling message files into
  15 message catalogs.  The command line switches it understands are detailed below:
  16
  17 .TP
  18 .I -new
  19 Erase the messageg catalog and start a new one.
  20 The default behavior is to update the catalog with the
  21 specified message file(s).  This will instead cause the old
  22 one to be deleted and a whole new one started.
  23 .TP
  24 .I -lang <l>
  25 This governs the form of the include file.
  26 Currently supported is C, C++ and ANSIC.  The latter two are
  27 identical in output.  This argument is position dependent,
  28 you can switch the language back and forth in between
  29 include files if you care to.
  30 .TP
  31 .I -h <hfile>
  32 Output identifiers to the specified header files.
  33 This creates a header file with all of the appropriate
  34 #define's in it.  Without this it would be up to you to
  35 ensure that you keep your code in sync with the catalog file.
  36 The header file is created from all of the previous message files
  37 on the command line, so the order of the command line is
  38 important.  This means that if you just put it at the end of
  39 the command line, all the defines will go in one file
  40
  41 .B gencat foo.m bar.m zap.m -h all.h
  42
  43 If you prefer to keep your dependencies down you can specify
  44 one after each message file, and each .h file will receive
  45 only the identifiers from the previous message file
  46
  47 .B gencat foo.m -h foo.h bar.m -h bar.h zap.m -h zap.h
  48
  49 As an added bonus, if you run the following sequence:
  50
  51 .B gencat foo.m -h foo.h
  52
  53 the file foo.h will NOT be modified the second time.
  54 .B gencat
  55 checks to see if the contents have changed before modifying
  56 things.  This means that you won't get spurious rebuilds of
  57 your source every time you change a message.  You can thus use
  58 a Makefile rule such as:
  59
  60  MSGSRC = foo.m bar.m
  61  GENFLAGS = -lang C
  62  GENCAT = gencat
  63  MSGFILES = messages/English
  64
  65  $(MSGFILES): $(MSGSRC)
  66        @for i in $?; do cmd="$(GENCAT) $(GENFLAGS) $@ $$i -h `basename $$i .m`.H"; echo $$cmd; $$cmd; done
  67
  68  foo.o:  foo.h
  69
  70 The for-loop isn't too pretty, but it works.  For each .m
  71 file that has changed we run
  72 .B gencat
  73 on it.  foo.o depends on
  74 the result of that
  75 .B gencat
  76 (foo.h) but foo.h won't actually
  77 be modified unless we changed the order (or added new members)
  78 to foo.m.
  79
  80
  81 .PP
  82 The
  83 .B gencat
  84 software has two purposes and is usually used in 2 passes.
  85 The first use is to generate the header files from the message files so
  86 that the software can use descriptive names when referring to
  87 sets and messages.
  88
  89 The following command will accomplish this:
  90
  91 .RS
  92 .B gencat -new /dev/null foobar.m -h foobar-nls.h
  93 .RE
  94
  95 The
  96 .B gencat
  97 software will take the foobar.m message file and produce a
  98 header file called foobar-nls.h which can the be included in the
  99 software.  The -new and /dev/null flags indicate that
 100 .B gencat
 101 should also
 102 generate a new message catalog but send the resultant catalog to the bit
 103 bucket.  (The
 104 .B gencat
 105 software doesn't work without these two entries).
 106
 107 If you want to generate multiple header files for multiple message
 108 files, you have to use the following command:
 109
 110 .B gencat -new /dev/null aaa.m -h aaa-nls.h bbb.m -h bbb-nls.m ....
 111
 112 This will generate a header file for each message file.  For each
 113 message set that your software accesses, you will need to include the
 114 corresponding header file.  If you would like to compile just one
 115 solitary header file for all your message sets, the following command
 116 can be used:
 117
 118 .B gencat -new /dev/null aaa.m bbb.m ccc.m -h foobar-nls.m
 119
 120 The other use for the
 121 .B gencat
 122 software is in generating message catalogs
 123 from the message files.  To generate a new message catalog, the
 124 following command can be used:
 125
 126 .RS
 127 .B gencat -new foobar.cat foobar.m
 128 .RE
 129
 130 This will take the foobar.m message file and compile it into a message
 131 catalog called foobar.cat.  To compile multiple message sets into one
 132 catalog, the following command can be used:
 133
 134 .B gencat -new foobar.cat foobar1.m foobar2.m foobar3.m ...
 135
 136 The usual way for compiling message catalogs is via a Makefile.  In this
 137 case, it is often easier to define a variable (say, MESSAGEFILES) to
 138 contain the list of message files which need to be compiled into a
 139 catalog.  eg, in the above example we would have a line within the
 140 Makefile reading:
 141
 142 .B MESSAGEFILES = foobar1.m foobar2.m foobar3.m ....
 143
 144 Then to compile these files into a catalog, we use the following line
 145 within the Makefile:
 146
 147 .RS
 148 .B gencat -new foobar.cat $(MESSAGEFILES)
 149 .RE
 150
 151 .SH SEE ALSO
 152 .BR xtract(1),
 153 .BR setlocale(3),
 154 .BR catopen(3),
 155 .BR catgets(3),
 156 .BR catclose(3)