[PYTHON DOC-SIG] Structured documentation syntax

[Jim Fulton]

Robin Friedrich wrote:
> 
> |> Date: Thu, 12 Sep 1996 09:42:47 -0400
> |> From: Jim Fulton <jim.fulton@digicool.com>
> ...
> |> 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.
> 
> OK now where getting somewhere. Does anyone volunteer to hack something
> up to try out? ;-)

Hm. Well, for the first part, "" -> [], I assume that this would be
a fairly minor change.

The second part needs some thinking by someone who is very familiar 
with the URL hierarchy defined by gendoc. (Is this documented 
somewhere?) My thought is that the hierarchy should be reviewed
before any hacking takes place. To me, this feels like an exercise 
for the gendoc author.

Jim

> 
> =================
> DOC-SIG  - SIG for the Python Documentation Project
> 
> send messages to: doc-sig@python.org
> administrivia to: doc-sig-request@python.org
> =================

-- 
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
=================