Documentation suggestions

[Fredrik Lundh]

A.M. Kuchling wrote:

> > I've proposed adding support for semi-automatic linking to external
> > documents, based on a simple tagging model, a couple of times, e.g.
> >
> >     http://mail.python.org/pipermail/python-list/2005-May/280751.html
>
> Very interesting.  There could be a manually-maintained list of feed
> URLs stored in a file in the Doc/ subdirectory.  That way, anyone with
> Python SVN access could add a feed, and it's not trapped in some
> database on python.org that half the pydotorg group doesn't know
> about.
>
> A Makefile target could then update the list of available examples,
> and check timestamps to only update the list every 24 hours or so,
> avoiding hitting the feeds every time you do "make lib".  Fred Drake
> would have some "make updatefeed" target for forcing an update when he
> makes the release tarballs.

exactly.

> ISTM getting the example into the HTML is the hard bit.  Maybe the
> simplest solution is to put
>
> % start auto-feeds
> % end auto-feeds
>
> into LaTeX source files, and have a script insert the examples between
> the markers with the right LaTeX markup.

or just add a marker (in some for me unknown way), and postprocess
the HTML files.  I'm not sure the links does necessarily belong in e.g.
PDF renderings of the documentation, but that's of course up to the
documentation maintainers.

> Hm, but then 'svn diff' will show lots of changes.  Maybe an '\input
> <modulename>-examples could be used instead, storing the examples in a
> separate file.  Something like
> '\InputFileExists{examples/select.tex}'...  Having some examples be
> for'atexit' and some specifically for 'atexit.register' seems
> difficult with this approach.

linking on module level only should definitely be good enough for a first
iteration.

> Assembling a patch for this would make an interesting evening's
> project.

if anyone wants some data to play with, I've posted a simple seealso file
here:

    http://effbot.org/librarybook/seealso.xml

</F>