Add a few more details in the source-code-formatting documentation.

This isn't exhaustive but it covers some of the more common layout
mistakes I've seen in submitted patches.

diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml
index 78d60bb5ae408ea843a3966fdba462b7fe7d0cb6..e78e59ad9000b72a4c74d145ff98e2febdca0c72 100644 (file)
--- a/doc/src/sgml/sources.sgml
+++ b/doc/src/sgml/sources.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   PostgreSQL Coding Conventions
@@ -7,24 +7,56 @@
    Formatting
 
    
-    Source code formatting uses 4 column tab spacing, with 
-    tabs preserved (i.e. tabs are not expanded to spaces).
+    Source code formatting uses 4 column tab spacing, with
+    tabs preserved (i.e., tabs are not expanded to spaces).
     Each logical indentation level is one additional tab stop.
-    Layout rules (brace positioning, etc) follow BSD conventions.
+   
+
+   
+    Layout rules (brace positioning, etc) follow BSD conventions.  In
+    particular, curly braces for the controlled blocks of if,
+    while, switch, etc go on their own lines.
+   
+
+   
+    Do not use C++ style comments (// comments).  Strict ANSI C
+    compilers do not accept them.  For the same reason, do not use C++
+    extensions such as declaring new variables mid-block.
+   
+
+   
+    The preferred style for multi-line comment blocks is
+
+/*
+ * comment text begins here
+ * and continues here
+ */
+
+    Note that comment blocks that begin in column 1 will be preserved as-is
+    by pgindent, but it will re-flow indented comment blocks
+    as though they were plain text.  If you want to preserve the line breaks
+    in an indented block, add dashes like this:
+
+    /*----------
+     * comment text begins here
+     * and continues here
+     *----------
+     */
+
    
 
    
     While submitted patches do not absolutely have to follow these formatting
     rules, it's a good idea to do so.  Your code will get run through
-    pgindent, so there's no point in making it look nice
-    under some other set of formatting conventions.
+    pgindent before the next release, so there's no point in
+    making it look nice under some other set of formatting conventions.
    
 
    
-    The src/tools directory contains sample settings 
-    files that can be used with the emacs, 
-    xemacs or vim 
-    editors to help ensure that they format code according to these 
+    The src/tools directory contains sample settings
+    files that can be used with the emacs,
+    xemacs or vim
+    editors to help ensure that they format code according to these
     conventions.