Annotatable Python docs -- now a reality !!!

Discussion in 'Python' started by Stephen Ferg, Sep 13, 2004.

  1. Stephen Ferg

    Stephen Ferg Guest

    Andrew Kuchling has just posted this (see below) on his blog.

    I'm confident that people will use this, if they know it is available.
    So now is the time to get the word out. This is something everyone in
    the Python community should know about it.

    ==================================================
    from http://www.amk.ca/diary/archives/cat_python.html#003336

    September 09, 2004

    Annotatable Python docs

    In recent months several posters on comp.lang.python have suggested
    that Python would benefit from making it possible for people to
    comment on the documentation, an approach similar to the PHP docs.
    However, no one has ever actually tried to set up such a system.

    In a half-hour hack, I wrapped a frameset around the Python 2.3.4
    documentation, added some JavaScript that updates another frame to
    display a Wiki page for the documentation page you're viewing, and
    simplified the Wiki pages as much as I easily could.

    The resulting annotatable documentation is at
    http://pydoc.amk.ca/frame.html. Please go and add any commentary,
    links, or other material you wish. Let's see if commenting on the docs
    is a feature people will use, or if it's a feature people just say
    they'll use.
    Stephen Ferg, Sep 13, 2004
    #1
    1. Advertising

  2. (Stephen Ferg) writes:

    > Andrew Kuchling has just posted this (see below) on his blog.


    He also posted about it here last week!
    ().

    Cheers,
    mwh

    --
    I have *both* hands clapping, but I'm still not sure it's a sound.
    When I tried deciding if it were a sound while clapping only one
    hand, I fell off my chair.
    -- Peter Hansen, Zen master, comp.lang.python
    Michael Hudson, Sep 13, 2004
    #2
    1. Advertising

  3. Stephen Ferg

    Guyon Morée Guest

    oooow man, i was working on this same thing since I was told: "do it
    yourself then!".


    but anyway, i had kinda the same idea using javascript to update a frame,
    but not in a wiki form...


    "Stephen Ferg" <> wrote in message
    news:...
    > Andrew Kuchling has just posted this (see below) on his blog.
    >
    > I'm confident that people will use this, if they know it is available.
    > So now is the time to get the word out. This is something everyone in
    > the Python community should know about it.
    >
    > ==================================================
    > from http://www.amk.ca/diary/archives/cat_python.html#003336
    >
    > September 09, 2004
    >
    > Annotatable Python docs
    >
    > In recent months several posters on comp.lang.python have suggested
    > that Python would benefit from making it possible for people to
    > comment on the documentation, an approach similar to the PHP docs.
    > However, no one has ever actually tried to set up such a system.
    >
    > In a half-hour hack, I wrapped a frameset around the Python 2.3.4
    > documentation, added some JavaScript that updates another frame to
    > display a Wiki page for the documentation page you're viewing, and
    > simplified the Wiki pages as much as I easily could.
    >
    > The resulting annotatable documentation is at
    > http://pydoc.amk.ca/frame.html. Please go and add any commentary,
    > links, or other material you wish. Let's see if commenting on the docs
    > is a feature people will use, or if it's a feature people just say
    > they'll use.
    Guyon Morée, Sep 13, 2004
    #3
  4. Michael Hudson <> said :

    > He also posted about it here last week!
    > ().


    Well I, for one, had missed that first annoucement, so thanks to Steve for
    the repeat !

    I trust it will also appear in the next weekly DrDobbs/Python URL...

    --
    YAFAP : http://www.multimania.com/fredp/
    Fred Pacquier, Sep 13, 2004
    #4
  5. On Mon, 13 Sep 2004 16:30:15 +0200,
    Guyon Morée <gumuz@NO_looze_SPAM.net> wrote:
    > oooow man, i was working on this same thing since I was told: "do it
    > yourself then!".
    > but anyway, i had kinda the same idea using javascript to update a frame,
    > but not in a wiki form...


    You can still help by offering patches to fix bugs in the JavaScript;
    various people have pointed out problems in the comments at
    http://www.airynothing.com/cgi-bin/mt-comments.cgi?entry_id=3336 .

    --amk
    A.M. Kuchling, Sep 13, 2004
    #5
  6. So, is there a way to search for annotations? I don't mean any text
    in particular, I mean 'show me everything that has been annotated'.
    Robin Siebler, Sep 13, 2004
    #6
  7. Stephen Ferg

    Bob Guest

    Why not convert them to a wiki format? That would be a good and clean way to do it.
    Bob, Sep 13, 2004
    #7
  8. On 13 Sep 2004 12:00:11 -0700, Bob <> 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:
    mail:
    Carlos Ribeiro, Sep 13, 2004
    #8
  9. Bob> Why not convert them to a wiki format?

    Convert what to a wiki format? Not everyone will have your reference
    message available.

    Skip
    Skip Montanaro, Sep 13, 2004
    #9
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. main\(\){};
    Replies:
    3
    Views:
    1,058
    Steve McLellan
    Dec 14, 2004
  2. Tormod Hystad
    Replies:
    0
    Views:
    432
    Tormod Hystad
    Jul 4, 2003
  3. KYG
    Replies:
    2
    Views:
    884
    Ian Collins
    Aug 18, 2008
  4. Stéphane Wirtel
    Replies:
    0
    Views:
    181
    Stéphane Wirtel
    Apr 19, 2007
  5. Al
    Replies:
    1
    Views:
    151
    Henry Law
    Oct 16, 2005
Loading...

Share This Page