Re: PATCH to document init_xxx and other function naming conventions

["Joseph S. Myers" <jsm at polyomino dot org dot uk>]

On Wed, 6 Aug 2003, Per Bothner wrote:

> I made the patch to gccint.texi rather than to
> http://gcc.gnu.org/codingconventions.html.
> I think the content of the latter should be merged
> into gccint.texi, and the web page just be a link to
> a chapter in the manual.

Why?  The logic behind what goes in the manual versus on the webpages is
that something goes on the webpages if branching for releases wouldn't be
appropriate, for which this is a borderline case (in general we don't
_want_ to have different conventions on different branches).  
codingconventions.html is distinguished from contribute.html by describing
what are meant to be invariants of the source tree as opposed to the pure
procedures in contribute.html, but it is still fairly close to being
procedural documentation.  And the internals manual seems an odd place for
documenting e.g. spelling conventions used on the web pages; at present it
documents the _technical_ interfaces in the source tree rather than
stylistic conventions.  (And the tutorial guide to Texinfo style - which
this patch doesn't follow - would seem out of place in the internals
manual, where it can be assumed that people will read external
documentation referred to as necessary.)

The documentation of upstream packages in codingconventions.html is
somewhat hybrid: it describes invariants (that particular files correspond
to those from other sources) but also the procedures associated with those
files.

-- 
Joseph S. Myers
jsm@polyomino.org.uk