[Doc-SIG] Re: reST: standalone hyperlinks

[David Goodger]

Tony J Ibbs (Tibs) <tony@lsl.co.uk> wrote on 2001-08-08 5:21 AM:
> Referring to the URI spec is not sufficient, since traditionally
> people have used ad-hoc schemes to detect URIs (particularly since
> the REs to detect them properly get, well, somewhat complex).

I've expanded the overview a bit in reStructuredText.txt:

"""
Two forms of URI are recognized:

1. Absolute URIs. These consist of a scheme, a colon (':'), and a
   scheme-specific part whose interpretation depends on the scheme.

   - The scheme is the name of the protocol, such as 'http', 'ftp',
     'mailto', or 'telnet'. The scheme consists of an initial letter,
     followed by letters, numbers, and/or '+', '-', '.'.

   - The scheme-specific part of the resource identifier may be either
     hierarchical or opaque.

     - Hierarchical identifiers begin with one or two slashes and may
       use slashes to separate hierarchical components of the path.
       Examples are web pages and FTP sites:

           http://www.python.org

           ftp://ftp.python.org/pub/python

     - Opaque identifiers do not begin with slashes. Examples are
       email addresses and newsgroups::

           mailto:someone@somewhere.com

           news:comp.lang.python

   With queries, fragments, and %-escape sequences, URIs can become
   quite complicated. A reStructuredText parser must be able to
   recognize any absolute URI, as defined in RFC239_.

2. Standalone email addresses, which are treated as if they were
   ablsolute URIs with a 'mailto:' scheme. Example::

       someone@somewhere.com

Punctuation at the end of a URI is not considered part of the URI.
"""

I don't think the spec needs to be any more detailed than this. (If
you do, please write the text! I'm sick of reading that RFC.) If the
reader wants to know more, they can follow the links to the RFC.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net