Author ezio.melotti
Recipients docs@python, eric.smith, ezio.melotti
Date 2020-07-27.16:31:32
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1595867493.01.0.94068638385.issue41411@roundup.psfhosted.org>
In-reply-to
Content
[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
History
Date User Action Args
2020-07-27 16:31:33ezio.melottisetrecipients: + ezio.melotti, eric.smith, docs@python
2020-07-27 16:31:33ezio.melottisetmessageid: <1595867493.01.0.94068638385.issue41411@roundup.psfhosted.org>
2020-07-27 16:31:32ezio.melottilinkissue41411 messages
2020-07-27 16:31:32ezio.melotticreate