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