gh-107017: Change Chapter Strings to Texts in the Introduction chapter. #107104

TommyUnreal · 2023-07-23T09:28:32Z

While the term "string" is well-known in computer science, it might not resonate with beginners or non-technical individuals. Term Texts emphasize practical application in a similar way to Numbers and Lists chapters. This can make the introduction part less intimidating and more beginner-oriented. On the other hand, people coming from other technologies will not be surprised that text is represented with strings.

Issue: remove the assumptions from The tutorial #107017

📚 Documentation preview 📚: https://cpython-previews--107104.org.readthedocs.build/

While term "string" is well known in computer science, it might not resonate with beginners or non-technical individuals. Term Texts emphasize practical application in similar way to Numbers and Lists chapters. This can make the introduction part less intimidating and more beginner-oriented. On the other hand people comming from other technologies will not be surprised that text is represented with strings.

evildmp · 2023-07-23T09:39:06Z

Doc/tutorial/introduction.rst

@@ -138,13 +138,14 @@ and uses the ``j`` or ``J`` suffix to indicate the imaginary part

 .. _tut-strings:

-Strings
+Texts


I'd actually keep the heading Strings, because that's the correct name.

evildmp · 2023-07-23T09:43:45Z

Doc/tutorial/introduction.rst

-in several ways.  They can be enclosed in single quotes (``'...'``) or
-double quotes (``"..."``) with the same result [#]_.  ``\`` can be used
-to escape quotes::
+Different kinds of text have the type :class:`str`.  This includes


I would suggest:

Python can manipulate text ("strings") as well as numbers. This can include [your list of examples].

Strings are enclosed [...].

evildmp · 2023-07-23T09:51:05Z

Doc/tutorial/introduction.rst

+characters "``!``", words "``rabbit``", names "``Paris``", sentences
+"``Got your back.``", etc. "``Yay! :)``".  They can be enclosed in single
+quotes (``'...'``) or double quotes (``"..."``) with the same result [#]_.
+``\`` can be used to escape quotes::


I think the concept of escaping (and the word) is not familiar to many beginners, so I'd suggest something like:

To quote a quote, we need to "escape" it, by preceding it with \::

evildmp · 2023-07-23T09:53:52Z

Doc/tutorial/introduction.rst

-to escape quotes::
+Different kinds of text have the type :class:`str`.  This includes
+characters "``!``", words "``rabbit``", names "``Paris``", sentences
+"``Got your back.``", etc. "``Yay! :)``".  They can be enclosed in single


Perhaps add:

Even "123" is a string (and not a number - because it's enclosed in quotes.

Changed the description, removed duplicate explanations and reworked examples so they are more consice with its paragraph.

evildmp · 2023-07-23T11:56:01Z

Doc/tutorial/introduction.rst

-strings are equivalent.  The string is enclosed in double quotes if
-the string contains a single quote and no double quotes, otherwise it is
-enclosed in single quotes.  The :func:`print` function produces a more
+In the interactive interpreter, the string definition and output string


"In the Python shell..."

hugovk

Some minor suggestions, thanks for the PR!

Doc/tutorial/introduction.rst

bedevere-bot · 2023-07-23T17:38:11Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

TommyUnreal · 2023-07-23T20:12:27Z

Some minor suggestions, thanks for the PR!

Thank you for the feedback!

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

hugovk

Thank you!

miss-islington · 2023-07-24T05:56:01Z

Thanks @TommyUnreal for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

bedevere-bot · 2023-07-24T05:56:18Z

GH-107167 is a backport of this pull request to the 3.12 branch.

…chapter. (pythonGH-107104) (cherry picked from commit 2cf9902) Co-authored-by: TommyUnreal <45427816+TommyUnreal@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

bedevere-bot · 2023-07-24T05:56:23Z

GH-107168 is a backport of this pull request to the 3.11 branch.

…chapter. (pythonGH-107104) (cherry picked from commit 2cf9902) Co-authored-by: TommyUnreal <45427816+TommyUnreal@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

… chapter. (GH-107104) (#107167) Co-authored-by: TommyUnreal <45427816+TommyUnreal@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

… chapter. (GH-107104) (#107168) Co-authored-by: TommyUnreal <45427816+TommyUnreal@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

* main: (73 commits) Thoroughly refactor the cases generator (python#107151) Docs: Add missing markup to Argument Clinic docs (python#106876) pythongh-107162: Document errcode.h usage in its comment (python#107177) pythongh-106320: Remove private _PyDict C API (python#107145) Fix PyVectorcall_Function doc versionadded (python#107140) Docs: Remove duplicate word in Argument Clinic howto heading (python#107169) pythongh-107017: Change Chapter Strings to Texts in the Introduction chapter. (python#107104) pythongh-106320: Remove private _PyObject C API (python#107159) Docs: fix typo in os.pwrite docstring (python#107087) pythongh-105291: Add link to migration guide for distutils (python#107130) pythongh-106948: Docs: Disable links for C standard library functions, OS utility functions and system calls (python#107062) pythongh-106320: Remove _PyBytes_Join() C API (python#107144) pythongh-106320: Remove private _PyObject C API (python#107147) pythongh-106320: Remove _PyTuple_MaybeUntrack() C API (python#107143) pythongh-106320: Remove _PyIsSelectable_fd() C API (python#107142) Remove superflous whitespaces in `layout.html`. (pythonGH-107067) pythongh-107122: Update what's news for dbm.*dbm.clear() method (pythongh-107135) pythongh-107122: Add clear method to dbm.ndbm module (pythongh-107126) pythongh-62519: Make pgettext search plurals when translation is not found (python#107118) pythongh-107122: Add clear method to dbm.gdbm.module (pythongh-107127) ...

bedevere-bot mentioned this pull request Jul 23, 2023

remove the assumptions from The tutorial #107017

Open

bedevere-bot added awaiting review docs Documentation in the Doc dir skip news labels Jul 23, 2023

evildmp suggested changes Jul 23, 2023

View reviewed changes

bedevere-bot added awaiting core review and removed awaiting review labels Jul 23, 2023

New structure of first paragraph in Text chapter.

3edff8b

evildmp approved these changes Jul 23, 2023

View reviewed changes

Refactor string quotes handling and examples.

de2e3c5

Changed the description, removed duplicate explanations and reworked examples so they are more consice with its paragraph.

TommyUnreal requested a review from evildmp July 23, 2023 11:54

evildmp suggested changes Jul 23, 2023

View reviewed changes

Replaced interactive interpreter with Python shell

0306f45

evildmp approved these changes Jul 23, 2023

View reviewed changes

hugovk requested changes Jul 23, 2023

View reviewed changes

Doc/tutorial/introduction.rst Outdated Show resolved Hide resolved

Doc/tutorial/introduction.rst Outdated Show resolved Hide resolved

Doc/tutorial/introduction.rst Outdated Show resolved Hide resolved

Doc/tutorial/introduction.rst Outdated Show resolved Hide resolved

bedevere-bot added awaiting changes and removed awaiting core review labels Jul 23, 2023

hugovk added needs backport to 3.11 only security fixes needs backport to 3.12 bug and security fixes labels Jul 23, 2023

TommyUnreal and others added 3 commits July 23, 2023 22:10

Adjust length to match header

7bd1f2a

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

Fix grammar.

bd02929

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

Add a space before the hash to follow PEP 8

ef4f321

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

Add a space before the hash to follow PEP 8

b737cac

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

hugovk approved these changes Jul 24, 2023

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting changes labels Jul 24, 2023

hugovk enabled auto-merge (squash) July 24, 2023 05:55

hugovk merged commit 2cf9902 into python:main Jul 24, 2023

bedevere-bot removed the awaiting merge label Jul 24, 2023

bedevere-bot removed the needs backport to 3.12 bug and security fixes label Jul 24, 2023

bedevere-bot removed the needs backport to 3.11 only security fixes label Jul 24, 2023

zware mentioned this pull request Jun 3, 2024

Tutorial - Broken Sentence #119995

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-107017: Change Chapter Strings to Texts in the Introduction chapter. #107104

gh-107017: Change Chapter Strings to Texts in the Introduction chapter. #107104

TommyUnreal commented Jul 23, 2023 •

edited by github-actions bot

Loading

evildmp Jul 23, 2023

evildmp Jul 23, 2023

evildmp Jul 23, 2023

evildmp Jul 23, 2023

evildmp Jul 23, 2023

hugovk left a comment

bedevere-bot commented Jul 23, 2023

TommyUnreal commented Jul 23, 2023

hugovk left a comment

miss-islington commented Jul 24, 2023

bedevere-bot commented Jul 24, 2023

bedevere-bot commented Jul 24, 2023

gh-107017: Change Chapter Strings to Texts in the Introduction chapter. #107104

gh-107017: Change Chapter Strings to Texts in the Introduction chapter. #107104

Conversation

TommyUnreal commented Jul 23, 2023 • edited by github-actions bot Loading

evildmp Jul 23, 2023

Choose a reason for hiding this comment

evildmp Jul 23, 2023

Choose a reason for hiding this comment

evildmp Jul 23, 2023

Choose a reason for hiding this comment

evildmp Jul 23, 2023

Choose a reason for hiding this comment

evildmp Jul 23, 2023

Choose a reason for hiding this comment

hugovk left a comment

Choose a reason for hiding this comment

bedevere-bot commented Jul 23, 2023

TommyUnreal commented Jul 23, 2023

hugovk left a comment

Choose a reason for hiding this comment

miss-islington commented Jul 24, 2023

bedevere-bot commented Jul 24, 2023

bedevere-bot commented Jul 24, 2023

TommyUnreal commented Jul 23, 2023 •

edited by github-actions bot

Loading