[Doc-SIG] Cross-reference proposal
Edward Welbourne <firstname.lastname@example.org>
Thu, 10 Feb 2000 13:20:36 +0000
> I hope I demonstrated (elsewhere, "London") that 4 is equally
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 email@example.com,
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.