[DOC-SIG] Xrefs

[Mark Hammond]

-----Original Message-----
From: Robin Friedrich <friedrich@pythonpros.com>
To: Doc-SIG <doc-sig@python.org>
Date: Tuesday, 24 February 1998 7:59
Subject: Re: [DOC-SIG] Xrefs


> ...
>.. [O'Reilly] http://www.oreilly.com/catalog/html2/index.html
>for an ordinary URL, or:
>.. [Wizbang] win32api:spamDialog.toolBar.wizBangPrime
>for an external reference object called win32api, or:
>.. [Geo-model] self.GeoPotentials.Model
>to point to an object within our current package with an absolute path.
>Since we mandate full pathing to python objects we don't need to specify
what the
>stating point of the reference is. Note also that the bracket highlighted
text
>does not have to correspond to the object it's pointing to.

This does seem pretty good, and the last word so far on the matter.  This
fits well with the existing code, and I imagine that if someone _really_
wanted the completely inline style, they could implement it with "<" tags.

Im probably way over generalising, but it does seem a good idea to reserve
some tokens for additional growth - I dont know - say an inline image
reference (ok - bad example - umm - anyway).  Maybe we could reserve "<" and
">" as special indicators to allow future growth.  At this stage, all it
means is that you must escape literal "<" and ">"...

Either way, the scheme above seems to meet my requirements, so we can steam
ahead :-)  How exactly do we get started (he says, suffering work overload
as it is :-)  Are there still design issues to resolve?

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?

Thanks,


Mark.



_______________
DOC-SIG  - SIG for the Python Documentation Project

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