First a note on the copyright.  This is the same one used by the
X Consortium (fortunately no one has started copyrighting copyrights),
so if your lawyers don't mind that one, they shouldn't mind this one.
Simply put, you can do what you want with this, although if you are
so inclined we'd appreciate it if you sent us back any enhancements,
bug fixes, or other related material, so we can make it available to
everyone else.  But if you don't want to, you don't have to.  So be it.

So.  What's here?  It's an implementation of the Message Catalog System,
as described in the X/Open Portability Guide (XSI Supplementary Definitions,
X/Open Company, Ltd, Prentice Hall, Englewood Cliffs, New Jersey 07632,
ISBN: 0-13-685850-3).  Included is a version of gencat, to generate
message catalogs, as well as the routines catgets, catopen, and catclose.
There is also the beginings of an X/Open compliant set of print routines,
but we'll talk about those later.

I haven't done a man page yet (sorry, but I've got a product to get out
the door, the pretty stuff has to come later).  However you can use the
definitions in the X/Open docs and it should all work.  I have, however,
added a series of pretty significant enhancements, particularly to gencat.

As follows:

Use: gencat [-new] [-or] [-lang C|C++|ANSIC] catfile msgfile [-h <header-file>]...

This version of gencat accepts a number of flags.
    -new	Erase the msg catalog and start a new one.
		The default behavior is to update the catalog with the
		specified msgfile(s).  This will instead cause the old
		one to be deleted and a whole new one started.
    -h <hfile>	Output identifiers to the specified header files.
		This creates a header file with all of the appropriate
		#define's in it.  Without this it would be up to you to
		ensure that you keep your code in sync with the catalog file.
		The header file is created from all of the previous msgfiles
		on the command line, so the order of the command line is
		important.  This means that if you just put it at the end of
		the command line, all the defines will go in one file
		    gencat foo.m bar.m zap.m -h all.h
		If you prefer to keep your dependencies down you can specify
		one after each message file, and each .h file will receive
		only the identifiers from the previous message file
		    gencat foo.m -h foo.h bar.m -h bar.h zap.m -h zap.h
		As an added bonus, if you run the following sequence:
		    gencat foo.m -h foo.h
		    gencat foo.m -h foo.h
		the file foo.h will NOT be modified the second time.  gencat
		checks to see if the contents have changed before modifying
		things.  This means that you won't get spurious rebuilds of
		your source everytime you change a message.  You can thus use
		a Makefile rule such as:

		MSGSRC=foo.m bar.m
		GENFLAGS=-or -lang C
		GENCAT=gencat
		NLSLIB=nlslib/OM/C
		$(NLSLIB):	$(MSGSRC)
			@for i in $?; do cmd="$(GENCAT) $(GENFLAGS) $@ $$i -h `basename $$i .m`.H"; echo $$cmd; $$cmd; done

		foo.o:	foo.h

		The for-loop isn't too pretty, but it works.  For each .m
		file that has changed we run gencat on it.  foo.o depends on
		the result of that gencat (foo.h) but foo.h won't actually
		be modified unless we changed the order (or added new members)
		to foo.m.  (I hope this is clear, I'm in a bit of a rush.)

    -lang <l>	This governs the form of the include file.
		Currently supported is C, C++ and ANSIC.  The latter two are
		identical in output.  This argument is position dependent,
		you can switch the language back and forth inbetween include
		files if you care to.

    -or		This is a hack, but a real useful one.
		MessageIds are ints, and it's not likely that you are going
		to go too high there if you generate them sequentially.
		catgets takes a msgId and a setId, since you can have multiple
		sets in a catalog.  What -or does is shift the setId up to
		the high end of a long, and put the msgId in the low half.
		Assuming you don't go over half a long (usually 2 bytes 
		nowadays) in either your set or msg ids, this will work great.
		Along with this are generated several macros for extracting
		ids and putting them back together.  You can then easily
		define a macro for catgets which uses this single number
		instead of the two.  Note that the form of the generated
		constants is somewhat different here.
		
		Take the file aboutMsgs.m

		$ aboutMsgs.m
		$ OmegaMail User Agent About Box Messages
		$

		$set 4 #OmAbout

		$			 About Box message and copyrights
		$ #Message
		# Welcome to OmegaMail(tm)
		$ #Copyright
		# Copyright (c) 1990 by Alphalpha Software, Inc.
		$ #CreatedBy
		# Created by:
		$ #About
		# About...
		# A
		#
		#
		$ #FaceBitmaps
		# /usr/lib/alphalpha/bitmaps/%s

		Here is the the output from: gencat foo aboutMsgs.m -h foo.h

		#define OmAboutSet		0x4
		#define OmAboutMessage		0x1
		#define OmAboutCopyright        0x2
		#define OmAboutCreatedBy        0x3
		#define OmAboutAbout    	0x4
		#define OmAboutFaceBitmaps      0x8

		and now from: gencat -or foo aboutMsgs.m -h foo.h

		/* Use these Macros to compose and decompose setId's and msgId's */
		#ifndef MCMakeId
		# define MCMakeId(s,m) (unsigned long)(((unsigned short)s<<(sizeof(short)*8))\
 				       |(unsigned short)m)
		# define MCSetId(id)   (unsigned int) (id >> (sizeof(short) * 8))
		# define MCMsgId(id)   (unsigned int) ((id << (sizeof(short) * 8))\
				       >> (sizeof(short) * 8))
		#endif

		#define OmAboutSet      	0x4
		#define OmAboutMessage  	0x40001
		#define OmAboutCopyright        0x40002
		#define OmAboutCreatedBy        0x40003
		#define OmAboutAbout    	0x40004
		#define OmAboutFaceBitmaps      0x40008


Okay, by now, if you've read the X/Open docs, you'll see I've made
a bunch of other extensions to the format of the msg catalog as well.
Note that you don't have to use any of these and, with one exception,
they are all compatible with the standard format.

$set 4 #OmAbout
    In the standard the third argument is a comment.  Here if the
    comment begins with a # then it is used to generate the setId constant
    (with the word "Set" appended).  This constant is also prepended onto
    all of the msgId constants for this set.  Anything after the first
    token is treated as a comment.

$ #Message
    As with set, I've modified the comment to indicate an identifier.
    There are cleaner ways to do this, but I was trying to retain a
    modicom of compatibility.  The identifier after # will be retained
    and used as the identifier for the next message (unless overridden
    before we get there).  If a message has no previous identifier then
    no identifier is generated in the include file (I use this quite a
    bit myself, the first identifier is a Menu item, the next three are
    accelerator, accelerator-text and mnemonic - I don't need identifiers
    for them, I just add 1, 2 and 3).

# Welcome to OmegaMail(tm)
    Finally the one incompatible extension.  If a line begins with #
    a msgId number is automatically generated for it by adding one to
    the previous msgId.  This wouldn't have been useful in the standard,
    since it didn't generate include files, but it's wonderful for this
    version.  It makes it easy to reorder the message file to put things
    where they belong and not have to worry about renumber anything (although
    of course you'll have to recompile).

That's about all for that.

Now, what about the print routines?  These are embarassing.  They are
a first pass.  They support only %[dxo] and %[s], although they support
*all* of the modifiers on those arguments (I had no idea there were
so many!).  They also, most importantly, support the position arguments
that allow you to reference arguments out of order.  There's a terrible
hack macro to handle varargs which I wrote because I wasn't sure if it
was okay to pass the address of the stack to a subroutine.  I've since
seen supposedly portable code that in fact does this, so I guess it's
okay.  If that's the case the code could become a lot simpler.  I welcome
anyone who would like to fix it up.  I just don't know when I'll get
the chance; it works, it's just ugly.


One last comment.  You probably want to know how reliable it is.  I've tested
the print routines pretty well.  I've used the msgcat routines intensely,
but I haven't exercised all of the options in the message catalog file
(like all of the \ characters) although I have implemented them all.
I'm pretty confident that all the basic stuff works, beyond that it's
possible that there are bugs.  As for portability, I've run it under
BSD4.3 (Apollo) and SYSV-hybrid (SCO).  (And I never want to see the
words "System V with BSD extensions" again in my life.)  I don't believe
that there are any heavy dependencies on Unix, although using another
system would probably require #ifdef's.

I apologize for the state of the documentation, the lack of comments,
the lack of testing, and all of the other things.  This project is
subsidiary to my primary goal (Graphical Email for Unix) and I'm afraid
I haven't been able to spend the time on it that I would have liked.
However I'll happily answer any questions that you may have, and will
be glad to serve as a distribution point for future revisions.  So if
you make any changes or add more X/Open functions, send me a copy and
I'll redistribute them.

Best of luck!
				    Kee Hinckley
				    September 12, 1990

Bugs:
    There is currently one known bug.  Updating an existing message
    catalog sometimes seems to not generate complete header files.
    If in doubt, delete the catalog and regenerate the whole thing.
					Kee - 02-12-92
    Note, I've just applied a patch from <Jan.Djarv@sa.erisoft.se>
    that may fix this problem.
					      03-12-92