proposed gettext doc patch for new standards

[Paul Eggert]

Here is a proposed patch to the gettext 0.11 documentation to bring it
up to date with respect to recently issued standards, notably POSIX
1003.1-2001 and LSB 1.1.0.  Also, it tries to make it clearer that
though printf "%1$s" is required by the X/Open extension to POSIX, it
is not part of the base standard.


2002-02-07  Paul Eggert  <address@hidden>

        Update for POSIX 1003.1-2001 and LSB 1.1.0.

        * doc/gettext.texi (Triggering): POSIX now requires LC_MESSAGES.
        (c-format): Point out that %1$s etc. are not required by C 99 or
        POSIX, but are required by X/Open and are common enough to use.
        (Programmers): Don't say that the POSIX committee couldn't
        agree on anything, as it's no longer true.
        (catgets, gettext, Temp Implementations, Temp catgets): Update
        references to standards and implementations.
        (AM_ICONV, C, clisp C): "POSIX" -> "X/Open" when talking about
        %1$s etc.

--- /reb/src/base/gettext/doc/gettext.texi      Wed Jan 30 02:59:52 2002
+++ ./gettext.texi      Thu Feb  7 14:13:48 2002
@@ -1497,10 +1497,9 @@ code above by a sequence of @code{setloc
 
 @noindent
 On all POSIX conformant systems the locale categories @code{LC_CTYPE},
address@hidden, @code{LC_MONETARY}, @code{LC_NUMERIC}, and
address@hidden are available.  On some modern systems there is also a
-locale @code{LC_MESSAGES} which is called on some old, XPG2 compliant
-systems @code{LC_RESPONSES}.
address@hidden, @code{LC_MESSAGES}, @code{LC_MONETARY},
address@hidden, and @code{LC_TIME} are available.  Some older
+systems lack @code{LC_MESSAGES} or call it @code{LC_RESPONSES}.
 
 Note that changing the @code{LC_CTYPE} also affects the functions
 declared in the @code{<ctype.h>} standard header.  If this is not
@@ -1776,6 +1775,9 @@ would have to write
 
 @noindent
 The routines in @code{msgfmt} know about this special notation.
+This notation is not required by C 99 or by POSIX, but it is required
+by X/Open and is supported by GNU/Linux, and many translators use it
+to good effect.
 
 Because not all strings in a program must be format strings it is not
 useful for @code{msgfmt} to test all the strings in the @file{.po} file.
@@ -3335,10 +3337,7 @@ this from their @file{.login} or @file{.
 One aim of the current message catalog implementation provided by
 GNU @code{gettext} was to use the system's message catalog handling, if the
 installer wishes to do so.  So we perhaps should first take a look at
-the solutions we know about.  The people in the POSIX committee did not
-manage to agree on one of the semi-official standards which we'll
-describe below.  In fact they couldn't agree on anything, so they decided
-only to include an example of an interface.  The major Unix vendors
+the solutions we know about.  The major Unix vendors
 are split in the usage of the two most important specifications: X/Open's
 catgets vs. Uniforum's gettext interface.  We'll describe them both and
 later explain our solution of this dilemma.
@@ -3355,8 +3354,9 @@ later explain our solution of this dilem
 @node catgets, gettext, Programmers, Programmers
 @section About @code{catgets}
 
-The @code{catgets} implementation is defined in the X/Open Portability
-Guide, Volume 3, XSI Supplementary Definitions, Chapter 5.  But the
+The @code{catgets} implementation is defined by POSIX 1003.1-2001 as
+part of its X/Open System Interfaces Extension option, and is required
+by the Linux Standard Base (LSB) Specification 1.1.0.  But the
 process of creating this standard seemed to be too slow for some of
 the Unix vendors so they created their implementations on preliminary
 versions of the standard.  Of course this leads again to problems while
@@ -3371,10 +3371,9 @@ some others address@hidden)
 
 But we must not forget one point: after all the trouble with transfering
 the rights on Unix(tm) they at last came to X/Open, the very same who
-published this specification.  This leads me to making the prediction
-that this interface will be in future Unix standards (e.g. Spec1170) and
-therefore part of all Unix implementation (implementations, which are
address@hidden to wear this name).
+originally published this specification.  This interface is now in
+Unix standards and is therefore required for every implementation that
+is allowed to call itself ``Unix''.
 
 @menu
 * Interface to catgets::        The interface
@@ -3457,9 +3456,9 @@ more easy to manage.
 @section About @code{gettext}
 
 The definition of the @code{gettext} interface 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.
+proposal and is supported by GNU/Linux and by at least one major Unix
+variant (Solaris).  It is also required by LSB 1.1.0.  Ports are
+available for several other operating systems.
 
 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
@@ -4377,21 +4376,9 @@ the X/Open @code{catgets} method, and th
 method.  The @code{catgets} method indexes messages by integers; the
 @code{gettext} method indexes them by their English translations.
 The @code{catgets} method has been around longer and is supported
-by more vendors.  The @code{gettext} method is supported by Sun,
-and it has been heard that the COSE multi-vendor initiative is
-supporting it.  Neither method is a POSIX standard; the POSIX.1
-committee had a lot of disagreement in this area.
-
-Neither one is in the POSIX standard.  There was much disagreement
-in the POSIX.1 committee about using the @code{gettext} routines
-vs. @code{catgets} (XPG).  In the end the committee couldn't
-agree on anything, so no messaging system was included as part
-of the standard.  I believe the informative annex of the standard
-includes the XPG3 messaging interfaces, address@hidden an example of
-a messaging system that has been address@hidden''
-
-They were very careful not to say anywhere that you should use one
-set of interfaces over the other.  For more on this topic please
+by more vendors.  The @code{gettext} method is supported by GNU/Linux
+and by Solaris.  Neither method is required by POSIX.
+For more on this topic please
 see the Programming for Internationalization FAQ.
 
 @node Temp catgets, Temp WSI, Temp Implementations, Temp Programmers
@@ -4416,18 +4403,12 @@ However, software developers have a hard
 these changes across so many platforms.
 
 And this has prompted the Unix vendors to begin to standardize their
-systems.  Hence the impetus for Spec1170.  Every major Unix vendor
+systems.  Hence the impetus for POSIX 1003.1-2001.  Every major Unix vendor
 has committed to supporting this standard and every Unix software
 developer waits with glee the day they can write software to this
 standard and simply recompile (without having to use autoconf)
 across different platforms.
 
-As I understand it, Spec1170 is roughly based upon version 4 of the
-X/Open Portability Guidelines (XPG4).  Because @code{catgets} and
-friends are defined in XPG4, I'm led to believe that @code{catgets}
-is a part of Spec1170 and hence will become a standardized component
-of all Unix systems.
-
 @node Temp WSI, Temp Notes, Temp catgets, Temp Programmers
 @subsection Temporary - Why a single implementation
 
@@ -5719,7 +5700,7 @@ and @code{LTLIBINTL} variables.
 @node AM_ICONV,  , AM_GNU_GETTEXT, autoconf macros
 @subsection AM_ICONV in @file{iconv.m4}
 
-The @code{AM_ICONV} macro tests for the presence of the POSIX
+The @code{AM_ICONV} macro tests for the presence of the X/Open
 @code{iconv} function family in either the C library or a separate
 @code{libiconv} library. If found, it sets the @code{am_cv_func_iconv}
 variable to @samp{yes}; it defines @code{HAVE_ICONV} to 1 in the autoconf
@@ -5997,7 +5978,7 @@ Use
 @code{xgettext -k_}
 
 @item Formatting with positions
address@hidden "%2$d %1$d"} (POSIX but not C 99)
address@hidden "%2$d %1$d"} (X/Open but not C 99)
 
 @item Portability
 autoconf (gettext.m4) and #if ENABLE_NLS
@@ -6239,7 +6220,7 @@ use
 @code{clisp-xgettext}
 
 @item Formatting with positions
address@hidden "%2$d %1$d"} (POSIX but not C 99)
address@hidden "%2$d %1$d"} (X/Open but not C 99)
 
 @item Portability
 On platforms without gettext, no translation.