STYLE: Make this document cover multiple languages.

Add a language-neutral section to the top, and demote all of the Lisp
stuff by a level.

diff --git a/STYLE b/STYLE
index a6a4f5c..49ad150 100644 (file)
--- a/STYLE
+++ b/STYLE
@@ -1,6 +1,35 @@
-Notes on Lisp style
+Notes on coding style
 
-* Language subset and extensions
+* General
+
+** Layout
+
+Lines are 77 characters at most, except for strange special effects.
+Don't ask.  This is not negotiable, though.  Don't try to tell me that
+your monitor is very wide so you can read longer lines.  My monitor is
+likely at least as wide.  On the other hand, most lines are easily short
+enough to fit in my narrow columns, so the right hand side of a wide
+window would be mostly blank.  This seems wasteful to me, when I could
+fill that space with more code.
+
+Horizontal whitespace for layout purposes -- i.e., indentation and
+alignment, rather than just separating words -- consists of as many tabs
+as possible, followed by as many spaces as necessary to reach the target
+column.  Tab stops occur at every eight columns.  You can tell this
+because when you cat a file to your terminal, that's how the tabs
+appear.  Editors which disagree about this are simply wrong.
+
+My indentation quantum is usually two columns.  It seems that some
+modern editors are deeply confused, and think that tab width and
+indentation quantum are the same thing, but they aren't.  Such broken
+editors will make a hopeless mess of my code.  If you have the
+misfortune to use such an editor, maybe you could contribute patches to
+fix it.
+
+
+* Lisp style
+
+** Language subset and extensions
 
 None of ANSI Common Lisp is off-limits.
 
@@ -53,8 +82,7 @@ suite, which makes additional use of ~xlunit~.  Running the test suite
 isn't essential to getting the translator built, so this isn't as much
 of a problem.
 
-
-* Layout
+** Layout
 
 I pretty much let Emacs indent my code for me, based on information
 collected by SLIME.  Some exceptions:
@@ -90,28 +118,6 @@ collected by SLIME.  Some exceptions:
     mandatory positional arguments that I had to split them.  So far,
     this situation hasn't come up.
 
-Lines are 77 characters at most, except for strange special effects.
-Don't ask.  This is not negotiable, though.  Don't try to tell me that
-your monitor is very wide so you can read longer lines.  My monitor is
-likely at least as wide.  On the other hand, most lines are easily short
-enough to fit in my narrow columns, so the right hand side of a wide
-window would be mostly blank.  This seems wasteful to me, when I could
-fill that space with more code.
-
-Horizontal whitespace for layout purposes -- i.e., indentation and
-alignment, rather than just separating words -- consists of as many tabs
-as possible, followed by as many spaces as necessary to reach the target
-column.  Tab stops occur at every eight columns.  You can tell this
-because when you cat a file to your terminal, that's how the tabs
-appear.  Editors which disagree about this are simply wrong.
-
-My indentation quantum is usually two columns.  It seems that some
-modern editors are deeply confused, and think that tab width and
-indentation quantum are the same thing, but they aren't.  Such broken
-editors will make a hopeless mess of my code.  If you have the
-misfortune to use such an editor, maybe you could contribute patches to
-fix it.
-
 Lisp code does have a tendency to march across to the right quite
 rapidly given a chance.  I have a number of strategies for dealing with
 this.
@@ -126,8 +132,7 @@ this.
   + Shrug my shoulders and let code dribble down the right hand side for
     a bit.
 
-
-* Packages and exporting
+** Packages and exporting
 
 A package collects symbols which are given meanings in one or more
 source files.  If a package's code is all in one file, then the package
@@ -159,8 +164,7 @@ See ~doc/list-symbols.lisp~ for more sophisticated reporting.  (In
 particular, this identifies what kind of thing(s) each external symbol
 names.)
 
-
-* Comments and file structuring
+** Comments and file structuring
 
 A file starts with a big ~;;;~ comment bearing the Emacs ~-*-lisp-*-~
 marker, a quick description, and copyright and licensing boilerplate.  I
@@ -212,8 +216,7 @@ Files end, as a result of long tradition, with a comment
 
 : ;;;----- That's all, folks --------------------------------------------------
 
-
-* Macro style
+** Macro style
 
 I don't mind complicated macros if they're doing something worthwhile.
 They need to have good documentation strings, though.
@@ -226,8 +229,7 @@ It's extremely bad taste for a macro to evaluate its evaluable
 parameters in any order other than strictly left to right, or to
 evaluate them more than once.
 
-
-* Data structures
+** Data structures
 
 I've tended to be happy with plain lists for homogeneous-ish
 collections.  Strongly heterogeneous collections (other than input
@@ -283,8 +285,7 @@ making a new structure type.  I tend to tidy up a few rough edges.
     to roll up your sleeves and mess with ~&aux~ parameters to pull it
     off.
 
-
-* Naming
+** Naming
 
 I'm a traditionalist in some ways, and one of the reasons I like Lisp is
 the richness of its history and tradition.
@@ -306,8 +307,7 @@ with the same intention, and the bindings are then explicitly ignored
 with a declaration.  The names begin ~hunoz~, ~hukairz~, and (I think)
 ~huaskt~.
 
-
-* Declarations
+** Declarations
 
 The code is light on declarations, other than ~ignore~ and similar used
 to muffle warnings.  The macros try to do sensible things with