[PYTHON DOC-SIG] Structured documentation syntax

[Jim Fulton]

Robin Friedrich wrote:
> 
> |> 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.

Absolutely.

I like the idea of using []s.

Furthermore, I can see a usage where instead of saying:

   blah blah blah [spam] blah blah 

   ....

.. [spam] http://...

One could say:

   blah blah blah spam [42] blah blah 

   ....

.. [42] http://...

Where "[42]" gets highlighted. Which I would fine more readable 
as text and just as readable as hypertext.

It would also be useful to define a URL hierarchy for gendoc
and allow relative references in footnotes, so that a doc string could
include links to documentation for other objects in the same module 
or other modules.  This would also help to reduce HTML dependencies.
For example, relative references might work for info files as well.

Jim

-- 
Jim Fulton         Digital Creations
jim@digicool.com   540.371.6909
## Python is my favorite language ##
##     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
=================