[Doc-SIG] Some random thoughts

[Tony J Ibbs (Tibs)]

First off topic, then back on (honest)...

> Edward Welbourne wrote:
> Tibs tells me my habitual use of, e.g.
>
>     try: val = dict[key]
>     except KeyError: val = default
>
> is unkind to other pythoneers.

to which Laurence Tratt replied:
> Yeah, that's fairly evil as is the whitespace abuse <wink>.

and then David Ascher said:
> Especially because it should be spelled
>
>   val = dict.get(key, default)
>
> =)

I should point out in Eddy's defence here that the company we work for
(although not for much longer in his case) is still using Python 1.3, in
which his example is correct (if evil).

As to the debate - I don't think there *is* much disagreement. We have three
cases (I reserve the right to add more as we go on - this *is* Python, after
all):

		(PS: please excuse any misformatting - I'm
		 fighting Outlook <fx:spit> - does anyone know
		 how to get its editor out of overwrite mode?)

NB: note I'm using EXAMPLES - can we try to do this, it makes it easier for
me to think...

1. Very short code fragments inline, typically containing identifiers.
   I'm willing to mandate that they can't cross line boundaries, even,
   if someone would like that.
   For example #fred# or #self.text = 3#

   (think of TeX and the $maths$ notation, I guess). These are candidates
   for the "guess the identifier and insert a cross reference" algorithm.

   I still don't like the appearance of Eddy's choice, but am yet to be
   convinced of any other choice either...

2. Examples of code that we expect to run Tim Peter's doc test tool over
   For example:

	>>> 1+4
	5

   This does not (by Tim's argument) need delimiting in any other way, as it
   can be detected by the same mechanism that doc test itself uses.
Furthermore,
   it is (I believe) Tim's contention that examples of code like this
*should*
   be perused by doc test, so this is a Good Way of doing it. See previous
   articles in this group, and also Tim's doctest.py itself.

3. Other code stuff - examples of chunks of invalid Python code, bits of
code
   we're showing for other reasons, pieces of Fortran, etc.
   For example:

	Code:
	    C Sometimes one wants misformatted Fortran examples...
	    DO I = 1,3
	       J = J + 1

   Note that the tag "Code:" is not necessarily correct - I think we
actually
   had "Example:" in an earlier draft.

Finally, we clearly need some way of escaping characters (otherwise I can't
refer to the Python comment character in a doc string's main text, for
instance!). We can't use \ (backslash) because that's already working as an
escape character (unless we were to insist on raw strings, which is a
no-no). I hereby propose, just for something to do, that it be ~,
so we could have:

	"""This is a test docstring

	I expect somewhere there's a variable called #fred#, to which
	I expect to assign integers (e.g., #fred = 3#). However, I'll
	be sure to comment it when I do, and comments start with ~#
	(or should that be #~##?).
	"""

Do I *like* ~ as the character? No. But a proposal people can disagree with
is better than no proposal (I hope).

Tibs (am I being conciliatory or argumentative?)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.demon.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)