Annotatable Python docs -- now a reality !!!

[Carlos Ribeiro]

On 13 Sep 2004 12:00:11 -0700, Bob <bobx at linuxmail.org> wrote:
> Why not convert them to a wiki format? That would be a good and clean way to do it.

In my not-so-humble opinion, the *best* way to solve it would be a
custom Wiki-like implementation, where the docs would stay as they are
(unedited) with comments attached to the text. I have imagined it like
this:

-- add some "anchors" to the documentation, using a visual indicator.
(for example, at the start of every subsection or even paragraph; the
anchor could aligned to the left margin without cluttering the
format).

-- clicking on the anchor allows one to collapse/expand the
annotations for that section.

-- once expanded, it would be possible to write an a new annotation
just by writing it with Wiki-style markup.

To make things complete, the Wiki-style markup would allow for links
to the documentation using a simple syntax; for example,
[[Library/strings]] would point to the documentation chapter for the
strings standard library. This would make navigation pretty easy.

But in retrospect, I think that AMD did the right thing. I could be
talking about it for days to end, but he did implement his version,
and made it available, and that's what count -- actual running code.


-- 
Carlos Ribeiro
Consultoria em Projetos
blog: http://rascunhosrotos.blogspot.com
blog: http://pythonnotes.blogspot.com
mail: carribeiro at gmail.com
mail: carribeiro at yahoo.com