1 .. highlightlang:: rest

     2 

     3 Style Guide

     4 ===========

     5 

     6 The Python documentation should follow the `Apple Publications Style Guide`_

     7 wherever possible. This particular style guide was selected mostly because it

     8 seems reasonable and is easy to get online.

     9 

    10 Topics which are not covered in the Apple's style guide will be discussed in

    11 this document.

    12 

    13 All reST files use an indentation of 3 spaces.  The maximum line length is 80

    14 characters for normal text, but tables, deeply indented code samples and long

    15 links may extend beyond that.

    16 

    17 Make generous use of blank lines where applicable; they help grouping things

    18 together.

    19 

    20 A sentence-ending period may be followed by one or two spaces; while reST

    21 ignores the second space, it is customarily put in by some users, for example

    22 to aid Emacs' auto-fill mode.

    23 

    24 Footnotes are generally discouraged, though they may be used when they are the

    25 best way to present specific information. When a footnote reference is added at

    26 the end of the sentence, it should follow the sentence-ending punctuation. The

    27 reST markup should appear something like this::

    28 

    29     This sentence has a footnote reference. [#]_ This is the next sentence.

    30 

    31 Footnotes should be gathered at the end of a file, or if the file is very long,

    32 at the end of a section. The docutils will automatically create backlinks to

    33 the footnote reference.

    34 

    35 Footnotes may appear in the middle of sentences where appropriate.

    36 

    37 Many special names are used in the Python documentation, including the names of

    38 operating systems, programming languages, standards bodies, and the like. Most

    39 of these entities are not assigned any special markup, but the preferred

    40 spellings are given here to aid authors in maintaining the consistency of

    41 presentation in the Python documentation.

    42 

    43 Other terms and words deserve special mention as well; these conventions should

    44 be used to ensure consistency throughout the documentation:

    45 

    46 CPU

    47     For "central processing unit." Many style guides say this should be spelled

    48     out on the first use (and if you must use it, do so!). For the Python

    49     documentation, this abbreviation should be avoided since there's no

    50     reasonable way to predict which occurrence will be the first seen by the

    51     reader. It is better to use the word "processor" instead.

    52 

    53 POSIX

    54     The name assigned to a particular group of standards. This is always

    55     uppercase.

    56 

    57 Python

    58     The name of our favorite programming language is always capitalized.

    59 

    60 Unicode

    61     The name of a character set and matching encoding. This is always written

    62     capitalized.

    63 

    64 Unix

    65     The name of the operating system developed at AT&T Bell Labs in the early

    66     1970s.

    67 

    68 

    69 .. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2006.pdf

    70