gnu gettext-0.11.2, manual edition 0.11.2, 24 May 2002

[Steven Augart]

I have a documentation fix for the manual for GNU Gettext, edition
0.11.2 of 24 May 2002.  I rewrote some of the description of the
catgets interface in order to make it easier to follow and to make the
English more natural.

-------------------------unidiff follows----------------------
--- gettext-0.11.2/doc/gettext.texi     Mon Apr 22 11:26:53 2002
+++ gettext-0.11.2+augart-docfix/doc/gettext.texi       Fri May 24 14:24:27 2002
@@ -3959,91 +3959,102 @@
 @code{<nl_types.h>} header file.
 
 @cindex @code{catopen}, a @code{catgets} function
address@hidden is used like in this:
address@hidden is used like this:
 
 @example
-nl_catd catd = catopen ("catalog_name", 0);
+nl_catd catd = catopen("catalog_name", 0);
 @end example
 
-The function takes as the argument the name of the catalog.  This usual
-refers to the name of the program or the package.  The second parameter
-is not further specified in the standard.  I don't even know whether it
-is implemented consistently among various systems.  So the common advice
-is to use @code{0} as the value.  The return value is a handle to the
-message catalog, equivalent to handles to file returned by @code{open}.
address@hidden's first argument is the name of the catalog.  This is
+usually the name of the program or the name of the package.  The second
+parameter is not further specified in the standard; I don't even know
+whether it is implemented consistently across various systems.  So the
+common advice is to use @code{0} as the value.  @code{catopen} returns a
+handle to the message catalog, a so-called @dfn{catalog descriptor}.
+This is of type @samp{nl_catd} and is analagous to the @dfn{file
+descriptor} returned by the Unix @code{open} system call.
 
 @cindex @code{catgets}, a @code{catgets} function
-This handle is of course used in the @code{catgets} function which can
-be used like this:
+This @dfn{catalog descriptor} is of course used to retrieve messages
+from the catalog, via the @code{catgets}
+function.  An example:
 
 @example
-char *translation = catgets (catd, set_no, msg_id, "original string");
+const char address@hidden = catgets(@var{catd}, @var{set_no}, @var{msg_id}, 
"@var{original string}");
 @end example
 
-The first parameter is this catalog descriptor.  The second parameter
-specifies the set of messages in this catalog, in which the message
-described by @code{msg_id} is obtained.  @code{catgets} therefore uses a
-three-stage addressing:
address@hidden is the catalog descriptor.  The @var{set_no} parameter
+specifies a particular set of messages in @var{catd}'s catalog.
address@hidden refers to a particular message in the catalog @var{catd}.
+To retrieve a particular @var{translation}, therefore, @code{catgets} uses 
three
+levels of addressing:
 
 @display
-catalog name @result{} set number @result{} message ID @result{} translation
address@hidden name} @result{} @var{set number} @result{} @var{message ID} 
@result{} @var{translation}
 @end display
 
 @c Anybody else loving Haskell??? :-) -- Uli
 
-The fourth argument is not used to address the translation.  It is given
-as a default value in case when one of the addressing stages fail.  One
-important thing to remember is that although the return type of catgets
-is @code{char *} the resulting string @emph{must not} be changed.  It
-should better be @code{const char *}, but the standard is published in
-1988, one year before ANSI C.
+The @var{original string} argument is not used to find the @var{translation}. 
+It is only a default value, to use in case one of the levels of
+addressing fails.
+
+Remember that, although the return type of @code{catgets} is formally defined
+as @code{char *}, the resulting string @emph{must not} be changed.
+(@var{translation}'s type should be @code{const char *}, but the catgets
+standard was published in 1988, one year before ANSI C formally added the
address@hidden keyword to the C language.)
 
 @noindent
 @cindex @code{catclose}, a @code{catgets} function
-The last of these function functions is used and behaves as expected:
+The last function, @code{catclose}, behaves as you'd expect:
 
 @example
-catclose (catd);
+catclose (@var{catd});
 @end example
 
-After this no @code{catgets} call using the descriptor is legal anymore.
+After this, @var{catd} is no longer a valid @dfn{catalog descriptor},
+and should not be used in any more calls to @code{catgets}.
 
 @node Problems with catgets,  , Interface to catgets, catgets
 @subsection Problems with the @code{catgets} Interface?!
 @cindex problems with @code{catgets} interface
 
-Now that this description seemed to be really easy --- where are the
-problems we speak of?  In fact the interface could be used in a
address@hidden looks easy based on this description --- where are the
+problems we speak of?  In fact, the interface can be used in a
 reasonable way, but constructing the message catalogs is a pain.  The
 reason for this lies in the third argument of @code{catgets}: the unique
-message ID.  This has to be a numeric value for all messages in a single
-set.  Perhaps you could imagine the problems keeping such a list while
-changing the source code.  Add a new message here, remove one there.  Of
-course there have been developed a lot of tools helping to organize this
-chaos but one as the other fails in one aspect or the other.  We don't
-want to say that the other approach has no problems but they are far
-more easy to manage.
address@hidden ID}.  
+This has to be a numeric value, unique among all messages in a single
address@hidden number}.  You can probably imagine the problems maintaining
+such a list while changing the source code.  Add a new message here,
+remove one there, and things get confusing.
+
+Of course, people have developed a number of tools to help organize this
+chaos; regrettably, each current tool fails in some aspect or other.
+We don't want to say that the other approach has no problems, but its
+problems seem far easier to manage.
 
 @node gettext, Comparison, catgets, Programmers
 @section About @code{gettext}
 @cindex @code{gettext}, a programmer's view
 
-The definition of the @code{gettext} interface comes from a Uniforum
+The @code{gettext} interface's definition comes from a Uniforum
 proposal and it is followed by at least one major Unix vendor
 (Sun) in its last developments.  It is not specified in any official
 standard, though.
 
 The main points about this solution is that it does not follow the
 method of normal file handling (open-use-close) and that it does not
-burden the programmer so many task, especially the unique key handling.
+burden the programmer with so many tasks, especially the unique key handling.
 Of course here also a unique key is needed, but this key is the message
 itself (how long or short it is).  See @ref{Comparison} for a more
 detailed comparison of the two methods.
 
-The following section contains a rather detailed description of the
-interface.  We make it that detailed because this is the interface
+The following section contains a detailed description of the
+interface.  It's detailed because this is the interface
 we chose for the GNU @code{gettext} Library.  Programmers interested
-in using this library will be interested in this description.
+in using the @code{gettext} library will be interested in this description.
 
 @menu
 * Interface to gettext::        The interface