classification
Title: Potentially confusing formulation in 6.1.4. Template strings
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: barry Nosy List: Gerrit.Holl, barry, docs@python, georg.brandl, zach.ware
Priority: normal Keywords:

Created on 2014-01-20 17:10 by Gerrit.Holl, last changed 2017-03-28 14:04 by barry. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 856 merged barry, 2017-03-27 22:36
Messages (6)
msg208553 - (view) Author: Gerrit Holl (Gerrit.Holl) * Date: 2014-01-20 17:10
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:
msg208554 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-01-20 17:18
+1.
msg208556 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2014-01-20 17:22
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().
msg208557 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-01-20 17:34
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 :)
msg208558 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-01-20 17:43
> 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.
msg290719 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2017-03-28 14:02
New changeset 9f74deba784fc8781d13ed564f69c02ed7c331bb by Barry Warsaw in branch 'master':
Improve the documentation for template strings (#856)
https://github.com/python/cpython/commit/9f74deba784fc8781d13ed564f69c02ed7c331bb
History
Date User Action Args
2017-03-28 14:04:40barrysetversions: + Python 3.7, - Python 2.7, Python 3.3, Python 3.4
2017-03-28 14:04:34barrysetstatus: open -> closed
resolution: fixed
stage: resolved
2017-03-28 14:02:09barrysetmessages: + msg290719
2017-03-27 22:36:40barrysetpull_requests: + pull_request759
2017-03-27 22:22:16barrysetassignee: docs@python -> barry
2014-01-20 17:43:54georg.brandlsetmessages: + msg208558
2014-01-20 17:35:57zach.waresetversions: + Python 2.7, Python 3.4
2014-01-20 17:34:44zach.waresetnosy: + zach.ware
messages: + msg208557
2014-01-20 17:22:35barrysetnosy: + barry

messages: + msg208556
title: Potentially confusing formulation in 6.1.4. Template strings -> Potentially confusing formulation in 6.1.4. Template strings
2014-01-20 17:18:18georg.brandlsetnosy: + georg.brandl
messages: + msg208554
2014-01-20 17:10:53Gerrit.Hollcreate