On Jan 23, 2006, at 5:49 PM, Ian Bicking wrote:
Bob Ippolito wrote:
One thing that's interesting about his approach is that the
links don't need to understand what their targets are -- i.e.,
you don't need special links for modules, or classes, or
methods. That could be particularly useful for TG if it meant
that it could link to document on other sites, maybe using the
package as a key to a rool url, like sqlobject points to http://
sqlobject.org/lib/, MochiKit to http://mochikit.com/doc/html/
MochiKit/, etc.
You can do that with just about anything. In fact, the MochiKit
make_docs.py script does something awfully close to that.
References that start with "MochiKit." refer to other modules of
MochiKit, so they end up at named anchors on other HTML pages.
References that aren't fully qualified just point at a named
anchor. It also prettifies the output of the reference such that
the user doesn't see the fully qualified name, since that's
generally just visual clutter.
So you are doing `MochiKit.DOM.TABLE`:mochiref, right? then
translating that to MochiKit/DOM.html#TABLE, and translating the
text to TABLE (based on the namespace of the containing document,
or always stripping the namespace?)
Here's some examples that cover all of the cases that mochi_name
currently handles:
:mochiref:`MochiKit.DOM.computedStyle(elem, style,
mozillaEquivalentCSS)`
<a href="DOM.html#fn-computedstyle">computedStyle(elem, style,
mozillaEquivalentCSS)</a>
:mochiref:`computedStyle(elem, style, mozillaEquivalentCSS)`
<a href="#fn-computedstyle">computedStyle(elem, style,
mozillaEquivalentCSS)</a>
:mochiref:`MochiKit.DOM`
<a href="DOM.html">MochiKit.DOM</a>
It's of course rather specialized, but it's very easy to cut and
paste the role I've written and do something slightly different for
another purpose.
All we need then is a global index of fully qualified names to
target URLs, and either rewrite the pages (nice for static
publishing) or do redirects (nice for linking).
Personally I try hard to make sure stuff I do doesn't depend on
arbitrary server-side junk, and that it's relatively friendly to
search engines. I don't see any good reason to use a redirector
here. It's not like we have a marketing department that cares about
exit page information :)
I'm really trying hard to not reimplement other people's stuff
though ;) OTOH, if the redirector was in place then at least it
would be HTTP-API compatible with Frederik's work. And I think one
thing we all share in common is that we care almost solely about
HTML output, and don't really care about PDF or whatever.
docutils does have quite nice PDF output (via pdftex, anyway), but
HTML is *way* more appropriate for this kind of document.
On the other hard, one /theoretical/ advantage that PythonDoc has is
that it would be possible to extend developer tools (IDEs and
whatnot) to understand its tags, which contain semantic information
that would be useful for tool tips, completion, etc. That's at a
cost though, just like manifest typing in general. Practically, I
can't imagine that happening any time soon.
-bob
