Markup revisions. Nothing was actually required to be able to format it,

freddrake · freddrake · commit d576e9df5fc7 · 2000-08-30T04:19:20.000Z
but many conventions were broken.
diff --git a/Doc/lib/libgettext.tex b/Doc/lib/libgettext.tex
@@ -9,7 +9,7 @@ \section{\module{gettext} ---
 
 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 @@ \subsection{GNU \program{gettext} API}
 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.
-
-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.}.
+\envvar{LANGUAGE}, \envvar{LC_ALL}, \envvar{LC_MESSAGES}, and
+\envvar{LANG} respectively.
+
+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,18 +95,18 @@ \subsection{Class-based API}
 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
 \function{bindtextdomain()}), and a list of languages.  All arguments
 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 @@ \subsection{Class-based API}
 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 @@ \subsection{Class-based API}
 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 @@ \subsubsection{The \class{NullTranslations} class}
 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 @@ \subsubsection{The \class{NullTranslations} class}
 \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,20 +224,20 @@ \subsubsection{The \class{GNUTranslations} class}
 
 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
 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'' \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 @@ \subsection{Internationalizing your programs and modules}
 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 @@ \subsection{Internationalizing your programs and modules}
 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 @@ \subsubsection{Localizing your module}
 
 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 @@ \subsubsection{Localizing your application}
 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 @@ \subsubsection{Deferred translations}
 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 @@ \subsubsection{Deferred translations}
 \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 @@ \subsection{Acknowledgements}
 \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
