
    Documentation on the planned mode setup conflict checker.
    =========================================================

  1. Survey.

 The principal checker tools shall be an internal list of 'clashes',
i.e., pairs of mode settings that are incompatible (to-day), and
the procedure FINDMODECLASHES, which takes two setup lists L1 and L2
as arguments, and returns a list of the clashes between them. If the
two arguments to FINDMODECLASHES are identical, as tested by
(EQ L1 L2), then clashes within this argument are sought, 'the simple
tests': each clash (<mode1> . <mode2>) is tested once. Else, 'the
double tests' are performed: We test both if L1 contains <mode1> and
L2 contains <mode2>, AND if L2 contains <mode1> and L1 contains <mode2>.

 The clash list should not be accessed directly (by non-developers).
I'll provide a procedure GETMODECLASHLIST for the inquisitive, but
no setting procedure. (Internally, right now it is the value of the
global variable !*!#ClashList!&, with or without case conversion. I
do not think this should be documented in the manual.)

 CHECKSETUP will automatically call FINDMODECLASHES or an equivalent
procedure, which means that mostly there is no need for the user to
employ FINDMODECLASHES directly.


 2. The type definition for clashes, and the interpretation.

 We follow the conventions in types.txt.

 modename ::= <id>		[i.e., a lisp identifier; see below]
 modetest ::= <any>		[i.e., a lisp s-expression; see below]
 modesettingtype ::= <lmodename><modetest>
 modeclash ::= dpmodesettingtype

 Semantics: A modename is an identifier, used as a designator of a
(main or minor) mode in the compact mode handler. To-day (1 Noveber
2003), the main or major mode designators are the following:
OBJECTTYPE, RESOLUTIONTYPE, VARIABLESETUP, STRATEGY, COEFFICIENTDOMAIN,
INPUTFORMAT, OUTPUTFORMAT, ANICK, VARIOUSFLAGS.
Each of these 'first level mode names' has zero or more permissible
subordinate minor mode designators; e.g., to-day VARIABLESETUP has
the following ones:
RINGTYPE. COMMUTATIVEORDER, NONCOMMUTATIVEORDER, VARIABLENUMBER,
INVARIABLES, OUTVARIABLES, VARIABLEWEIGHTS.
In principal, these 'second level mode names' could have subordinate
'third level mode names', et cetera, as long as we have a clear tree
structure; but this is not used now.

 You may find most of the possible types by performing
  (PRINTSETUP)
at the bergman command level, or by inspecting the setting of the
internal (undocumented!) list !#!&ListOfModes!#!* in the source
file modes.sl. Probably, I should also write down and update the
explicit tree. Modes which are fully present only after loading
some package, like ANICK, are not found as easily now.

 The lmodename shall consist of zero or more mode names, at
levels 1, 2, ..., such that they represent a path from the root
of the mode names tree. E.g., () and (VARIABLESETUP OUTVARIABLES)
are valid lmodenames.

 The modetest shall be an s-expression, which may contain the
special variable ITEM.

 When a mode setting type is tested with a proposed mode setting
list L, the lmodename is used for two purposed. First, we test
whether or not the mode name path it represents is encoded in L.
If it isn't, the mode setting type is not present (i.e., the test
returns NIL). If it is, the corresponding part of L, 'the item',
is lambda bound to ITEM in the mode test, which then is
evaluated, to non-NIL or NIL; and this value decides whether or
not the mode setting type is present in L.

 There is a (simple) mode clash (MST1 . MST2) between the proposed
mode settings L1 and L2, if the mode setting type MST1 is present
in L1, and the mode setting type MST2 is present in L2.


 3. Auxiliary procedures.

 I should have a mode setting type finder, something like

 ModePath (lmodename, suggested_modesetting) : gany

yielding NIL if the path corresponding to lmodename isn't
present in suggested_modesetting, and else returning the
'node' corresponding to walking this path from the root
down. (If lmodename = NIL, then (T . suggested_modesetting)
should be returned, where T stands in for the mode names
tree root. Else, if lmodename = (MN1 ... MNr), then the
return value will be either NIL, or a part of
suggested_modesetting, consisting of a dotted pair
(MNr . item).)


 I should have a mode setting type checker, something like

 ModeSettingP (modesettingtype, suggested_modesetting) : bool

(acting on arguments MSP and L as described in section 2). I
do not know if these should be user available and protocolled.
My plan was to assume correct structures for the arguments to
ModePath and ModeSettingP, without further syntax control;
which might lead to weird errors, if queer arguments are given.

 Possibly, we might want to be able to construct messages from
found clashes. However, the main efforts should be made in
order to eliminate them!

JoeB, 2003-11-01
