Ezio Melotti <ezio.melo...@gmail.com> added the comment:
HOWTOs are generally used to explain how to accomplish a certain task, so I'm
not sure if they are a good fit for this situation.
In the list of proposed solutions in my first message, 1-3 should be quite easy
to implement. This leaves us with 4-5.
To summarize what we already have (let me know if I missed anything):
* string.rst[0] (the string module):
String constants (string constants)
Custom String Formatting (string.Formatter)
Format String Syntax (explains the syntax of {...})
Format Specification Mini-Language
Format examples
Template strings (string.Template)
Helper functions (string.capwords)
* stdtypes.rst[1] (about Python builtin types):
Text Sequence Type — str (short intro about str)
String Methods (all the str.* methods)
printf-style String Formatting (old %-formatting)
* introduction.rst[2] (the string section in the tutorial)
* lexical_analysis.rst[3]
String and Bytes literals
String literal concatenation
Formatted string literals
The lexical analysis is probably fine as is. The introduction in the tutorial
should mention f-strings, include a couple of examples, and link to the
documentation for more. The stdtypes page is already quite long and crowded,
so I'm wary about adding more stuff in there. So, unless we add a separate
page somewhere, the string page seems the best candidate, even if technically
it should be about the string module.
On top of items 1-3 of my previous message, to solve 4-5 I suggest to:
1) move the printf-style formatting section to string.rst;
2) add a section about f-strings under Format String Syntax in string.rst,
focusing on differences and caveats that are unique to f-strings;
3) add some f-string-specific examples after the format examples
4) mention f-string in the string section of the tutorial, and in the text
sequence type section of stdtypes.rst;
The string.rst page could then look something like:
String constants (string constants)
Custom String Formatting (string.Formatter)
Format String Syntax (explains the syntax of {...})
Format Specification Mini-Language
Format examples
f-strings
f-strings examples
printf-style String Formatting (old %-formatting)
Template strings (string.Template)
Helper functions (string.capwords)
This should consolidate all the docs in two places: string.rst and
lexical_analysis.rst (they have a different target, so the separation is ok).
All other places can then refer to this. Once this is done, we can still
decide to move these out of string.rst.
[0]: https://docs.python.org/3/library/string.html
[1]: https://docs.python.org/3/library/stdtypes.html#textseq
[2]: https://docs.python.org/3/tutorial/introduction.html#strings
[3]:
https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals
----------
_______________________________________
Python tracker <rep...@bugs.python.org>
<https://bugs.python.org/issue41411>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
