Ezio Melotti <ezio.melotti@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-l... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41411> _______________________________________