Anonymous avatar Anonymous committed 15a85c1

Merge 56702-56729 and write a bit on reST source style guide.

Comments (0)

Files changed (7)

Doc-26/documenting/rest.rst

 is significant in reST, so all lines of the same paragraph must be left-aligned
 to the same level of indentation.
 
-The Python docs use an indentation of 3 spaces.
-
 
 Inline markup
 -------------
   separated from the surrounding text by non-word characters, you have to use
   an escaped space to get around that.
 
-.. XXX more?
+.. XXX more?

Doc-26/documenting/style.rst

 wherever possible. This particular style guide was selected mostly because it
 seems reasonable and is easy to get online.
 
-.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf
+Topics which are not covered in the Apple's style guide will be discussed in
+this document.
 
-Topics which are not covered in the Apple's style guide will be discussed in
-this document if necessary.
+All reST files use an indentation of 3 spaces.  The maximum line length is 80
+characters for normal text, but tables, deeply indented code samples and long
+links may extend beyond that.
+
+Make generous use of blank lines where applicable; they help grouping things
+together.
 
 Footnotes are generally discouraged, though they may be used when they are the
 best way to present specific information. When a footnote reference is added at
     This sentence has a footnote reference. [#]_ This is the next sentence.
 
 Footnotes should be gathered at the end of a file, or if the file is very long,
-at the end of a section. The docutils will automatically create backlinks to the
-footnote reference.
+at the end of a section. The docutils will automatically create backlinks to
+the footnote reference.
 
 Footnotes may appear in the middle of sentences where appropriate.
 
 
 Unix
     The name of the operating system developed at AT&T Bell Labs in the early
-    1970s.
+    1970s.
+
+
+.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf
+

Doc-3k/documenting/rest.rst

 is significant in reST, so all lines of the same paragraph must be left-aligned
 to the same level of indentation.
 
-The Python docs use an indentation of 3 spaces.
-
 
 Inline markup
 -------------
   separated from the surrounding text by non-word characters, you have to use
   an escaped space to get around that.
 
-.. XXX more?
+.. XXX more?

Doc-3k/documenting/style.rst

 wherever possible. This particular style guide was selected mostly because it
 seems reasonable and is easy to get online.
 
-.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf
+Topics which are not covered in the Apple's style guide will be discussed in
+this document.
 
-Topics which are not covered in the Apple's style guide will be discussed in
-this document if necessary.
+All reST files use an indentation of 3 spaces.  The maximum line length is 80
+characters for normal text, but tables, deeply indented code samples and long
+links may extend beyond that.
+
+Make generous use of blank lines where applicable; they help grouping things
+together.
 
 Footnotes are generally discouraged, though they may be used when they are the
 best way to present specific information. When a footnote reference is added at
     This sentence has a footnote reference. [#]_ This is the next sentence.
 
 Footnotes should be gathered at the end of a file, or if the file is very long,
-at the end of a section. The docutils will automatically create backlinks to the
-footnote reference.
+at the end of a section. The docutils will automatically create backlinks to
+the footnote reference.
 
 Footnotes may appear in the middle of sentences where appropriate.
 
 
 Unix
     The name of the operating system developed at AT&T Bell Labs in the early
-    1970s.
+    1970s.
+
+
+.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf
+

Doc-3k/library/os.rst

 
 This module provides a more portable way of using operating system dependent
 functionality than importing a operating system dependent built-in module like
-:mod:`posix` or :mod:`nt`.
+:mod:`posix` or :mod:`nt`. (If you just want to read or write a file see
+:func:`open`.)
 
 This module searches for an operating system dependent built-in module like
 :mod:`mac` or :mod:`posix` and exports the same functions and data as found
 File Object Creation
 --------------------
 
-These functions create new file objects.
+These functions create new file objects. (See also :func:`open`.)
 
 
 .. function:: fdopen(fd[, mode[, bufsize]])
    following values (as defined in the :mod:`stat` module) or bitwise or-ed
    combinations of them:
 
-* ``S_ISUID``
-
-* ``S_ISGID``
-
-* ``S_ENFMT``
-
-* ``S_ISVTX``
-
-* ``S_IREAD``
-
-* ``S_IWRITE``
-
-* ``S_IEXEC``
-
-* ``S_IRWXU``
-
-* ``S_IRUSR``
-
-* ``S_IWUSR``
-
-* ``S_IXUSR``
-
-* ``S_IRWXG``
-
-* ``S_IRGRP``
-
-* ``S_IWGRP``
-
-* ``S_IXGRP``
-
-* ``S_IRWXO``
-
-* ``S_IROTH``
-
-* ``S_IWOTH``
-
-* ``S_IXOTH``
+* ``stat.S_ISUID``
+
+* ``stat.S_ISGID``
+
+* ``stat.S_ENFMT``
+
+* ``stat.S_ISVTX``
+
+* ``stat.S_IREAD``
+
+* ``stat.S_IWRITE``
+
+* ``stat.S_IEXEC``
+
+* ``stat.S_IRWXU``
+
+* ``stat.S_IRUSR``
+
+* ``stat.S_IWUSR``
+
+* ``stat.S_IXUSR``
+
+* ``stat.S_IRWXG``
+
+* ``stat.S_IRGRP``
+
+* ``stat.S_IWGRP``
+
+* ``stat.S_IXGRP``
+
+* ``stat.S_IRWXO``
+
+* ``stat.S_IROTH``
+
+* ``stat.S_IWOTH``
+
+* ``stat.S_IXOTH``
 
    Availability: Macintosh, Unix, Windows.
 
    .. note::
 
       Although Windows supports :func:`chmod`, you can only  set the file's read-only
-      flag with it (via the ``S_IWRITE``  and ``S_IREAD`` constants or a corresponding
-      integer value).  All other bits are ignored.
+      flag with it (via the ``stat.S_IWRITE``  and ``stat.S_IREAD``
+      constants or a corresponding integer value).  All other bits are
+      ignored.
 
 
 .. function:: chown(path, uid, gid)
 
    Create a filesystem node (file, device special file or named pipe) named
    *filename*. *mode* specifies both the permissions to use and the type of node to
-   be created, being combined (bitwise OR) with one of S_IFREG, S_IFCHR, S_IFBLK,
-   and S_IFIFO (those constants are available in :mod:`stat`). For S_IFCHR and
-   S_IFBLK, *device* defines the newly created device special file (probably using
+   be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
+   ``stat.S_IFCHR``, ``stat.S_IFBLK``,
+   and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`).
+   For ``stat.S_IFCHR`` and
+   ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
    :func:`os.makedev`), otherwise it is ignored.
 
    .. versionadded:: 2.3

Doc-3k/library/tk.rst

 classes.  In addition, the internal module :mod:`_tkinter` provides a threadsafe
 mechanism which allows Python and Tcl to interact.
 
-Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for
-more information on other GUI toolkits for Python.
+:mod:`Tkinter`'s chief virtues are that it is fast, and that it usually comes
+bundled with Python. Although it has been used to create some very good
+applications, including IDLE, it has weak documentation and an outdated look and
+feel. For more modern, better documented, and much more extensive GUI
+libraries, see the :ref:`other-gui-packages` section.
 
 .. toctree::
    

Doc-3k/library/zipfile.rst

       Documentation on the ZIP file format by Phil Katz, the creator of the format and
       algorithms used.
 
-   `Info-ZIP Home Page <http://www.info-zip.org/pub/infozip/>`_
+   `Info-ZIP Home Page <http://www.info-zip.org/>`_
       Information about the Info-ZIP project's ZIP archive programs and development
       libraries.
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.