<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body text="#000000" bgcolor="#ffffff">
<font size="-1">Sandro,<br>
</font><br>
On 2011/08/13 05:22, Sandro Tosi wrote:
<blockquote
cite="mid:CAPdtAj3fG6OwyyS72A5X4Zarz3iU0zfqzto_vL3FzH0TFBBcMg@mail.gmail.com"
type="cite">
<pre wrap="">Hello Sam,
you wrote a lot, I'll try to reply to all your points, but I'll be
dense: don't take thta for disrespect.
</pre>
</blockquote>
<small>None taken. I appreciate you've a lot to do.</small><br>
<blockquote
cite="mid:CAPdtAj3fG6OwyyS72A5X4Zarz3iU0zfqzto_vL3FzH0TFBBcMg@mail.gmail.com"
type="cite">
<pre wrap="">
On Thu, Aug 11, 2011 at 04:00, Sam Thompson <a class="moz-txt-link-rfc2396E" href="mailto:python@samthompson.com"><python@samthompson.com></a> wrote:
</pre>
<blockquote type="cite">
<pre wrap="">Sandro,
</pre>
</blockquote>
</blockquote>
<small>[snip]</small><br>
<blockquote
cite="mid:CAPdtAj3fG6OwyyS72A5X4Zarz3iU0zfqzto_vL3FzH0TFBBcMg@mail.gmail.com"
type="cite">
<blockquote type="cite">
<pre wrap="">
Thanks for explaining this. I could not find any mention of this in the
documentation itself. While I expect this may be obvious to those "in the
know", can I suggest that this important policy be explicitly stated at the
head of the documentation that this applies to, so that:
a) people don't waste your time filing bugs for things you have a policy not
to fix (note that I'm complaining about the policy - it's fine), and
b) people know that the documentation is not necessarily 100% to be relied
upon (in light of your comment below about backporting fixes), or
alternatively, remove this documentation and redirect visitors to the up-to
date version.
</pre>
</blockquote>
<pre wrap="">
You're actually suggesting to add a banner to every single page of doc
for older release, which is unfeasible. We provide documentation for
older versions "as was" when that version was last released, I don't
see the point in explaining what's the status of a specific version in
its doc.
</pre>
</blockquote>
<small>There is more than one way to address this. As I stated
earlier, I respect the project's decision not to maintain old
versions of the documentation. But I have noticed that when
projects still offer old versions of code or other material for
access or download, they are usually pretty clear about the fact
that it's unmaintained, at least at the entry points/download
links. I still haven't seen a reference to the policy, on
python.org, *outside* of the actual docs themselves.<br>
<br>
There probably are SSI or other script based solutions (I don't
know, maybe Python?) that could be used to tag each of these old
pages, even if you aren't editing them individually; I disagree
that it's unfeasible entirely, even though I'm not suggesting this
approach.</small><br>
<blockquote
cite="mid:CAPdtAj3fG6OwyyS72A5X4Zarz3iU0zfqzto_vL3FzH0TFBBcMg@mail.gmail.com"
type="cite">
<pre wrap="">
python.org/doc makes quite clear what are the supported doc version,
linking only one for 2.x and 3.x .
</pre>
</blockquote>
<small>This is an interesting point. The very first link in the body
of this page links to a page that lists all the old versions;
<a class="moz-txt-link-freetext" href="http://www.python.org/doc/versions/">http://www.python.org/doc/versions/</a>, where I don't even need to
make up the URL to get old documents. So in addition to the links
in the documentation navigation itself to previous versions,
there's actually a direct link to each old version. Note, I'm not
saying this is a bad thing, but this is a perfect candidate page
in your currently maintained web site (outside of the
documentation itself) where a simple sentence added at the head,
e.g. "Please note that only the latest documentation in the 2.x
and 3.x series is actively maintained". That's one change to one
document. I'd say that's feasible, and expresses the policy
succinctly.</small><br>
<blockquote
cite="mid:CAPdtAj3fG6OwyyS72A5X4Zarz3iU0zfqzto_vL3FzH0TFBBcMg@mail.gmail.com"
type="cite">
<pre wrap="">[snip]
</pre>
<blockquote type="cite">
<pre wrap="">It may be worth providing some more general guidance to users in the
documentation introductory section(s) about the best way to find out which
versions support which language constructs, if old documentation isn't it.
Maybe the "What's new in x?" lists?
</pre>
</blockquote>
<pre wrap="">
that's exactly the entry point you're looking for: just note that not
every change ends up there.
</pre>
</blockquote>
<small>Thanks for these suggestions. The fact that not every change
is not in these documents may limit their utility to answer my
question "which version introduced feature x?". However, I found
references to bytes literals in the "what's new in 2.6", so I'm
comfortable with this advice as an approach to my problem in
general.</small><br>
<blockquote
cite="mid:CAPdtAj3fG6OwyyS72A5X4Zarz3iU0zfqzto_vL3FzH0TFBBcMg@mail.gmail.com"
type="cite">
<pre wrap="">
</pre>
<blockquote type="cite">
<pre wrap="">The links you're using to access teh documentation (I don't know if
only for showing the problem or as a general use) points to a specific
release, that will no longer be updated. So if you want to refer to
the lastest 2.x documentation the correct link is:
<a class="moz-txt-link-freetext" href="http://docs.python.org/">http://docs.python.org/</a>
and for Python 3.x it is:
<a class="moz-txt-link-freetext" href="http://docs.python.org/py3k/">http://docs.python.org/py3k/</a>
The link I used to access 2.6.7 was in the left navigation of the site at
the link <a class="moz-txt-link-freetext" href="http://docs.python.org/">http://docs.python.org/</a> under "Docs for other versions". It's true
</pre>
</blockquote>
<pre wrap="">
exactly, so you didn't use the latest documentation available :) of
course, that's related a version of Python you don't have on your
machine.
</pre>
</blockquote>
<small>OK, but I was trying to answer a question about which
versions would support the b"" literal feature. I knew it wasn't
the latest version. At the time, I didn't know it wasn't correct,
because it wasn't maintained. All that needed to change to fix
this issue was to disclose this, somewhere where I could have seen
it. Even better, provide the advice on the page
<a class="moz-txt-link-freetext" href="http://www.python.org/doc/versions/">http://www.python.org/doc/versions/</a> in addition to my previous
suggestion, viz. "Please note that only the latest documentation
in the 2.x and 3.x series is actively maintained. For information
on support in previous versions, please refer to the "what's new"
documentation". </small><br>
<blockquote
cite="mid:CAPdtAj3fG6OwyyS72A5X4Zarz3iU0zfqzto_vL3FzH0TFBBcMg@mail.gmail.com"
type="cite">
<pre wrap="">
</pre>
<blockquote type="cite">
<pre wrap="">that the URLs accessed for other specific releases before 2.7.2 and 2.6.7
were formed by extrapolation, in order to work out what versions of the
documentation were affected by the perceived issue. That exercise was
ultimately worthless, given the policy as now stated.
Instead, my report should have been against the current, maintained 2.x
documentation, i.e. "Can you please add a reference in this page saying
which version this significant change to string literals was made?". If you
</pre>
</blockquote>
<pre wrap="">
sometimes it is done, for example in case we add new methods there's
often a "Added in: X.Y" tag at the end.
</pre>
</blockquote>
<small>I think this change is worthy, particularly as the old docs
are incorrect. Just my view though.</small><br>
<blockquote
cite="mid:CAPdtAj3fG6OwyyS72A5X4Zarz3iU0zfqzto_vL3FzH0TFBBcMg@mail.gmail.com"
type="cite">
<pre wrap="">
</pre>
<blockquote type="cite">
<pre wrap="">take none the other suggestions on board, which is reasonable given their
scope and impact, can I strongly urge you to at least update the current
versions of the 2.x and 3.x document for lexical analysis to this effect?
</pre>
</blockquote>
<pre wrap="">
It *is* fixed, as you said, in 2.7.1 and 2.7.2 : the latter version is
the current one, so case closed.
</pre>
</blockquote>
<small>That's your prerogative, of course. The correctness of the
current versions was never the problem in relation to this
feature. With respect, I still think there's a good argument for
changes to:<br>
a) Reflect the current policy on documentation maintenance
clearly, on <a class="moz-txt-link-freetext" href="http://www.python.org/doc/versions/">http://www.python.org/doc/versions/</a> at the very least.<br>
b) In the case of the Bytes literal change, to add the "Added in:
x.y" tag you mentioned to the lexical analysis pages for all
currently maintained document versions.<br>
<br>
If you're still not convinced, that's fine; I'll leave it there.<br>
<br>
Regards,<br>
Sam.</small><br>
</body>
</html>