Redundand information on Doc/reference/lexical_analysis.rst

[gpkc]

BPO	31571
Nosy	@gvanrossum, @mitsuhiko, @serhiy-storchaka, @Mariatta, @gpkc
PRs	bpo-31571: Removing redundant information (Docs) #3691 [3.6] bpo-31571: Remove duplicated info in Lexical Analysis documentation (GH-3691) #3754

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2017-09-25.23:25:56.209>
created_at = <Date 2017-09-24.14:56:17.868>
labels = ['3.7', 'docs']
title = 'Redundand information on Doc/reference/lexical_analysis.rst'
updated_at = <Date 2017-09-25.23:25:56.208>
user = 'https://github.com/gpkc'

bugs.python.org fields:

activity = <Date 2017-09-25.23:25:56.208>
actor = 'Mariatta'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-09-25.23:25:56.209>
closer = 'Mariatta'
components = ['Documentation']
creation = <Date 2017-09-24.14:56:17.868>
creator = 'Guilherme'
dependencies = []
files = []
hgrepos = []
issue_num = 31571
keywords = ['patch']
message_count = 12.0
messages = ['302859', '302860', '302862', '302863', '302864', '302890', '302912', '302971', '302974', '302989', '302990', '302991']
nosy_count = 6.0
nosy_names = ['gvanrossum', 'aronacher', 'docs@python', 'serhiy.storchaka', 'Mariatta', 'Guilherme']
pr_nums = ['3691', '3754']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue31571'
versions = ['Python 3.6', 'Python 3.7']

[gpkc]

The file Doc/reference/lexical_analysis.rst has at least two redundant parts.

The first one is quoted below:
"As of Python 3.3 it is possible again to prefix string literals with a u prefix to simplify maintenance of dual 2.x and 3.x codebases."

This is repeated a couple paragraphs after:
"New in version 3.3: Support for the unicode legacy literal (u'value') was reintroduced to simplify the maintenance of dual Python 2.x and 3.x codebases. See PEP-414 for more information."

Also, this other one:
"Note that numeric literals do not include a sign; a phrase like -1 is actually an expression composed of the unary operator - and the literal 1."

Is literally repeated twice, only that on the first time it has quotes around the - operator:
"Note that numeric literals do not include a sign; a phrase like -1 is actually an expression composed of the unary operator ‘-‘ and the literal 1."

[serhiy-storchaka]

The first pair was added in 50364b4 by Armin Ronacher.

The duplicate of the other phrase was introduced in 60f2f0c.

[Mariatta]

I think we can remove

As of Python 3.3 it is possible again to prefix ..."

and keep the other one where it says:

.. versionadded:: 3.3
   Support for the unicode legacy literal ....

About the sentence about numeric literals that appears twice: it appears on different sections of the language reference documentation. It's very likely for a person to only read one section and not the other. I think it's ok to have them in different places like that.

[gpkc]

I believe that the sentence regarding the - operator also applies to Integer literals and Imaginary literals. But it only appears on the Floating point literals and Numeric literals sections.

[gpkc]

Also, "Numeric literals" is a more general section, so rules that apply for the three types of numeric literals should probably go there to avoid repetition. Maybe the Integer, Floating point and Imaginary literal sections should be one section level deeper, so that they are under the Numeric Literal section.

[gvanrossum]

Is there anything here that requires my attention?

[serhiy-storchaka]

Guido, in 60f2f0c you added the phrase "Note that numeric literals do not include a sign; ..." in the "Numeric literals" section. Did you mean moving it from the "Floating point literals" section or creating a duplicate?

[gvanrossum]

That's *really* old. Please clean up as you see fit!

On Sep 24, 2017 10:33 PM, "Serhiy Storchaka" <report@bugs.python.org> wrote:

Serhiy Storchaka added the comment:

Guido, in 60f2f0c you added the phrase
"Note that numeric literals do not include a sign; ..." in the "Numeric
literals" section. Did you mean moving it from the "Floating point
literals" section or creating a duplicate?

----------

---

Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue31571\>

---

[gpkc]

In that case, I believe the PR I've opened should be fine?

[Mariatta]

New changeset 4a2d00c by Mariatta (Guilherme Caminha) in branch 'master':
bpo-31571: Remove duplicated info in Lexical Analysis documentation (GH-3691)
4a2d00c

[Mariatta]

New changeset 26b940f by Mariatta (Miss Islington (bot)) in branch '3.6':
bpo-31571: Remove duplicated info in Lexical Analysis documentation (GH-3691) (GH-3754)
26b940f

[Mariatta]

The proposed change seems fine. Merged and backported.
Thanks everyone!