Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[doc] Range tutorial shorthand could be made clearer #84800

Closed
ChasBelov mannequin opened this issue May 14, 2020 · 7 comments
Closed

[doc] Range tutorial shorthand could be made clearer #84800

ChasBelov mannequin opened this issue May 14, 2020 · 7 comments
Labels
3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir easy type-bug An unexpected behavior, bug, or error

Comments

@ChasBelov
Copy link
Mannequin

ChasBelov mannequin commented May 14, 2020

BPO 40620
Nosy @terryjreedy, @csabella, @miss-islington, @rahul-kumi, @iritkatriel, @ChasBelov, @jdevries3133
PRs
  • bpo-40620: Clarify tutorial controlflow.rst range examples #26919
  • [3.10] bpo-40620: Clarify tutorial controlflow.rst range examples (GH-26919) #26927
  • [3.9] bpo-40620: Clarify tutorial controlflow.rst range examples (GH-26919) #26928
  • 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 2021-06-27.19:53:33.289>
    created_at = <Date 2020-05-14.06:12:52.400>
    labels = ['easy', 'type-bug', '3.9', '3.10', '3.11', 'docs']
    title = '[doc] Range tutorial shorthand could be made clearer'
    updated_at = <Date 2021-06-27.19:53:33.289>
    user = 'https://github.com/ChasBelov'

    bugs.python.org fields:

    activity = <Date 2021-06-27.19:53:33.289>
    actor = 'iritkatriel'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2021-06-27.19:53:33.289>
    closer = 'iritkatriel'
    components = ['Documentation']
    creation = <Date 2020-05-14.06:12:52.400>
    creator = 'Chas Belov'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 40620
    keywords = ['patch', 'easy']
    message_count = 7.0
    messages = ['368817', '368998', '396557', '396596', '396597', '396598', '396599']
    nosy_count = 8.0
    nosy_names = ['terry.reedy', 'docs@python', 'cheryl.sabella', 'miss-islington', 'rahul-kumi', 'iritkatriel', 'Chas Belov', 'jack__d']
    pr_nums = ['26919', '26927', '26928']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'behavior'
    url = 'https://bugs.python.org/issue40620'
    versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

    @ChasBelov
    Copy link
    Mannequin Author

    ChasBelov mannequin commented May 14, 2020

    I found https://docs.python.org/3.7/tutorial/controlflow.html#the-range-function section 4.3 confusing. The range() Function shows the following example:

    >>> for i in range(5):
    ...     print(i)
    ...
    0
    1
    2
    3
    4

    [some instructional text]

    range(5, 10)
       5, 6, 7, 8, 9
    
    range(0, 10, 3)
       0, 3, 6, 9
    
    range(-10, -100, -30)
      -10, -40, -70

    This appears to be an instruction to type, for example:
    range(5, 10)
    at the prompt, and that the response will be:
    5, 6, 7, 8, 9

    leading to a perceived bug when I type at the prompt:
    >>> range(5, 10)
    and receive the response
    range(5, 10)

    I ultimately figured out that the example is a shorthand to substitute
    range(5, 10)
    for the original
    range(5)

    >>> for i in range(5, 10):
    ...     print(i)
    ...
    5
    6
    7
    8
    9

    It would be less confusing if the example instead read:

    ----------------------------

    Substituting "range(5, 10)" for "range(5)" results in (one number per line)
    5, 6, 7, 8, 9

    Substituting "range(0, 10, 3)" results in
    0, 3, 6, 9

    and substituting "range(-10, -100, -30)" results in
    -10, -40, -70

    ---------------------------

    such that it is clear that the statements are not meant to be taken as literal stand-alone entries to be typed at the prompt but are instead substitutions.

    @ChasBelov ChasBelov mannequin added 3.7 (EOL) end of life labels May 14, 2020
    @terryjreedy
    Copy link
    Member

    This block is the same in 3.9 and 3.8.

    My first though is this block is a holdover from 2.7, where range returned list. But looking at what is written previously, I think your interpretation is correct -- and agree that something other that code and corresponding output in a code block is confusing. So this might better be a list than a code block. Cheryl, do you have an idea of what might be better?

    @terryjreedy terryjreedy added docs Documentation in the Doc dir 3.8 only security fixes 3.9 only security fixes labels May 16, 2020
    @terryjreedy terryjreedy added type-bug An unexpected behavior, bug, or error docs Documentation in the Doc dir labels May 16, 2020
    @iritkatriel iritkatriel added easy 3.10 only security fixes 3.11 only security fixes and removed 3.7 (EOL) end of life 3.8 only security fixes labels Jun 23, 2021
    @iritkatriel iritkatriel changed the title Range tutorial shorthand could be made clearer [doc] Range tutorial shorthand could be made clearer Jun 23, 2021
    @terryjreedy
    Copy link
    Member

    Another alternative is to make the example *be* interactive.
    This would also teach the easy, standard, and often better way to see the output of an iterable.

    >>> list(range(5, 10))
    [5, 6, 7, 8, 9]
    >>> list(range(0, 10, 3))
    [0, 3, 6, 9]
    >>> list(range(-10, -100, -30))
    [-10, -40, -70]

    @iritkatriel
    Copy link
    Member

    New changeset 2f49c9d by jdevries3133 in branch 'main':
    bpo-40620: Clarify tutorial controlflow.rst range examples (GH-26919)
    2f49c9d

    @iritkatriel
    Copy link
    Member

    New changeset aeb6339 by Miss Islington (bot) in branch '3.10':
    bpo-40620: Clarify tutorial controlflow.rst range examples (GH-26919) (GH-26927)
    aeb6339

    @iritkatriel
    Copy link
    Member

    New changeset 1acd1e6 by Miss Islington (bot) in branch '3.9':
    bpo-40620: Clarify tutorial controlflow.rst range examples (GH-26919) (GH-26928)
    1acd1e6

    @iritkatriel
    Copy link
    Member

    Thank you Jack!

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir easy type-bug An unexpected behavior, bug, or error
    Projects
    None yet
    Development

    No branches or pull requests

    2 participants