[PYTHON DOC-SIG] Structured documentation syntax

[Robin Friedrich]

|> From skip@automatrix.com Thu Sep 12 07:25 CDT 1996
|> Date: Thu, 12 Sep 1996 08:22:54 -0400
|> From: Skip Montanaro <skip@automatrix.com>
|> To: klm@CNRI.Reston.Va.US
|> Cc: Robin Friedrich <friedric@rose.rsoc.rockwell.com>,
|>         s-ping@orange.cv.tottori-u.ac.jp, doc-sig@python.org
|> Subject: Re: [PYTHON DOC-SIG] Structured documentation syntax
|> Reply-To: skip@calendar.com (Skip Montanaro)
|> Content-Type: text
|> Content-Length: 802
|> 
|> Ken Manheimer writes:
|>    
|>    Having not kept track of the specifics, i don't know what disqualifies
|>    what i would consider the obvious candidate - angle brackets, eg,
|>    "<http://www.python.org>".  This is the way i've frequently seen URLs
|>    distinguished - is there a reason not to use them generally for
|>    hyperlinks?  Maybe because they specifically imply URLs, or because
|>    they're already dedicated to some other purpose?
|> 
|> That was my thought also.  I believe the "official" way to distinguish URLs
|> in otherwise plain ASCII text is with a URL: prefix, as in:
|> 
|> 	<URL:http://www.python.org/>
|> 

OK guys. Here's the reasoning.
You want the doc string to be as easy to read and devoid of
uninformative markups as possible. Placing the actual link address
(which can be quite long) in the body of the doc string really hurts
that. IMHO moving the link address to a footnote area solves this and
still provides enough data for the processor to generate the
appropriate HTML. That leaves only some kind of delimiter of what text
is to be highlighted in the flow of the text. This I feel preserves the
readability of the doc string for those reading source. This idea came
from setext.

-Robin

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

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