[docs] Issue: no reference to bytes alias in documentation for 2.6.x and 2.7 (related to closed issue 1865)

[Sam Thompson]

Sandro,

Thanks for your detailed response. In summary, I appear to have had the 
wrong end of the stick, but I've made some suggestions that may make 
things better for the doc maintainers as well as the users, particularly 
new ones like me. I hope this feedback is helpful. I appreciate the 
efforts that you and the rest of the team make with the documentation; 
please don't infer these comments are made in a critical or cynical spirit.

On 2011/08/11 10:39, Sandro Tosi wrote:
> Hello Sam,
> thanks for your email.
>
> On Wed, Aug 3, 2011 at 11:57, Sam Thompson<python at samthompson.com>  wrote:
>> Hi,
>>
>> I'm new to Python so might have the wrong end of the stick, however I noted
>> that although the py3k porting documentation (e.g. at
>> http://docs.python.org/dev/py3k/howto/pyporting.html) says that both python
>> 2.6 and 2.7 support use of b"xxx" style literals, there's no mention of it
>> in any of the 2.6.x documentation for literals (e.g.
>> http://docs.python.org/release/2.6.7/reference/lexical_analysis.html#id7).
> Currently, 2.6 is in security-fix only, so its documentation cannot be
> change anymore, that's why you don't see it fixed there.
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.
>> I found a closed bug in the issue tracker (http://bugs.python.org/issue1865)
>> which appears to originally have covered this issue but the version was
>> changed to 2.7 before it was resolved (although it's also not fixed in 2.7's
>> version at
>> http://docs.python.org/release/2.7/reference/lexical_analysis.html#id7, but
>> is fixed in 2.7.1 and 2.7.2).
>>
>> It looks like the solution used for 2.7.1+ would be appropriate for the
>> older versions, since there do not appear to be other substantial changes to
>> this part of the documentation between these versions.
> The way we release Python patch-version (x.x.N where only N is
> increased) is meant to replace N-1 and all the previous versions. So
> we don't backport documentation (nor code) fixed to 2.7.0 if the fix
> is in 2.7.1 and so on.
I appreciate this and it certainly explains the policy in relation to 
documentation updates. However, the specific use case I encountered here 
was an attempt to understand which versions of Python 2.x code I wrote 
using this b"" literal construction would be compatible with, since 
versions prior to 2.7.x are still widely deployed.

In hindsight, there may have been another approach (review of issues 
log?) that I could have used to establish the versions that support b"" 
literals. I looked for it in the documentation, noting that there is on 
the page referred to other text that discusses specific version support, 
for example at the top of the page, 3rd paragraph "New in version 2.3: 
An encoding declaration ..." and also the only footnote on this page.

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?

> 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:
>
> http://docs.python.org/
>
> and for Python 3.x it is:
>
> http://docs.python.org/py3k/
>
The link I used to access 2.6.7 was in the left navigation of the site 
at the link http://docs.python.org/ under "Docs for other versions". 
It's true 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 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?

Thanks & regards,
Sam.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20110811/efee5f7b/attachment.html>