[Python-checkins] r56730 - in doctools/trunk: Doc-26/documenting/rest.rst Doc-26/documenting/style.rst Doc-3k/documenting/rest.rst Doc-3k/documenting/style.rst Doc-3k/library/os.rst Doc-3k/library/tk.rst Doc-3k/library/zipfile.rst
georg.brandl
python-checkins at python.org
Sat Aug 4 09:22:22 CEST 2007
Author: georg.brandl
Date: Sat Aug 4 09:22:22 2007
New Revision: 56730
Modified:
doctools/trunk/Doc-26/documenting/rest.rst
doctools/trunk/Doc-26/documenting/style.rst
doctools/trunk/Doc-3k/documenting/rest.rst
doctools/trunk/Doc-3k/documenting/style.rst
doctools/trunk/Doc-3k/library/os.rst
doctools/trunk/Doc-3k/library/tk.rst
doctools/trunk/Doc-3k/library/zipfile.rst
Log:
Merge 56702-56729 and write a bit on reST source style guide.
Modified: doctools/trunk/Doc-26/documenting/rest.rst
==============================================================================
--- doctools/trunk/Doc-26/documenting/rest.rst (original)
+++ doctools/trunk/Doc-26/documenting/rest.rst Sat Aug 4 09:22:22 2007
@@ -22,8 +22,6 @@
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
-------------
@@ -250,4 +248,4 @@
separated from the surrounding text by non-word characters, you have to use
an escaped space to get around that.
-.. XXX more?
\ No newline at end of file
+.. XXX more?
Modified: doctools/trunk/Doc-26/documenting/style.rst
==============================================================================
--- doctools/trunk/Doc-26/documenting/style.rst (original)
+++ doctools/trunk/Doc-26/documenting/style.rst Sat Aug 4 09:22:22 2007
@@ -7,10 +7,15 @@
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 if necessary.
+this document.
+
+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
@@ -20,8 +25,8 @@
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.
@@ -54,4 +59,8 @@
Unix
The name of the operating system developed at AT&T Bell Labs in the early
- 1970s.
\ No newline at end of file
+ 1970s.
+
+
+.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf
+
Modified: doctools/trunk/Doc-3k/documenting/rest.rst
==============================================================================
--- doctools/trunk/Doc-3k/documenting/rest.rst (original)
+++ doctools/trunk/Doc-3k/documenting/rest.rst Sat Aug 4 09:22:22 2007
@@ -22,8 +22,6 @@
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
-------------
@@ -250,4 +248,4 @@
separated from the surrounding text by non-word characters, you have to use
an escaped space to get around that.
-.. XXX more?
\ No newline at end of file
+.. XXX more?
Modified: doctools/trunk/Doc-3k/documenting/style.rst
==============================================================================
--- doctools/trunk/Doc-3k/documenting/style.rst (original)
+++ doctools/trunk/Doc-3k/documenting/style.rst Sat Aug 4 09:22:22 2007
@@ -7,10 +7,15 @@
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 if necessary.
+this document.
+
+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
@@ -20,8 +25,8 @@
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.
@@ -54,4 +59,8 @@
Unix
The name of the operating system developed at AT&T Bell Labs in the early
- 1970s.
\ No newline at end of file
+ 1970s.
+
+
+.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf
+
Modified: doctools/trunk/Doc-3k/library/os.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/os.rst (original)
+++ doctools/trunk/Doc-3k/library/os.rst Sat Aug 4 09:22:22 2007
@@ -8,7 +8,8 @@
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
@@ -348,7 +349,7 @@
File Object Creation
--------------------
-These functions create new file objects.
+These functions create new file objects. (See also :func:`open`.)
.. function:: fdopen(fd[, mode[, bufsize]])
@@ -775,51 +776,52 @@
following values (as defined in the :mod:`stat` module) or bitwise or-ed
combinations of them:
-* ``S_ISUID``
+* ``stat.S_ISUID``
-* ``S_ISGID``
+* ``stat.S_ISGID``
-* ``S_ENFMT``
+* ``stat.S_ENFMT``
-* ``S_ISVTX``
+* ``stat.S_ISVTX``
-* ``S_IREAD``
+* ``stat.S_IREAD``
-* ``S_IWRITE``
+* ``stat.S_IWRITE``
-* ``S_IEXEC``
+* ``stat.S_IEXEC``
-* ``S_IRWXU``
+* ``stat.S_IRWXU``
-* ``S_IRUSR``
+* ``stat.S_IRUSR``
-* ``S_IWUSR``
+* ``stat.S_IWUSR``
-* ``S_IXUSR``
+* ``stat.S_IXUSR``
-* ``S_IRWXG``
+* ``stat.S_IRWXG``
-* ``S_IRGRP``
+* ``stat.S_IRGRP``
-* ``S_IWGRP``
+* ``stat.S_IWGRP``
-* ``S_IXGRP``
+* ``stat.S_IXGRP``
-* ``S_IRWXO``
+* ``stat.S_IRWXO``
-* ``S_IROTH``
+* ``stat.S_IROTH``
-* ``S_IWOTH``
+* ``stat.S_IWOTH``
-* ``S_IXOTH``
+* ``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)
@@ -884,9 +886,11 @@
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
Modified: doctools/trunk/Doc-3k/library/tk.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/tk.rst (original)
+++ doctools/trunk/Doc-3k/library/tk.rst Sat Aug 4 09:22:22 2007
@@ -21,8 +21,11 @@
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::
Modified: doctools/trunk/Doc-3k/library/zipfile.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/zipfile.rst (original)
+++ doctools/trunk/Doc-3k/library/zipfile.rst Sat Aug 4 09:22:22 2007
@@ -85,7 +85,7 @@
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.
More information about the Python-checkins
mailing list