[Doc-SIG] Cross-reference proposal

[Tony J Ibbs (Tibs)]

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.)