[issue4441] Improve os open flag options doc

[Terry J. Reedy]

New submission from Terry J. Reedy <tjreedy at udel.edu>:

os module doc, File Descriptor Operations, at end.

Suggestions:

1. Replace
"The following data items are available for use in constructing the
flags parameter to the open() function."
with
"The following data items are options for the flag argument to the
open() function. These can be combined using the bitwise OR operator |."
(and remove the redundant text from the block headings -- see below).

2. In the next sentence, replace 'will not be' with 'are not'.

3. The next sentence ends with 'consult open(2).' I presume this refers
to unix manual section on the open system call.  This is cryptic and
useless to many Windows users.  Where are descriptions for flags valid
on Windows?

4. Block captions: remove repeated text and move availability note above
rather than below the block. 'Available on Unix and Windows', 'Available
on Unix only', 'Available on Windows only', 'Gnu extensions....'.

5. The items in the fifth block are *not* open() options.  The caption
should instead be an un-indented introductory sentence before the block.
"The following data items are parameters to the lseek() function. ..."

----------
assignee: georg.brandl
components: Documentation
messages: 76471
nosy: georg.brandl, tjreedy
severity: normal
status: open
title: Improve os open flag options doc
versions: Python 2.7, Python 3.0

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue4441>
_______________________________________