Add table of contents.

Add new section: CVS Tagging Conventions.
Add copyright.
Add link to swig-dev mailing list.


git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@992 626c5289-ae23-0410-ae9c-e8d60b6d4f22

SWIG/Doc/engineering.html

@@ -20,7 +20,24 @@ beazley@cs.uchicago.edu <br>
 <p>
 (Note : This is a work in progress.) 
 
+<h2>Table of Contents</h2>
+<ul>
+<li><a name="i1" href="#1">1. Introduction</a>
+<li><a name="i2" href="#2">2. Programming Languages and Libraries</a>
+<li><a name="i3" href="#3">3. The Source Directory and Module Names</a>
+<li><a name="i4" href="#4">4. Include Files</a>
+<li><a name="i5" href="#5">5. File Structure</a>
+<li><a name="i6" href="#6">6. Bottom-Up Design</a>
+<li><a name="i7" href="#7">7. Functions</a>
+<li><a name="i8" href="#8">8. Naming Conventions</a>
+<li><a name="i9" href="#9">9. Visibility</a>
+<li><a name="i10" href="#10">10. Miscellaneous Coding Guidelines</a>
+<li><a name="i11" href="#11">11. CVS Tagging Conventions</a>
+</ul>
+
+<a name="1" href="#i1">
 <h2>1. Introduction</h2>
+</a>
 
 The purpose of this document is to describe various coding conventions
 and organizational aspects for SWIG developers. The idea for this
@@ -58,7 +75,9 @@ should be developed within the SWIG project.  These rules are
 primarily drawn from my own experience developing software and
 observing the practices of other successful projects.
 
+<a name="2" href="#i2">
 <h2>2. Programming Languages and Libraries </h2>
+</a>
 
 All SWIG modules must be written in either ANSI C or one of the
 scripting languages for which SWIG can generate an interface (e.g.,
@@ -81,7 +100,9 @@ should always be included inside a conditional compilation block so
 that it can be omitted on problematic platforms.  If you are unsure
 about a library call, check the man page or contact Dave.
 
+<a name="3" href="#i3">
 <h2>3. The Source Directory and Module Names</h2>
+</a>
 
 All SWIG modules are contained within the "Source" directory.  Within
 this directory, each module is placed into its own subdirectory.  The
@@ -100,7 +121,9 @@ sure the first letter is capitalized.  Also, module names should not
 start with numbers, include underscores or any other special
 non-alphanumeric characters.
 
-<h2>4. Include files </h2>
+<a name="4" href="#i4">
+<h2>4. Include Files </h2>
+</a>
 
 All modules should include a header file that defines the public interface. 
 The name of this header file should be of the form "swigmodule.h" where
@@ -150,7 +173,9 @@ extern "C" {
 <p>
 To minimize compilation time, please include as few other header files as possible.
 
+<a name="5" href="#i5">
 <h2>5. File Structure </h2>
+</a>
 
 Each file in a module should be given a filename that is all lowercase letters
 such as "parser.c", not "Parser.c" or "PARSER.c".   Please note that filenames
@@ -210,7 +235,9 @@ multiple files.  Similarly, you should avoid the temptation to create
 many small files as this increases compilation time and makes the
 directory structure too complicated.
 
+<a name="6" href="#i6">
 <h2>6. Bottom-Up Design </h2>
+</a>
 
 Within each source file, the preferred organization is to use what is
 known as "bottom-up" design.  Under this scheme, lower-level functions
@@ -248,7 +275,9 @@ benefits particular to C. In particular, a bottom-up design generally
 eliminates the need to include forward references--resulting in
 cleaner code and fewer compilation errors.
 
+<a name="7" href="#i7">
 <h2>7. Functions</h2>
+</a>
 
 All functions should have a function header that gives the function name
 and a short description like this:
@@ -279,7 +308,9 @@ Function declarations should <b>NOT</b> use the pre-ANSI function
 declaration syntax.   The ANSI standard has been around long enough for 
 this to be a non-issue.
 
+<a name="8" href="#i8">
 <h2>8. Naming Conventions</h2>
+</a>
 
 The following conventions are used to name various objects throughout SWIG.
 
@@ -362,7 +393,9 @@ typedef struct SwigScanner {
 Static declarations are free to use any naming convention that is appropriate. However, most
 existing parts of SWIG use lower-case names and follow the same convention as described for functions.
 
+<a name="9" href="#i9">
 <h2>9. Visibility</h2>
+</a>
 
 Modules should keep the following rules in mind when exposing their internals:
 
@@ -403,12 +436,50 @@ making your changes.
 
 </ul>
 
-<h2>10. Miscellaneous </h2>
+<a name="10" href="#i10">
+<h2>10. Miscellaneous Coding Guidelines</h2>
+</a>
 
 <ul>
 <li> Do not use the ternary ?: operator.  It is unnecessarily error prone,
 hard for people to read, and hard to maintain code that uses it.
+[I don't agree w/ this guideline.  ?: operator can be abused
+just like everything else, but it can also be used cleanly.  In some styles of
+programming, it is the best tool for the job.  --ttn]
 </ul>
 
+<a name="11" href="#i11">
+<h2>11. CVS Tagging Conventions</h2>
+</a>
+
+Use <tt>cvs tag</tt> to declare some set of file revisions as related in some
+symbolic way.  This eases reference, retrieval and manipulation of these files
+later.  At the moment (2001/01/16 14:02:53), the conventions are very simple;
+let's hope they stay that way!
+
+<p>
+There are two types of tags, internal (aka personal) and external.
+Internal tags are used by SWIG developers primarily, whereas external
+tags are used when communicating with people w/ anonymous cvs access.
+<ul>
+<li> Internal tags should start with the developer name and a hyphen.
+<li> External tags should start with "v-".
+</ul>
+
+That's all there is to it.  Some example tags:
+
+<ul>
+<li> ttn-pre-xml-patch
+<li> ttn-post-xml-patch
+<li> ttn-going-on-vacation-so-dutifully-tagging-now
+<li> v-1-3-a37-fixes-bug-2432
+<li> v-1-3-a37-fixes-bug-2433
+<li> v-1-3-a37-fixes-bug-2432-again
+<li> v-1-3-a37-release
+</ul>
+
+<hr>
+Copyright (C) 1999-2001
+<a href="mailto:swig-dev@cs.uchicago.edu">SWIG Development Team</a>
 </body>
 </html>