[Doc-SIG] Update to Docutils

[David Goodger]

As always, the latest CVS snapshot can be had from

    http://docutils.sf.net/docutils-snapshot.tgz

Embedded URIs in Hyperlink References
=====================================

Back in June, Simon Budig proposed a new syntax for reStructuredText
hyperlinks, to allow target URIs/URLs to be specified inline with the
reference in the text.  I was initially ambivalent/against the
proposal (a similar mechanism was one of the flaws I found in my
analysis of StructuredText!).  One of the core values of
reStructuredText is its readability, and although the proposed syntax
offers convenience, I wasn't sure if the convenience was worth the
cost.

After a great deal of thought and much input from users, I've decided
that there are reasonable use cases for such a construct, and we've
settled on a reasonable syntax.  The following syntax will be used::

    See the `Python home page <http://www.python.org>`_ for info.

This is exactly equivalent to::

    See the `Python home page`_ for info.

    .. _Python home page: http://www.python.org

As with the non-embedded reference forms, a single trailing underscore
means "named", and you can use the same name to reference the same
target URI again.  Two trailing underscores means "anonymous"; the
target URI cannot be referenced again.

Full details can be found in the spec:

  http://docutils.sf.net/spec/rst/reStructuredText.html#embedded-uris

Details of the issues considered and alternatives weighed can be found
here:

  http://docutils.sf.net/spec/rst/alternatives.html#inline-external-targets


Recognition of Schemeless Email Addresses in Targets
====================================================

The parser has always recognized bare standalone email addresses in
text, like "Send email to jdoe@example.com", automatically prefixing a
"mailto:" URI scheme.  I noticed some cases of schemeless email
addresses in explicit targets, like this::

    .. _mail me: me@example.org

Such targets were *not* getting a "mailto:" scheme prefix, resulting
in bad hyperlinks.  That's been fixed now, in explicit targets and in
the new embedded URIs.


French & Slovak Language Support
================================

New language modules have been contributed to Docutils: Slovak from
Miroslav Vasko, and French from Stefane Fermigier.  Already supported
are German, Swedish, and English.

New language modules are always welcome.  They're easy to make;
they're just translations of a couple dozen terms.  See the newly
expanded "Docutils Internationalization" for instructions:

    http://docutils.sf.net/spec/howto/i18n.html

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/