[Doc-SIG] Update to Docutils

David Goodger goodger@python.org
Fri, 15 Nov 2002 21:56:06 -0500

As always, the latest CVS snapshot can be had from


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

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:


Details of the issues considered and alternatives weighed can be found


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:


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/