Various documentation updates

7 files changed, 50 insertions, 50 deletions

diff --git a/docs/api/core.rst b/docs/api/core.rst
index e554938..6993764 100644
--- a/docs/api/core.rst
+++ b/docs/api/core.rst
@@ -7,6 +7,9 @@ The core API provides the basic core functionality.  Primarily it provides
 the :class:`Locale` object and ways to create it.  This object
 encapsulates a locale and exposes all the data it contains.
 
+All the core functionality is also directly importable from the `babel`
+module for convenience.
+
 Basic Interface
 ---------------
 
diff --git a/docs/dates.rst b/docs/dates.rst
index 94474f7..f03c21a 100644
--- a/docs/dates.rst
+++ b/docs/dates.rst
@@ -1,5 +1,7 @@
 .. -*- mode: rst; encoding: utf-8 -*-
 
+.. _date-and-time:
+
 =============
 Date and Time
 =============
diff --git a/docs/display.rst b/docs/display.rst
index 640795c..06901a2 100644
--- a/docs/display.rst
+++ b/docs/display.rst
@@ -1,5 +1,7 @@
 .. -*- mode: rst; encoding: utf-8 -*-
 
+.. _display-names:
+
 ====================
 Locale Display Names
 ====================
@@ -8,9 +10,9 @@ Locale Display Names
 Introduction
 ============
 
-While `message catalogs <messages.html>`_ allow you to localize any messages
-in your application, there are a number of strings that are used in many
-applications for which translations are readily available.
+While :ref:`message catalogs <messages>` allow you to localize any
+messages in your application, there are a number of strings that are used
+in many applications for which translations are readily available.
 
 Imagine for example you have a list of countries that users can choose from,
 and you'd like to display the names of those countries in the language the
@@ -61,8 +63,7 @@ language:
 
     >>> locale = Locale('es')
     >>> month_names = locale.months['format']['wide'].items()
-    >>> month_names.sort()
-    >>> for idx, name in month_names:
+    >>> for idx, name in sorted(month_names):
     ...     print name
     enero
     febrero
diff --git a/docs/intro.rst b/docs/intro.rst
index 0de1a5d..25e0069 100644
--- a/docs/intro.rst
+++ b/docs/intro.rst
@@ -16,42 +16,34 @@ localization (L10N) can be separated into two different aspects:
 Message Catalogs
 ================
 
-While the Python standard library includes a
-`gettext <http://docs.python.org/lib/module-gettext.html>`_ module that enables
-applications to use message catalogs, it requires developers to build these
-catalogs using GNU tools such as ``xgettext``, ``msgmerge``, and ``msgfmt``.
-And while ``xgettext`` does have support for extracting messages from Python
-files, it does not know how to deal with other kinds of files commonly found
-in Python web-applications, such as templates, nor does it provide an easy
-extensibility mechanism to add such support.
+While the Python standard library includes a :mod:`gettext` module that
+enables applications to use message catalogs, it requires developers to
+build these catalogs using GNU tools such as ``xgettext``, ``msgmerge``,
+and ``msgfmt``.  And while ``xgettext`` does have support for extracting
+messages from Python files, it does not know how to deal with other kinds
+of files commonly found in Python web-applications, such as templates, nor
+does it provide an easy extensibility mechanism to add such support.
 
-Babel addresses this by providing a framework where various extraction methods
-can be plugged in to a larger message extraction framework, and also removes
-the dependency on the GNU ``gettext`` tools for common tasks, as these aren't
-necessarily available on all platforms. See `Working with Message Catalogs`_
-for details on this aspect of Babel.
-
-.. _`Working with Message Catalogs`: messages.html
+Babel addresses this by providing a framework where various extraction
+methods can be plugged in to a larger message extraction framework, and
+also removes the dependency on the GNU ``gettext`` tools for common tasks,
+as these aren't necessarily available on all platforms. See
+:ref:`messages` for details on this aspect of Babel.
 
 
 Locale Data
 ===========
 
-Furthermore, while the Python standard library does include support for basic
-localization with respect to the formatting of numbers and dates (the
-`locale <http://docs.python.org/lib/module-locale.html>`_ module, among others),
-this support is based on the assumption that there will be only one specific
-locale used per process (at least simultaneously.) Also, it doesn't provide
-access to other kinds of locale data, such as the localized names of countries,
-languages, or time-zones, which are frequently needed in web-based applications.
-
-For these requirements, Babel includes data extracted from the `Common Locale
-Data Repository (CLDR) <http://unicode.org/cldr/>`_, and provides a number of
-convenient methods for accessing and using this data. See `Locale Display
-Names`_, `Date Formatting`_, and `Number Formatting`_ for more information on
-this aspect of Babel.
-
-
-.. _`Locale Display Names`: display.html
-.. _`Date Formatting`: dates.html
-.. _`Number Formatting`: numbers.html
+Furthermore, while the Python standard library does include support for
+basic localization with respect to the formatting of numbers and dates
+(the :mod:`locale` module, among others), this support is based on the
+assumption that there will be only one specific locale used per process
+(at least simultaneously.) Also, it doesn't provide access to other kinds
+of locale data, such as the localized names of countries, languages, or
+time-zones, which are frequently needed in web-based applications.
+
+For these requirements, Babel includes data extracted from the `Common
+Locale Data Repository (CLDR) <http://unicode.org/cldr/>`_, and provides a
+number of convenient methods for accessing and using this data. See
+:ref:`display-names`, :ref:`date-and-time`, and :ref:`numbers` for more
+information on this aspect of Babel.
diff --git a/docs/messages.rst b/docs/messages.rst
index 9f4bfab..683e7ae 100644
--- a/docs/messages.rst
+++ b/docs/messages.rst
@@ -1,5 +1,7 @@
 .. -*- mode: rst; encoding: utf-8 -*-
 
+.. _messages:
+
 =============================
 Working with Message Catalogs
 =============================
@@ -45,10 +47,8 @@ The general procedure for building message catalogs looks something like this:
    regenerate the POT file and merge the changes into the various
    locale-specific PO files, for example using ``msgmerge``
 
-Python provides the `gettext module`_ as part of the standard library, which
-enables applications to work with appropriately generated MO files.
-
- .. _`gettext module`: http://docs.python.org/lib/module-gettext.html
+Python provides the :mod:`gettext` module as part of the standard library,
+which enables applications to work with appropriately generated MO files.
 
 As ``gettext`` provides a solid and well supported foundation for translating
 application messages, Babel does not reinvent the wheel, but rather reuses this
@@ -74,13 +74,13 @@ When message extraction is based on directories instead of individual files,
 there needs to be a way to configure which files should be treated in which
 manner. For example, while many projects may contain ``.html`` files, some of
 those files may be static HTML files that don't contain localizable message,
-while others may be `Django`_ templates, and still others may contain `Genshi`_
+while others may be `Jinja2`_ templates, and still others may contain `Genshi`_
 markup templates. Some projects may even mix HTML files for different templates
 languages (for whatever reason). Therefore the way in which messages are
 extracted from source files can not only depend on the file extension, but
 needs to be controllable in a precise manner.
 
-.. _`Django`: http://www.djangoproject.com/
+.. _`Jinja2`: http://jinja.pocoo.org/
 .. _`Genshi`: http://genshi.edgewall.org/
 
 Babel accepts a configuration file to specify this mapping of files to
@@ -161,10 +161,8 @@ for comments. Empty lines are ignored, too.
 .. note:: if you're performing message extraction using the command Babel
           provides for integration into ``setup.py`` scripts, you can also
           provide this configuration in a different way, namely as a keyword
-          argument to the ``setup()`` function. See `Distutils/Setuptools
-          Integration`_ for more information.
-
-.. _`distutils/setuptools integration`: setup.html
+          argument to the ``setup()`` function. See
+          :ref:`setup-integration` for more information.
 
 
 Default Extraction Methods
diff --git a/docs/numbers.rst b/docs/numbers.rst
index 2800472..fb71adf 100644
--- a/docs/numbers.rst
+++ b/docs/numbers.rst
@@ -1,8 +1,10 @@
 .. -*- mode: rst; encoding: utf-8 -*-
 
-==========================
+.. _numbers:
+
+=================
 Number Formatting
-==========================
+=================
 
 
 Support for locale-specific formatting and parsing of numbers is provided by
diff --git a/docs/setup.rst b/docs/setup.rst
index 6bb2a02..ef203e9 100644
--- a/docs/setup.rst
+++ b/docs/setup.rst
@@ -1,5 +1,7 @@
 .. -*- mode: rst; encoding: utf-8 -*-
 
+.. _setup-integration:
+
 ================================
 Distutils/Setuptools Integration
 ================================