Skip to content

Conversation

@galenseilis
Copy link

@galenseilis galenseilis commented Oct 17, 2024

Fix unclear phrasing in exception traceback documentation for PDB.

Description:

Revised the sentence from:

"If no traceback is given, it uses the one of the exception that is currently being handled."

to:

"If no traceback is given, it uses one of the exceptions that is currently being handled."

The original phrasing was grammatically awkward and unclear due to the use of "the one of the exception", which incorrectly implied a specific, pre-identified exception. The revision eliminates this ambiguity by changing it to "one of the exceptions", which makes it clear that the traceback is selected from multiple possible exceptions being handled.

This improves readability and accuracy, ensuring the documentation is easier to understand.


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

x unclear phrasing in exception traceback documentation

Description:

Revised the sentence from:

    "If no traceback is given, it uses the one of the exception that is currently being handled."

to:

    "If no traceback is given, it uses one of the exceptions that is currently being handled."

The original phrasing was grammatically awkward and unclear due to the use of "the one of the exception", which incorrectly implied a specific, pre-identified exception. The revision eliminates this ambiguity by changing it to "one of the exceptions", which makes it clear that the traceback is selected from multiple possible exceptions being handled.

This improves readability and accuracy, ensuring the documentation is easier to understand.
@ghost
Copy link

ghost commented Oct 17, 2024

All commit authors signed the Contributor License Agreement.
CLA signed

@bedevere-app bedevere-app bot added docs Documentation in the Doc dir skip news awaiting review labels Oct 17, 2024
@gaogaotiantian
Copy link
Member

Sorry but your understanding of the sentence is incorrect. The sentence means "it uses the one (traceback) of the 'exception that is currently being handled'". the one means the traceback, which was used earlier, not the exception. After your change the meaning would be wrong.

I agree that it's not the clearest sentence in the world, but it has been there for 17 years :) Unless it's wrong, we usually do not accept polishing PRs because people have different opinions about what's the best way to explain something and it could be an endless discussion, which would take too much time for core devs to review.

I'll close the PR for now, but thank you for your willingness to make Python better.

@galenseilis
Copy link
Author

galenseilis commented Oct 17, 2024

@gaogaotiantian

Thank you for catching my error. I can understand from your clarification how I misunderstood it.

That hesitancy to open up an opinion-based discussion which could go on indefinitely makes sense.

I'm somewhat convinced that the phrase is not merely ambiguous, although we agree it is ambiguous, but it is also not a valid (English) sentence. I've checked against multiple grammar checkers (CA, USA, UK) and they all agree that "If no traceback is given, it uses the one of the exception that is currently being handled." is not valid.

I'm not particularly knowledgeable about grammar, nor do I usually care about grammar when the meaning is clear. There are topics of grammar that are opinion-based, or dialectical, but there are also aspects of grammar that are almost universally accepted. Part of the reason I misunderstood the sentence in the first place may be related to the phrase not being a valid sentence while at the same time being misleading. One of the grammar checkers suggested a correction, and oddly enough came to the same (incorrect) suggestion that I gave.

My suggestion is to evaluate whether the grammatical issue is opinion-based. If it is, then leave it alone. If it is not opinion-based, then pick a valid correction and leave it alone after that.

Thank you for reviewing my PR.

@galenseilis galenseilis deleted the patch-1 branch October 17, 2024 04:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants