Patchwork [v3] restore C++STYLE formatting

login
register
mail settings
Submitter Jonathan Wakely
Date June 11, 2010, 4:05 p.m.
Message ID <AANLkTikwZNAjrzJ71E4L_GYwfAvYDACcc3KweKyKwxtc@mail.gmail.com>
Download mbox | patch
Permalink /patch/55342/
State New
Headers show

Comments

Jonathan Wakely - June 11, 2010, 4:05 p.m.
the C++STYLE guide got mangled on conversion to docbook, this restores
the indentation so it's actually useful again. I also fixed a few
errors and added some markup.  I might convert the whole
<literallayout> block to proper <para>s some time, but not today.

2010-06-11  Jonathan Wakely  <jwakely.gcc@gmail.com>

	* doc/xml/manual/appendix_contributing.xml: Indent code examples
	to match original C++STYLE document. Fix typos and syntax errors.
	Add some basic docbook markup.
	* doc/html/*: Regenerate.

tested with 'make doc-html' on Fedora and checked in to trunk.

Patch

Index: doc/xml/manual/appendix_contributing.xml
===================================================================
--- doc/xml/manual/appendix_contributing.xml	(revision 160611)
+++ doc/xml/manual/appendix_contributing.xml	(working copy)
@@ -52,7 +52,7 @@ 
 	  organization is ANSI and their web-site is right
 	  <ulink url="http://www.ansi.org">here.</ulink>
 	  (And if you've already registered with them, clicking this link will take you to directly to the place where you can
-	  <ulink url="http://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC+14882:2003">buy the standard on-line.)</ulink>
+	  <ulink url="http://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC+14882:2003">buy the standard on-line</ulink>.)
 	</para>
       </listitem>
 
@@ -509,7 +509,7 @@  indicate a place that may require attent
       __embedded_cplusplus
       // long double conversion members mangled as __opr
       // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html
-      _opr
+      __opr
     </literallayout>
   </sect2>
 
@@ -520,52 +520,60 @@  indicate a place that may require attent
       it is intended to precede the recommendations of the GNU Coding
       Standard, which can be referenced in full here:
 
-      http://www.gnu.org/prep/standards/standards.html#Formatting
+      <ulink url="http://www.gnu.org/prep/standards/standards.html#Formatting">http://www.gnu.org/prep/standards/standards.html#Formatting</ulink>
 
       The rest of this is also interesting reading, but skip the "Design
       Advice" part.
 
       The GCC coding conventions are here, and are also useful:
-      http://gcc.gnu.org/codingconventions.html
+      <ulink url="http://gcc.gnu.org/codingconventions.html">http://gcc.gnu.org/codingconventions.html</ulink>
 
       In addition, because it doesn't seem to be stated explicitly anywhere
       else, there is an 80 column source limit.
 
-      ChangeLog entries for member functions should use the
+      <filename>ChangeLog</filename> entries for member functions should use the
       classname::member function name syntax as follows:
 
-      1999-04-15  Dennis Ritchie  &lt;dr@att.com&gt;
+<code>
+1999-04-15  Dennis Ritchie  &lt;dr@att.com&gt;
 
       * src/basic_file.cc (__basic_file::open): Fix thinko in
       _G_HAVE_IO_FILE_OPEN bits.
+</code>
 
       Notable areas of divergence from what may be previous local practice
       (particularly for GNU C) include:
 
       01. Pointers and references
-      char* p = "flop";
-      char&amp; c = *p;
-      -NOT-
-      char *p = "flop";  // wrong
-      char &amp;c = *p;      // wrong
+      <code>
+        char* p = "flop";
+        char&amp; c = *p;
+          -NOT-
+        char *p = "flop";  // wrong
+        char &amp;c = *p;      // wrong
+      </code>
 
       Reason: In C++, definitions are mixed with executable code. Here,
-      p is being initialized, not *p. This is near-universal
+      <code>p</code> is being initialized, not <code>*p</code>.  This is near-universal
       practice among C++ programmers; it is normal for C hackers
       to switch spontaneously as they gain experience.
 
       02. Operator names and parentheses
-      operator==(type)
-      -NOT-
-      operator == (type)  // wrong
+      <code>
+        operator==(type)
+          -NOT-
+        operator == (type)  // wrong
+      </code>
 
-      Reason: The == is part of the function name. Separating
+      Reason: The <code>==</code> is part of the function name. Separating
       it makes the declaration look like an expression.
 
       03. Function names and parentheses
-      void mangle()
-      -NOT-
-      void mangle ()  // wrong
+      <code>
+        void mangle()
+          -NOT-
+        void mangle ()  // wrong
+      </code>
 
       Reason: no space before parentheses (except after a control-flow
       keyword) is near-universal practice for C++. It identifies the
@@ -573,86 +581,98 @@  indicate a place that may require attent
       opposed to an expression or other overloaded use of parentheses.
 
       04. Template function indentation
-      template&lt;typename T&gt;
-      void
-      template_function(args)
-      { }
-      -NOT-
-      template&lt;class T&gt;
-      void template_function(args) {};
+      <code>
+        template&lt;typename T&gt;
+          void
+          template_function(args)
+          { }
+          -NOT-
+        template&lt;class T&gt;
+        void template_function(args) {};
+      </code>
 
       Reason: In class definitions, without indentation whitespace is
       needed both above and below the declaration to distinguish
       it visually from other members. (Also, re: "typename"
-      rather than "class".)  T often could be int, which is
+      rather than "class".)  <code>T</code> often could be <code>int</code>, which is
       not a class. ("class", here, is an anachronism.)
 
       05. Template class indentation
-      template&lt;typename _CharT, typename _Traits&gt;
-      class basic_ios : public ios_base
-      {
-      public:
-      // Types:
-      };
-      -NOT-
-      template&lt;class _CharT, class _Traits&gt;
-      class basic_ios : public ios_base
-      {
-      public:
-      // Types:
-      };
-      -NOT-
-      template&lt;class _CharT, class _Traits&gt;
-      class basic_ios : public ios_base
-      {
-      public:
-      // Types:
-      };
+      <code>
+        template&lt;typename _CharT, typename _Traits&gt;
+          class basic_ios : public ios_base
+          {
+          public:
+            // Types:
+          };
+          -NOT-
+        template&lt;class _CharT, class _Traits&gt;
+        class basic_ios : public ios_base
+          {
+          public:
+            // Types:
+          };
+          -NOT-
+        template&lt;class _CharT, class _Traits&gt;
+          class basic_ios : public ios_base
+        {
+          public:
+            // Types:
+        };
+      </code>
 
       06. Enumerators
-      enum
-      {
-      space = _ISspace,
-      print = _ISprint,
-      cntrl = _IScntrl
-      };
-      -NOT-
-      enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
+      <code>
+        enum
+        {
+          space = _ISspace,
+          print = _ISprint,
+          cntrl = _IScntrl
+        };
+          -NOT-
+        enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
+      </code>
 
       07. Member initialization lists
       All one line, separate from class name.
 
-      gribble::gribble()
-      : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
-      { }
-      -NOT-
-      gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
-      { }
+      <code>
+        gribble::gribble()
+        : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
+        { }
+          -NOT-
+        gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
+        { }
+      </code>
 
       08. Try/Catch blocks
-      try
-      {
-      //
-      }
-      catch (...)
-      {
-      //
-      }
-      -NOT-
-      try {
-      //
-      } catch(...) {
-      //
-      }
+      <code>
+        try
+          {
+            //
+          }
+        catch (...)
+          {
+            //
+          }
+          -NOT-
+        try {
+          //
+        } catch(...) {
+          //
+        }
+      </code>
 
       09. Member functions declarations and definitions
       Keywords such as extern, static, export, explicit, inline, etc
       go on the line above the function name. Thus
 
+      <code>
       virtual int
       foo()
       -NOT-
       virtual int foo()
+      </code>
 
       Reason: GNU coding conventions dictate return types for functions
       are on a separate line than the function name and parameter list
@@ -663,42 +683,49 @@  indicate a place that may require attent
 
 
       10. Invocation of member functions with "this-&gt;"
-      For non-uglified names, use this-&gt;name to call the function.
+      For non-uglified names, use <code>this-&gt;name</code> to call the function.
 
+      <code>
       this-&gt;sync()
       -NOT-
       sync()
+      </code>
 
       Reason: Koenig lookup.
 
       11. Namespaces
+      <code>
       namespace std
       {
-      blah blah blah;
+        blah blah blah;
       } // namespace std
 
       -NOT-
 
       namespace std {
-      blah blah blah;
+        blah blah blah;
       } // namespace std
+      </code>
 
       12. Spacing under protected and private in class declarations:
       space above, none below
       i.e.
 
+      <code>
       public:
-      int foo;
+        int foo;
 
       -NOT-
       public:
 
-      int foo;
+        int foo;
+      </code>
 
       13. Spacing WRT return statements.
       no extra spacing before returns, no parenthesis
       i.e.
 
+      <code>
       }
       return __ret;
 
@@ -711,21 +738,22 @@  indicate a place that may require attent
 
       }
       return (__ret);
+      </code>
 
 
       14. Location of global variables.
       All global variables of class type, whether in the "user visible"
-      space (e.g., cin) or the implementation namespace, must be defined
+      space (e.g., <code>cin</code>) or the implementation namespace, must be defined
       as a character array with the appropriate alignment and then later
       re-initialized to the correct value.
 
       This is due to startup issues on certain platforms, such as AIX.
-      For more explanation and examples, see src/globals.cc. All such
+      For more explanation and examples, see <filename>src/globals.cc</filename>. All such
       variables should be contained in that file, for simplicity.
 
       15. Exception abstractions
-      Use the exception abstractions found in functexcept.h, which allow
-      C++ programmers to use this library with -fno-exceptions. (Even if
+      Use the exception abstractions found in <filename class="headerfile">functexcept.h</filename>, which allow
+      C++ programmers to use this library with <literal>-fno-exceptions</literal>.  (Even if
       that is rarely advisable, it's a necessary evil for backwards
       compatibility.)
 
@@ -733,9 +761,11 @@  indicate a place that may require attent
       All start with the name of the function where the exception is
       thrown, and then (optional) descriptive text is added. Example:
 
+      <code>
       __throw_logic_error(__N("basic_string::_S_construct NULL not valid"));
+      </code>
 
-      Reason: The verbose terminate handler prints out exception::what(),
+      Reason: The verbose terminate handler prints out <code>exception::what()</code>,
       as well as the typeinfo for the thrown exception. As this is the
       default terminate handler, by putting location info into the
       exception string, a very useful error message is printed out for
@@ -755,21 +785,21 @@  indicate a place that may require attent
       to use names that begin with underscores. This is called "uglification".
       The convention is:
 
-      Local and argument names:  __[a-z].*
+      Local and argument names:  <literal>__[a-z].*</literal>
 
-      Examples:  __count  __ix  __s1
+      Examples:  <code>__count  __ix  __s1</code>
 
-      Type names and template formal-argument names: _[A-Z][^_].*
+      Type names and template formal-argument names: <literal>_[A-Z][^_].*</literal>
 
-      Examples:  _Helper  _CharT  _N
+      Examples:  <code>_Helper  _CharT  _N</code>
 
-      Member data and function names: _M_.*
+      Member data and function names: <literal>_M_.*</literal>
 
-      Examples:  _M_num_elements  _M_initialize ()
+      Examples:  <code>_M_num_elements  _M_initialize ()</code>
 
-      Static data members, constants, and enumerations: _S_.*
+      Static data members, constants, and enumerations: <literal>_S_.*</literal>
 
-      Examples: _S_max_elements  _S_default_value
+      Examples: <code>_S_max_elements  _S_default_value</code>
 
       Don't use names in the same scope that differ only in the prefix,
       e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names.
@@ -781,87 +811,88 @@  indicate a place that may require attent
       --------------------------
 
       [BY EXAMPLE]
+      <code>
 
       #ifndef  _HEADER_
       #define  _HEADER_ 1
 
       namespace std
       {
-      class gribble
-      {
-      public:
-      gribble() throw();
+        class gribble
+        {
+        public:
+          gribble() throw();
 
-      gribble(const gribble&amp;);
+          gribble(const gribble&amp;);
 
-      explicit
-      gribble(int __howmany);
+          explicit
+          gribble(int __howmany);
 
-      gribble&amp;
-      operator=(const gribble&amp;);
+          gribble&amp;
+          operator=(const gribble&amp;);
 
-      virtual
-      ~gribble() throw ();
+          virtual
+          ~gribble() throw ();
 
-      // Start with a capital letter, end with a period.
-      inline void
-      public_member(const char* __arg) const;
+          // Start with a capital letter, end with a period.
+          inline void
+          public_member(const char* __arg) const;
 
-      // In-class function definitions should be restricted to one-liners.
-      int
-      one_line() { return 0 }
+          // In-class function definitions should be restricted to one-liners.
+          int
+          one_line() { return 0 }
 
-      int
-      two_lines(const char* arg)
-      { return strchr(arg, 'a'); }
+          int
+          two_lines(const char* arg)
+          { return strchr(arg, 'a'); }
 
-      inline int
-      three_lines();  // inline, but defined below.
+          inline int
+          three_lines();  // inline, but defined below.
 
-      // Note indentation.
-      template&lt;typename _Formal_argument&gt;
-      void
-      public_template() const throw();
+          // Note indentation.
+          template&lt;typename _Formal_argument&gt;
+            void
+            public_template() const throw();
 
-      template&lt;typename _Iterator&gt;
-      void
-      other_template();
+          template&lt;typename _Iterator&gt;
+            void
+            other_template();
 
-      private:
-      class _Helper;
+        private:
+          class _Helper;
 
-      int _M_private_data;
-      int _M_more_stuff;
-      _Helper* _M_helper;
-      int _M_private_function();
+          int _M_private_data;
+          int _M_more_stuff;
+          _Helper* _M_helper;
+          int _M_private_function();
 
-      enum _Enum
-      {
-      _S_one,
-      _S_two
-      };
-
-      static void
-      _S_initialize_library();
-      };
+          enum _Enum
+            {
+              _S_one,
+              _S_two
+            };
 
-      // More-or-less-standard language features described by lack, not presence.
+          static void
+          _S_initialize_library();
+        };
+
+        // More-or-less-standard language features described by lack, not presence.
       # ifndef _G_NO_LONGLONG
-      extern long long _G_global_with_a_good_long_name;  // avoid globals!
+        extern long long _G_global_with_a_good_long_name;  // avoid globals!
       # endif
 
-      // Avoid in-class inline definitions, define separately;
-      // likewise for member class definitions:
-      inline int
-      gribble::public_member() const
-      { int __local = 0; return __local; }
-
-      class gribble::_Helper
-      {
-      int _M_stuff;
+        // Avoid in-class inline definitions, define separately;
+        // likewise for member class definitions:
+        inline int
+        gribble::public_member() const
+        { int __local = 0; return __local; }
+
+        class gribble::_Helper
+        {
+          int _M_stuff;
 
-      friend class gribble;
-      };
+          friend class gribble;
+        };
       }
 
       // Names beginning with "__": only for arguments and
@@ -873,41 +904,42 @@  indicate a place that may require attent
 
       namespace std
       {
-      template&lt;typename T&gt;  // notice: "typename", not "class", no space
-      long_return_value_type&lt;with_many, args&gt;
-      function_name(char* pointer,               // "char *pointer" is wrong.
-      char* argument,
-      const Reference&amp; ref)
-      {
-      // int a_local;  /* wrong; see below. */
-      if (test)
-      {
-      nested code
-      }
-
-      int a_local = 0;  // declare variable at first use.
-
-      //  char a, b, *p;   /* wrong */
-      char a = 'a';
-      char b = a + 1;
-      char* c = "abc";  // each variable goes on its own line, always.
-
-      // except maybe here...
-      for (unsigned i = 0, mask = 1; mask; ++i, mask &lt;&lt;= 1) {
-      // ...
-      }
-      }
-
-      gribble::gribble()
-      : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
-      { }
-
-      inline int
-      gribble::three_lines()
-      {
-      // doesn't fit in one line.
-      }
+        template&lt;typename T&gt;  // notice: "typename", not "class", no space
+          long_return_value_type&lt;with_many, args&gt;
+          function_name(char* pointer,               // "char *pointer" is wrong.
+                        char* argument,
+                        const Reference&amp; ref)
+          {
+            // int a_local;  /* wrong; see below. */
+            if (test)
+            {
+              nested code
+            }
+
+            int a_local = 0;  // declare variable at first use.
+
+            //  char a, b, *p;   /* wrong */
+            char a = 'a';
+            char b = a + 1;
+            char* c = "abc";  // each variable goes on its own line, always.
+
+            // except maybe here...
+            for (unsigned i = 0, mask = 1; mask; ++i, mask &lt;&lt;= 1) {
+              // ...
+            }
+          }
+
+        gribble::gribble()
+        : _M_private_data(0), _M_more_stuff(0), _M_helper(0)
+        { }
+
+        int
+        gribble::three_lines()
+        {
+          // doesn't fit in one line.
+        }
       } // namespace std
+      </code>
     </literallayout>
   </sect2>
 </sect1>