Python Documentation (vs PHP stuff)

[Fredrik Lundh]

Terry Reedy wrote:

> Conclusion 1: if PHP is anything as awful as the manual, it is not for me.

the whole idea that turning the manual into a wiki or a forum will solve all
problems is extremely naive.

on the other hand, having written lots of "manual enhancing material", I would
love to be able to add links to the library manual in some non-intrusive way
(similar to blog trackbacks).  what you need is a way to uniquely identify a
library construct (e.g. a psuedo-URL or simply a dotted path), a way to
contribute a path/link collection, and an addition to the HTML generation
toolchain that adds relevant links to the generated HTML.  e.g.

    <annotations src="http://effbot.org/python-annotations.xml">
        <example>
            <title>Building An Asynchronous FTP Client</title>
            <target>asynchat.async_chat</target>
            <href>http://effbot.org/zone/asyncore-ftp-client.htm</href>
        </example>
         <example>
            <title>The select module</title>
            <target>select.select</target>
            <href>http://effbot.org/librarybook/select.htm</href>
        </example>
        <example>
            <title>Using the tempfile module to open temporary files</title>
            <target>tempfile</target>
            <target>tempfile.TemporaryFile</target>
            <href>http://effbot.org/librarybook/tempfile.htm#tempfile-example-2</href>
        </example>
        <example>
            <title>Importing Python Modules</title>
            <target>statement:import</target>
            <target>statement:from</target>
            <href>http://effbot.org/zone/import-confusion.htm</href>
        </example>
    </annotation>

(I'm sure some RDF hacker can come up with an unreadable alternative
to this, if necessary ;-)

this eliminates the need for constant monitoring of wiki pages and forums, and
reduces the workload for the documentation editors compared to all the "feel
free to contribute patches" alternatives.  if some annotation provider produces
bad stuff or spam, remove his/her annotations, or use a whitelist/blacklist on
individual items.

if someone fixes the python.org end of things, I can generate an effbot.org
annotation index within a day or two.

</F>