[Doc-SIG] docstring grammar

[Edward Welbourne]

MAL said:
7 I would extend the reference scheme to a lookup in the module
  globals in case the local one (in the Reference section) fails.
  You could then write e.g. "For details see the [string] module."
  and the doc tool would then generate some hyperlink to the
  string module provided the string module is loaded into the
  global namespace.

We have, it occurs to me, another important namespace: unimported
modules.  Thus the string module doesn't import re, I assume, but may
wish to refer to it (e.g. to say `this function is a cheap variant of
the eponymous one in re') in its doc-strings.  Fortunately, we also have
a handy name to hang this namespace off (which can't coincide with a
name in either of our namespaces): import.  Thus: `this function is a
cheap variant of import.re.search' could be sensible in doc strings.

Note, however, that some bypassing of this may be achieved using the
[blah] notation (which is good).

I have a problem with too much vertical white space, but I believe the
perturbations Tibs suggested (and which match what's in gendoc /
pythondoc - if my memory isn't disserving me again - so must be
feasible) suffice to deal with that.  I can make my editor window more
than a hundred columns wide if I want, and know that code lines jutting
past that are too long; but I still only get 55 lines in sight at the
same time, and real code often involves wanting to see more than that.
This situation gets badly exacerbated by being obliged to throw
gratuitous blank lines (though not as much as by my tendency to
verbosity).  But, like Tibs, I can live with the vspace if I must.

What happened to gendoc / pythondoc ?

	Eddy.