Re: ClientCookie bug (followup)
Gary Feldman <gafStopSpamDat a@ziplink.stopa llspam.net> writes:
[color=blue]
> On 18 Aug 2003 14:43:06 +0100, jjl@pobox.com (John J. Lee) wrote:
>[color=green]
> >Hmm, good idea, but I really don't want to split the documentation up
> >-- one page is simpler -- and the example is instructive for people[/color]
>
> Then definitely blockquote it (or indent it some other way), and consider
> putting it into a smaller font, or using a grey background, or something
> else to indicate that it's a digression.[/color]
Again, that would be a good idea if it *were* a digression, but it's
necessary for understanding what the module gets up to. Without that
understanding in the reader's mind, it's hard to explain the code that
one uses in practice if it's any more complicated than urlopen. And
the very top of the page says:
| import ClientCookie
| response = ClientCookie.ur lopen("http://foo.bar.com/")
|
|This function behaves identically to urllib2.urlopen , except that it
|deals with cookies automatically. That's probably all you need to
|know.
So you don't even have to read further than that for most purposes. I
can't see how to improve on that, but I'm happy to learn how!
[color=blue]
> Orange would draw attention to
> it; you want the opposite.[/color]
Only the comment is in emacs-orange (well, my copy of python-mode uses
that kind of rust-orange for Python comments), so it doesn't
particularly draw attention to that block of code more than the rest.
And I *do* want to draw attention to the comment, so people read the
comment before the code.
Admittedly, it doesn't seem to work ;-) (on a sample of one
misinterpreter, Mark, so far -- I only just added that comment
recently, though there are several other warnings that cover the same
ground elsewhere).
John
Gary Feldman <gafStopSpamDat a@ziplink.stopa llspam.net> writes:
[color=blue]
> On 18 Aug 2003 14:43:06 +0100, jjl@pobox.com (John J. Lee) wrote:
>[color=green]
> >Hmm, good idea, but I really don't want to split the documentation up
> >-- one page is simpler -- and the example is instructive for people[/color]
>
> Then definitely blockquote it (or indent it some other way), and consider
> putting it into a smaller font, or using a grey background, or something
> else to indicate that it's a digression.[/color]
Again, that would be a good idea if it *were* a digression, but it's
necessary for understanding what the module gets up to. Without that
understanding in the reader's mind, it's hard to explain the code that
one uses in practice if it's any more complicated than urlopen. And
the very top of the page says:
| import ClientCookie
| response = ClientCookie.ur lopen("http://foo.bar.com/")
|
|This function behaves identically to urllib2.urlopen , except that it
|deals with cookies automatically. That's probably all you need to
|know.
So you don't even have to read further than that for most purposes. I
can't see how to improve on that, but I'm happy to learn how!
[color=blue]
> Orange would draw attention to
> it; you want the opposite.[/color]
Only the comment is in emacs-orange (well, my copy of python-mode uses
that kind of rust-orange for Python comments), so it doesn't
particularly draw attention to that block of code more than the rest.
And I *do* want to draw attention to the comment, so people read the
comment before the code.
Admittedly, it doesn't seem to work ;-) (on a sample of one
misinterpreter, Mark, so far -- I only just added that comment
recently, though there are several other warnings that cover the same
ground elsewhere).
John
Comment