[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / doc / style-guide.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="doc.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="doc.html" title='Documenting Python' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="latex-primer.html" />
<link rel="prev" href="directories.html" />
<link rel="parent" href="doc.html" />
<link rel="next" href="latex-primer.html" />
<meta name='aesop' content='information' />
<title>3 Style Guide </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="2 Directory Structure"
  href="directories.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="Documenting Python"
  href="doc.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4 LaTeX Primer"
  href="latex-primer.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Documenting Python</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="directories.html">2 Directory Structure</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="doc.html">Documenting Python</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="latex-primer.html">4 LaTeX Primer</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION000400000000000000000"></A><A NAME="style-guide"></A>
<BR>
3 Style Guide 
</H1>

<P>
The Python documentation should follow the <em class="citetitle"><a
 href="http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf"
 title="Apple Publications Style Guide"
 >Apple Publications Style Guide</a></em> wherever possible.  This particular
  style guide was selected mostly because it seems reasonable and is
  easy to get online.

<P>
Topics which are not covered in the Apple's style guide will be
  discussed in this document if necessary.

<P>
Many special names are used in the Python documentation, including
  the names of operating systems, programming languages, standards
  bodies, and the like.  Many of these were assigned <span class="LaTeX">LaTeX</span> macros
  at some point in the distant past, and these macros lived on long
  past their usefulness.  In the current markup, most of these entities
  are not assigned any special markup, but the preferred spellings are
  given here to aid authors in maintaining the consistency of
  presentation in the Python documentation.

<P>
Other terms and words deserve special mention as well; these conventions
  should be used to ensure consistency throughout the documentation:

<P>
<DL>
<DT><STRONG>CPU</STRONG></DT>
<DD>For ``central processing unit.''  Many style guides say this
    should be spelled out on the first use (and if you must use it,
    do so!).  For the Python documentation, this abbreviation should
    be avoided since there's no reasonable way to predict which occurrence
    will be the first seen by the reader.  It is better to use the
    word ``processor'' instead.

<P>
</DD>
<DT><STRONG>POSIX</STRONG></DT>
<DD>The name assigned to a particular group of standards.  This is
        always uppercase.  Use the macro <tt class='macro'>&#92;POSIX</tt> to represent this
        name.

<P>
</DD>
<DT><STRONG>Python</STRONG></DT>
<DD>The name of our favorite programming language is always
        capitalized.

<P>
</DD>
<DT><STRONG>Unicode</STRONG></DT>
<DD>The name of a character set and matching encoding.  This is
        always written capitalized.

<P>
</DD>
<DT><STRONG><span class="Unix">Unix</span></STRONG></DT>
<DD>The name of the operating system developed at AT&amp;T Bell Labs
        in the early 1970s.  Use the macro <tt class='macro'>&#92;UNIX</tt> to use this
        name.
  
</DD>
</DL>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="2 Directory Structure"
  href="directories.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="Documenting Python"
  href="doc.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4 LaTeX Primer"
  href="latex-primer.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Documenting Python</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="directories.html">2 Directory Structure</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="doc.html">Documenting Python</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="latex-primer.html">4 LaTeX Primer</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="doc.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="doc.html" title='Documenting Python' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='last' href='about.html' title='About this document...' />
	10	<link rel='help' href='about.html' title='About this document...' />
	11	<link rel="next" href="latex-primer.html" />
	12	<link rel="prev" href="directories.html" />
	13	<link rel="parent" href="doc.html" />
	14	<link rel="next" href="latex-primer.html" />
	15	<meta name='aesop' content='information' />
	16	<title>3 Style Guide </title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="2 Directory Structure"
	24	href="directories.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="Documenting Python"
	27	href="doc.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="4 LaTeX Primer"
	30	href="latex-primer.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Documenting Python</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><img src='../icons/blank.png'
	37	border='0' height='32' alt='' width='32' /></td>
	38	<td class='online-navigation'><img src='../icons/blank.png'
	39	border='0' height='32' alt='' width='32' /></td>
	40	</tr></table>
	41	<div class='online-navigation'>
	42	<b class="navlabel">Previous:</b>
	43	<a class="sectref" rel="prev" href="directories.html">2 Directory Structure</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="doc.html">Documenting Python</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="latex-primer.html">4 LaTeX Primer</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H1><A NAME="SECTION000400000000000000000"></A><A NAME="style-guide"></A>
	54	<BR>
	55	3 Style Guide
	56	</H1>
	57
	58	<P>
	59	The Python documentation should follow the <em class="citetitle"><a
	60	href="http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf"
	61	title="Apple Publications Style Guide"
	62	>Apple Publications Style Guide</a></em> wherever possible. This particular
	63	style guide was selected mostly because it seems reasonable and is
	64	easy to get online.
65
66	<P>
67	Topics which are not covered in the Apple's style guide will be
68	discussed in this document if necessary.
69
70	<P>
71	Many special names are used in the Python documentation, including
72	the names of operating systems, programming languages, standards
73	bodies, and the like. Many of these were assigned <span class="LaTeX">LaTeX</span> macros
74	at some point in the distant past, and these macros lived on long
75	past their usefulness. In the current markup, most of these entities
76	are not assigned any special markup, but the preferred spellings are
77	given here to aid authors in maintaining the consistency of
78	presentation in the Python documentation.
79
80	<P>
81	Other terms and words deserve special mention as well; these conventions
82	should be used to ensure consistency throughout the documentation:
83
84	<P>
85	<DL>
86	<DT><STRONG>CPU</STRONG></DT>
87	<DD>For ``central processing unit.'' Many style guides say this
88	should be spelled out on the first use (and if you must use it,
89	do so!). For the Python documentation, this abbreviation should
90	be avoided since there's no reasonable way to predict which occurrence
91	will be the first seen by the reader. It is better to use the
92	word ``processor'' instead.
93
94	<P>
95	</DD>
96	<DT><STRONG>POSIX</STRONG></DT>
97	<DD>The name assigned to a particular group of standards. This is
98	always uppercase. Use the macro <tt class='macro'>\POSIX</tt> to represent this
99	name.
100
101	<P>
102	</DD>
103	<DT><STRONG>Python</STRONG></DT>
104	<DD>The name of our favorite programming language is always
105	capitalized.
106
107	<P>
108	</DD>
109	<DT><STRONG>Unicode</STRONG></DT>
110	<DD>The name of a character set and matching encoding. This is
111	always written capitalized.
112
113	<P>
114	</DD>
115	<DT><STRONG><span class="Unix">Unix</span></STRONG></DT>
116	<DD>The name of the operating system developed at AT&T Bell Labs
117	in the early 1970s. Use the macro <tt class='macro'>\UNIX</tt> to use this
118	name.
119
120	</DD>
121	</DL>
122
123	<P>
124
125	<DIV CLASS="navigation">
126	<div class='online-navigation'>
127	<p></p><hr />
128	<table align="center" width="100%" cellpadding="0" cellspacing="2">
129	<tr>
130	<td class='online-navigation'><a rel="prev" title="2 Directory Structure"
131	href="directories.html"><img src='../icons/previous.png'
132	border='0' height='32' alt='Previous Page' width='32' /></A></td>
133	<td class='online-navigation'><a rel="parent" title="Documenting Python"
134	href="doc.html"><img src='../icons/up.png'
135	border='0' height='32' alt='Up One Level' width='32' /></A></td>
136	<td class='online-navigation'><a rel="next" title="4 LaTeX Primer"
137	href="latex-primer.html"><img src='../icons/next.png'
138	border='0' height='32' alt='Next Page' width='32' /></A></td>
139	<td align="center" width="100%">Documenting Python</td>
140	<td class='online-navigation'><a rel="contents" title="Table of Contents"
141	href="contents.html"><img src='../icons/contents.png'
142	border='0' height='32' alt='Contents' width='32' /></A></td>
143	<td class='online-navigation'><img src='../icons/blank.png'
144	border='0' height='32' alt='' width='32' /></td>
145	<td class='online-navigation'><img src='../icons/blank.png'
146	border='0' height='32' alt='' width='32' /></td>
147	</tr></table>
148	<div class='online-navigation'>
149	<b class="navlabel">Previous:</b>
150	<a class="sectref" rel="prev" href="directories.html">2 Directory Structure</A>
151	<b class="navlabel">Up:</b>
152	<a class="sectref" rel="parent" href="doc.html">Documenting Python</A>
153	<b class="navlabel">Next:</b>
154	<a class="sectref" rel="next" href="latex-primer.html">4 LaTeX Primer</A>
155	</div>
156	</div>
157	<hr />
158	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
159	</DIV>
160	<!--End of Navigation Panel-->
161	<ADDRESS>
162	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
163	</ADDRESS>
164	</BODY>
165	</HTML>