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

[Sandro Tosi]

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.

On Thu, Aug 11, 2011 at 04:00, Sam Thompson <python at samthompson.com> wrote:
> 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.

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.

python.org/doc makes quite clear what are the supported doc version,
linking only one for 2.x and 3.x .

> 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?)

or the what's new section of the latest documentation.

> 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?

that's exactly the entry point you're looking for: just note that not
every change ends up there.

> 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

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.

> 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

sometimes it is done, for example in case we add new methods there's
often a "Added in: X.Y" tag at the end.

> 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?

It *is* fixed, as you said, in 2.7.1 and 2.7.2 : the latter version is
the current one, so case closed.

Regards,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi