Index: /documentation/coding_standards/Style Guide for Python Code, GA version.htm
===================================================================
--- /documentation/coding_standards/Style Guide for Python Code, GA version.htm	(revision 3448)
+++ /documentation/coding_standards/Style Guide for Python Code, GA version.htm	(revision 3449)
@@ -34,16 +34,16 @@
  <o:DocumentProperties>
   <o:Author>nielsen ole</o:Author>
-  <o:LastAuthor>sexton jane</o:LastAuthor>
-  <o:Revision>3</o:Revision>
-  <o:TotalTime>45</o:TotalTime>
+  <o:LastAuthor>gray duncan</o:LastAuthor>
+  <o:Revision>6</o:Revision>
+  <o:TotalTime>51</o:TotalTime>
   <o:Created>2006-02-16T06:00:00Z</o:Created>
-  <o:LastSaved>2006-02-16T06:02:00Z</o:LastSaved>
-  <o:Pages>1</o:Pages>
-  <o:Words>4006</o:Words>
-  <o:Characters>22839</o:Characters>
+  <o:LastSaved>2006-08-04T01:38:00Z</o:LastSaved>
+  <o:Pages>2</o:Pages>
+  <o:Words>4017</o:Words>
+  <o:Characters>22898</o:Characters>
   <o:Company>Geoscience Australia</o:Company>
   <o:Lines>190</o:Lines>
   <o:Paragraphs>53</o:Paragraphs>
-  <o:CharactersWithSpaces>26792</o:CharactersWithSpaces>
+  <o:CharactersWithSpaces>26862</o:CharactersWithSpaces>
   <o:Version>10.6626</o:Version>
  </o:DocumentProperties>
@@ -52,4 +52,7 @@
   <w:SpellingState>Clean</w:SpellingState>
   <w:GrammarState>Clean</w:GrammarState>
+  <w:Compatibility>
+   <w:UseFELayout/>
+  </w:Compatibility>
   <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel>
  </w:WordDocument>
@@ -64,4 +67,20 @@
 <style>
 <!--
+ /* Font Definitions */
+ @font-face
+	{font-family:"MS Mincho";
+	panose-1:2 2 6 9 4 2 5 8 3 4;
+	mso-font-alt:"\FF2D\FF33 \660E\671D";
+	mso-font-charset:128;
+	mso-generic-font-family:modern;
+	mso-font-pitch:fixed;
+	mso-font-signature:-1610612033 1757936891 16 0 131231 0;}
+@font-face
+	{font-family:"\@MS Mincho";
+	panose-1:2 2 6 9 4 2 5 8 3 4;
+	mso-font-charset:128;
+	mso-generic-font-family:modern;
+	mso-font-pitch:fixed;
+	mso-font-signature:-1610612033 1757936891 16 0 131231 0;}
  /* Style Definitions */
  p.MsoNormal, li.MsoNormal, div.MsoNormal
@@ -72,5 +91,6 @@
 	font-size:12.0pt;
 	font-family:"Times New Roman";
-	mso-fareast-font-family:"Times New Roman";}
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
 h3
 	{mso-margin-top-alt:auto;
@@ -95,5 +115,6 @@
 	font-size:10.0pt;
 	font-family:"Courier New";
-	mso-fareast-font-family:"Times New Roman";}
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Courier New";}
 p.navigation, li.navigation, div.navigation
 	{mso-style-name:navigation;
@@ -105,5 +126,6 @@
 	font-size:12.0pt;
 	font-family:"Times New Roman";
-	mso-fareast-font-family:"Times New Roman";}
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
 p.header, li.header, div.header
 	{mso-style-name:header;
@@ -112,5 +134,6 @@
 	font-size:12.0pt;
 	font-family:"Times New Roman";
-	mso-fareast-font-family:"Times New Roman";}
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
 p.content, li.content, div.content
 	{mso-style-name:content;
@@ -120,5 +143,6 @@
 	font-size:12.0pt;
 	font-family:"Times New Roman";
-	mso-fareast-font-family:"Times New Roman";}
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
 p.navicon, li.navicon, div.navicon
 	{mso-style-name:navicon;
@@ -131,5 +155,6 @@
 	font-size:12.0pt;
 	font-family:"Times New Roman";
-	mso-fareast-font-family:"Times New Roman";}
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
 p.textlinks, li.textlinks, div.textlinks
 	{mso-style-name:textlinks;
@@ -142,5 +167,6 @@
 	font-size:12.0pt;
 	font-family:"Times New Roman";
-	mso-fareast-font-family:"Times New Roman";}
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
 p.navicon1, li.navicon1, div.navicon1
 	{mso-style-name:navicon1;
@@ -153,5 +179,6 @@
 	font-size:12.0pt;
 	font-family:"Times New Roman";
-	mso-fareast-font-family:"Times New Roman";}
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
 p.textlinks1, li.textlinks1, div.textlinks1
 	{mso-style-name:textlinks1;
@@ -164,5 +191,6 @@
 	font-size:12.0pt;
 	font-family:"Times New Roman";
-	mso-fareast-font-family:"Times New Roman";}
+	mso-fareast-font-family:"Times New Roman";
+	mso-bidi-font-family:"Times New Roman";}
 span.SpellE
 	{mso-style-name:"";
@@ -255,5 +283,5 @@
 to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
 --><!--[if gte mso 9]><xml>
- <o:shapedefaults v:ext="edit" spidmax="8194"/>
+ <o:shapedefaults v:ext="edit" spidmax="9218"/>
 </xml><![endif]--><!--[if gte mso 9]><xml>
  <o:shapelayout v:ext="edit">
@@ -353,5 +381,5 @@
   </td>
   <td style='padding:.75pt .75pt .75pt .75pt'>
-  <p class=MsoNormal><st1:date Year="2001" Day="5" Month="7">05-Jul-2001</st1:date></p>
+  <p class=MsoNormal><st1:date Month="7" Day="5" Year="2001">05-Jul-2001</st1:date></p>
   </td>
  </tr>
@@ -363,6 +391,6 @@
   <td style='padding:.75pt .75pt .75pt .75pt'>
   <p class=MsoNormal>Modified slightly by Ole Nielsen &lt;<span class=SpellE>Ole.Nielsen</span>
-  at <span class=SpellE>ga.gov.au</span>&gt; and Duncan Gray &lt;<span
-  class=SpellE>Duncan.gray</span> at <span class=SpellE>ga.gov.au</span>&gt;</p>
+  at ga.gov.au&gt; and Duncan Gray &lt;<span class=SpellE>Duncan.gray</span> at
+  ga.gov.au&gt;</p>
   <p class=MsoNormal>Geoscience Australia 2005. </p>
   <p class=MsoNormal>The GA modifications are clearly flagged using blue
@@ -386,5 +414,5 @@
 <pre><span style='mso-spacerun:yes'>    </span>This document gives coding conventions for the Python code</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>comprising</span> the standard library for the main Python distribution.</pre><pre><span style='mso-spacerun:yes'>    </span>Please see the companion informational PEP describing style</pre><pre><span style='mso-spacerun:yes'>    </span><span
-class=GramE>guidelines</span> for the C code in the C implementation of Python[1].</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>This document was adapted from Guido's original Python Style</pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'> </span>Guide <span
+class=GramE>guidelines</span> for the C code in the C implementation of Python[1].</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>This document was adapted from Guido's original Python Style</pre><pre><span style='mso-spacerun:yes'>    </span>Guide <span
 class=GramE>essay[</span>2], with some additions from Barry's style guide[5].</pre><pre><span style='mso-spacerun:yes'>    </span>Where there's conflict, Guido's style rules for the purposes of</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>this</span> PEP.<span style='mso-spacerun:yes'>  </span>This PEP may still be incomplete (in fact, it may never</pre><pre><span style='mso-spacerun:yes'>    </span><span
@@ -399,5 +427,5 @@
 class=GramE>the</span> style guide just doesn't apply.<span style='mso-spacerun:yes'>  </span>When in doubt, use your best</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>judgement</span>.<span style='mso-spacerun:yes'>  </span>Look at other examples and decide what looks best.</pre><pre><span style='mso-spacerun:yes'>    </span>And don't hesitate to ask!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Two good reasons to break a particular rule:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>(1) When applying the rule would make the code less readable, even</pre><pre><span style='mso-spacerun:yes'>        </span><span
-class=GramE>for</span> someone who is used to reading code that follows the rules.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>(2) To be consistent with surrounding code that also breaks it</pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'>     </span>(<span
+class=GramE>for</span> someone who is used to reading code that follows the rules.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>(2) To be consistent with surrounding code that also breaks it</pre><pre><span style='mso-spacerun:yes'>        </span>(<span
 class=GramE>maybe</span> for historic reasons) -- <span class=GramE>although</span> this is also an</pre><pre><span style='mso-spacerun:yes'>        </span><span
 class=GramE>opportunity</span> to clean up someone else's mess (in true XP style).</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
@@ -405,15 +433,12 @@
 <h3>Code lay-out</h3>
 
-<pre><span style='mso-spacerun:yes'>  </span>Indentation</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Use the default of <span
-class=SpellE>Emacs</span>' Python-mode: 4 spaces for one</pre><pre><span style='mso-spacerun:yes'>    </span><span
+<pre><span style='mso-spacerun:yes'>  </span>Indentation</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Use the default of Emacs' Python-mode: 4 spaces for one</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>indentation</span> level.<span style='mso-spacerun:yes'>  </span>For really old code that you don't want to</pre><pre><span style='mso-spacerun:yes'>    </span><span
-class=GramE>mess</span> up, you can continue to use 8-space tabs.<span style='mso-spacerun:yes'>  </span><span
-class=SpellE>Emacs</span> Python-mode</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>mess</span> up, you can continue to use 8-space tabs.<span style='mso-spacerun:yes'>  </span>Emacs Python-mode</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>auto-</span>detects the prevailing indentation level used in a file and</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>sets</span> its indentation parameters accordingly.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span><span
 class=GramE>Tabs or Spaces?</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Never mix tabs and spaces.<span style='mso-spacerun:yes'>  </span>The most popular way of indenting</pre><pre><span style='mso-spacerun:yes'>    </span>Python is with spaces only.<span style='mso-spacerun:yes'>  </span>The second-most popular way is with</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>tabs</span> only.<span style='mso-spacerun:yes'>  </span>Code indented with a mixture of tabs and spaces should</pre><pre><span style='mso-spacerun:yes'>    </span><span
-class=GramE>be</span> converted to using spaces exclusively.<span style='mso-spacerun:yes'>  </span>(In <span
-class=SpellE>Emacs</span>, select the</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>be</span> converted to using spaces exclusively.<span style='mso-spacerun:yes'>  </span>(In Emacs, select the</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>whole</span> buffer and hit ESC-x <span class=SpellE>untabify</span>.)<span style='mso-spacerun:yes'>  </span>When invoking the python</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>command</span> line interpreter with the -t option, it issues warnings</pre><pre><span style='mso-spacerun:yes'>    </span><span
@@ -421,11 +446,10 @@
 class=SpellE>tt</span></pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>these</span> warnings become errors.<span style='mso-spacerun:yes'>  </span>These options are highly</pre><pre><span style='mso-spacerun:yes'>    </span><span
-class=GramE>recommended</span>!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>For new projects, spaces-only are strongly recommended over tabs.</pre><pre><span style='mso-spacerun:yes'>    </span>Most editors have features that make this easy to do.<span style='mso-spacerun:yes'>  </span>(In <span
-class=SpellE>Emacs</span>,</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>recommended</span>!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>For new projects, spaces-only are strongly recommended over tabs.</pre><pre><span style='mso-spacerun:yes'>    </span>Most editors have features that make this easy to do.<span style='mso-spacerun:yes'>  </span>(In Emacs,</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>make</span> sure indent-tabs-mode is nil).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Maximum Line Length</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>There are still many devices around that are limited to 80</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>character</span> lines; plus, limiting windows to 80 characters makes it</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>possible</span> to have several windows side-by-side.<span style='mso-spacerun:yes'>  </span>The default</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>wrapping</span> on such devices looks ugly.<span style='mso-spacerun:yes'>  </span>Therefore, please limit all</pre><pre><span style='mso-spacerun:yes'>    </span><span
-class=GramE>lines</span> to a maximum of 79 characters (<span class=SpellE>Emacs</span> wraps lines that are</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>lines</span> to a maximum of 79 characters (Emacs wraps lines that are</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>exactly</span> 80 characters long).<span style='mso-spacerun:yes'>  </span>For flowing long blocks of text</pre><pre><span style='mso-spacerun:yes'>    </span>(<span
 class=SpellE>docstrings</span> or comments), limiting the length to 72 characters is</pre><pre><span style='mso-spacerun:yes'>    </span><span
@@ -433,6 +457,5 @@
 class=GramE>implied</span> line continuation inside parentheses, brackets and braces.</pre><pre><span style='mso-spacerun:yes'>    </span>If necessary, you can add an extra pair of parentheses around an</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>expression</span>, but sometimes using a backslash looks better.<span style='mso-spacerun:yes'>  </span>Make</pre><pre><span style='mso-spacerun:yes'>    </span><span
-class=GramE>sure</span> to indent the continued line appropriately.<span style='mso-spacerun:yes'>  </span><span
-class=SpellE>Emacs</span></pre><pre><span style='mso-spacerun:yes'>    </span>Python-mode does this right.<span style='mso-spacerun:yes'>  </span>Some examples:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=GramE>sure</span> to indent the continued line appropriately.<span style='mso-spacerun:yes'>  </span>Emacs</pre><pre><span style='mso-spacerun:yes'>    </span>Python-mode does this right.<span style='mso-spacerun:yes'>  </span>Some examples:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>class</span> Rectangle(Blob):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
 class=GramE>def</span> __init__(self, width, height,</pre><pre><span style='mso-spacerun:yes'>                     </span><span
@@ -442,5 +465,5 @@
 class=GramE>highlight</span> &gt; 100:</pre><pre><span style='mso-spacerun:yes'>                </span><span
 class=GramE>raise</span> <span class=SpellE>ValueError</span>(&quot;sorry, you lose&quot;)</pre><pre><span style='mso-spacerun:yes'>            </span><span
-class=GramE>if</span> width == 0 and height == 0 and (<span class=SpellE>color</span> == 'red' or</pre><pre><span style='mso-spacerun:yes'>                                               </span><span
+class=GramE>if</span> width == 0 and height == 0 and (<span class=SpellE>color</span> == 'red' or</pre><pre><span style='mso-spacerun:yes'>                          </span><span style='mso-spacerun:yes'>                     </span><span
 class=GramE>emphasis</span> is None):</pre><pre><span style='mso-spacerun:yes'>                </span><span
 class=GramE>raise</span> <span class=SpellE>ValueError</span>(&quot;I don't think so&quot;)</pre><pre><span style='mso-spacerun:yes'>            </span><span
@@ -454,8 +477,8 @@
 class=GramE>implementations</span>).</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>When blank lines are used to separate method definitions, there is</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>also</span> a blank line between the `class' line and the first method</pre><pre><span style='mso-spacerun:yes'>    </span><span
-class=GramE>definition</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'> </span>Use blank lines in functions, <s>sparingly</s> <i
+class=GramE>definition</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Use blank lines in functions, <s>sparingly</s> <i
 style='mso-bidi-font-style:normal'><span style='color:blue'>liberally</span></i>, to indicate logical</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>sections</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Python accepts the control-L (i.e. ^L) form feed character as</pre><pre><span style='mso-spacerun:yes'>    </span><span
-class=SpellE>whitespace</span>; <span class=SpellE>Emacs</span> (and some printing tools) treat these</pre><pre><span style='mso-spacerun:yes'>    </span><span
+class=SpellE>whitespace</span>; Emacs (and some printing tools) treat these</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>characters</span> as page separators, so you may use them to separate</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>pages</span> of related sections of your file.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Encodings (<a
@@ -490,5 +513,5 @@
 class=GramE>and</span> before module <span class=SpellE>globals</span> and constants.<span style='mso-spacerun:yes'>  </span>Imports should be grouped, </pre><pre
 style='margin-left:24.0pt'><span style='mso-spacerun:yes'>  </span><span
-class=GramE>with</span> the order being</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>1. <span
+class=GramE>with</span> the order being</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span><span style='mso-spacerun:yes'>    </span>1. <span
 class=GramE>standard</span> library imports</pre><pre><span style='mso-spacerun:yes'>      </span>2. <span
 class=GramE>related</span> major package imports (i.e. all email package imports next)</pre><pre><span style='mso-spacerun:yes'>      </span>3. <span
@@ -522,13 +545,17 @@
 class=SpellE>whitespace</span> in the following places:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately inside parentheses, brackets or braces, as in:</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
 class=GramE>spam(</span> ham[ 1 ], { eggs: 2 } )&quot;.<span style='mso-spacerun:yes'>  </span>Always write this as</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
-class=GramE>spam(</span>ham[1], {eggs: 2})&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately before a comma, semicolon, or colon, as in:</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
-class=GramE>if</span> x == 4 : print x , y ; x , y = y , x&quot;.<span style='mso-spacerun:yes'>  </span>Always write this as</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;<span
-class=GramE>if</span> x == 4: print x, y; x, y = y, x&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately before the open parenthesis that starts the argument</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>spam(</span>ham[1], {eggs: 2})&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately before a comma, semicolon, or colon, as in:</pre><pre><span style='mso-spacerun:yes'>      </span><span
+lang=ES style='mso-ansi-language:ES'>&quot;<span class=SpellE>if</span> x == <span
+class=GramE>4 :</span> <span class=SpellE>print</span> x , y ; x , y = y , x&quot;.<span style='mso-spacerun:yes'>  </span></span>Always write this as</pre><pre><span style='mso-spacerun:yes'>      </span><span
+lang=ES style='mso-ansi-language:ES'>&quot;<span class=SpellE>if</span> x == 4: <span
+class=SpellE>print</span> x, y; x, y = y, x&quot;.<o:p></o:p></span></pre><pre><span
+lang=ES style='mso-ansi-language:ES'><o:p>&nbsp;</o:p></span></pre><pre><span
+lang=ES style='mso-ansi-language:ES'><span style='mso-spacerun:yes'>    </span></span>- Immediately before the open parenthesis that starts the argument</pre><pre><span style='mso-spacerun:yes'>      </span><span
 class=GramE>list</span> of a function call, as in &quot;spam (1)&quot;.<span style='mso-spacerun:yes'>  </span>Always write</pre><pre><span style='mso-spacerun:yes'>      </span><span
 class=GramE>this</span> as &quot;spam(1)&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Immediately before the open parenthesis that starts an indexing or</pre><pre><span style='mso-spacerun:yes'>      </span><span
 class=GramE>slicing</span>, as in: &quot;<span class=SpellE>dict</span> ['key'] = list [index]&quot;.<span style='mso-spacerun:yes'>  </span>Always</pre><pre><span style='mso-spacerun:yes'>      </span><span
 class=GramE>write</span> this as &quot;<span class=SpellE>dict</span>['key'] = list[index]&quot;.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- More than one space around an assignment (or other) operator to</pre><pre><span style='mso-spacerun:yes'>      </span><span
-class=GramE>align</span> it with another, as in:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span>x<span style='mso-spacerun:yes'>             </span>= 1</pre><pre><span style='mso-spacerun:yes'>          </span>y<span style='mso-spacerun:yes'>             </span>= 2</pre><pre><span style='mso-spacerun:yes'>          </span><span
-class=SpellE>long_variable</span> = 3</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Always write this as</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span style='mso-spacerun:yes'>      </span>x = 1</pre><pre><span style='mso-spacerun:yes'>          </span>y = 2</pre><pre><span style='mso-spacerun:yes'>          </span><span
+class=GramE>align</span> it with another, as in:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span>x<span style='mso-spacerun:yes'>             </span>= 1</pre><pre><span style='mso-spacerun:yes'>          </span>y<span style='mso-spacerun:yes'>             </span>= 2</pre><pre> <span style='mso-spacerun:yes'>         </span><span
+class=SpellE>long_variable</span> = 3</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Always write this as</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span>x = 1</pre><pre><span style='mso-spacerun:yes'>          </span>y = 2</pre><pre><span style='mso-spacerun:yes'>          </span><span
 class=SpellE>long_variable</span> = 3</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>(Don't bother to argue with him on any of the above -- Guido's</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>grown</span> accustomed to this style over 20 years.)</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>  </span>Other Recommendations</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Always surround these binary operators with a single space on</pre><pre><span style='mso-spacerun:yes'>      </span><span
@@ -538,8 +565,12 @@
 class=GramE>either</span> side of a binary operator.<span style='mso-spacerun:yes'>  </span>Some examples:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span><span
 class=SpellE>i</span> = i+1</pre><pre><span style='mso-spacerun:yes'>          </span><span
-class=GramE>submitted</span> = submitted + 1</pre><pre><span style='mso-spacerun:yes'>          </span>x = x*2 - 1</pre><pre><span style='mso-spacerun:yes'>          </span>hypot2 = x*x + y*y</pre><pre><span style='mso-spacerun:yes'>          </span>c = (<span
-class=SpellE>a+b</span>) * (a-b)</pre><pre><span style='mso-spacerun:yes'>          </span>c = (a + b) * (a - b)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Don't use spaces around the '=' sign when used to indicate a</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>submitted</span> = submitted + 1</pre><pre><span style='mso-spacerun:yes'>          </span>x = x*2 - 1</pre><pre><span style='mso-spacerun:yes'>          </span><span
+lang=ES style='mso-ansi-language:ES'>hypot2 = <span class=SpellE>x*x</span> + <span
+class=SpellE>y*y</span><o:p></o:p></span></pre><pre><span lang=ES
+style='mso-ansi-language:ES'><span style='mso-spacerun:yes'>          </span>c = (<span
+class=SpellE>a+b</span>) * (a-b)<o:p></o:p></span></pre><pre><span lang=ES
+style='mso-ansi-language:ES'><span style='mso-spacerun:yes'>          </span></span>c = (a + b) * (a - b)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Don't use spaces around the '=' sign when used to indicate a</pre><pre><span style='mso-spacerun:yes'>      </span><span
 class=GramE>keyword</span> argument or a default parameter value.<span style='mso-spacerun:yes'>  </span>For instance:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span><span
-class=GramE>def</span> complex(real, <span class=SpellE>imag</span>=0.0):</pre><pre><span style='mso-spacerun:yes'>              </span><span
+class=GramE>def</span> complex(real, <span class=SpellE>imag</span>=0.0):</pre><pre><span style='mso-spacerun:yes'>            </span><span style='mso-spacerun:yes'>  </span><span
 class=GramE>return</span> magic(r=real, <span class=SpellE>i</span>=<span
 class=SpellE>imag</span>)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Compound statements (multiple statements on the same line) are</pre><pre><span style='mso-spacerun:yes'>      </span><span
@@ -548,5 +579,5 @@
 class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>          </span>Yes: if <span
 class=SpellE>foo</span> == 'blah':</pre><pre><span style='mso-spacerun:yes'>                   </span><span
-class=SpellE>do_blah_<span class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>          </span>No:<span style='mso-spacerun:yes'>  </span><span
+class=SpellE>do_blah_<span class=GramE>thing</span></span><span class=GramE>()</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>       </span><span style='mso-spacerun:yes'>   </span>No:<span style='mso-spacerun:yes'>  </span><span
 class=SpellE>do_<span class=GramE>one</span></span><span class=GramE>(</span>); <span
 class=SpellE>do_two</span>(); <span class=SpellE>do_three</span>()</pre><pre><span style='mso-spacerun:yes'>          </span>Yes: <span
@@ -564,6 +595,5 @@
 class=GramE>out</span> of complete sentences, and each sentence should end in a</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>period</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>You should use two spaces after a sentence-ending period, since it</pre><pre><span style='mso-spacerun:yes'>    </span><span
-class=GramE>makes</span> <span class=SpellE>Emacs</span> wrapping and filling work <span
-class=SpellE>consistenty</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>When writing English, <span
+class=GramE>makes</span> Emacs wrapping and filling work <span class=SpellE>consistenty</span>.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>When writing English, <span
 class=SpellE>Strunk</span> and White apply.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Python coders from non-English speaking countries: please write</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>your</span> comments in English, unless you are 120% sure that the code</pre><pre><span style='mso-spacerun:yes'>    </span><span
@@ -587,5 +617,5 @@
 class=GramE>group</span>; either full initials, first name or surname. For example, if </pre><pre><span style='mso-spacerun:yes'>    </span>Duncan S Gray found an issue, he could insert in the code:</pre><pre><o:p>&nbsp;</o:p></pre><pre
 style='margin-top:0cm;margin-right:12.0pt;margin-bottom:0cm;margin-left:12.0pt;
-margin-bottom:.0001pt'><span style='mso-spacerun:yes'>    </span>#FIXME (DSG): Should check that function returns something sensible and<o:p></o:p></pre><pre> <span style='mso-spacerun:yes'>     </span>#<span
+margin-bottom:.0001pt'><span style='mso-spacerun:yes'>    </span>#FIXME (DSG): Should check that function returns something sensible and</pre><pre><span style='mso-spacerun:yes'>      </span>#<span
 class=GramE>raise</span> a meaningful exception if it returns None for example</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>This allows other developers to identify areas which require attention with </pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>the</span> added bonus of knowing who logged the issue.</pre><pre><o:p>&nbsp;</o:p></pre>
@@ -605,5 +635,12 @@
 style='color:blue'>Ideally, all modules, functions, classes, and methods should have <o:p></o:p></span></i></pre><pre><i
 style='mso-bidi-font-style:normal'><span style='color:blue'><span style='mso-spacerun:yes'>      </span><span
-class=GramE>a</span> <span class=SpellE>docstring</span>.<o:p></o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <a
+class=GramE>a</span> <span class=SpellE>docstring</span>.<o:p></o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'> <span style='mso-spacerun:yes'>   </span>- For test methods #s are preferred, over <span
+class=SpellE>docstrings</span>.<span style='mso-spacerun:yes'>  </span><span
+class=SpellE>Docstrings</span> dont <o:p></o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><span
+style='mso-tab-count:1'>      </span>work well with verbose=2. <o:p></o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><o:p>&nbsp;</o:p></span></i></pre><pre><i
+style='mso-bidi-font-style:normal'><span style='color:blue'><o:p>&nbsp;</o:p></span></i></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <a
 href="http://www.python.org/peps/pep-0257.html">PEP 257</a> describes good <span
 class=SpellE>docstring</span> conventions.<span style='mso-spacerun:yes'>  </span>Note that most</pre><pre><span style='mso-spacerun:yes'>      </span><span
@@ -613,5 +650,5 @@
 class=SpellE>foobang</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Optional <span
 class=SpellE>plotz</span> says to <span class=SpellE>frobnicate</span> the <span
-class=SpellE>bizbaz</span> first.</pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'>   </span>&quot;&quot;&quot;</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- For one liner <span
+class=SpellE>bizbaz</span> first.</pre><pre><span style='mso-spacerun:yes'>      </span>&quot;&quot;&quot;</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- For one liner <span
 class=SpellE>docstrings</span>, it's okay to keep the closing &quot;&quot;&quot; on</pre><pre><span style='mso-spacerun:yes'>      </span><span
 class=GramE>the</span> same line.</pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
@@ -647,5 +684,5 @@
 class=GramE>character</span>!)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- <span
 class=SpellE>Capitalized_Words_With_Underscores</span> (ugly!)</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>There's also the style of using a short unique prefix to group</pre><pre><span style='mso-spacerun:yes'>    </span><span
-class=GramE>related</span> names together.<span style='mso-spacerun:yes'>  </span>This is not used much in Python, but it</pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'> </span><span
+class=GramE>related</span> names together.<span style='mso-spacerun:yes'>  </span>This is not used much in Python, but it</pre><pre><span style='mso-spacerun:yes'>    </span><span
 class=GramE>is</span> mentioned for completeness.<span style='mso-spacerun:yes'>  </span>For example, the <span
 class=SpellE><span class=GramE>os.stat</span></span><span class=GramE>()</span></pre><pre><span style='mso-spacerun:yes'>    </span><span
@@ -697,5 +734,5 @@
 class=GramE>(e.g. _socket).</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Python packages should have short, all-lowercase names, <s>without</s> </pre><pre><span style='mso-spacerun:yes'>      </span><span
 class=GramE><i style='mso-bidi-font-style:normal'><span style='color:blue'>possibly</span></i></span><i
-style='mso-bidi-font-style:normal'><span style='color:blue'> with</span></i> underscores.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Class Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span><span style='mso-spacerun:yes'>  </span>Almost without exception, class names use the <span
+style='mso-bidi-font-style:normal'><span style='color:blue'> with</span></i> underscores.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Class Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>Almost without exception, class names use the <span
 class=SpellE>CapWords</span> convention.</pre><pre><span style='mso-spacerun:yes'>      </span>Classes for internal use have a leading underscore in addition.</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>Exception Names</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>If a module defines a single exception raised for all sorts of</pre><pre><span style='mso-spacerun:yes'>      </span><span
 class=GramE>conditions</span>, it is generally called &quot;error&quot; or &quot;Error&quot;.<span style='mso-spacerun:yes'>  </span>It seems</pre><pre><span style='mso-spacerun:yes'>      </span><span
@@ -769,5 +806,5 @@
 class=GramE>really</span> mean &quot;if x is not None&quot; -- e.g. when testing whether a</pre><pre><span style='mso-spacerun:yes'>      </span><span
 class=GramE>variable</span> or argument that defaults to None was set to some other</pre><pre><span style='mso-spacerun:yes'>      </span><span
-class=GramE>value</span>.<span style='mso-spacerun:yes'>  </span>The other value might be a value that's false in a</pre><pre><span style='mso-spacerun:yes'>      </span>Boolean context!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Class-based exceptions are always preferred over string-based</pre><pre><span style='mso-spacerun:yes'>      </span><span
+class=GramE>value</span>.<span style='mso-spacerun:yes'>  </span>The other value might be a value that's false in a</pre><pre><span style='mso-spacerun:yes'>      </span>Boolean context!</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>- Class-based exceptions are always preferred over string-based</pre><pre> <span style='mso-spacerun:yes'>     </span><span
 class=GramE>exceptions</span>.<span style='mso-spacerun:yes'>  </span>Modules or packages should define their own</pre><pre><span style='mso-spacerun:yes'>      </span><span
 class=GramE>domain-specific</span> base exception class, which should be subclassed</pre><pre><span style='mso-spacerun:yes'>      </span><span
@@ -806,5 +843,5 @@
 class=GramE>from</span> types import <span class=SpellE>StringTypes</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
 class=GramE>if</span> <span class=SpellE>isinstance</span>(obj, <span
-class=SpellE>StringTypes</span>):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>     </span><span style='mso-spacerun:yes'> </span>In Python 2.0 and 2.1, you should do:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
+class=SpellE>StringTypes</span>):</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>      </span>In Python 2.0 and 2.1, you should do:</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>        </span><span
 class=GramE>from</span> types import <span class=SpellE>StringType</span>, <span
 class=SpellE>UnicodeType</span></pre><pre><span style='mso-spacerun:yes'>        </span><span
@@ -842,5 +879,5 @@
 class=SpellE>Docstring</span> Conventions, <span class=SpellE>Goodger</span>, <span
 class=GramE>van</span> <span class=SpellE>Rossum</span></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[4] <a
-href="http://www.wikipedia.com/wiki/CamelCase">http://www.wikipedia.com/wiki/CamelCase</a></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[5] Barry's GNU Mailman style guide</pre><pre><span style='mso-spacerun:yes'>        </span><a
+href="http://www.wikipedia.com/wiki/CamelCase">http://www.wikipedia.com/wiki/CamelCase</a></pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>    </span>[5] Barry's GNU Mailman style guide</pre><pre><span style='mso-spacerun:yes'>      </span><span style='mso-spacerun:yes'>  </span><a
 href="http://barry.warsaw.us/software/STYLEGUIDE.txt">http://barry.warsaw.us/software/STYLEGUIDE.txt</a></pre><pre><o:p>&nbsp;</o:p></pre><pre><o:p>&nbsp;</o:p></pre>
 
Index: /documentation/user_manual/anuga_user_manual.tex
===================================================================
--- /documentation/user_manual/anuga_user_manual.tex	(revision 3448)
+++ /documentation/user_manual/anuga_user_manual.tex	(revision 3449)
@@ -13,4 +13,9 @@
 %Figures \label{fig: }
 
+% Is latex failing with;
+% `modanuga_user_manual.ind' not found?
+% try this command-line
+%   makeindex modanuga_user_manual.idx
+% To produce the modanuga_user_manual.ind file.
 
 
@@ -1463,19 +1468,39 @@
 \begin{itemize}
 \item \code{indices} which is a list of ids of triangles to which set\_quantity should apply its assignment of values.
-\item \code{location} determines which part of the triangles to assign to. Options are 'vertices' (default), 'edges', and 'centroids'.
+\item \code{location} determines which part of the triangles to assign
+  to. Options are 'vertices' (default), 'edges', 'unique vertices', and 'centroids'.
 \end{itemize}
-
-
-\end{methoddesc}
-
-
-
-
-
-
 
 %%%
 \anuga provides a number of predefined initial conditions to be used
 with \code{set\_quantity}.
+
+\end{methoddesc}
+
+
+
+
+\begin{funcdesc}{set_region}{tag, quantity, X, location='vertices'}
+  Module: \module{pyvolution.domain}
+  (see also \module{pyvolution.region.Set\_region})
+  (see also \module{pyvolution.quantity.set\_values})
+  
+This function is used to assign values to individual quantities given
+a regional tag.   It is similar to set\_quantity. 
+For example, if in pmesh a regional tag of 'ditch' was
+used, set\_region can be used to set elevation of this region to
+-10m. X is the constant or function to be applied to the quantity,
+over the tagged region.  Location describes how the values will be
+applied.  Options are 'vertices' (default), 'edges', 'unique
+vertices', and 'centroids'.
+
+This method can also be called with a list of region objects.  This is
+useful for adding quantities in regions, and having one quantity
+value based on another quantity. See  \module{pyvolution.region} for
+more details.
+\end{funcdesc}
+
+
+
 
 \begin{funcdesc}{slump_tsunami}{length, depth, slope, width=None, thickness=None,
