rest25/documenting/style.rst => rest262/documenting/style.rst
2
3Style Guide
4===========
5
6The Python documentation should follow the `Apple Publications Style Guide`_
7wherever possible. This particular style guide was selected mostly because it
8seems reasonable and is easy to get online.
9
n10-.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf
n10+Topics which are not covered in the Apple's style guide will be discussed in
11+this document.
11
n12-Topics which are not covered in the Apple's style guide will be discussed in
n13+All reST files use an indentation of 3 spaces.  The maximum line length is 80
13-this document if necessary.
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.
14
15Footnotes are generally discouraged, though they may be used when they are the
16best way to present specific information. When a footnote reference is added at
17the end of the sentence, it should follow the sentence-ending punctuation. The
18reST markup should appear something like this::
19
20    This sentence has a footnote reference. [#]_ This is the next sentence.
21
22Footnotes should be gathered at the end of a file, or if the file is very long,
n23-at the end of a section. The docutils will automatically create backlinks to the
n32+at the end of a section. The docutils will automatically create backlinks to
24-footnote reference.
33+the footnote reference.
25
26Footnotes may appear in the middle of sentences where appropriate.
27
28Many special names are used in the Python documentation, including the names of
29operating systems, programming languages, standards bodies, and the like. Most
30of these entities are not assigned any special markup, but the preferred
31spellings are given here to aid authors in maintaining the consistency of
32presentation in the Python documentation.
50
51Unicode
52    The name of a character set and matching encoding. This is always written
53    capitalized.
54
55Unix
56    The name of the operating system developed at AT&T Bell Labs in the early
57    1970s.
t67+ 
68+ 
69+.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2008.pdf
70+ 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op