[Python-checkins] python/dist/src/Doc/lib libgettext.tex,1.17,1.18

Thu, 24 Apr 2003 11:14:55 -0700

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv20840

Modified Files:
	libgettext.tex 
Log Message:
Updated a bunch of docs to describe how message ids and strings are
Unicode in GNUTranslations.  Also provide better descriptions of
*gettext() overridden methods, esp. w.r.t. the behavior in the face of
fallbacks.

Index: libgettext.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libgettext.tex,v
retrieving revision 1.17
retrieving revision 1.18
diff -C2 -d -r1.17 -r1.18
*** libgettext.tex	11 Apr 2003 21:28:10 -0000	1.17
--- libgettext.tex	24 Apr 2003 18:14:49 -0000	1.18
***************
*** 286,302 ****
  overrides \method{_parse()} to enable reading GNU \program{gettext}
  format \file{.mo} files in both big-endian and little-endian format.
! It also adds the ability to coerce both message ids and message
! strings to Unicode.

  \class{GNUTranslations} parses optional meta-data out of the
  translation catalog.  It is convention with GNU \program{gettext} to
  include meta-data as the translation for the empty string.  This
! meta-data is in \rfc{822}-style \code{key: value} pairs, and must
! contain the \code{Project-Id-Version}.  If the key
  \code{Content-Type} is found, then the \code{charset} property is used
  to initialize the ``protected'' \member{_charset} instance variable,
! defaulting to \code{None} if not found.  The entire set of
! key/value pairs are placed into a dictionary and set as the
! ``protected'' \member{_info} instance variable.

  If the \file{.mo} file's magic number is invalid, or if other problems
--- 286,311 ----
  overrides \method{_parse()} to enable reading GNU \program{gettext}
  format \file{.mo} files in both big-endian and little-endian format.
! It also coerces both message ids and message strings to Unicode.

  \class{GNUTranslations} parses optional meta-data out of the
  translation catalog.  It is convention with GNU \program{gettext} to
  include meta-data as the translation for the empty string.  This
! meta-data is in \rfc{822}-style \code{key: value} pairs, and should
! contain the \code{Project-Id-Version} key.  If the key
  \code{Content-Type} is found, then the \code{charset} property is used
  to initialize the ``protected'' \member{_charset} instance variable,
! defaulting to \code{None} if not found.  If the charset encoding is
! specified, then all message ids and message strings read from the
! catalog are converted to Unicode using this encoding.  The
! \method{ugettext()} method always returns a Unicode, while the
! \method{gettext()} returns an encoded 8-bit string.  For the message
! id arguments of both methods, either Unicode strings or 8-bit strings
! containing only US-ASCII characters are acceptable.  Note that the
! Unicode version of the methods (i.e. \method{ugettext()} and
! \method{ungettext()}) are the recommended interface to use for
! internationalized Python programs.
! 
! The entire set of key/value pairs are placed into a dictionary and set
! as the ``protected'' \member{_info} instance variable.

  If the \file{.mo} file's magic number is invalid, or if other problems
***************
*** 304,329 ****
  can raise \exception{IOError}.

! The other usefully overridden method is \method{ugettext()}, which
! returns a Unicode string by passing both the translated message string
! and the value of the ``protected'' \member{_charset} variable to the
! builtin \function{unicode()} function.  Note that if you use
! \method{ugettext()} you probably also want your message ids to be
! Unicode.  To do this, set the variable \var{coerce} to \code{True} in
! the \class{GNUTranslations} constructor.  This ensures that both the
! message ids and message strings are decoded to Unicode when the file
! is read, using the file's \code{charset} value.  If you do this, you
! will not want to use the \method{gettext()} method -- always use
! \method{ugettext()} instead.

! To facilitate plural forms, the methods \method{ngettext} and
! \method{ungettext} are overridden as well.

! \begin{methoddesc}[GNUTranslations]{__init__}{
!     \optional{fp\optional{, coerce}}}
! Constructs and parses a translation catalog in GNU gettext format.
! \var{fp} is passed to the base class (\class{NullTranslations})
! constructor.  \var{coerce} is a flag specifying whether message ids
! and message strings should be converted to Unicode when the file is
! parsed.  It defaults to \code{False} for backward compatibility.
  \end{methoddesc}

--- 313,373 ----
  can raise \exception{IOError}.

! The following methods are overridden from the base class implementation:

! \begin{methoddesc}[GNUTranslations]{gettext}{message}
! Look up the \var{message} id in the catalog and return the
! corresponding message string, as an 8-bit string encoded with the
! catalog's charset encoding, if known.  If there is no entry in the
! catalog for the \var{message} id, and a fallback has been set, the
! look up is forwarded to the fallback's \method{gettext()} method.
! Otherwise, the \var{message} id is returned.
! \end{methoddesc}

! \begin{methoddesc}[GNUTranslations]{ugettext}{message}
! Look up the \var{message} id in the catalog and return the
! corresponding message string, as a Unicode string.  If there is no
! entry in the catalog for the \var{message} id, and a fallback has been
! set, the look up is forwarded to the fallback's \method{ugettext()}
! method.  Otherwise, the \var{message} id is returned.
! \end{methoddesc}
! 
! \begin{methoddesc}[GNUTranslations]{ngettext}{singular, plural, n}
! Do a plural-forms lookup of a message id.  \var{singular} is used as
! the message id for purposes of lookup in the catalog, while \var{n} is
! used to determine which plural form to use.  The returned message
! string is an 8-bit string encoded with the catalog's charset encoding,
! if known.
! 
! If the message id is not found in the catalog, and a fallback is
! specified, the request is forwarded to the fallback's
! \method{ngettext()} method.  Otherwise, when \var{n} is 1 \var{singular} is
! returned, and \var{plural} is returned in all other cases.
! 
! \versionadded{2.3}
! \end{methoddesc}
! 
! \begin{methoddesc}[GNUTranslations]{ungettext}{singular, plural, n}
! Do a plural-forms lookup of a message id.  \var{singular} is used as
! the message id for purposes of lookup in the catalog, while \var{n} is
! used to determine which plural form to use.  The returned message
! string is a Unicode string.
! 
! If the message id is not found in the catalog, and a fallback is
! specified, the request is forwarded to the fallback's
! \method{ungettext()} method.  Otherwise, when \var{n} is 1 \var{singular} is
! returned, and \var{plural} is returned in all other cases.
! 
! Here is an example:
! 
! \begin{verbatim}
! n = len(os.listdir('.'))
! cat = GNUTranslations(somefile)
! message = cat.ungettext(
!     'There is %(num)d file in this directory',
!     'There are %(num)d files in this directory',
!     n) % {'n': n}
! \end{verbatim}
! 
! \versionadded{2.3}
  \end{methoddesc}