Update C++ style guide to 3.199:

- Update an example to omit the blank line between C and C++ #includes.
 - Rewrite the paragraph about #include ordering.
 - Clarify namespace closing comments.
 - Discourage const references for input arguments which are aliased beyond
   the scope of the function call.
 - Replace all '&' with '&'.
 - Clarify that interfaces must have virtual destructors.
 - Add an explicit example for |else if|.
 - C++11 updates.

Update Objective-C style guide to 2.36:
 - Remove requirement to list @dynamic implementations.
 - Remove requirement to never synthesize CFType properties, since they may
   be retained on 10.6.
 - Use __weak and __strong type declaration modifiers rather than comments.
 - Make the copyright/license information consistent.
 - An example initializer comment revealed too much about the implementation.
 - Correct spelling mistakes.
 - Fix names that didn't follow Cocoa conventions.
 - Fix examples to conform to style.
 - Add a section about no braces for empty interfaces.
 - Add a section about automatically synthesized instance variables.
 - Codify avoidance of accessors in -init and -dealloc methods.
 - Changes for the 80-column rule.
 - Weaken the language around object ownership type qualifiers.
 - Document the rules for formatting blocks.

Update JavaScript style guide to 2.27:
 - Introduce EcmaScript 5 Strict verbiage.
 - Add a note about private constructors.
 - Simplify explanations about JSDoc comments.
 - Sort the JSDoc tags.
 - Remove the sections about type-checking now that the JSDoc tags and JS
   types are no longer one table.
 - Convert <tt> to <code>, because the XSL processor eats <tt>.
 - Add @suppress.
 - Mark @inheritDoc deprecated in favor of @override.
 - Add a section about inner classes and enums being defined in the same file
   as the top-level class they are defined on.

Update Python style guide to 2.28:
 - Change "Naming" summary to match body.
 - Make the prohibition against backslash line continuation explicit.
 - Update the TODO section to match the C++ style guide.
 - Declare Python code without a shebang line to be stylish.
 - Clarify rules on function docstrings.
 - Fix spelling errors.
 - Update with styleguide.xsl 1.33.

Update styleguide.xsl to 1.33:
 - Clean up style guide JS.
 - Links to anchor tags auto-expand.

cppguide.xml

@@ -4,7 +4,7 @@
 
 <p align="right">
 
-Revision 3.188
+Revision 3.199
 </p>
 
 
@@ -209,7 +209,6 @@ Tashana Landray
         definitions of the classes they use, and usually have to
         include several header files.
       </p>
-      
       <SUBSECTION title="Note:">
         If you use a symbol <code>Foo</code> in your source file, you
         should bring in a definition for <code>Foo</code> yourself,
@@ -383,11 +382,13 @@ Tashana Landray
              <code>.h</code> files.</li>
       </ol>
       <p>
-        The preferred ordering reduces hidden dependencies.  We want
+        With the preferred ordering, if <code><var>dir/foo2</var>.h</code>
-        every header file to be compilable on its own.  The easiest
+        omits any necessary includes, the build of
-        way to achieve this is to make sure that every one of them is
+        <code><var>dir/foo</var>.cc</code> or
-        the first <code>.h</code> file <code>#include</code>d in some
+        <code><var>dir/foo</var>_test.cc</code> will break.
-        <code>.cc</code>.  
+        Thus, this rule ensures that build breaks show up first
+        for the people working on these files, not for innocent people
+        in other packages.
       </p>
       <p>
         <code><var>dir/foo</var>.cc</code> and
@@ -412,7 +413,6 @@ Tashana Landray
 
         #include &lt;sys/types.h&gt;
         #include &lt;unistd.h&gt;
-
         #include &lt;hash_map&gt;
         #include &lt;vector&gt;
 
@@ -468,6 +468,7 @@ Tashana Landray
       <DECISION>
         <p>
           Use namespaces according to the policy described below.
+          Terminate namespaces with comments as shown in the given examples.
         </p>
 
         <SUBSECTION title="Unnamed Namespaces">
@@ -490,9 +491,7 @@ Tashana Landray
                    associated with a particular class may be declared
                    in that class as types, static data members or
                    static member functions rather than as members of
-                   an unnamed namespace.  Terminate the unnamed
+                   an unnamed namespace.
-                   namespace as shown, with a comment <code>//
-                   namespace</code>.
                  </p>
                  </li>
             <li> Do not use unnamed namespaces in <code>.h</code>
@@ -1239,7 +1238,7 @@ Tashana Landray
           An interface class can never be directly instantiated
           because of the pure virtual method(s) it declares.  To make
           sure all implementations of the interface can be destroyed
-          correctly, they must also declare a virtual destructor (in
+          correctly, the interface must also declare a virtual destructor (in
           an exception to the first rule, this should not be pure).  See
           Stroustrup, <cite>The C++ Programming Language</cite>, 3rd
           edition, section 12.4 for details.
@@ -1574,14 +1573,24 @@ Tashana Landray
           non-<code>const</code> reference parameters.
         </p>
         <p>
-          One case when you might want an input parameter to be a
+
-          <code>const</code> pointer is if you want to emphasize that the
+         However, there are some instances where using <code>const T*</code>
-          argument is not copied, so it must exist for the lifetime of the
+         is preferable to <code>const T&amp;</code> for input parameters. For
-          object; it is usually best to document this in comments as
+         example:
-          well.  STL adapters such as <code>bind2nd</code> and
+
-          <code>mem_fun</code> do not permit reference parameters, so
+         You want to pass in NULL.
-          you must declare functions with pointer parameters in these
+
-          cases, too.
+         The function saves a pointer or reference to the input.
+         
+
+         Remember that most of the time input parameters are going to be
+         specified as <code>const T&amp;</code>.  Using <code>const T*</code>
+         instead communicates to the reader that the input is somehow treated
+         differently.  So if you choose <code>const T*</code> rather than
+         <code>const T&amp;</code>, do so for a concrete reason; otherwise it
+         will likely confuse readers by making them look for an explanation
+         that doesn't exist.
+
         </p>
       </DECISION>
     </BODY>
@@ -2606,28 +2615,29 @@ Tashana Landray
   </BODY>
   </STYLEPOINT>
 
-  <STYLEPOINT title="C++0x">
+  <STYLEPOINT title="C++11">
   <SUMMARY>
-    Use only approved libraries and language extensions from C++0x.
+    Use only approved libraries and language extensions from C++11 (formerly
+    known as C++0x).
     Currently, none are approved.
   </SUMMARY>
   <BODY>
     <DEFINITION>
-      C++0x is the next ISO C++ standard, currently in
+      C++11 is the latest ISO C++ standard.
-      <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3092.pdf">final
+      It contains
-      committee draft</a> form.  It contains
+      <a href="http://en.wikipedia.org/wiki/C%2B%2B11">significant
-      <a href="http://en.wikipedia.org/wiki/C%2B%2B0x">significant
       changes</a> both to the language and libraries.
+      
     </DEFINITION>
     <PROS>
-      We expect that C++0x will become the next standard, and eventually will
+      C++11 has become the official standard, and eventually will
       be supported by most C++ compilers.  It standardizes some common C++
       extensions that we use already, allows shorthands for some operations,
-      and has some safety improvements.
+      and has some performance and safety improvements.
     </PROS>
     <CONS>
       <p>
-        The C++0x standard is substantialy more complex than its predecessor
+        The C++11 standard is substantially more complex than its predecessor
         (1,300 pages versus 800 pages), and is
         unfamilar to many developers.  The long-term effects of some
         features on code readability and maintenance are unknown.  We cannot
@@ -2635,7 +2645,7 @@ Tashana Landray
         tools that may be of interest (gcc, icc, clang, Eclipse, etc.).
       </p>
       <p>
-        As with <a href="#Boost">Boost</a>, some C++0x extensions encourage
+        As with <a href="#Boost">Boost</a>, some C++11 extensions encourage
         coding practices that hamper readability&#8212;for example by removing
         checked redundancy (such as type names) that may be helpful to readers,
         or by encouraging template metaprogramming.  Other extensions
@@ -2645,9 +2655,12 @@ Tashana Landray
       </p>
     </CONS>
     <DECISION>
-      Use only C++0x libraries and language features that have been approved
+      Use only C++11 libraries and language features that have been approved
       for use.  Currently, no such features are approved.
       Features will be approved individually as appropriate.
+      Avoid writing code that is incompatible with C++11 (even though it
+      works in C++03).
+      
     </DECISION>
   </BODY>
   </STYLEPOINT>
@@ -3845,7 +3858,9 @@ Tashana Landray
       <CODE_SNIPPET>
         if (condition) {  // no spaces inside parentheses
           ...  // 2 space indent.
-        } else {  // The else goes on the same line as the closing brace.
+        } else if (...) {  // The else goes on the same line as the closing brace.
+          ...
+        } else {
           ...
         }
       </CODE_SNIPPET>
@@ -4069,7 +4084,7 @@ Tashana Landray
         the <code>&amp;&amp;</code> logical AND operators are at the
         end of the line.  This is more common in Google code, though
         wrapping all operators at the beginning of the line is also
-        allowed.  Feel free to insert extra parentheses judiciously,
+        allowed.  Feel free to insert extra parentheses judiciously
         because they can be very helpful in increasing readability
         when used appropriately.  Also note that you should always use the
         punctuation operators, such as <code>&amp;&amp;</code> and
@@ -4550,7 +4565,7 @@ Tashana Landray
 <HR/>
 
 <p align="right">
-Revision 3.188
+Revision 3.199
 </p>
 
 

objcguide.xml

@@ -4,7 +4,7 @@
 
 <p align="right">
 
-Revision 2.24
+Revision 2.36
 </p>
 
 
@@ -129,8 +129,8 @@ Revision 2.24
   </p>
 
 <CODE_SNIPPET>
-    //  GTMFoo.h
+    //  Foo.h
-    //  FooProject
+    //  AwesomeProject
     //
     //  Created by Greg Miller on 6/13/08.
     //  Copyright 2008 Google, Inc. All rights reserved.
@@ -144,26 +144,27 @@ Revision 2.24
     // documenting.
     //
     // (no blank line between this comment and the interface)
-    @interface GTMFoo : NSObject {
+    @interface Foo : NSObject {
      @private
-      NSString *foo_;
       NSString *bar_;
+      NSString *bam_;
     }
 
-    // Returns an autoreleased instance of GMFoo. See -initWithString: for details
+    // Returns an autoreleased instance of Foo. See -initWithBar: for details
-    // about the argument.
+    // about |bar|.
-    + (id)fooWithString:(NSString *)string;
+    + (id)fooWithBar:(NSString *)bar;
 
-    // Designated initializer. |string| will be copied and assigned to |foo_|.
+    // Designated initializer. |bar| is a thing that represents a thing that
-    - (id)initWithString:(NSString *)string;
+    // does a thing.
+    - (id)initWithBar:(NSString *)bar;
 
-    // Gets and sets the string for |foo_|.
+    // Gets and sets |bar_|.
-    - (NSString *)foo;
+    - (NSString *)bar;
-    - (void)setFoo:(NSString *)newFoo;
+    - (void)setBar:(NSString *)bar;
 
-    // Does some work on |blah| and returns YES if the work was completed
+    // Does some work with |blah| and returns YES if the work was completed
-    // successfuly, and NO otherwise.
+    // successfully, and NO otherwise.
-    - (BOOL)doWorkWithString:(NSString *)blah;
+    - (BOOL)doWorkWithBlah:(NSString *)blah;
 
     @end
   </CODE_SNIPPET>
@@ -177,51 +178,51 @@ Revision 2.24
 
   <CODE_SNIPPET>
     //
-    //  GTMFoo.m
+    //  Foo.m
-    //  FooProject
+    //  AwesomeProject
     //
     //  Created by Greg Miller on 6/13/08.
     //  Copyright 2008 Google, Inc. All rights reserved.
     //
 
-    #import "GTMFoo.h"
+    #import "Foo.h"
 
 
-    @implementation GTMFoo
+    @implementation Foo
 
-    + (id)fooWithString:(NSString *)string {
+    + (id)fooWithBar:(NSString *)bar {
-      return [[[self alloc] initWithString:string] autorelease];
+      return [[[self alloc] initWithBar:bar] autorelease];
     }
 
     // Must always override super's designated initializer.
     - (id)init {
-      return [self initWithString:nil];
+      return [self initWithBar:nil];
     }
 
-    - (id)initWithString:(NSString *)string {
+    - (id)initWithBar:(NSString *)bar {
       if ((self = [super init])) {
-        foo_ = [string copy];
+        bar_ = [bar copy];
-        bar_ = [[NSString alloc] initWithFormat:@"hi %d", 3];
+        bam_ = [[NSString alloc] initWithFormat:@"hi %d", 3];
       }
       return self;
     }
 
     - (void)dealloc {
-      [foo_ release];
       [bar_ release];
+      [bam_ release];
       [super dealloc];
     }
 
-    - (NSString *)foo {
+    - (NSString *)bar {
-      return foo_;
+      return bar_;
     }
 
-    - (void)setFoo:(NSString *)newFoo {
+    - (void)setBar:(NSString *)bar {
-      [foo_ autorelease];
+      [bar_ autorelease];
-      foo_ = [newFoo copy];  
+      bar_ = [bar copy];
     }
 
-    - (BOOL)doWorkWithString:(NSString *)blah {
+    - (BOOL)doWorkWithBlah:(NSString *)blah {
       // ...
       return NO;
     }
@@ -232,7 +233,7 @@ Revision 2.24
   <p>
     Blank lines before and after <code>@interface</code>,
     <code>@implementation</code>, and <code>@end</code> are optional. If your
-    <code>@interface</code> declares instance variables, as most do, any blank
+    <code>@interface</code> declares instance variables, a blank
     line should come after the closing brace (<code>}</code>).
   <p>
   </p>
@@ -260,14 +261,19 @@ Revision 2.24
 
   <STYLEPOINT title="Line Length">
     <SUMMARY>
-      Each line of text in your code should be at most 80 characters long.
+      Each line of text in your code should try to be at most 80 characters
+      long.
     </SUMMARY>
     <BODY>
       <p>
-        Even though Objective-C tends to be a more verbose language than C++,
+        Strive to keep your code within 80 columns. We realize that Objective C
-        to aid in the interoperability with that guide, we have decided
+        is a verbose language and in some cases it may be more readable to
-        to keep the limit at 80 columns as well. It's easier to live with
+        extend slightly beyond 80 columns, but this should definitely be the
-        than you might expect.
+        exception and not commonplace.
+      </p>
+      <p>
+        If a reviewer asks that you reformat a line because they feel it can be
+        fit in 80 columns and still be readable, you should do so.
       </p>
       
       <p>
@@ -435,7 +441,7 @@ Revision 2.24
     <BODY>
       <p>
         This applies to class declarations, instance variables, and method
-        delcarations. For example:
+        declarations. For example:
       </p>
       <CODE_SNIPPET>
         @interface MyProtocoledClass : NSObject&lt;NSWindowDelegate&gt; {
@@ -448,6 +454,92 @@ Revision 2.24
     </BODY>
   </STYLEPOINT>
 
+  <STYLEPOINT title="Blocks">
+    <SUMMARY>
+      Blocks are preferred to the target-selector pattern when creating
+      callbacks, as it makes code easier to read. Code inside blocks should be
+      indented four spaces.
+    </SUMMARY>
+    <BODY>
+      <p>
+        There are several appropriate style rules, depending on how long the
+        block is:
+      </p>
+      <ul>
+        <li>If the block can fit on one line, no wrapping is necessary.</li>
+        <li>
+          If it has to wrap, the closing brace should line up with the first
+          character of the line on which the block is declared.
+        </li>
+        <li>Code within the block should be indented four spaces.</li>
+        <li>
+          If the block is large, e.g. more than 20 lines, it is recommended to
+          move it out-of-line into a local variable.
+        </li>
+        <li>
+          If the block takes no parameters, there are no spaces between the
+          characters <code>^{</code>. If the block takes parameters, there is no
+          space between the <code>^(</code> characters, but there is one space
+          between the <code>) {</code> characters.
+        </li>
+        <li>
+          Two space indents inside blocks are also allowed, but should only
+          be used when it's consistent with the rest of the project's code.
+        </li>
+      </ul>
+      <CODE_SNIPPET>
+        // The entire block fits on one line.
+        [operation setCompletionBlock:^{ [self onOperationDone]; }];
+
+        // The block can be put on a new line, indented four spaces, with the
+        // closing brace aligned with the first character of the line on which
+        // block was declared.
+        [operation setCompletionBlock:^{
+            [self.delegate newDataAvailable];
+        }];
+
+        // Using a block with a C API follows the same alignment and spacing
+        // rules as with Objective-C.
+        dispatch_async(fileIOQueue_, ^{
+            NSString* path = [self sessionFilePath];
+            if (path) {
+              // ...
+            }
+        });
+
+        // An example where the parameter wraps and the block declaration fits
+        // on the same line. Note the spacing of |^(SessionWindow *window) {|
+        // compared to |^{| above.
+        [[SessionService sharedService]
+            loadWindowWithCompletionBlock:^(SessionWindow *window) {
+                if (window) {
+                  [self windowDidLoad:window];
+                } else {
+                  [self errorLoadingWindow];
+                }
+            }];
+
+        // An example where the parameter wraps and the block declaration does
+        // not fit on the same line as the name.
+        [[SessionService sharedService]
+            loadWindowWithCompletionBlock:
+                ^(SessionWindow *window) {
+                    if (window) {
+                      [self windowDidLoad:window];
+                    } else {
+                      [self errorLoadingWindow];
+                    }
+                }];
+
+        // Large blocks can be declared out-of-line.
+        void (^largeBlock)(void) = ^{
+            // ...
+        };
+        [operationQueue_ addOperationWithBlock:largeBlock];
+      </CODE_SNIPPET>
+    </BODY>
+  </STYLEPOINT>
+
 </CATEGORY>
 
 <CATEGORY title="Naming">
@@ -743,8 +835,9 @@ Revision 2.24
 
   <STYLEPOINT title="File Comments">
     <SUMMARY>
-      Start each file with a copyright notice, followed by a
+      Start each file with a basic description of the contents of the file,
-      description of the contents of the file.
+      followed by an author, and then followed by a copyright notice and/or
+      license boilerplate.
     </SUMMARY>
     <BODY>
       <SUBSECTION title="Legal Notice and Author Line">
@@ -753,10 +846,12 @@ Revision 2.24
         <p>
           Every file should contain the following items, in order:
           <ul>
+            <li>a basic description of the contents of the file</li>
+            <li>an author line</li>
             <li>a copyright statement (for example,
                 <code>Copyright 2008 Google Inc.</code>)</li>
-            <li>a license boilerplate.  Choose the appropriate boilerplate
+            <li>license boilerplate if neccessary. Choose the appropriate
-                for the license used by the project (for example,
+                boilerplate for the license used by the project (e.g.
                 Apache 2.0, BSD, LGPL, GPL)</li>
           </ul>
         </p>
@@ -838,42 +933,46 @@ Revision 2.24
     </SUMMARY>
     <BODY>
       <p>
-        Instance variable pointers to objects derived from NSObject are
+        Instance variables which are pointers to objects derived from NSObject
-        presumed to be retained, and should be documented as <b>weak</b> if
+        are presumed to be retained, and should be either commented as weak or
-        they are not retained by the class. However, instance variables which
+        declared with the <b>__weak</b> lifetime qualifier when applicable.
-        are labeled as IBOutlets are presumed to not be retained by the class,
+        Similarly, declared properties must specify a <b>weak</b> or
-        and should be documented as <b>strong</b> if the class does retain
+        <b>assign</b> property attribute if they are not retained by the
-        them.
+        class.  An exception is instance variables labeled as IBOutlets in Mac
+        software, which are presumed to not be retained.
       </p>
       <p>
         Where instance variables are pointers to CoreFoundation, C++, and
-        other non-Objective-C objects, they should always be documented in
+        other non-Objective-C objects, they should always be declared with
-        comments as strong or weak. Be mindful that support for automatic C++
+        the __strong and __weak type modifiers to indicate which pointers are
-        objects encapsulated in Objective-C objects is disabled by default, as
+        and are not retained. CoreFoundation and other non-Objective-C object
-        described <a href="http://chanson.livejournal.com/154253.html">here</a>.
+        pointers require explicit memory management, even when building for
+        automatic reference counting or garbage collection. When the __weak
+        type modifier is not allowed (e.g. C++ member variables when compiled
+        under clang), a comment should be used instead.
       </p>
       <p>
-        Examples of strong and weak documentation:
+        Be mindful that support for automatic C++ objects encapsulated in
+        Objective-C objects is disabled by default, as described <a href="http://chanson.livejournal.com/154253.html">here</a>.
+      </p>
+      <p>
+        Examples of strong and weak declarations:
         <CODE_SNIPPET>
           @interface MyDelegate : NSObject {
            @private
-            IBOutlet NSButton* okButton_;  // normal NSControl
+            IBOutlet NSButton *okButton_;  // normal NSControl; implicitly weak on Mac only
-            IBOutlet NSMenu* myContextMenu_;  // manually-loaded menu (strong)
 
             AnObjcObject* doohickey_;  // my doohickey
-            MyController* controller_;  // so we can send msgs back (weak, owns me)
+            __weak MyObjcParent *parent_;  // so we can send msgs back (owns me)
 
             // non-NSObject pointers...
-            CWackyCPPClass* wacky_;  // some cross-platform object (strong)
+            __strong CWackyCPPClass *wacky_;  // some cross-platform object
-            CFDictionaryRef* dict_;  // (strong)
+            __strong CFDictionaryRef *dict_;
           }
+          @property(strong, nonatomic) NSString *doohickey;
+          @property(weak, nonatomic) NSString *parent;
           @end
         </CODE_SNIPPET>
-        <dl>
-          <dt>strong</dt><dd>The object will be <code>retain</code>'d by this class</dd>
-          <dt>weak</dt><dd>The object will be <b>not</b> be <code>retain</code>'d by this class
-          (e.g. a delegate).</dd>
-        </dl>
       </p>
     </BODY>
   </STYLEPOINT>
@@ -1171,7 +1270,52 @@ Revision 2.24
     </BODY>
   </STYLEPOINT>
 
-  <STYLEPOINT title="dealloc should process instance variables in declaration                      order">
+  <STYLEPOINT title="Avoid Accessors During init and dealloc">
+    <SUMMARY>
+      Instance subclasses may be in an inconsistent state during
+      <code>init</code> and <code>dealloc</code> method execution, so code in
+      those methods should avoid invoking accessors.
+    </SUMMARY>
+    <BODY>
+      <p>
+        Subclasses have not yet been initialized or have already deallocated
+        when <code>init</code> and <code>dealloc</code> methods execute, making
+        accessor methods potentially unreliable. Whenever practical, directly
+        assign to and release ivars in those methods rather than rely on
+        accessors.
+      </p>
+      <CODE_SNIPPET>
+        - (id)init {
+          self = [super init];
+          if (self) {
+            bar_ = [[NSMutableString alloc] init];  // good
+          }
+          return self;
+        }
+
+        - (void)dealloc {
+          [bar_ release];                           // good
+          [super dealloc];
+        }
+      </CODE_SNIPPET>
+      <BAD_CODE_SNIPPET>
+        - (id)init {
+          self = [super init];
+          if (self) {
+            self.bar = [NSMutableString string];  // avoid
+          }
+          return self;
+        }
+
+        - (void)dealloc {
+          self.bar = nil;                         // avoid
+          [super dealloc];
+        }
+      </BAD_CODE_SNIPPET>
+    </BODY>
+  </STYLEPOINT>
+
+  <STYLEPOINT title="Dealloc Instance Variables in Declaration                      Order">
     <SUMMARY>
       <code>dealloc</code> should process instance variables in the same order
       the <code>@interface</code> declares them, so it is easier for a reviewer
@@ -1452,60 +1596,6 @@ Revision 2.24
           <code>retain</code>.
         </p>
       </SUBSECTION>
-      <SUBSECTION title="Never synthesize CFType properties">
-        <p>
-          CFTypes should always have the <code>@dynamic</code> implementation
-          directive.
-        </p>
-        <p>
-          Since CFTypes can't have the <code>retain</code> property
-          attribute, the developer must handle retaining and releasing the
-          value themselves. In the rare case that you do actually want
-          assignment it is better to make that completely clear by actually
-          implementing the setter and getter and commenting why that is the
-          case.
-        </p>
-      </SUBSECTION>
-      <SUBSECTION title="List out all implementation directives">
-        <p>
-          Use implementation directives for all properties even if they are
-          <code>@dynamic</code> by default.
-        </p>
-        <p>
-          Even though <code>@dynamic</code> is default, explicitly list it out
-          with all of the other property implementation directives making it
-          clear how every property in a class is handled at a single glance.
-        </p>
-        <BAD_CODE_SNIPPET>
-          @interface MyClass : NSObject
-          @property(readonly) NSString *name;
-          @end
-
-          @implementation MyClass
-          .
-          .
-          .
-          - (NSString*)name {
-            return @"foo";
-          }
-          @end
-        </BAD_CODE_SNIPPET>
-        <CODE_SNIPPET>
-          @interface MyClass : NSObject
-          @property(readonly) NSString *name;
-          @end
-
-          @implementation MyClass
-          @dynamic name;
-          .
-          .
-          .
-          - (NSString*)name {
-            return @"foo";
-          }
-          @end
-        </CODE_SNIPPET>
-      </SUBSECTION>
       <SUBSECTION title="Atomicity">
         <p>
           Be aware of the overhead of properties. By default, all synthesized
@@ -1533,6 +1623,61 @@ Revision 2.24
       </SUBSECTION>
     </BODY>
   </STYLEPOINT>
+
+  <STYLEPOINT title="Interfaces Without Instance Variables">
+    <SUMMARY>
+      Omit the empty set of braces on interfaces that do not declare any
+      instance variables.
+    </SUMMARY>
+    <BODY>
+      <CODE_SNIPPET>
+        @interface MyClass : NSObject
+        // Does a lot of stuff
+        - (void)fooBarBam;
+        @end
+      </CODE_SNIPPET>
+      <BAD_CODE_SNIPPET>
+        @interface MyClass : NSObject {
+        }
+        // Does a lot of stuff
+        - (void)fooBarBam;
+        @end
+      </BAD_CODE_SNIPPET>
+    </BODY>
+  </STYLEPOINT>
+
+  <STYLEPOINT title="Automatically Synthesized Instance Variables">
+    <SUMMARY>
+      <p>
+        For code that will run on iOS only, use of automatically synthesized
+        instance variables is preferred.
+      </p>
+      <p>
+        When synthesizing the instance variable, use
+        <code>@synthesize var = var_;</code> as this prevents accidentally calling
+        <code>var = blah;</code> when <code>self.var = blah;</code> is intended.
+      </p>
+    </SUMMARY>
+    <BODY>
+      <CODE_SNIPPET>
+        // Header file
+        @interface Foo : NSObject
+        // A guy walks into a bar.
+        @property(nonatomic, copy) NSString *bar;
+        @end
+
+        // Implementation file
+        @interface Foo ()
+        @property(nonatomic, retain) NSArray *baz;
+        @end
+
+        @implementation Foo
+        @synthesize bar = bar_;
+        @synthesize baz = baz_;
+        @end
+      </CODE_SNIPPET>
+    </BODY>
+  </STYLEPOINT>
 </CATEGORY>
 
 
@@ -1601,7 +1746,7 @@ Revision 2.24
 <HR/>
 
 <p align="right">
-Revision 2.24
+Revision 2.36
 </p>
 
 

pyguide.html

@@ -6,28 +6,33 @@
 <LINK HREF="styleguide.css" type="text/css" rel="stylesheet">
 <SCRIPT language="javascript" type="text/javascript">
 
-                function ShowHideByName(bodyName, buttonName) {
+                function GetElementsByName(name) {
-	          var bodyElements;
+                  // Workaround a bug on old versions of opera.
-                  var linkElement;
                   if (document.getElementsByName) {
-                    bodyElements = document.getElementsByName(bodyName);
+                    return document.getElementsByName(name);
-                    linkElement = document.getElementsByName('link-' + buttonName)[0];
                   } else {
-                    bodyElements = [document.getElementById(bodyName)];
+                    return [document.getElementById(name)];
-                    linkElement = document.getElementById('link-' + buttonName);
                   }
+                }
+
+                /**
+                 * @param {string} namePrefix The prefix of the body name.
+                 * @param {function(boolean): boolean} getVisibility Computes the new
+                 *     visibility state, given the current one.
+                 */
+                function ChangeVisibility(namePrefix, getVisibility) {
+                  var bodyName = namePrefix + '__body';
+                  var buttonName = namePrefix + '__button';
+                  var bodyElements = GetElementsByName(bodyName);
+                  var linkElement = GetElementsByName('link-' + buttonName)[0];
                   if (bodyElements.length != 1) {
-                    alert("ShowHideByName() got the wrong number of bodyElements:  " + bodyElements.length);
+                    throw Error('ShowHideByName() got the wrong number of bodyElements:  ' + 
+                        bodyElements.length);
                   } else {
                     var bodyElement = bodyElements[0];
-                    var buttonElement;
+                    var buttonElement = GetElementsByName(buttonName)[0];
-                    if (document.getElementsByName) {
+                    var isVisible = bodyElement.style.display != "none";
-                      var buttonElements = document.getElementsByName(buttonName);
+                    if (getVisibility(isVisible)) {
-                      buttonElement = buttonElements[0];
-                    } else {
-                      buttonElement = document.getElementById(buttonName);
-                    }
-                    if (bodyElement.style.display == "none" || bodyElement.style.display == "") {
                       bodyElement.style.display = "inline";
                       linkElement.style.display = "block";
                       buttonElement.innerHTML = '▽';
@@ -39,14 +44,16 @@
                   }
                 }
 
+                function ShowHideByName(namePrefix) {
+                  ChangeVisibility(namePrefix, function(old) { return !old; });
+                }
+
+                function ShowByName(namePrefix) {
+                  ChangeVisibility(namePrefix, function() { return true; });
+                }
+
                 function ShowHideAll() {
-                  var allButton;
+                  var allButton = GetElementsByName("show_hide_all_button")[0];
-                  if (document.getElementsByName) {
-                    var allButtons = document.getElementsByName("show_hide_all_button");
-	            allButton = allButtons[0];
-                  } else {
-                    allButton = document.getElementById("show_hide_all_button");
-                  }
                   if (allButton.innerHTML == '▽') {
                     allButton.innerHTML = '▶';
                     SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '▶');
@@ -72,27 +79,56 @@
                 }
 
 
+                function EndsWith(str, suffix) {
+                  var l = str.length - suffix.length;
+                  return l >= 0 && str.indexOf(suffix, l) == l;
+                }
+
+                function RefreshVisibilityFromHashParam() {
+                  var hashRegexp = new RegExp('#([^&#]*)$');
+                  var hashMatch = hashRegexp.exec(window.location.href);
+                  var anchor = hashMatch && GetElementsByName(hashMatch[1])[0];
+                  var node = anchor;
+                  var suffix = '__body';
+                  while (node) {
+                    var id = node.id;
+                    var matched = id && EndsWith(id, suffix);
+                    if (matched) {
+                      var len = id.length - suffix.length;
+                      ShowByName(matched.substring(0, len));
+                      if (anchor.scrollIntoView) {
+                        anchor.scrollIntoView();
+                      }
+                      
+                      return;
+                    }
+                    node = node.parentNode;
+                  }
+                }
+
+                window.onhashchange = RefreshVisibilityFromHashParam;
+
                 window.onload = function() {
                   // if the URL contains "?showall=y", expand the details of all children
-                  {
+                  var showHideAllRegex = new RegExp("[\\?&](showall)=([^&#]*)");
-                    var showHideAllRegex = new RegExp("[\\?&](showall)=([^&#]*)");
+                  var showHideAllValue = showHideAllRegex.exec(window.location.href);
-                    var showHideAllValue = showHideAllRegex.exec(window.location.href);
+                  if (showHideAllValue != null) {
-                    if (showHideAllValue != null) {
+                    if (showHideAllValue[2] == "y") {
-                      if (showHideAllValue[2] == "y") {
+                      SetHiddenState(document.getElementsByTagName("body")[0].childNodes, 
-                        SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '▽');
+                          "inline", '▽');
-                      } else {
+                    } else {
-                        SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '▶');
+                      SetHiddenState(document.getElementsByTagName("body")[0].childNodes, 
-                      }
+                          "none", '▶');
                     }
-                    var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)");
-                    var showOneValue = showOneRegex.exec(window.location.href);
-                    if (showOneValue != null) {
-                      var body_name = showOneValue[2] + '__body';
-                      var button_name = showOneValue[2] + '__button';
-                      ShowHideByName(body_name, button_name);
-                    }
-
                   }
+                  var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)");
+                  var showOneValue = showOneRegex.exec(window.location.href);
+                  if (showOneValue) {
+                    ShowHideByName(showOneValue[2]);
+                  }
+
+
+                  RefreshVisibilityFromHashParam();
                 }
               </SCRIPT>
 </HEAD>
@@ -100,7 +136,7 @@
 <H1>Google Python Style Guide</H1>
   <p align="right">
 
-    Revision 2.20
+    Revision 2.28
   </p>
   
   <address>
@@ -144,7 +180,7 @@
 <H3><A name="Displaying_Hidden_Details_in_this_Guide" id="Displaying_Hidden_Details_in_this_Guide">Displaying Hidden Details in this Guide</A></H3>
 <SPAN class="link_button" id="link-Displaying_Hidden_Details_in_this_Guide__button" name="link-Displaying_Hidden_Details_in_this_Guide__button"><A href="?showone=Displaying_Hidden_Details_in_this_Guide#Displaying_Hidden_Details_in_this_Guide">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Displaying_Hidden_Details_in_this_Guide__body','Displaying_Hidden_Details_in_this_Guide__button')" name="Displaying_Hidden_Details_in_this_Guide__button" id="Displaying_Hidden_Details_in_this_Guide__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Displaying_Hidden_Details_in_this_Guide')" name="Displaying_Hidden_Details_in_this_Guide__button" id="Displaying_Hidden_Details_in_this_Guide__button">▶</SPAN>
       <DIV style="display:inline;" class="">
        This style guide contains many details that are initially
        hidden from view.  They are marked by the triangle icon, which you
@@ -183,7 +219,7 @@
 <H3><A name="pychecker" id="pychecker">pychecker</A></H3>
 <SPAN class="link_button" id="link-pychecker__button" name="link-pychecker__button"><A href="?showone=pychecker#pychecker">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('pychecker__body','pychecker__button')" name="pychecker__button" id="pychecker__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('pychecker')" name="pychecker__button" id="pychecker__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Run <code>pychecker</code> over your code.
       </DIV>
@@ -255,7 +291,7 @@
 <H3><A name="Imports" id="Imports">Imports</A></H3>
 <SPAN class="link_button" id="link-Imports__button" name="link-Imports__button"><A href="?showone=Imports#Imports">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports__body','Imports__button')" name="Imports__button" id="Imports__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports')" name="Imports__button" id="Imports__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Use <code>import</code>s for packages and modules only.
       </DIV>
@@ -283,7 +319,7 @@
           prefix.
           <br>
           Use <code>from x import y as z</code> if two modules named
-          <code>z</code> are to be imported or if <code>y</code> is an
+          <code>y</code> are to be imported or if <code>y</code> is an
           inconveniently long name.
         </P>
         For example the module
@@ -305,7 +341,7 @@
 <H3><A name="Packages" id="Packages">Packages</A></H3>
 <SPAN class="link_button" id="link-Packages__button" name="link-Packages__button"><A href="?showone=Packages#Packages">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Packages__body','Packages__button')" name="Packages__button" id="Packages__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Packages')" name="Packages__button" id="Packages__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Import each module using the full pathname location of the module.
       </DIV>
@@ -340,7 +376,7 @@ from sound.effects import echo
 <H3><A name="Exceptions" id="Exceptions">Exceptions</A></H3>
 <SPAN class="link_button" id="link-Exceptions__button" name="link-Exceptions__button"><A href="?showone=Exceptions#Exceptions">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Exceptions__body','Exceptions__button')" name="Exceptions__button" id="Exceptions__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Exceptions')" name="Exceptions__button" id="Exceptions__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Exceptions are allowed but must be used carefully.
       </DIV>
@@ -408,7 +444,7 @@ from sound.effects import echo
 <H3><A name="Global_variables" id="Global_variables">Global variables</A></H3>
 <SPAN class="link_button" id="link-Global_variables__button" name="link-Global_variables__button"><A href="?showone=Global_variables#Global_variables">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Global_variables__body','Global_variables__button')" name="Global_variables__button" id="Global_variables__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Global_variables')" name="Global_variables__button" id="Global_variables__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Avoid global variables.
       </DIV>
@@ -449,7 +485,7 @@ from sound.effects import echo
 <H3><A name="Nested/Local/Inner_Classes_and_Functions" id="Nested/Local/Inner_Classes_and_Functions">Nested/Local/Inner Classes and Functions</A></H3>
 <SPAN class="link_button" id="link-Nested/Local/Inner_Classes_and_Functions__button" name="link-Nested/Local/Inner_Classes_and_Functions__button"><A href="?showone=Nested/Local/Inner_Classes_and_Functions#Nested/Local/Inner_Classes_and_Functions">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Nested/Local/Inner_Classes_and_Functions__body','Nested/Local/Inner_Classes_and_Functions__button')" name="Nested/Local/Inner_Classes_and_Functions__button" id="Nested/Local/Inner_Classes_and_Functions__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Nested/Local/Inner_Classes_and_Functions')" name="Nested/Local/Inner_Classes_and_Functions__button" id="Nested/Local/Inner_Classes_and_Functions__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Nested/local/inner classes and functions are fine.
       </DIV>
@@ -479,7 +515,7 @@ from sound.effects import echo
 <H3><A name="List_Comprehensions" id="List_Comprehensions">List Comprehensions</A></H3>
 <SPAN class="link_button" id="link-List_Comprehensions__button" name="link-List_Comprehensions__button"><A href="?showone=List_Comprehensions#List_Comprehensions">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('List_Comprehensions__body','List_Comprehensions__button')" name="List_Comprehensions__button" id="List_Comprehensions__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('List_Comprehensions')" name="List_Comprehensions__button" id="List_Comprehensions__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Okay to use for simple cases.
       </DIV>
@@ -548,7 +584,7 @@ from sound.effects import echo
 <H3><A name="Default_Iterators_and_Operators" id="Default_Iterators_and_Operators">Default Iterators and Operators</A></H3>
 <SPAN class="link_button" id="link-Default_Iterators_and_Operators__button" name="link-Default_Iterators_and_Operators__button"><A href="?showone=Default_Iterators_and_Operators#Default_Iterators_and_Operators">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Default_Iterators_and_Operators__body','Default_Iterators_and_Operators__button')" name="Default_Iterators_and_Operators__button" id="Default_Iterators_and_Operators__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Default_Iterators_and_Operators')" name="Default_Iterators_and_Operators__button" id="Default_Iterators_and_Operators__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Use default iterators and operators for types that support them, 
         like lists, dictionaries, and files.
@@ -593,7 +629,7 @@ from sound.effects import echo
 <H3><A name="Generators" id="Generators">Generators</A></H3>
 <SPAN class="link_button" id="link-Generators__button" name="link-Generators__button"><A href="?showone=Generators#Generators">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Generators__body','Generators__button')" name="Generators__button" id="Generators__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Generators')" name="Generators__button" id="Generators__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Use generators as needed.
       </DIV>
@@ -626,7 +662,7 @@ from sound.effects import echo
 <H3><A name="Lambda_Functions" id="Lambda_Functions">Lambda Functions</A></H3>
 <SPAN class="link_button" id="link-Lambda_Functions__button" name="link-Lambda_Functions__button"><A href="?showone=Lambda_Functions#Lambda_Functions">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lambda_Functions__body','Lambda_Functions__button')" name="Lambda_Functions__button" id="Lambda_Functions__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lambda_Functions')" name="Lambda_Functions__button" id="Lambda_Functions__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Okay for one-liners.
       </DIV>
@@ -666,7 +702,7 @@ from sound.effects import echo
 <H3><A name="Default_Argument_Values" id="Default_Argument_Values">Default Argument Values</A></H3>
 <SPAN class="link_button" id="link-Default_Argument_Values__button" name="link-Default_Argument_Values__button"><A href="?showone=Default_Argument_Values#Default_Argument_Values">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Default_Argument_Values__body','Default_Argument_Values__button')" name="Default_Argument_Values__button" id="Default_Argument_Values__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Default_Argument_Values')" name="Default_Argument_Values__button" id="Default_Argument_Values__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Okay in most cases.
       </DIV>
@@ -727,7 +763,7 @@ from sound.effects import echo
 <H3><A name="Properties" id="Properties">Properties</A></H3>
 <SPAN class="link_button" id="link-Properties__button" name="link-Properties__button"><A href="?showone=Properties#Properties">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Properties__body','Properties__button')" name="Properties__button" id="Properties__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Properties')" name="Properties__button" id="Properties__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Use properties for accessing or setting data where you would 
         normally have used simple, lightweight accessor or setter methods. 
@@ -823,7 +859,7 @@ from sound.effects import echo
 <H3><A name="True/False_evaluations" id="True/False_evaluations">True/False evaluations</A></H3>
 <SPAN class="link_button" id="link-True/False_evaluations__button" name="link-True/False_evaluations__button"><A href="?showone=True/False_evaluations#True/False_evaluations">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('True/False_evaluations__body','True/False_evaluations__button')" name="True/False_evaluations__button" id="True/False_evaluations__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('True/False_evaluations')" name="True/False_evaluations__button" id="True/False_evaluations__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Use the "implicit" false if at all possible.
       </DIV>
@@ -908,7 +944,7 @@ from sound.effects import echo
 <H3><A name="Deprecated_Language_Features" id="Deprecated_Language_Features">Deprecated Language Features</A></H3>
 <SPAN class="link_button" id="link-Deprecated_Language_Features__button" name="link-Deprecated_Language_Features__button"><A href="?showone=Deprecated_Language_Features#Deprecated_Language_Features">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Deprecated_Language_Features__body','Deprecated_Language_Features__button')" name="Deprecated_Language_Features__button" id="Deprecated_Language_Features__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Deprecated_Language_Features')" name="Deprecated_Language_Features__button" id="Deprecated_Language_Features__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Use string methods instead of the <code>string</code> module
         where possible.  Use function call syntax instead
@@ -944,7 +980,7 @@ from sound.effects import echo
 <H3><A name="Lexical_Scoping" id="Lexical_Scoping">Lexical Scoping</A></H3>
 <SPAN class="link_button" id="link-Lexical_Scoping__button" name="link-Lexical_Scoping__button"><A href="?showone=Lexical_Scoping#Lexical_Scoping">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lexical_Scoping__body','Lexical_Scoping__button')" name="Lexical_Scoping__button" id="Lexical_Scoping__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lexical_Scoping')" name="Lexical_Scoping__button" id="Lexical_Scoping__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Okay to use.
       </DIV>
@@ -1010,7 +1046,7 @@ from sound.effects import echo
 <H3><A name="Function_and_Method_Decorators" id="Function_and_Method_Decorators">Function and Method Decorators</A></H3>
 <SPAN class="link_button" id="link-Function_and_Method_Decorators__button" name="link-Function_and_Method_Decorators__button"><A href="?showone=Function_and_Method_Decorators#Function_and_Method_Decorators">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Function_and_Method_Decorators__body','Function_and_Method_Decorators__button')" name="Function_and_Method_Decorators__button" id="Function_and_Method_Decorators__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Function_and_Method_Decorators')" name="Function_and_Method_Decorators__button" id="Function_and_Method_Decorators__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Use decorators judiciously when there is a clear advantage.
       </DIV>
@@ -1080,7 +1116,7 @@ from sound.effects import echo
 <H3><A name="Threading" id="Threading">Threading</A></H3>
 <SPAN class="link_button" id="link-Threading__button" name="link-Threading__button"><A href="?showone=Threading#Threading">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Threading__body','Threading__button')" name="Threading__button" id="Threading__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Threading')" name="Threading__button" id="Threading__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Do not rely on the atomicity of built-in types.
       </DIV>
@@ -1110,7 +1146,7 @@ from sound.effects import echo
 <H3><A name="Power_Features" id="Power_Features">Power Features</A></H3>
 <SPAN class="link_button" id="link-Power_Features__button" name="link-Power_Features__button"><A href="?showone=Power_Features#Power_Features">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Power_Features__body','Power_Features__button')" name="Power_Features__button" id="Power_Features__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Power_Features')" name="Power_Features__button" id="Power_Features__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Avoid these features.
       </DIV>
@@ -1148,7 +1184,7 @@ from sound.effects import echo
 <H3><A name="Semicolons" id="Semicolons">Semicolons</A></H3>
 <SPAN class="link_button" id="link-Semicolons__button" name="link-Semicolons__button"><A href="?showone=Semicolons#Semicolons">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Semicolons__body','Semicolons__button')" name="Semicolons__button" id="Semicolons__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Semicolons')" name="Semicolons__button" id="Semicolons__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Do not terminate your lines with semi-colons and do not use
         semi-colons to put two commands on the same line.
@@ -1160,7 +1196,7 @@ from sound.effects import echo
 <H3><A name="Line_length" id="Line_length">Line length</A></H3>
 <SPAN class="link_button" id="link-Line_length__button" name="link-Line_length__button"><A href="?showone=Line_length#Line_length">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Line_length__body','Line_length__button')" name="Line_length__button" id="Line_length__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Line_length')" name="Line_length__button" id="Line_length__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Maximum line length is <em>80 characters</em>.
       </DIV>
@@ -1171,6 +1207,10 @@ from sound.effects import echo
       earlier.
     </p>
 
+    <p>
+      Do not use backslash line continuation.
+    </p>
+
     <p>
       Make use of Python's
       
@@ -1209,7 +1249,7 @@ from sound.effects import echo
 <H3><A name="Parentheses" id="Parentheses">Parentheses</A></H3>
 <SPAN class="link_button" id="link-Parentheses__button" name="link-Parentheses__button"><A href="?showone=Parentheses#Parentheses">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Parentheses__body','Parentheses__button')" name="Parentheses__button" id="Parentheses__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Parentheses')" name="Parentheses__button" id="Parentheses__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Use parentheses sparingly.
       </DIV>
@@ -1241,7 +1281,7 @@ from sound.effects import echo
 <H3><A name="Indentation" id="Indentation">Indentation</A></H3>
 <SPAN class="link_button" id="link-Indentation__button" name="link-Indentation__button"><A href="?showone=Indentation#Indentation">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Indentation__body','Indentation__button')" name="Indentation__button" id="Indentation__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Indentation')" name="Indentation__button" id="Indentation__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Indent your code blocks with <em>4 spaces</em>.
       </DIV>
@@ -1278,7 +1318,7 @@ from sound.effects import echo
 <H3><A name="Blank_Lines" id="Blank_Lines">Blank Lines</A></H3>
 <SPAN class="link_button" id="link-Blank_Lines__button" name="link-Blank_Lines__button"><A href="?showone=Blank_Lines#Blank_Lines">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Blank_Lines__body','Blank_Lines__button')" name="Blank_Lines__button" id="Blank_Lines__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Blank_Lines')" name="Blank_Lines__button" id="Blank_Lines__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Two blank lines between top-level definitions, one blank line 
         between method definitions.
@@ -1297,7 +1337,7 @@ from sound.effects import echo
 <H3><A name="Whitespace" id="Whitespace">Whitespace</A></H3>
 <SPAN class="link_button" id="link-Whitespace__button" name="link-Whitespace__button"><A href="?showone=Whitespace#Whitespace">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Whitespace__body','Whitespace__button')" name="Whitespace__button" id="Whitespace__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Whitespace')" name="Whitespace__button" id="Whitespace__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Follow standard typographic rules for the use of spaces around 
         punctuation.
@@ -1376,24 +1416,18 @@ from sound.effects import echo
 <H3><A name="Shebang_Line" id="Shebang_Line">Shebang Line</A></H3>
 <SPAN class="link_button" id="link-Shebang_Line__button" name="link-Shebang_Line__button"><A href="?showone=Shebang_Line#Shebang_Line">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Shebang_Line__body','Shebang_Line__button')" name="Shebang_Line__button" id="Shebang_Line__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Shebang_Line')" name="Shebang_Line__button" id="Shebang_Line__button">▶</SPAN>
       <DIV style="display:inline;" class="">
-        All <code>.py</code> files (except <code>__init__.py</code> package
+        Most <code>.py</code> files do not need to start with a
-        files) should begin with a
+        <code>#!</code> line.  Start the main file of a  binary with
-        
+        <code>#!/usr/bin/python</code>.
-        <code>#!/usr/bin/python&lt;version&gt;</code>
-        shebang line.
       </DIV>
       <DIV class=""><DIV class="stylepoint_body" name="Shebang_Line__body" id="Shebang_Line__body" style="display: none">
         
         <p>
-          Always use the most specific version that you can to ensure
+          This line is used by the kernel to find the Python interpreter, but is
-          compatibility. For examples, if your program uses a language feature
+          ignored by Python when importing modules.  It is only necessary on a
-          that that first appeared in Python 2.4, use
+          file that will be executed directly.
-          <code>/usr/bin/python2.4</code> (or something newer) instead of
-          <code>/usr/bin/python2</code>. Otherwise, your program might not
-          behave the way you expect it to, because the interpreter uses an
-          older version of the language.
         </p>
       </DIV></DIV>
     </DIV>
@@ -1402,7 +1436,7 @@ from sound.effects import echo
 <H3><A name="Comments" id="Comments">Comments</A></H3>
 <SPAN class="link_button" id="link-Comments__button" name="link-Comments__button"><A href="?showone=Comments#Comments">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Comments__body','Comments__button')" name="Comments__button" id="Comments__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Comments')" name="Comments__button" id="Comments__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Be sure to use the right style for module, function, method and in-line
         comments.
@@ -1450,24 +1484,66 @@ from sound.effects import echo
 <SPAN class="stylepoint_subsection">Functions and Methods</SPAN>
 
     <p>
-      Any function or method which is not both obvious and very short
+      As used in this section "function" applies to methods, function, and
-      needs a doc string. Additionally, any externally accessible
+      generators.
-      function or method regardless of length or simplicity needs a
-      doc string. The doc string should include what the function does
-      and have detailed descriptions of the input and output.  It
-      should not, generally, describe how it does it unless it's some
-      complicated algorithm.  For tricky code block/inline comments
-      within the code are more appropriate.  The doc string should give
-      enough information to write a call to the function without
-      looking at a single line of the function's code. Args should be
-      individually documented, an explanation following after a colon,
-      and should use a uniform hanging indent of 2 or 4 spaces. The
-      doc string should specify the expected types where specific types
-      are required. A "Raises:" section should list all exceptions
-      that can be raised by the function. The doc string for generator
-      functions should use "Yields:" rather than "Returns:".
     </p>
 
+    <p>
+      A function must have a docstring, unless it meets all of the following
+      criteria:
+      <ul>
+        <li>not externally visible</li>
+        <li>very short</li>
+        <li>obvious</li>
+      </ul>
+    </p>
+
+    <p>
+      A docstring should give enough information to write a call to the function
+      without reading the function's code.  A docstring should describe the
+      function's calling syntax and its semantics, not its implementation.  For
+      tricky code, comments alongside the code are more appropriate than using
+      docstrings.
+    </p>
+
+    <p>
+      Certain aspects of a function should be documented in special sections,
+      listed below. Each section begins with a heading line, which ends with a
+      colon. Sections should be indented two spaces, except for the heading.
+    </p>
+
+    <dl>
+      <dt>Args:</dt>
+      <dd>
+        List each parameter by name. A description should follow the name, and
+        be separated by a colon and a space. If the description is too long to
+        fit on a single 80-character line, use a hanging indent of 2 or 4 spaces
+        (be consistent with the rest of the file).
+
+        <p>
+          The description should mention required type(s) and the meaning of
+          the argument.
+        </p>
+
+        <p>
+          If a function accepts *foo (variable length argument lists) and/or
+          **bar (arbitrary keyword arguments), they should be listed as *foo and
+          **bar.
+        </p>
+      </dd>
+
+      <dt>Returns: (or Yields: for generators)</dt>
+      <dd>
+        Describe the type and semantics of the return value. If the function
+        only returns None, this section is not required.
+      </dd>
+
+      <dt>Raises:</dt>
+      <dd>
+        List all exceptions that are relevant to the interface.
+      </dd>
+    </dl>
+
     <DIV class=""><PRE>
 <span class="external"></span>def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
   <span class="external">  </span>"""Fetches rows from a Bigtable.
@@ -1581,7 +1657,7 @@ from sound.effects import echo
 <H3><A name="Classes" id="Classes">Classes</A></H3>
 <SPAN class="link_button" id="link-Classes__button" name="link-Classes__button"><A href="?showone=Classes#Classes">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Classes__body','Classes__button')" name="Classes__button" id="Classes__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Classes')" name="Classes__button" id="Classes__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         If a class inherits from no other base classes, explicitly inherit
     from <code>object</code>.  This also applies to nested classes.
@@ -1627,7 +1703,7 @@ from sound.effects import echo
 <H3><A name="Strings" id="Strings">Strings</A></H3>
 <SPAN class="link_button" id="link-Strings__button" name="link-Strings__button"><A href="?showone=Strings#Strings">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Strings__body','Strings__button')" name="Strings__button" id="Strings__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Strings')" name="Strings__button" id="Strings__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Use the <code>%</code> operator for formatting strings,
         even when the parameters are all strings.  Use your best judgement
@@ -1681,40 +1757,47 @@ Don'<span class="external"></span>t do this.
 <H3><A name="TODO_Comments" id="TODO_Comments">TODO Comments</A></H3>
 <SPAN class="link_button" id="link-TODO_Comments__button" name="link-TODO_Comments__button"><A href="?showone=TODO_Comments#TODO_Comments">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('TODO_Comments__body','TODO_Comments__button')" name="TODO_Comments__button" id="TODO_Comments__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('TODO_Comments')" name="TODO_Comments__button" id="TODO_Comments__button">▶</SPAN>
-    <DIV style="display:inline;" class="">
+      <DIV style="display:inline;" class="">
-      Use <code>TODO</code> comments for code that is temporary, a
+        Use <code>TODO</code> comments for code that is temporary, a
-      short-term solution, or good-enough but not perfect.
+        short-term solution, or good-enough but not perfect.
+      </DIV>
+      <DIV class=""><DIV class="stylepoint_body" name="TODO_Comments__body" id="TODO_Comments__body" style="display: none">
+        <p>
+          <code>TODO</code>s should include the string <code>TODO</code> in
+          all caps, followed by the
+          
+          name, e-mail address, or other
+          identifier
+          of the person who can best provide context about the problem
+          referenced by the <code>TODO</code>,
+          in parentheses.  A colon is optional.  A comment explaining what there
+          is to do is required. The main purpose is to have
+          a consistent <code>TODO</code> format that can be searched to find the
+          person who can provide more details upon request.  A
+          <code>TODO</code> is not a commitment that the person referenced
+          will fix the problem.  Thus when you create a <code>TODO</code>, it is
+          almost always your
+          
+          name
+          that is given.
+        </p>
+        
+        <DIV class=""><PRE># TODO(kl@gmail.com): Use a "*" here for string repetition.
+# TODO(Zeke) Change this to use relations.</PRE></DIV>
+        <p>
+          If your <code>TODO</code> is of the form "At a future date do
+          something" make sure that you either include a very specific
+          date ("Fix by November 2009") or a very specific event
+          ("Remove this code when all clients can handle XML responses.").
+        </p>
+      </DIV></DIV>
     </DIV>
-    <DIV class=""><DIV class="stylepoint_body" name="TODO_Comments__body" id="TODO_Comments__body" style="display: none">
-      <p>
-        <code>TODO</code>s should include the string <code>TODO</code> in
-        all caps, followed by your
-        
-        name, e-mail address, or other
-        identifier
-        in parentheses.  A colon is optional. A comment explaining what there
-        is to do is required. The main purpose is to have
-        a consistent <code>TODO</code> format searchable by the person
-        adding the comment (who can provide more details upon request).  A
-        <code>TODO</code> is not a commitment to provide the fix yourself.
-      </p>
-      
-      <DIV class=""><PRE># TODO(kl@gmail.com): Drop the use of "has_key".
-# TODO(Zeke) change this to use relations.</PRE></DIV>
-      <p>
-        If your <code>TODO</code> is of the form "At a future date do
-        something" make sure that you either include a very specific
-        date ("Fix by November 2009") or a very specific event
-        ("Remove this code when all clients can handle XML responses.").
-      </p>
-    </DIV></DIV>
-  </DIV>
     <DIV class="">
 <H3><A name="Imports_formatting" id="Imports_formatting">Imports formatting</A></H3>
 <SPAN class="link_button" id="link-Imports_formatting__button" name="link-Imports_formatting__button"><A href="?showone=Imports_formatting#Imports_formatting">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports_formatting__body','Imports_formatting__button')" name="Imports_formatting__button" id="Imports_formatting__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports_formatting')" name="Imports_formatting__button" id="Imports_formatting__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Imports should be on separate lines.
       </DIV>
@@ -1757,7 +1840,7 @@ Don'<span class="external"></span>t do this.
 <H3><A name="Statements" id="Statements">Statements</A></H3>
 <SPAN class="link_button" id="link-Statements__button" name="link-Statements__button"><A href="?showone=Statements#Statements">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Statements__body','Statements__button')" name="Statements__button" id="Statements__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Statements')" name="Statements__button" id="Statements__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Generally only one statement per line.
       </DIV>
@@ -1794,7 +1877,7 @@ Don'<span class="external"></span>t do this.
 <H3><A name="Access_Control" id="Access_Control">Access Control</A></H3>
 <SPAN class="link_button" id="link-Access_Control__button" name="link-Access_Control__button"><A href="?showone=Access_Control#Access_Control">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Access_Control__body','Access_Control__button')" name="Access_Control__button" id="Access_Control__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Access_Control')" name="Access_Control__button" id="Access_Control__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         If an accessor function would be trivial you should use public variables
         instead of accessor functions to avoid the extra cost of function 
@@ -1817,11 +1900,13 @@ Don'<span class="external"></span>t do this.
 <H3><A name="Naming" id="Naming">Naming</A></H3>
 <SPAN class="link_button" id="link-Naming__button" name="link-Naming__button"><A href="?showone=Naming#Naming">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Naming__body','Naming__button')" name="Naming__button" id="Naming__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Naming')" name="Naming__button" id="Naming__button">▶</SPAN>
       <DIV style="display:inline;" class="">
-        <code>module_name, package_name, ClassName, method_name, ExceptionName, 
+        <code>module_name, package_name, ClassName,
-        function_name, GLOBAL_VAR_NAME, instance_var_name, 
+        method_name, ExceptionName,
-        function_parameter_name, local_var_name.</code>
+        function_name, GLOBAL_CONSTANT_NAME,
+        global_var_name, instance_var_name, function_parameter_name,
+        local_var_name.</code>
       </DIV>
       <DIV class=""><DIV class="stylepoint_body" name="Naming__body" id="Naming__body" style="display: none">
     <P class="">
@@ -1958,7 +2043,7 @@ Don'<span class="external"></span>t do this.
 <H3><A name="Main" id="Main">Main</A></H3>
 <SPAN class="link_button" id="link-Main__button" name="link-Main__button"><A href="?showone=Main#Main">
           link
-        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Main__body','Main__button')" name="Main__button" id="Main__button">▶</SPAN>
+        </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Main')" name="Main__button" id="Main__button">▶</SPAN>
       <DIV style="display:inline;" class="">
         Even a file meant to be used as a script should be importable and a 
         mere import should not have the side effect of executing the script's 
@@ -2027,7 +2112,7 @@ Don'<span class="external"></span>t do this.
 
 
 <p align="right">
-Revision 2.20
+Revision 2.28
 </p>
 
 

styleguide.xsl

@@ -30,28 +30,33 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
 
               <SCRIPT language="javascript" type="text/javascript">
 
-                function ShowHideByName(bodyName, buttonName) {
+                function GetElementsByName(name) {
-	          var bodyElements;
+                  // Workaround a bug on old versions of opera.
-                  var linkElement;
                   if (document.getElementsByName) {
-                    bodyElements = document.getElementsByName(bodyName);
+                    return document.getElementsByName(name);
-                    linkElement = document.getElementsByName('link-' + buttonName)[0];
                   } else {
-                    bodyElements = [document.getElementById(bodyName)];
+                    return [document.getElementById(name)];
-                    linkElement = document.getElementById('link-' + buttonName);
                   }
+                }
+
+                /**
+                 * @param {string} namePrefix The prefix of the body name.
+                 * @param {function(boolean): boolean} getVisibility Computes the new
+                 *     visibility state, given the current one.
+                 */
+                function ChangeVisibility(namePrefix, getVisibility) {
+                  var bodyName = namePrefix + '<xsl:value-of select="$body_suffix"/>';
+                  var buttonName = namePrefix + '<xsl:value-of select="$button_suffix"/>';
+                  var bodyElements = GetElementsByName(bodyName);
+                  var linkElement = GetElementsByName('link-' + buttonName)[0];
                   if (bodyElements.length != 1) {
-                    alert("ShowHideByName() got the wrong number of bodyElements:  " + bodyElements.length);
+                    throw Error('ShowHideByName() got the wrong number of bodyElements:  ' + 
+                        bodyElements.length);
                   } else {
                     var bodyElement = bodyElements[0];
-                    var buttonElement;
+                    var buttonElement = GetElementsByName(buttonName)[0];
-                    if (document.getElementsByName) {
+                    var isVisible = bodyElement.style.display != "none";
-                      var buttonElements = document.getElementsByName(buttonName);
+                    if (getVisibility(isVisible)) {
-                      buttonElement = buttonElements[0];
-                    } else {
-                      buttonElement = document.getElementById(buttonName);
-                    }
-                    if (bodyElement.style.display == "none" || bodyElement.style.display == "") {
                       bodyElement.style.display = "inline";
                       linkElement.style.display = "block";
                       buttonElement.innerHTML = '<xsl:value-of select="$hide_button_text"/>';
@@ -63,14 +68,16 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
                   }
                 }
 
+                function ShowHideByName(namePrefix) {
+                  ChangeVisibility(namePrefix, function(old) { return !old; });
+                }
+
+                function ShowByName(namePrefix) {
+                  ChangeVisibility(namePrefix, function() { return true; });
+                }
+
                 function ShowHideAll() {
-                  var allButton;
+                  var allButton = GetElementsByName("show_hide_all_button")[0];
-                  if (document.getElementsByName) {
-                    var allButtons = document.getElementsByName("show_hide_all_button");
-	            allButton = allButtons[0];
-                  } else {
-                    allButton = document.getElementById("show_hide_all_button");
-                  }
                   if (allButton.innerHTML == '<xsl:value-of select="$hide_button_text"/>') {
                     allButton.innerHTML = '<xsl:value-of select="$show_button_text"/>';
                     SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '<xsl:value-of select="$show_button_text"/>');
@@ -96,27 +103,56 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
                 }
 
 
+                function EndsWith(str, suffix) {
+                  var l = str.length - suffix.length;
+                  return l >= 0 &amp;&amp; str.indexOf(suffix, l) == l;
+                }
+
+                function RefreshVisibilityFromHashParam() {
+                  var hashRegexp = new RegExp('#([^&amp;#]*)$');
+                  var hashMatch = hashRegexp.exec(window.location.href);
+                  var anchor = hashMatch &amp;&amp; GetElementsByName(hashMatch[1])[0];
+                  var node = anchor;
+                  var suffix = '<xsl:value-of select="$body_suffix"/>';
+                  while (node) {
+                    var id = node.id;
+                    var matched = id &amp;&amp; EndsWith(id, suffix);
+                    if (matched) {
+                      var len = id.length - suffix.length;
+                      ShowByName(matched.substring(0, len));
+                      if (anchor.scrollIntoView) {
+                        anchor.scrollIntoView();
+                      }
+                      
+                      return;
+                    }
+                    node = node.parentNode;
+                  }
+                }
+
+                window.onhashchange = RefreshVisibilityFromHashParam;
+
                 window.onload = function() {
                   // if the URL contains "?showall=y", expand the details of all children
-                  {
+                  var showHideAllRegex = new RegExp("[\\?&amp;](showall)=([^&amp;#]*)");
-                    var showHideAllRegex = new RegExp("[\\?&amp;](showall)=([^&amp;#]*)");
+                  var showHideAllValue = showHideAllRegex.exec(window.location.href);
-                    var showHideAllValue = showHideAllRegex.exec(window.location.href);
+                  if (showHideAllValue != null) {
-                    if (showHideAllValue != null) {
+                    if (showHideAllValue[2] == "y") {
-                      if (showHideAllValue[2] == "y") {
+                      SetHiddenState(document.getElementsByTagName("body")[0].childNodes, 
-                        SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '<xsl:value-of select="$hide_button_text"/>');
+                          "inline", '<xsl:value-of select="$hide_button_text"/>');
-                      } else {
+                    } else {
-                        SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '<xsl:value-of select="$show_button_text"/>');
+                      SetHiddenState(document.getElementsByTagName("body")[0].childNodes, 
-                      }
+                          "none", '<xsl:value-of select="$show_button_text"/>');
                     }
-                    var showOneRegex = new RegExp("[\\?&amp;](showone)=([^&amp;#]*)");
-                    var showOneValue = showOneRegex.exec(window.location.href);
-                    if (showOneValue != null) {
-                      var body_name = showOneValue[2] + '<xsl:value-of select="$body_suffix"/>';
-                      var button_name = showOneValue[2] + '<xsl:value-of select="$button_suffix"/>';
-                      ShowHideByName(body_name, button_name);
-                    }
-
                   }
+                  var showOneRegex = new RegExp("[\\?&amp;](showone)=([^&amp;#]*)");
+                  var showOneValue = showOneRegex.exec(window.location.href);
+                  if (showOneValue) {
+                    ShowHideByName(showOneValue[2]);
+                  }
+
+
+                  RefreshVisibilityFromHashParam();
                 }
               </SCRIPT>
           </HEAD>
@@ -214,9 +250,7 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
       </xsl:variable>
       <xsl:variable name="onclick_definition">
         <xsl:text>javascript:ShowHideByName('</xsl:text>
-        <xsl:value-of select="$stylepoint_name"/><xsl:value-of select="$body_suffix"/>
+        <xsl:value-of select="$stylepoint_name"/>
-        <xsl:text>','</xsl:text>
-        <xsl:value-of select="$buttonName"/>
         <xsl:text>')</xsl:text>
       </xsl:variable>
       <SPAN class="link_button" id="link-{$buttonName}" name="link-{$buttonName}">