classification
Title: "This isn't defined beyond that" phrase is not friendly to non-native English speakers.
Type: Stage:
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7, Python 2.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: akuchling, docs@python, georg.brandl, loewis, naoki, r.david.murray, terry.reedy, tim.peters
Priority: normal Keywords:

Created on 2010-05-11 11:13 by naoki, last changed 2010-10-17 09:23 by georg.brandl. This issue is now closed.

Messages (8)
msg105498 - (view) Author: INADA Naoki (naoki) * Date: 2010-05-11 11:13
http://docs.python.org/library/difflib.html#difflib.SequenceMatcher.quick_ratio
> This isn’t defined beyond that it is an upper bound on ratio(), and is faster to compute.

"beyond" is a bit confusing because it also means "over" and this
sentence refers upper bound.

I think "This isn't defined in detail more than..." is easier.
msg105507 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-05-11 13:05
Unfortunately that wouldn't be correct English, as far as I know.

How about "This isn't defined other than that..."  I think that reads a bit more clearly than "beyond that" even to a native speaker, even though beyond is valid in this context.
msg105584 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2010-05-12 13:13
How about just dropping those words entirely, and writing "Return an approximate upper bound on ratio() very quickly.  This is not as accurate as ratio(), but is faster to compute."  (We'd make similar changes to real_quick_ratio()'s text.)
msg105606 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2010-05-12 20:21
I think it's important to note that this may err towards larger numbers (rather than being merely inaccurate).

I also find this "an upper bound on ratio()" difficult to understand. IIUC, it is the correct value being bounded, not the result of the function under discussion that is bounded (by the correct value).
msg105608 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2010-05-12 20:42
I find this whole discussion to be hilarious ;-)

"Approximate upper bound" is gibberish - "upper bound" is a crisp concept that means what it says.  It's not necessarily true that an upper bound is inaccurate - it may be exactly right.  So "this is not as accurate as ratio()" overstates the case.

"quick_ratio() returns an upper bound on what ratio() returns" is the truth, and can't be improved by adding more words.   Appealing to a "correct" result would also be misleading (what ratio() returns is a more-or-less arbitrary computation whose only claim to "correctness" is that ratio() returns what it's documented to return).

If people find the gloss in the docs confusing, remove the gloss entirely, leaving just the correct:

"Return an upper bound on ratio() relatively quickly."
msg105742 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-05-14 19:10
I agree with Tim. Drop the zero-info glosses. For real_quick_ratio(),
    "Return an upper bound on ratio() even more quickly."
should be sufficient (assuming that it *is* always quicker.

Just curious, The descriptions say ratio() <= quick_ratio() and ratio() <= very_quick_ratio. is it also guaranteed that quick_ratio() <= real_quick_ratio()? Or might one 'luck out' with a better answer from the faster method? (I can imagine either being true.)
msg105743 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2010-05-14 19:17
Terry asks:

> is it also guaranteed that quick_ratio() <= real_quick_ratio()

Nope!  The docs don't say that, so it's not guaranteed.

It's not the _intent_ of the code that it be true, either.  The only point to quick_ratio() and real_quick_ratio() is speed.
msg118918 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-10-17 09:23
Removed gloss in r85610.
History
Date User Action Args
2010-10-17 09:23:14georg.brandlsetstatus: open -> closed

nosy: + georg.brandl
messages: + msg118918

resolution: fixed
2010-05-14 19:17:08tim.peterssetmessages: + msg105743
2010-05-14 19:10:59terry.reedysetnosy: + terry.reedy
messages: + msg105742
2010-05-12 20:42:23tim.peterssetnosy: + tim.peters
messages: + msg105608
2010-05-12 20:21:15loewissetnosy: + loewis
messages: + msg105606
2010-05-12 13:13:44akuchlingsetnosy: + akuchling
messages: + msg105584
2010-05-11 13:05:32r.david.murraysetversions: + Python 3.1, - Python 3.3
2010-05-11 13:05:17r.david.murraysetnosy: + r.david.murray
messages: + msg105507
2010-05-11 11:13:54naokicreate