[DOC-SIG] Xrefs

[David Ascher]

On Mon, 2 Mar 1998, Robin Friedrich wrote:

> > eg, I saw the note saying "you must explicitly reference all objects".  I
> > dont like that idea - IMO, you should require the same level of reference
> > that the code would.  Eg:
> >
> > def foo():
> >   pass
> > def bar()"
> >   """ See also [foo function]
> >  ..[foo function] foo # Should not need to know the full location
> >
> > Or did I mis-understand?
> 
> didn't misunderstand.  That's because it was thought that it would make it
> easier for the reader (of the source) to know which object without having to
> calculate the python scoping rules and deduce the correct path. Maybe this is
> unnecessary. It would make things somewhat more complicated for gendoc though.
> If you guys think it's easy enough fine, (i hearby volunteer NOT to code this
> bit).

Do we really want to limit ourselves to Python scoping rules (e.g. the
two-scope rule) in a purely textual description?  It strikes me that
Python's rules, which make some sense in the context of evaluated code,
make very little sense in the context of documentation.  E.g. I think
it'd be nice to be able to have:

	class Klass
		def f3():
			print 'Ni!'

		def f1():
			foo = 'SPAM!'

			def f2():
			""" and here I refer to f1, Klass, f2,
			Klass.f3, and f1.foo
			"""
				something...


After all, .py files are pretty static...

--da


_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________