[New-bugs-announce] [issue41411] Improve and consolidate f-strings docs

[Ezio Melotti]

New submission from Ezio Melotti <ezio.melotti at gmail.com>:

[Creating a new issue from #41045]

I was just just trying to link to someone the documentation for f-strings, but:
1) Searching "fstring" only returns two results about xdrlib[0];
2) Searching "f-string" returns many unrelated results[1];
3) The first (and closer) result (string -- Common string operations[2]) yields nothing while using ctrl+f with fstring, f-string, f', f";
4) at the top of that page there are two links in a "see also":
  * Text Sequence Type — str[3]: it mentions raw strings at the beginning, but also yields no results for fstring, f-string, f', f";
  * String Methods[4]: that is another section of the previous page (so ctrl+f doesn't find anything), but has a link to "Format String Syntax"[5];
5) The "Format String Syntax" page[5] has another link in the middle of a paragraph that points to "formatted string literals", that eventually brings us to the right page[6];
6) the "right page"[6] has a wall of text with a block of code containing the grammar, luckily followed by a few examples.

I think we should:
1) add index entries for "f-string" and "fstring" in the relevant sections of the docs, so that they appear in the search result;
2) in the Text Sequence Type — str[3] section, have a bullet list for f-strings, raw-strings, and possibly u-strings;
3) possibly use the term "f-string" in addition (or instead) of "formatted string literal", to make the pages more ctrl+f-friendly throughout the docs;
4) possibly have another more newbie-friendly section on f-string (compared to the lexical analysis page) in the tutorial, in the stdtypes page[7] (e.g. before the printf-style String Formatting" section[8]), or in the string page[2] (e.g. after the "Format String Syntax" section[10]);
5) possibly reorganize and consolidate the different sections about strings, string methods, str.format(), the format mini-language, f-strings, raw/unicode-strings, %-style formatting in a single page or two (a page for the docs and one for the grammar), since it seems to me that over the years these sections got a bit scattered around as they were being added.

[0]: https://docs.python.org/3/search.html?q=fstring
[1]: https://docs.python.org/3/search.html?q=f-string
[2]: https://docs.python.org/3/library/string.html
[3]: https://docs.python.org/3/library/stdtypes.html#textseq
[4]: https://docs.python.org/3/library/stdtypes.html#string-methods
[5]: https://docs.python.org/3/library/string.html#formatstrings
[6]: https://docs.python.org/3/reference/lexical_analysis.html#f-strings
[7]: https://docs.python.org/3/library/stdtypes.html
[8]: https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting

----------
assignee: docs at python
components: Documentation
messages: 374398
nosy: docs at python, eric.smith, ezio.melotti
priority: normal
severity: normal
stage: needs patch
status: open
title: Improve and consolidate f-strings docs
type: enhancement
versions: Python 3.10, Python 3.8, Python 3.9

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