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

Jump to bottom

Potentially confusing formulation in 6.1.4. Template strings #64513

Closed
gerritholl mannequin opened this issue Jan 20, 2014 · 6 comments
Closed

Potentially confusing formulation in 6.1.4. Template strings #64513

gerritholl mannequin opened this issue Jan 20, 2014 · 6 comments
Assignees
@warsaw
Labels
3.7 (EOL) end of life docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@gerritholl
Copy link
Mannequin

gerritholl mannequin commented Jan 20, 2014

BPO 20314
Nosy @warsaw, @birkenfeld, @gerritholl, @zware
PRs
  • Improve the documentation for template strings #856
    		•

    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 = 'https://github.com/warsaw'
closed_at = <Date 2017-03-28.14:04:34.013>
created_at = <Date 2014-01-20.17:10:53.946>
labels = ['type-feature', '3.7', 'docs']
title = 'Potentially confusing formulation in 6.1.4. Template\tstrings'
updated_at = <Date 2017-03-28.14:04:40.775>
user = 'https://github.com/gerritholl'

    bugs.python.org fields:

    activity = <Date 2017-03-28.14:04:40.775>
actor = 'barry'
assignee = 'barry'
closed = True
closed_date = <Date 2017-03-28.14:04:34.013>
closer = 'barry'
components = ['Documentation']
creation = <Date 2014-01-20.17:10:53.946>
creator = 'Gerrit.Holl'
dependencies = []
files = []
hgrepos = []
issue_num = 20314
keywords = []
message_count = 6.0
messages = ['208553', '208554', '208556', '208557', '208558', '290719']
nosy_count = 5.0
nosy_names = ['barry', 'georg.brandl', 'docs@python', 'Gerrit.Holl', 'zach.ware']
pr_nums = ['856']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue20314'
versions = ['Python 3.7']
    @gerritholl
    Copy link
    Mannequin Author

    gerritholl mannequin commented Jan 20, 2014

    The standard library documentation “6.1. string — Common string operations” describes string formatting through the .format method and the corresponding mini-language, and the Template class. In the part describing the Template class (6.1.4) is the text:

    Instead of the normal %-based substitutions, Templates support $-based substitutions, using the following rules:

    This is potentially confusing. The documentation in this section has not made any mention of %-based substitutions. Rather, a novel reader may, at this point, think that {}-based substitution is normal. I would suggest to resolve this issue by simply not mentioning %-based substitutions, replacing the sentence above by:

    Templates support $-based substitutions, using the following rules:

    @gerritholl gerritholl mannequin assigned docspython Jan 20, 2014
    @gerritholl gerritholl mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Jan 20, 2014
    @birkenfeld
    Copy link
    Member

    +1.

    @warsaw
    Copy link
    Member

    warsaw commented Jan 20, 2014

    On Jan 20, 2014, at 05:10 PM, Gerrit Holl wrote:

    This is potentially confusing. The documentation in this section has not
    made any mention of %-based substitutions. Rather, a novel reader may, at
    this point, think that {}-based substitution is normal. I would suggest to
    resolve this issue by simply not mentioning %-based substitutions, replacing
    the sentence above by:

    > Templates support $-based substitutions, using the following rules:

    +1

    PEP-292 templates predate .format().

    @warsaw warsaw changed the title Potentially confusing formulation in 6.1.4. Template strings Potentially confusing formulation in 6.1.4. Template strings Jan 20, 2014
    @zware
    Copy link
    Member

    zware commented Jan 20, 2014

    I would suggest moving the section "4.7.2. printf-style String Formatting" from stdtypes to string, alongside the other two formatting specifications, or otherwise moving %-formatting and {}-formatting into the same page that is not stdtypes. 4.7.2 is a pretty long section, and it seems odd to me that it is still in that page instead of with the other string formatting specs, though it is the only place that would have made sense in a pre-{}-and-$-formatting world.

    On the other hand, Gerrit's proposed solution is a *lot* simpler :)

    @birkenfeld
    Copy link
    Member

    I would suggest moving the section "4.7.2. printf-style String
    Formatting" from stdtypes to string

    That's something I wanted to do for a long time. Problem is that non-Intersphinx external links will break (and I guess quite a few people have a bookmark on that section)... so it might be good to keep 4.7.2 with a pointer.

    @warsaw warsaw assigned warsaw and unassigned docspython Mar 27, 2017
    @warsaw
    Copy link
    Member

    warsaw commented Mar 28, 2017

    New changeset 9f74deb by Barry Warsaw in branch 'master':
    Improve the documentation for template strings (#856)
    9f74deb

    @warsaw warsaw closed this as completed Mar 28, 2017
    @warsaw warsaw added the 3.7 (EOL) end of life label Mar 28, 2017
    @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
    Assignees

    @warsaw warsaw

    Labels
    3.7 (EOL) end of life docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    3 participants
    @birkenfeld @warsaw @zware