[Doc-SIG] Cross-reference proposal

[Edward Welbourne]

> 2. I *do* use comments in doc strings!

Not an issue.  As I specified it, the use of #...# is for samples of
*code when they appear in text* within a doc string.  Thus, for example:

    One can call #open('/tmp/junk', 'w')# to obtain a scratch file or
    one can use:

    Code:
        i = 0
        while 1:
            try: fd = open('/tmp/junk%d' % i, 'r') # ith template file
            except IOError:
                return open('/tmp/junk%d' % i, 'w') # nonexistent file
            fd.close()
            i = 1 + i

The parser knows when it's in an embedded Code: block so regards # as
starting a comment in one of those; but where it meets # in the text of
a paragraph, it knows that it's the start of an in-text code fragment.

Furthermore, in a Code: block but after the first # on a line, we can
use #...# to delimit fragments of code appearing in a comment (just as
we can use *emphasis* in comments without the * being interpreted as
`multiply') and have the doc-string parser understand it as such.

If you're putting comments *against the text* in a doc string, # thus,
as opposed to *within an example block*, you're being gratuitously
perverse and you deserve everything you get ;^>

As to # not being pretty ... tough.  Being unambiguous is important,
being easy to spot is important, being easy to type is important, being
pretty is what the down-stream tools support.  Fontification and
colouring might be able to help, in the mean time ...

	Eddy.