classification
Title: Clarify "or-ing together" doctest option flags
Type: Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ekorn, eric.araujo, math_foo, python-dev, r.david.murray, terry.reedy
Priority: normal Keywords: patch

Created on 2011-05-22 10:09 by ekorn, last changed 2014-10-06 14:57 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
issue12148.patch math_foo, 2014-04-16 23:43 rewords "or's together" to use "bitwise-or" instead. review
Messages (8)
msg136509 - (view) Author: (ekorn) Date: 2011-05-22 10:09
Combining multiple option flags to doctest.testmod(optionflags=...) requires the bitwise or operator |, not plain "or". I therefore suggest rewording "or-ing together individual option flags." to "or-ing together individual option flags, using the 'bitwise or' operator |.", perhaps with a link to http://docs.python.org/reference/expressions.html#binary-bitwise-operations.

Example:

"""
Doctest option flags must be or-ed together with '|', not 'or'.

>>> print "A  B  C"
A B...
"""
import doctest

print "Combining option flags using bitwise '|'..."
doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS)
print "Combining option flags using logical 'or'..."
doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE or doctest.ELLIPSIS)
msg136522 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-05-22 12:54
I think adding the word 'bitwise' in front of "or'ed" and linking it to that section would be sufficient.
msg136643 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-23 14:22
As a non-native speaker, I found constructs such as “OR-ed” or “syncing” a bit non-obvious when I started reading docs.  +1 on adding “bitwise”, +1 on changing to “combined with the | operator”.  (Yes, this is an or-ed vote.)
msg137152 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-05-28 20:38
The basic fix is to replace the fake verb 'to or', conjugated not really properly as "or's" or "or'ing", with the real noun 'bitwise-or'.

help(doctest.testmod)
...
    Optional keyword arg "optionflags" or's together module constants,
    and defaults to 0.  This is new in 2.3.  Possible values (see the
    docs for details):

Eliminate 'this is new...' here and above. Suggested replacement:

    Optional keyword arg "optionflags" (default 0) is the bitwise-or
    of the following module constants (see the docs for details):

help(doctest.testfile)
...
    Optional keyword arg "optionflags" or's together module constants,
    and defaults to 0.  Possible values (see the docs for details):

Same replacement (whatever we decide on).

Lib 25.2.4. Basic API
doctest.testfile entry:
...
Optional argument optionflags or’s together option flags. See section Option Flags and Directives.

->
Optional argument optionflags is the bitwise-or of options flags. See section Option Flags and Directives.

doctest.testmode entry refers back to above.

25.2.3.5. Option Flags and Directives

doctest.COMPARISON_FLAGS 
A bitmask or’ing together all the comparison flags above.
doctest.REPORTING_FLAGS 
A bitmask or’ing together all the reporting flags above.

A bitmask that is the bitwise-or of all the comparison flags above.
ditto with 'reporting' instead.

-or-
A bitmask -- the bitwise-or of ...

I think this is all. Searching on "or'" does not work because sphinx nicely replaces "'" with a non-ascii unicode char ;-).
msg137200 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-29 16:46
I found “bitwise OR-ed” in library/fcntl.rst library/functions.rst library/os.rst library/winsound.rst (using grep, not Sphinx :)
msg137215 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-05-29 19:17
I like bitwise-or better than bitwise OR because 'bitwise-or' is a distinct operation from 'or', and making it hyphenated emphasizes that.
msg216625 - (view) Author: Caelyn McAulay (math_foo) Date: 2014-04-16 23:43
I grepped for 's together' and found two instances of "or's together" in the docs which I reworded to use bitwise-or instead, in the attached patch.
msg228702 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-06 14:57
New changeset 1439619daf42 by Georg Brandl in branch '3.4':
Closes #12148: clarify "or's together option flags" in doctest docs.
https://hg.python.org/cpython/rev/1439619daf42
History
Date User Action Args
2014-10-06 14:57:11python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg228702

resolution: fixed
stage: resolved
2014-04-17 00:34:43terry.reedysetversions: + Python 3.4, Python 3.5, - Python 3.1, Python 3.2, Python 3.3
2014-04-16 23:43:35math_foosetfiles: + issue12148.patch

nosy: + math_foo
messages: + msg216625

keywords: + patch
2011-05-29 19:17:38r.david.murraysetmessages: + msg137215
2011-05-29 16:46:17eric.araujosetmessages: + msg137200
2011-05-28 20:38:15terry.reedysetnosy: + terry.reedy
messages: + msg137152
2011-05-23 14:22:33eric.araujosetnosy: + eric.araujo

messages: + msg136643
versions: + Python 3.1
2011-05-22 12:54:52r.david.murraysetnosy: + r.david.murray

messages: + msg136522
versions: + Python 3.2, Python 3.3
2011-05-22 10:09:26ekorncreate