Another merge. Only doc stuff was affected (but this aligns the UTF-32

codec changes in trubk and branch).  Hopefully the Py3k glossary wasn't
different from the trunk one.

Doc/contents.rst

@@ -14,6 +14,7 @@
    install/index.rst
    documenting/index.rst
    howto/index.rst
+   glossary.rst
 
    about.rst
    bugs.rst

Doc/documenting/markup.rst

@@ -290,6 +290,11 @@ Variable names are an exception, they should be marked simply with ``*var*``.
 
 For all other roles, you have to write ``:rolename:`content```.
 
+.. note::
+
+   For all cross-referencing roles, if you prefix the content with ``!``, no
+   reference/hyperlink will be created.
+
 The following roles refer to objects in modules and are possibly hyperlinked if
 a matching identifier is found:
 
@@ -374,6 +379,20 @@ to objects:
    The name of a grammar token (used in the reference manual to create links
    between production displays).
 
+
+The following role creates a cross-reference to the term in the glossary:
+
+.. describe:: term
+
+   Reference to a term in the glossary.  The glossary is created using the
+   ``glossary`` directive containing a definition list with terms and
+   definitions.  It does not have to be in the same file as the ``term``
+   markup, in fact, by default the Python docs have one global glossary
+   in the ``glossary.rst`` file.
+
+   If you use a term that's not explained in a glossary, you'll get a warning
+   during build.
+
 ---------
 
 The following roles don't do anything special except formatting the text

Doc/tutorial/index.rst

@@ -41,6 +41,8 @@ language's flavor and style. After reading it, you will be able to read and
 write Python modules and programs, and you will be ready to learn more about the
 various Python library modules described in the Python Library Reference.
 
+The :ref:`glossary` is also worth going through.
+
 .. toctree::
 
    appetite.rst
@@ -57,4 +59,3 @@ various Python library modules described in the Python Library Reference.
    whatnow.rst
    interactive.rst
    floatingpoint.rst
-   glossary.rst

Doc/tutorial/stdlib.rst

@@ -158,13 +158,15 @@ and :mod:`smtplib` for sending mail::
    >>> import smtplib
    >>> server = smtplib.SMTP('localhost')
    >>> server.sendmail('soothsayer@example.org', 'jcaesar@example.org',
-   """To: jcaesar@example.org
-   From: soothsayer@example.org
-
-   Beware the Ides of March.
-   """)
+   ... """To: jcaesar@example.org
+   ... From: soothsayer@example.org
+   ...
+   ... Beware the Ides of March.
+   ... """)
    >>> server.quit()
 
+(Note that the second example needs a mailserver running on localhost.)
+
 
 .. _tut-dates-and-times: