Author ezio.melotti
Recipients amaajemyfren, docs@python, eric.smith, ezio.melotti, gvanrossum
Date 2020-07-28.12:04:30
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1595937871.34.0.962385424752.issue41411@roundup.psfhosted.org>
In-reply-to
Content
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
History
Date User Action Args
2020-07-28 12:04:31ezio.melottisetrecipients: + ezio.melotti, gvanrossum, eric.smith, docs@python, amaajemyfren
2020-07-28 12:04:31ezio.melottisetmessageid: <1595937871.34.0.962385424752.issue41411@roundup.psfhosted.org>
2020-07-28 12:04:31ezio.melottilinkissue41411 messages
2020-07-28 12:04:30ezio.melotticreate