1. Introduction and Motivation
  EDITHIST  is  an  extension  to  interlisp's  file  package  that permanently
preserves the history of new versions of files.

  EDITHIST should be regarded as an extension to  the  existing  mechanism  for
recording a "who-edited-last" comment within the body of each function.

  Every  time a file is remade, a new entry is made in the edit history for the
file, a list containing the following information:
        ( DATE  AUTHOR FILE (CHANGES) ( COMMENTS ) )
where:

DATE            is the result of (DATE)

AUTHOR          is (OR INITIALS USERID)

FILE            is the full file name of the output

CHANGES         is the same list of  changed  items  as  is  on  the  filedates
                property.

COMMENTS        is acquired (optionally) by ASKUSER during the makefile

2. How to use it
  Include (LOAD '<DDYER>EDITHIST.COM 'SYSLOAD) in your INIT.LISP

  The default settings of the control parameters for EDITHIST will:

   - Ask  you  to  type  comments  each  time  a changed file is made with
     MAKEFILE

   - Automatically "capture" files  that  do  not  already  have  an  edit
     history

   - Maintain an edit history no more that 30 entries long.

  You  may  or  may  not  wish to change the default setting of two parameters:
ASKEDITHIST to control the use of ASKUSER, and  LIMITEDITHIST  to  control  the
pruning of the edit histories.

3. ASKUSER
  Normally,  ASKUSER  is  invoked each time the file is made and invites you to
type some descriptive comments about the edit you just made.

  Controls on ASKUSER are implemented  by  the  value  of  ASKEDITHIST  and  by
several options understood by MAKEFILE.

Permanant settings, controlled by the value of ASKEDITHIST

                NIL             don't ask, don't extend the edithistory

                NOCOMMENT       don't  ask,  extend  the  edithistory  with  no
                                comments list

                COMMENT         ask for comments, extend edithistory

                T               add EDITHISTORY to files that  don't  have  it,
                                ask  for  comments and extend the edit history.
                                This is implemented by adding (INITEDITHIST) to
                                MAKEFILEFORMS.  This is the default setting.

Temporary overrides, specified by OPTIONS to MAKEFILE.  This is the second  arg
                to MAKEFILE or the first argument to MAKEFILES.

                ASK or COMMENT  temporarily  resets  ASKEDITHIST  to  T, so you
                                will be asked for comments this one time only.

                NOASK or NOCOMMENT
                                temporarily resets ASKEDITHIST to NOCOMMENT, so
                                you will not be asked  for  comments  this  one
                                time only.

  when ASKUSER prompts you with:
        comments:
you  get  to  type  one  LINE  of  forms.  so either type your comments with no
carriage returns, or enclose them in parentheses.

4. Pruning
  EDITHIST entries do not accumulate without bound.  When a threshold number of
entries have been made (see LIMITEDITHIST below) a pruning process  is  invoked
that  tries to reduce the size of the list while preserving as much information
as possible.  The approximate pruning algorithm is:

   1. Preserve the first N entries

   2. Among the rest, merge entries that have no comments  and  that  have
      the same author

   3. If  still  above threshold, merge any entries that have no comments,
      ignoring authors.

   4. If still above threshold, merge all the oldest entries to get  below
      threshold.

  The entries pruned by this procedure are merged with the adjacent entries, in
which  case the FILE AUTHOR and DATE properties become a cons cell specifying a
range, the CHANGES list becomes the union of all changes, and the COMMENTS list
becomes the concatenation of all comments.

  Whenever the edit history is pruned, a message  is  printed  giving  the  new
length.  Once phase 4 pruning is in effect, the history will be shortened every
time the file is made.

  At  some  point, you will undoubtably want to manually edit the edit history,
to remove inconsequential entries.  See EDITDEF above.

  Controls on pruning of the edit history  are  implemented  by  LIMITEDITHIST,
which should be (CONS #softlimit #hardlimit).  The default value is ( 10 . 30 )
which  will keep the 10 most recent entries inviolable, and will invoke pruning
when the list grows to 30 entries.

5. Internals
  The basic entries for each edit history list are kept in an  ALIST  keyed  by
the  name  of the edit history: eg. the name of the file.  Each edit history is
ordered chronologically, oldest first.  The root of the alist is EDITHISTALIST,
but to  examine/modify  edit  histories,  use  (EDITDEF  'NAME  'EDITHIST)  and
(SHOWDEF 'NAME 'EDITHIST), where NAME defaults to the NAME.EXT of the file.

  The  edit  histories  are  declared  DONTCOPY, so will not appear in compiled
files.  The history will be recovered from the original source file  if  it  is
remade  without  being fully loaded, as would occur if you edited a function in
the compiled file causing its EXPR definition to  be  loaded  from  the  source
file.

  If  a  single  (EDITHIST  --) command on the file coms contains more than one
edithistory, all but the first are considered dormant, and not added  to.    at
MAKEFILE  time.   This provides a means of archiving the edit history of a file
that has been created by merging several other files.

6. A Sample Edit History
(EDIT.LISP
         (" 8-Jul-80 18:34:41"
            DD: <DDYER>EDITHIST.LISP.26
            (EDITHISTCOMS EDITHIST.LISP))
          (" 8-Jul-80 21:16:01"
            DD: <DDYER>EDITHIST.LISP.27
            (MAKEDITHIST)
            (added output file to the history list entry))
          (" 8-Jul-80 21:25:48"
            DD: <DDYER>EDITHIST.LISP.28
            (EDITHIST.LISP)
            (cleaned up edit history list))))

                               Table of Contents
1. Introduction and Motivation                                                0
2. How to use it                                                              0
3. ASKUSER                                                                    0
4. Pruning                                                                    0
5. Internals                                                                  0
6. A Sample Edit History                                                      0