home *** CD-ROM | disk | FTP | other *** search
/ Serving the Web / ServingTheWeb1995.disc1of1.iso / linux / slacksrce / d / libc / libc-4.6 / libc-4 / libc-linux / nls / README < prev   
Encoding:
Text File  |  1993-10-20  |  9.5 KB  |  218 lines
  1. First a note on the copyright.  This is the same one used by the
  2. X Consortium (fortunately no one has started copyrighting copyrights),
  3. so if your lawyers don't mind that one, they shouldn't mind this one.
  4. Simply put, you can do what you want with this, although if you are
  5. so inclined we'd appreciate it if you sent us back any enhancements,
  6. bug fixes, or other related material, so we can make it available to
  7. everyone else.  But if you don't want to, you don't have to.  So be it.
  8.  
  9. So.  What's here?  It's an implementation of the Message Catalog System,
  10. as described in the X/Open Portability Guide (XSI Supplementary Definitions,
  11. X/Open Company, Ltd, Prentice Hall, Englewood Cliffs, New Jersey 07632,
  12. ISBN: 0-13-685850-3).  Included is a version of gencat, to generate
  13. message catalogs, as well as the routines catgets, catopen, and catclose.
  14. There is also the beginings of an X/Open compliant set of print routines,
  15. but we'll talk about those later.
  16.  
  17. I haven't done a man page yet (sorry, but I've got a product to get out
  18. the door, the pretty stuff has to come later).  However you can use the
  19. definitions in the X/Open docs and it should all work.  I have, however,
  20. added a series of pretty significant enhancements, particularly to gencat.
  21.  
  22. As follows:
  23.  
  24. Use: gencat [-new] [-or] [-lang C|C++|ANSIC] catfile msgfile [-h <header-file>]...
  25.  
  26. This version of gencat accepts a number of flags.
  27.     -new    Erase the msg catalog and start a new one.
  28.         The default behavior is to update the catalog with the
  29.         specified msgfile(s).  This will instead cause the old
  30.         one to be deleted and a whole new one started.
  31.     -h <hfile>    Output identifiers to the specified header files.
  32.         This creates a header file with all of the appropriate
  33.         #define's in it.  Without this it would be up to you to
  34.         ensure that you keep your code in sync with the catalog file.
  35.         The header file is created from all of the previous msgfiles
  36.         on the command line, so the order of the command line is
  37.         important.  This means that if you just put it at the end of
  38.         the command line, all the defines will go in one file
  39.             gencat foo.m bar.m zap.m -h all.h
  40.         If you prefer to keep your dependencies down you can specify
  41.         one after each message file, and each .h file will receive
  42.         only the identifiers from the previous message file
  43.             gencat foo.m -h foo.h bar.m -h bar.h zap.m -h zap.h
  44.         As an added bonus, if you run the following sequence:
  45.             gencat foo.m -h foo.h
  46.             gencat foo.m -h foo.h
  47.         the file foo.h will NOT be modified the second time.  gencat
  48.         checks to see if the contents have changed before modifying
  49.         things.  This means that you won't get spurious rebuilds of
  50.         your source everytime you change a message.  You can thus use
  51.         a Makefile rule such as:
  52.  
  53.         MSGSRC=foo.m bar.m
  54.         GENFLAGS=-or -lang C
  55.         GENCAT=gencat
  56.         NLSLIB=nlslib/OM/C
  57.         $(NLSLIB):    $(MSGSRC)
  58.             @for i in $?; do cmd="$(GENCAT) $(GENFLAGS) $@ $$i -h `basename $$i .m`.H"; echo $$cmd; $$cmd; done
  59.  
  60.         foo.o:    foo.h
  61.  
  62.         The for-loop isn't too pretty, but it works.  For each .m
  63.         file that has changed we run gencat on it.  foo.o depends on
  64.         the result of that gencat (foo.h) but foo.h won't actually
  65.         be modified unless we changed the order (or added new members)
  66.         to foo.m.  (I hope this is clear, I'm in a bit of a rush.)
  67.  
  68.     -lang <l>    This governs the form of the include file.
  69.         Currently supported is C, C++ and ANSIC.  The latter two are
  70.         identical in output.  This argument is position dependent,
  71.         you can switch the language back and forth inbetween include
  72.         files if you care to.
  73.  
  74.     -or        This is a hack, but a real useful one.
  75.         MessageIds are ints, and it's not likely that you are going
  76.         to go too high there if you generate them sequentially.
  77.         catgets takes a msgId and a setId, since you can have multiple
  78.         sets in a catalog.  What -or does is shift the setId up to
  79.         the high end of a long, and put the msgId in the low half.
  80.         Assuming you don't go over half a long (usually 2 bytes 
  81.         nowadays) in either your set or msg ids, this will work great.
  82.         Along with this are generated several macros for extracting
  83.         ids and putting them back together.  You can then easily
  84.         define a macro for catgets which uses this single number
  85.         instead of the two.  Note that the form of the generated
  86.         constants is somewhat different here.
  87.         
  88.         Take the file aboutMsgs.m
  89.  
  90.         $ aboutMsgs.m
  91.         $ OmegaMail User Agent About Box Messages
  92.         $
  93.  
  94.         $set 4 #OmAbout
  95.  
  96.         $             About Box message and copyrights
  97.         $ #Message
  98.         # Welcome to OmegaMail(tm)
  99.         $ #Copyright
  100.         # Copyright (c) 1990 by Alphalpha Software, Inc.
  101.         $ #CreatedBy
  102.         # Created by:
  103.         $ #About
  104.         # About...
  105.         # A
  106.         #
  107.         #
  108.         $ #FaceBitmaps
  109.         # /usr/lib/alphalpha/bitmaps/%s
  110.  
  111.         Here is the the output from: gencat foo aboutMsgs.m -h foo.h
  112.  
  113.         #define OmAboutSet      0x4
  114.         #define OmAboutMessage  0x1
  115.         #define OmAboutCopyright        0x2
  116.         #define OmAboutCreatedBy        0x3
  117.         #define OmAboutAbout    0x4
  118.         #define OmAboutFaceBitmaps      0x8
  119.  
  120.         and now from: gencat -or foo aboutMsgs.m -h foo.h
  121.  
  122.         /* Use these Macros to compose and decompose setId's and msgId's */
  123.         #ifndef MCMakeId
  124.         # define MCMakeId(s,m)  (unsigned long)(((unsigned short)s<<(sizeof(short)*8))\
  125.                             |(unsigned short)m)
  126.         # define MCSetId(id)    (unsigned int) (id >> (sizeof(short) * 8))
  127.         # define MCMsgId(id)    (unsigned int) ((id << (sizeof(short) * 8))\
  128.                             >> (sizeof(short) * 8))
  129.         #endif
  130.  
  131.         #define OmAboutSet      0x4
  132.         #define OmAboutMessage  0x40001
  133.         #define OmAboutCopyright        0x40002
  134.         #define OmAboutCreatedBy        0x40003
  135.         #define OmAboutAbout    0x40004
  136.         #define OmAboutFaceBitmaps      0x40008
  137.  
  138.  
  139. Okay, by now, if you've read the X/Open docs, you'll see I've made
  140. a bunch of other extensions to the format of the msg catalog as well.
  141. Note that you don't have to use any of these and, with one exception,
  142. they are all compatible with the standard format.
  143.  
  144. $set 4 #OmAbout
  145.     In the standard the third argument is a comment.  Here if the
  146.     comment begins with a # then it is used to generate the setId constant
  147.     (with the word "Set" appended).  This constant is also prepended onto
  148.     all of the msgId constants for this set.  Anything after the first
  149.     token is treated as a comment.
  150.  
  151. $ #Message
  152.     As with set, I've modified the comment to indicate an identifier.
  153.     There are cleaner ways to do this, but I was trying to retain a
  154.     modicom of compatibility.  The identifier after # will be retained
  155.     and used as the identifier for the next message (unless overridden
  156.     before we get there).  If a message has no previous identifier then
  157.     no identifier is generated in the include file (I use this quite a
  158.     bit myself, the first identifier is a Menu item, the next three are
  159.     accelerator, accelerator-text and mnemonic - I don't need identifiers
  160.     for them, I just add 1, 2 and 3).
  161.  
  162. # Welcome to OmegaMail(tm)
  163.     Finally the one incompatible extension.  If a line begins with #
  164.     a msgId number is automatically generated for it by adding one to
  165.     the previous msgId.  This wouldn't have been useful in the standard,
  166.     since it didn't generate include files, but it's wonderful for this
  167.     version.  It makes it easy to reorder the message file to put things
  168.     where they belong and not have to worry about renumber anything (although
  169.     of course you'll have to recompile).
  170.  
  171. That's about all for that.
  172.  
  173. Now, what about the print routines?  These are embarassing.  They are
  174. a first pass.  They support only %[dxo] and %[s], although they support
  175. *all* of the modifiers on those arguments (I had no idea there were
  176. so many!).  They also, most importantly, support the position arguments
  177. that allow you to reference arguments out of order.  There's a terrible
  178. hack macro to handle varargs which I wrote because I wasn't sure if it
  179. was okay to pass the address of the stack to a subroutine.  I've since
  180. seen supposedly portable code that in fact does this, so I guess it's
  181. okay.  If that's the case the code could become a lot simpler.  I welcome
  182. anyone who would like to fix it up.  I just don't know when I'll get
  183. the chance; it works, it's just ugly.
  184.  
  185.  
  186. One last comment.  You probably want to know how reliable it is.  I've tested
  187. the print routines pretty well.  I've used the msgcat routines intensely,
  188. but I haven't exercised all of the options in the message catalog file
  189. (like all of the \ characters) although I have implemented them all.
  190. I'm pretty confident that all the basic stuff works, beyond that it's
  191. possible that there are bugs.  As for portability, I've run it under
  192. BSD4.3 (Apollo) and SYSV-hybrid (SCO).  (And I never want to see the
  193. words "System V with BSD extensions" again in my life.)  I don't believe
  194. that there are any heavy dependencies on Unix, although using another
  195. system would probably require #ifdef's.
  196.  
  197. I apologize for the state of the documentation, the lack of comments,
  198. the lack of testing, and all of the other things.  This project is
  199. subsidiary to my primary goal (Graphical Email for Unix) and I'm afraid
  200. I haven't been able to spend the time on it that I would have liked.
  201. However I'll happily answer any questions that you may have, and will
  202. be glad to serve as a distribution point for future revisions.  So if
  203. you make any changes or add more X/Open functions, send me a copy and
  204. I'll redistribute them.
  205.  
  206. Best of luck!
  207.                     Kee Hinckley
  208.                     September 12, 1990
  209.  
  210. Bugs:
  211.     There is currently one known bug.  Updating an existing message
  212.     catalog sometimes seems to not generate complete header files.
  213.     If in doubt, delete the catalog and regenerate the whole thing.
  214.                     Kee - 02-12-92
  215.     Note, I've just applied a patch from <Jan.Djarv@sa.erisoft.se>
  216.     that may fix this problem.
  217.                           03-12-92
  218.