[issue41411] Improve and consolidate f-strings docs

[Ama Aje My Fren]

Ama Aje My Fren <amaajemyfren at gmail.com> added the comment:

Hi,

Thanks Ezio for the detailed response.

> 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 the best of my seeing there are only two places in the documentation that have information about f-strings. The tutorial[0] and the reference[1]
I have done PR 21681 that adds index to the tutorial although searching[2][3] does not seem to be better now that the reference has an index.

> The lexical analysis is probably fine as is.
I agree.

> The introduction in the tutorial should mention f-strings ....

This is there[0] but it _IS_ hard to find, when you don't know it is there.
It may not be very "introduction-y", and if you like I can make a go at trying to reword it.

> The stdtypes page is already quite long and crowded ...

True. But is this wrong? In my feeling this is reference documentation. It should be accurate, complete and clear. It may not need to be "textbook-like".

Some thoughts:
- There may be benefit in reorganising stdtypes.rst to improve the flow without changing the actual content. This could mean breaking it up into a number of documents rather than the monolith it is.
- It does feel like printf[4] was plugged in later because str.format()[5] had been explained earlier. (Although I believe printf came before str.format()). A first time reader of the document will find it hard to know the one way that is right when it comes to formatting.
- f-strings should probably also be described here because it _is_ built in, no? It may not be accurate to say it is in /Lib/strings. There is no reference that a developer can just look at to remind/confirm to themselves how to "do it".

> So, unless we add a separate page somewhere

This is why I was thinking of a HOWTO. Going back to your original pain in msg371912, someone wanted the f-string documentation and:
-- It was hard to find. (indexing? better table of contents?)
-- It was not very helpful WHEN it was found. (A second entry with f-strings in Lib that is easier for a dev to use?)

But now (and this is mainly to me) it appears that another problem is a need to consistently, clearly, and in one place describe the various elements/nuances/eccentricities of presenting data in Python: 
  - string
  - string.Formatter,
  - string.Template,
  - str.format()
  - f-string
  - Format Specification Mini-Language
  - maybe even __format__ and conversion?
  - etc

I propose one of the following two:
1) A new section in Library documentation just to handle strings, then systematically removing them elsewhere.(Built-In Functions, Built-In Types, Text Processing Services)
2) We take all that Python history and explain it in a HOWTO, and add a developer friendly reference in the Library for f-string. More like Logging Cookbook rather than Logging Howto.

!) above is similar to what you propose ... but different-ish.

[0] https://docs.python.org/dev/tutorial/inputoutput.html#formatted-string-literals
[1] https://docs.python.org/dev/reference/lexical_analysis.html#f-strings
[2] https://docs.python.org/dev/search.html?q=fstring
[3] https://docs.python.org/dev/search.html?q=f-string
[4] https://docs.python.org/dev/library/stdtypes.html#printf-style-bytes-formatting
[5] https://docs.python.org/dev/library/stdtypes.html#str.format

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue41411>
_______________________________________