24 Jul 2004  Dick.Dunbar@Siebel.com

We've made a significant committment to Jam at Siebel, and ready to give back to the community of users.

Benefits:
 - Jam is simple ... deceptively simple.
 - Out of the box, it supports the platforms we are interested in

Distractions:
- Jam is under-documented.
  The design and goals are clear enough, but the real impediment to using Jam
  is the lack of adequate examples and "best practices" guidelines.
  We intend to start the dialog to correct this deficiency.

- The industry has moved on ... threading, dynamic load libraries,
  new compilers, and standards, all contribute to the need to do a facelift on Jam.

- Regular syntax and conventions
  One of the inhibitors to learning how to effectively use Jam are the
  use of typography and language.  The Jam implementation allows one to
  develop your own Build language;  nouns, verbs, adjectives, adverbs ...
  the actual words are important to form a proper mental model.

---------- Change Principles --------
1) We've made very few changes to the jam code itself;
   Jambase has been completely reconstructed.  
   a) Most of the rules/actions are retained, but rearranged.
   b) Capitalization rules are regularized, to aid in reading Jambase
      ALLCAPS are variables
      InitialCaps are rules or actions
      lowercase are built in Jam commands

2) The documentation is arranged by complexity.
   a) Jamfile:  for development engineers.
      It describes "what" is to be built.  Should be 1-3 pages long.
   b) Jamrules: is a bit more complicated, for analysts or
      OS platform specialists.  It describes "how" the code is built.
   c) Jambase: is for the Jam engineer, who must know everything about
      all platforms, and be ready to provide transparent support for
      the goals listed above.

--------- Change Log -------
24 Jul 2004: Initial contribution to Perforce Depot
 - Ok, so I have to do a "p4 edit" to keep changing this file.

 1) Makefile:  A user should be able to build Jam on any platform
    directly from the distribution, without having to modify Makefile.
    Our Makefile targets 4 platforms we care about:
    Windows:  nmake win
    AIX:      make aix -- Visual Age C++ 6.0.0.7
    HPUX:     make hp 
    Solaris:  make sol

2) Jam.html, Jamfile.html, Jambase.html
   All updated to reflect our changes, primarily to Capitalization

3) Jambase
   Complete reorganized, but there are very few substantive changes.
   JambaseXref.html  An annotated Jambase with cross references for
   easy viewing of Jambase.
   Jambase.rex ... The html xref program.  To be rewritten in Python.

4) Test
   Directory of Jam examples.

5) make1.c
   globs.cmdout needs a newline to separate commands in the  "-o" file.

6) jam.h
   Increase command line length for modern windows systems.

7) Jamfile, used to build Jam.  Two Rule changes:
   LinkLibraries -> Libs
   Library       -> Archive

8) Jam.html, Jamfile.html, Jambase.html ... all edited and changed to our 
   Capitalization conventions for VARIABLES, Rules, built-ins.
 
   These early papers on Jam were rewritten so as to use the conventions
   and Rule names in our implementation.  The material is still useful,
   but confusing when it does not use the current Jambase conventions.

   jam.paper.html  1994, Chrisopher Seiwald
   SybaseJam.html 1997, Laura Wingerd "Constructing a Large Project"
   jam-example.html  Robert Cowham
   GettingStarted.html 2001 Tutorial, Laura Wingerd
   mfc_app.html  2004 Roger Lipscombe

   The jamming mailbox was downloaded, and manually edited to remove
   duplication and reduce the size of the material.

   jamming.mbox

   JambaseXref.html.  Experimental: Represents an earlier version.
   This will be updated as we progress.