[Doc-SIG] Cross-reference proposal

[Edward Welbourne]

> I hope I demonstrated (elsewhere, "London") that 4 is equally
> dangerous

The first word of each sentence is capitalised.  This can lead to
further mis-fires of rule 4.

> english allows acronyms with "." as well ... N.B.
I.mech.eng., Ph.D., ...
which all end in a dangling ., which might make them recognisable,
except that legit name.attr may appear at end of sentence.

Further (c.f. why I don't advocate @ for the in-text code delimiter),
text may legitimately contain domain names ... which we *do* want to
make subjects of hyperlinks, but the href is invented differently than
if it were a dotted python identifier ... indeed, chaos.org.uk wants to
be linked as http://www.chaos.org.uk/ while eddy@chaos.org.uk,
naturally, should be either a mailto or (which I'd prefer, but others
might not) http://www.chaos.org.uk/~eddy/.

> ... #fred.spam# (to use Eddy's annotation, which I still hate)
Can someone come up with a viable alternative that's less ugly ?
Will North Americans have problems with using # in text as the number
indicator ? [what is standard N.A. usage of # ?]

Would ` . ' (a dot surrounded by space) be acceptable as a delimiter for
code embedded in text ?  (I don't like it, but I guess it could work ...)

> Summary: ... no markup ... guess..., but ... with ... markup is *all*

So, back to my earlier question: Ping, how much palaver would it take to
have two ways of processing a doc-string, for the phase which decides
what's code (and possibly hyperlink) and what's not:

  marked up -- if the doc-string appears to be using #...# for in-text
  code fragments, take those fragments as code (no guessing)

  unmarked -- if the doc-string doesn't use #...#, make Ping's educated
  guesses at what is code and what isn't

then generate hrefs from identifiers in the code fragments thus
identified ?  Other hrefs may be generated other ways -- e.g. to URLs in
the text -- but hrefs to python objects only get auto-generated if in a
code fragment, however it has been recognised.

	Eddy.