Potentially confusing formulation in 6.1.4. Template strings

[gerritholl]

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]

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:

[birkenfeld]

+1.

[warsaw]

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().

[zware]

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]

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]

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