Markup revisions. Nothing was actually required to be able to format it,
but many conventions were broken.
diff --git a/Doc/lib/libgettext.tex b/Doc/lib/libgettext.tex
index 5f56d04..e1a6c47 100644
--- a/Doc/lib/libgettext.tex
+++ b/Doc/lib/libgettext.tex
@@ -9,7 +9,7 @@
The \module{gettext} module provides internationalization (I18N) and
localization (L10N) services for your Python modules and applications.
-It supports both the GNU \program{gettext} message catalog API and a
+It supports both the GNU \code{gettext} message catalog API and a
higher level, class-based API that may be more appropriate for Python
files. The interface described below allows you to write your
module and application messages in one natural language, and provide a
@@ -30,27 +30,28 @@
languages on the fly, you probably want to use the class-based API
instead.
-\begin{funcdesc}{bindtextdomain}{domain, localedir\code{=None}}
+\begin{funcdesc}{bindtextdomain}{domain\optional{, localedir}}
Bind the \var{domain} to the locale directory
\var{localedir}. More concretely, \module{gettext} will look for
-binary \file{.mo} files for the given domain using the path (on Unix):
+binary \file{.mo} files for the given domain using the path (on \UNIX):
\file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo},
where \var{languages} is searched for in the environment variables
-\code{LANGUAGE}, \code{LC_ALL}, \code{LC_MESSAGES}, and \code{LANG}
-respectively.
+\envvar{LANGUAGE}, \envvar{LC_ALL}, \envvar{LC_MESSAGES}, and
+\envvar{LANG} respectively.
-If \var{localedir} is \code{None}, then the current binding for
-\var{domain} is returned\footnote{The default locale directory is system
-dependent; e.g. on standard RedHat Linux it is
-\file{/usr/share/locale}, but on Solaris it is
-\file{/usr/lib/locale}. The \module{gettext} module does not try to
-support these system dependent defaults; instead its default is
-\file{\code{sys.prefix}/share/locale}. For this reason, it is always
-best to call \code{gettext.bindtextdomain()} with an explicit absolute
-path at the start of your application.}.
+If \var{localedir} is omitted or \code{None}, then the current binding
+for \var{domain} is returned.\footnote{
+ The default locale directory is system dependent; e.g.\ on
+ RedHat Linux it is \file{/usr/share/locale}, but on Solaris it
+ is \file{/usr/lib/locale}. The \module{gettext} module does
+ not try to support these system dependent defaults; instead
+ its default is \file{\code{sys.prefix}/share/locale}. For
+ this reason, it is always best to call
+ \function{bindtextdomain()} with an explicit absolute path at
+ the start of your application.}
\end{funcdesc}
-\begin{funcdesc}{textdomain}{domain\code{=None}}
+\begin{funcdesc}{textdomain}{\optional{domain}}
Change or query the current global domain. If \var{domain} is
\code{None}, then the current global domain is returned, otherwise the
global domain is set to \var{domain}, which is returned.
@@ -94,7 +95,7 @@
Translations instances can also install themselves in the built-in
namespace as the function \function{_()}.
-\begin{funcdesc}{find}{domain, localedir\code{=None}, languages\code{=None}}
+\begin{funcdesc}{find}{domain\optional{, localedir\optional{, languages}}}
This function implements the standard \file{.mo} file search
algorithm. It takes a \var{domain}, identical to what
\function{textdomain()} takes, and optionally a \var{localedir} (as in
@@ -102,10 +103,10 @@
are strings.
If \var{localedir} is not given, then the default system locale
-directory is used\footnote{See the footnote for
-\function{bindtextdomain()} above.}. If \var{languages} is not given,
-then the following environment variables are searched: \code{LANGUAGE},
-\code{LC_ALL}, \code{LC_MESSAGES}, and \code{LANG}. The first one
+directory is used.\footnote{See the footnote for
+\function{bindtextdomain()} above.} If \var{languages} is not given,
+then the following environment variables are searched: \envvar{LANGUAGE},
+\envvar{LC_ALL}, \envvar{LC_MESSAGES}, and \envvar{LANG}. The first one
returning a non-empty value is used for the \var{languages} variable.
The environment variables can contain a colon separated list of
languages, which will be split.
@@ -120,8 +121,8 @@
If no such file is found, then \code{None} is returned.
\end{funcdesc}
-\begin{funcdesc}{translation}{domain, localedir\code{=None},
-languages\code{=None}, class_\code{=None}}
+\begin{funcdesc}{translation}{domain\optional{, localedir\optional{,
+ languages\optional{, class_}}}}
Return a \class{Translations} instance based on the \var{domain},
\var{localedir}, and \var{languages}, which are first passed to
\function{find()} to get the
@@ -133,7 +134,7 @@
function raises \exception{IOError}.
\end{funcdesc}
-\begin{funcdesc}{install}{domain, localedir\code{=None}, unicode\code{=0}}
+\begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode}}}
This installs the function \function{_} in Python's builtin namespace,
based on \var{domain}, and \var{localedir} which are passed to the
function \function{translation()}. The \var{unicode} flag is passed to
@@ -160,7 +161,7 @@
to write your own specialized translation classes. Here are the
methods of \class{NullTranslations}:
-\begin{methoddesc}[NullTranslations]{__init__}{fp\code{=None}}
+\begin{methoddesc}[NullTranslations]{__init__}{\optional{fp}}
Takes an optional file object \var{fp}, which is ignored by the base
class. Initializes ``protected'' instance variables \var{_info} and
\var{_charset} which are set by derived classes. It then calls
@@ -184,18 +185,18 @@
\end{methoddesc}
\begin{methoddesc}[NullTranslations]{info}{}
-Return the ``protected'' \var{_info} variable.
+Return the ``protected'' \member{_info} variable.
\end{methoddesc}
\begin{methoddesc}[NullTranslations]{charset}{}
-Return the ``protected'' \var{_charset} variable.
+Return the ``protected'' \member{_charset} variable.
\end{methoddesc}
-\begin{methoddesc}[NullTranslations]{install}{unicode\code{=0}}
+\begin{methoddesc}[NullTranslations]{install}{\optional{unicode}}
If the \var{unicode} flag is false, this method installs
-\code{self.gettext} into the built-in namespace, binding it to
-\function{_}. If \var{unicode} is true, it binds \code{self.ugettext}
-instead.
+\method{self.gettext()} into the built-in namespace, binding it to
+\samp{_}. If \var{unicode} is true, it binds \method{self.ugettext()}
+instead. By default, \var{unicode} is false.
Note that this is only one way, albeit the most convenient way, to
make the \function{_} function available to your application. Because it
@@ -223,12 +224,12 @@
It also 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 RFC822-style
-\code{key: value} pairs. If the key \code{Content-Type:} is found,
+translation for the empty string. This meta-data is in \rfc{822}-style
+\code{key: value} pairs. If the key \code{Content-Type} is found,
then the \code{charset} property is used to initialize the
-``protected'' \code{_charset} instance variable. The entire set of
+``protected'' \member{_charset} instance variable. The entire set of
key/value pairs are placed into a dictionary and set as the
-``protected'' \code{_info} instance variable.
+``protected'' \member{_info} instance variable.
If the \file{.mo} file's magic number is invalid, or if other problems
occur while reading the file, instantiating a \class{GNUTranslations} class
@@ -236,7 +237,7 @@
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'' \code{_charset} variable to the
+and the value of the ``protected'' \member{_charset} variable to the
builtin \function{unicode()} function.
\subsubsection{Solaris \file{.mo} file support}
@@ -297,12 +298,12 @@
fp.close()
\end{verbatim}
-In this example, the string ``\code{writing a log message}'' is marked as
-a candidate for translation, while the strings ``\code{mylog.txt}'' and
-``\code{w}'' are not.
+In this example, the string \code{'writing a log message'} is marked as
+a candidate for translation, while the strings \code{'mylog.txt'} and
+\code{'w'} are not.
-The GNU \program{gettext} package provides a tool, called
-\program{xgettext}, that scans C and C++ source code looking for these
+The GNU \code{gettext} package provides a tool, called
+\program{xgettext}, that scans C and \Cpp{} source code looking for these
specially marked strings. \program{xgettext} generates what are
called \file{.pot} files, essentially structured human readable files
which contain every marked string in the source code. These
@@ -312,10 +313,11 @@
For I18N Python programs however, \program{xgettext} won't work; it
doesn't understand the myriad of string types support by Python. The
standard Python distribution provides a tool called
-\program{pygettext} that does though (found in the \file{Tools/i18n}
-directory)\footnote{Fran\c cois Pinard has written a program called
+\program{pygettext} that does though (found in the \file{Tools/i18n/}
+directory).\footnote{Fran\c cois Pinard has written a program called
\program{xpot} which does a similar job. It is distributed separately
-from the Python distribution.}. This is a command line script that
+from the Python distribution.
+} This is a command line script that
supports a similar interface as \program{xgettext}; see its
documentation for details. Once you've used \program{pygettext} to
create your \file{.pot} files, you can use the standard GNU
@@ -330,13 +332,12 @@
If you are localizing your module, you must take care not to make
global changes, e.g. to the built-in namespace. You should not use
-the GNU \program{gettext} API but instead the class-based API.
+the GNU \code{gettext} API but instead the class-based API.
Let's say your module is called ``spam'' and the module's various
natural language translation \file{.mo} files reside in
-\file{/usr/share/locale} in GNU
-\program{gettext} format. Here's what you would put at the top of
-your module:
+\file{/usr/share/locale} in GNU \program{gettext} format. Here's what
+you would put at the top of your module:
\begin{verbatim}
import gettext
@@ -369,7 +370,7 @@
gettext.install('myapplication')
\end{verbatim}
-If you need to set the locale directory or the \code{unicode} flag,
+If you need to set the locale directory or the \var{unicode} flag,
you can pass these into the \function{install()} function:
\begin{verbatim}
@@ -444,7 +445,7 @@
This works because the dummy definition of \function{_()} simply returns
the string unchanged. And this dummy definition will temporarily
override any definition of \function{_()} in the built-in namespace
-(until the \code{del} command).
+(until the \keyword{del} command).
Take care, though if you have a previous definition of \function{_} in
the local namespace.
@@ -470,10 +471,10 @@
\end{verbatim}
In this case, you are marking translatable strings with the function
-\function{N_()}\footnote{The choice of \function{N_()} here is totally
+\function{N_()},\footnote{The choice of \function{N_()} here is totally
arbitrary; it could have just as easily been
-\function{MarkThisStringForTranslation()}.},
-which won't conflict with any definition of
+\function{MarkThisStringForTranslation()}.
+} which won't conflict with any definition of
\function{_()}. However, you will need to teach your message extraction
program to look for translatable strings marked with \function{N_()}.
\program{pygettext} and \program{xpot} both support this through the
@@ -488,7 +489,7 @@
\begin{itemize}
\item Peter Funk
\item James Henstridge
- \item Marc-Andre Lemburg
+ \item Marc-Andr\'e Lemburg
\item Martin von L\"owis
\item Fran\c cois Pinard
\item Barry Warsaw