Documentation suggestions

[A.M. Kuchling]

On Tue, 6 Dec 2005 18:33:05 +0100, 
> 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.

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.  

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.  

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

--amk