[PYTHON DOC-SIG] Structured documentation syntax

[Skip Montanaro]

   Why not simply use the Netscape-style of highlighting links, e.g.
   simply write http://somewhere/outthere and have that converted
   directly to a link ? (using the http://, ftp://,... as tag
   to recognize them)
   
The problem is in knowing where to stop when the URL is embedded in a
sentence.  In many operating systems, common punctuation characters (commas,
periods, etc) are valid in URLs.  So, if I write:

   Check out the Python documentation at http://www.python.org.

Where is the end of the URL?  Since the common parenthetical character pairs
occur much less frequently in URLs, they become a much safer choice.  In
particular, using < and > works the best because start and end HTML tags and
so must be used in their entity forms (&lt; and &gt;) within a URL (at least
in an HTML context).  So, it's easy for a dumb program to pick out the URL
in the following:

   Check out the Python documentation at <URL:http://www.python.org>.

The "URL:" is pretty much superfluous these days, but there are other
address-like things presumably waiting in the wings like URIs (Uniform
Resourse Identifiers, I believe) that are supposed to give a measure of
location indepence to information.

Skip Montanaro     |   Musi-Cal: http://concerts.calendar.com/
skip@calendar.com  |   Conference Calendar: http://conferences.calendar.com/
(518)372-5583      |   Python: http://www.python.org/

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================