Edward Welbourne wrote (I'm giving up including the date, since Outlook <fs:spit> ain't helping me and I'm not sure anyone cares):
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 ...)
No. (do I need explanations? do I *have* explanations? well, *I* wouldn't be able to visually parse it - I prefer Eddy's "#"!)
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.
As I've said in a reply to Peter Funk elsewhere, I think you *can't* guess if a doc string is not marked up because it (deliberately) wasn't, or because it (for instance) predates markup. So I think the choices have to be: i. doc string is clearly marked up (I'll concede detecting that for practical purposes, for some value of "clearly"), and there are #...# (or whatever). ii. doc string is clearly marked up, but there are no #...#? How do you tell if they just didn't *want* any cross references? iii. doc string clearly isn't marked up (for values of "clearly" as defined above, or perhaps their inverse!). In case i you can obviously use the cross references, and must not generate new ones. In case ii, I think there should be an option to the processor (e.g., -force_xref) which forces generation of cross references if the user believes they have "obviously" been omitted. But it needs a human to tell. In case iii, I'd prefer an option to tell the processor about the (probably infrequent) cases where the absence of markup was deliberate (e.g., -absent_xref). But in practice, I might have to live with the markup getting generated regardless - so could I have a pragma to say "this doc string contains no markup" please? (ouch) Tibs, getting tangled in conditional clauses -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)