Documentation suggestions

[Fredrik Lundh]

Ian Bicking 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
> >     http://mail.python.org/pipermail/python-list/2005-May/280755.html
> >     http://effbot.org/zone/idea-seealso.htm
>
> I'm unclear what the workflow is that you are proposing.  Given a
> <seealso> chunk, how does it get into the documentation?  Do you submit
> it via the bug tracker, and a committer puts it in the repository, and
> the build process puts it into the HTML?

yep.  you can view the seealso file as a collection of all trackbacks you
might have sent.

see andrew's post for an implementation outline.

> Incidentally, I was noticing on microformats.org that they were talking
> about a rev attribute
> (http://www.microformats.org/blog/2005/12/01/rel-vs-rev/) which might
> work like:
>
>   <a href="http://python.org/doc/current/lib/module-atexit.html"
> rev="example">
>
> And would be embedded in your page on that module.  Then you might
> simply notify python.org that the page exists, and it would parse out
> the relation to the documentation based on this.  Anyway, I was just
> reading about rev yesterday, so it came to mind, but it's otherwise an
> aside.

the problem with rev is that it's a 1:1 relation between the two pages.

the seealso file is more about linking your pages to a "virtual target
domain", so that anyone that's interested can build their own service
on top of it.  web 2.0, you know...

</F>