PDP-10.its/doc/mudman/ncomba.info

NCOMBAT		(TAA, 3/8/77)

	NCOMBAT is intended to replace both the old, MUDDLE version of
NCOMBAT and the standard COMBAT.  It has all the features of NCOMBAT,
including user-tailorable compilation types (see below), a 'Short'
compilation type which asks only the bare minimum of questions, and a
'backup' character which allows one to back up in the question sequence,
in the event that a mistake was made.  Although the interface is rather
different from that of COMBAT, the NCOMBAT features are as unobtrusive
as possible for those who don't want to use them, and it is considerably
faster than either COMBAT or the old NCOMBAT.

User interface
	NCOMBAT's user interface is patterned after, though not
identical to, a CALICO interface like that used in the MUDDLE version of
NCOMBAT.  In particular, it expects in response to any given prompt a
particular type of input from the user, which may be a file name, a
'symbol', or text.  Ordinarily, the type of input expected is indicated
by the 'syntactic prompt' which follows the normal prompt; this is one
of '(FILESPEC)', '(SYM)', and '(TEXT)'.  The 'Toggle verbosity'
compilation type turns the printing of the syntactic prompt on and off,
and causes a tailor file to be written out when used.
	A number of special characters are defined for any of these
types of input:
  ctrl-@:  Clears the input buffer, just as in MUDDLE.
  ctrl-D:  Redisplays the input buffer.
  ctrl-G:  When given as the first character of an answer, allows one to
	   get the answer from a user-defined type.  See the section on
	   tailoring. 
  ctrl-L:  Clears the screen and redisplays the input buffer.
  ctrl-Q:  Has special effects when a compilation is being made.  (See
	   below.)  See also the section on file name input.
  ctrl-R:  Causes NCOMBAT to 'back up'.  Typically this means go to the
	   previous question asked, but in certain modes it may have a
	   slightly different effect.  When a MUDCOM is running, this
	   kills it and pretends that ctrl-R has been typed at the
	   'Compare' question.
  ctrl-S:  Abnormally ends whatever is being done, and returns to
	   'toplevel':  the 'Type of compilation' question.  If a MUDCOM
	   is running, it will be killed.  When a long compilation
	   (How to run is 'Many') is being made, the portions already
	   made will be saved.  See the 'Flush many' compilation type.
  ?:	   When given as the first character of an answer, this causes a
	   more detailed description of what is expected to be printed,
	   along with the current default and how to obtain it.
  \:	   This quotes whatever character follows it, including
	   <rubout>, <altmode>, &c.  It does NOT have the effect of
	   quoting strange characters in file names; see the section on
	   file name input.  \, used as a quote character, never echoes,
	   and cannot be rubbed out.
In addition, when the syntactic prompt is (SYM), ctrl-F is useful.

Symbolic input
	If you are familiar with CALICO, this can probably be skipped. 
When entering symbolic input, one need only type the characters required
to uniquely specify the desired choice:  the interface will complete the
response, and in addition can display the available choices at any
point.  In particular, <space> requests the interface to complete the
response as far as it can.  If the response is uniquely specified, it
will be displayed in its entirety, followed by '!'; if more than one
choice is still possible, then the interface will display the portion of
those choices which is unambiguously specified, followed by '&'.  For
instance, if 'Expand floads' and 'Expand splices' are among the choices,
and 'Ex<space>' has been typed, 'Expand &' will be displayed since the
'Ex' reduces the choices to those two.
	In some cases, if <space> is the first character typed it will
select the default (first) choice and terminate.
	When ctrl-F is typed, the interface will display all remaining
choices. 
	To terminate responses in this mode, either <altmode> or <crlf>
may be used.  In either case, the interface first completes the current
response as far as it can.  If only one choice then remains, the answer
is terminated and can be used.  If more than one choice is possible, it
is just as if <space> had been typed.
	Typing <altmode> or <crlf> before any other characters have been
entered causes the default answer to be used.

File names
	File names are expected in the standard dev:sname;fname1 fname2
format.  Typically, typing simply <alt> or <crlf> answers 'no' to the
question, while <space><alt> says 'Use the default'.  In certain special
cases (input file and output file), when some answer to the question is
imperative, the default will be used in either case.  File names should
NOT be surrounded by quotes in this mode.
	It is rather painful to get funny characters (such as <space>)
into file names.  When the file-name parser sees a ctrl-Q, it uses the
following character in the name being generated regardless. 
Unfortunately, the ctrl-Q must be quoted to get it past the reader,
since it has special effects in the normal case.  Thus, the file
'TAA; FOO >' has to be entered as 'TAA;\ FOO >'.

Text
	Text is just that:  [relatively] arbitrary characters,
terminated by <altmode>.  Since <crlf> is allowed in text, it does not
terminate input.  Text type input is used in a number of cases where it
isn't quite appropriate, such as the redo list and package mode
questions.  If it is known that the expected response is a list or
string, as in those cases, the appropriate brackets should NOT be
supplied.  Assuming, of course, that winnage is desired.


Submitting compilations
	The first question asked by NCOMBAT is 'Type of compilation'. 
In addition to a number of special possibilities described later, there
are two (in addition to any provided by the user through the tailoring
facility) answers to this question which cause a compilation to be
submitted:  'Verbose' (the default) and 'Short'.  The only distinction
is that 'Verbose' causes all the normal questions to be asked:  new
compiler, input file, precompilation, 97 switches, things to do, and so
on; 'Short', on the other hand, defaults the answers to all questions
except new compiler, input file, and how to run.
	If 'Many' was given as 'How to run' for a previous compilation,
and the resulting plan has not yet been written out, all subsequent
plans will be appended to it.  The ONLY way to get rid of this plan is
to answer 'Many flush' to the 'Type' question.  Typing ctrl-S or
answering 'Abort' to the 'How to run' question will abort the current
portion of the moby compilation, but not the whole thing.
	If  'Many' was mistakenly given as 'How to run', and you don't
wish to destroy the plan you have generated, it is possible to (in
essence) go back to the 'How to run' question by answering 'Many print'
for the compilation type.  In this case, you are NOT!!! back in the
plan-making loop; ctrl-R acts just like ctrl-S.
	When submitting a compilation, one may type ctrl-Q at any time. 
This has the same immediate effect as an altmode, but in addition causes
all questions between the one just answered and the 'things to do'
question to be defaulted.  This is particularly useful in the 'Verbose'
sequence of questions.
	Ctrl-R, here, backs up to the last question asked.  There are
two qualifications.  First, if ctrl-Q has been typed, then it backs up
to the last question that would have been asked if ctrl-Q had not been
typed.  Second, the four questions 'Precompilation to load', 'Compare',
'Redo', and 'Package mode' are treated as a group:  if the package mode
question has not yet been answered, it is possible to back up normally;
but once that question has been answered, backing up to it will go to
the first member of the group, 'Precompilation'.
	Ctrl-G allows one to obtain the answer to the current question
from any user-defined group.  It requests a group name, and uses the
answer/default supplied therein, printing the information so obtained. 
The ctrl-G must be typed as the first character of the answer for this
to occur.  This allows one to use parts of a defined group without
either using the group itself or altering it for the occasion.  For
(TEXT) type input (such as things to do), the string is placed in the
input buffer but not completed, so it may be edited before an altmode is
typed.   See also the 'Xerox group' command.
	Note that there is a distinction made between 'Compare' and
'Redo'; the former causes a MUDCOM to be run, and the latter asks for
the names of functions to be recompiled.  It is possible to do both, in
which case the two groups of functions are appended to form the redo
list for the compilation.  Note also that if a MUDCOM has been run, the
'Package mode' question will not be asked, since the answer is supplied
by the MUDCOM.  Either ctrl-R or ctrl-S may be used to kill a running
MUDCOM. 

	One of the responses to the 'How to run' question is 'Abort',
which returns directly to the 'Type of compilation' question without
writing out a plan, starting up a pcomp, or anything else.  Its effect
is exactly that of a control-S.  In particular, if you are making a long
compilation, only the portion just completed, NOT the entire
compilation, will be aborted.

	It is also possible at the 'How to run' question to supply an
answer to any of the compilation questions (Input file, etc.).  The
'Question' response asks for the name of a question, then asks that
question.  Any number of questions can be asked in this manner, one at a
time.  This is particularly useful for filling in the blanks left by a
'Short' type compilation, or by a user-defined types.

	When a compilation has been finished, NCOMBAT normally loops
back to the 'Type of compilation' question, but changes the default from
'Verbose' to 'None' (==Quit), unless another compilation may reasonably
be expected.  This enables one to leave by typing a single <altmode>. 
It is possible to modify its behavior such that it either kills itself
after finishing the compilation, or loops back with 'Verbose' as the
default for the 'Type of compilation' question.  NCOMBAT first decides
whether a long compilation is being made; if so, the default remains
'Verbose.'  It then examines the current compilation type:  if 'Another
compilation?' has been set to 'Yes', the question will be asked with
default 'Verbose'; if to 'No', NCOMBAT will kill itself; if to 'ASK',
further consideration is required.  If the user is in 'Multiple' mode
(the 'Multiple' compilation type), the type of compilation will be asked
with the 'Verbose' default.  Otherwise, NCOMBAT examines the state of
two tailorable switches, set by the 'Another compilation?' compilation
type.  If this has been set to 'No', the job will die; if to 'yes', the
type question will be asked with default 'Verbose'; if to 'ask', the
type questio will be asked with default 'None'.  Normally this is 'ask'.
Note that this switch is like 'Toggle verbosity' in that it will have no
effect unless user-defined compilation types exist.


User tailoring
	It is often the case that a particular file is compiled quite
often, or that some sequence of actions must be performed as the 'Things
to do' before many compilations.  NCOMBAT allows the user to define his
own 'compilation types', each of which specifies exactly those questions
which should be asked and the answers for those which should not.  For
example, one could have a type named 'Esign', which says that the input
file is always SEND;ESIGN > and in addition provides for the floading of
two files in 'Things to do'.  Further, since most questions are
defaulted, one might choose to answer only those questions which are
interesting, such as precompilation.  It is also possible to supply a
default answer for a question which will be asked.
	In addition, there are some questions which are not asked by the
verbose compilation type, but which nevertheless are available to
user-defined types.  These are:  Macro compile, Macro flush, Max space,
Expand splices, Special mode, and Glue.   It is a restriction of the
compiler that the logical 'AND' of macro compile and max space must be
false.
	One can select any of one's defined compilation types as an
answer to the 'Type of compilation' question, just like 'Verbose' and
'Short'.  Except that the questions asked may differ, user-defined types
are identical to the predefined types.

Tailor files
	User-defined types are saved (and loaded) from the file
<sname>;%combt tailor.  It is possible to load other tailor files, but
the %combt file in <sname> is loaded during startup.  Tailor files are
quite similar to gc-dumped files, and thus cannot be edited using TECO.

Create type
	This special compilation type requests a name for the type
being made, then enters a loop with the prompt 'Question'.  One may
choose any of the available questions, and either supply an answer or
(the default) request that the question be asked when a compilation of
this type is being submitted.  Note that only the 'How to run' and
'Another compilation?' questions will be asked unless others are
explicitly supplied; but one may supply answers to 'How to run' and
'Another compilation' when creating a type.
	In this mode, ctrl-R will return to the 'Question' loop if one
has just supplied an answer; otherwise, it returns to the 'Type of
compilation' loop, aborting the type.
	Ctrl-G behaves exactly as it does in the normal loop.
	To indicate that one is finished, one should answer 'Finis' to
the 'question' prompt.  It is possible to supply several different
versions of the answer to particular question:  the last one given will
be used.  One may wish to default a particular question, after
specifying that it was to be asked or after supplying some different
default.  This may be done by answering 'Delete question' to the
'Question' prompt, whereupon one will be asked for a particular question
to ignore.  This question will then be completely ignored.  Note that
ALL interesting questions are initially in this state.
	There is also a 'Set question default' "question."  This
requests a question name, then asks the user to supply an answer.  The
question will be asked, with the default supplied.  Thus default
settings of switches can be changed, and one can supply a file name for
the precompilation while still being asked whether precompilation is
desired.  Unfortunately, user-supplied defaults for TEXT-type questions
are used if <altmode> is answered; to get rid of the default, type
<space><altmode>.  Note that this is exactly the inverse of the
convention for defaulting file names.

	When 'Finis' has been typed, a new copy of one's tailor file is
written out.  This may, in combination with 'Load tailor' and
'Replace tailor', have undesirable side effects.

Print type
	This requests the name of one of the types currently loaded,
and prints out for it all questions which either will be asked when a
compilation is being submitted or which have user-supplied defaults.  If
a particular question has been globally 'turned off' (such as the new
compiler question, when there is no new compiler), an asterisk will be
printed on the appropriate line to indicate that the information there
is currently not used.

Delete type
	This requests the name of one of the currently-loaded types,
and deletes it.  A new copy of the tailor file is written out, so all
trace of the type will vanish when this command is used.

Alter type
	This requests a type name, then becomes identical to
Create type, except that some questions already have answers.  Again,
'Finis' must be typed to leave the loop and cause the modifications to
be filed; typing ctrl-R or ctrl-S will leave the loop, but the
modifications will be forgotten.

Load tailor, Replace tailor
	Both of these request a file name, defaulting to the last one
used for either a load tailor or replace tailor command.  Initially this
is <sname>;%combt tailor.  Load tailor appends the types defined in the
specified file to those already loaded, while Replace tailor throws away
those already loaded first.  The types defined in this way are not
distinguished from those loaded from one's own combat tailor; in
particular, using 'Toggle.verbosity' or any of create, alter, and delete
type will cause all the types currently loaded to be written out to
the combat tailor.  If, therefore, one has done a replace tailor, one
can easily lose all of one's own types in this manner.  I.e., it is
very easy to screw oneself.

Xerox tailor
	This requests the name of an existing user-defined type, and a
new type name.  The new type becomes an exact copy of the
previously-existing type.  This is particularly useful when one has
several different types which do almost the same thing.


Unimplemented features
	An SNAME question will be installed, though not in the normal
'Verbose' sequence.  This would cause the setting of the sname default,
which would alleviate some of the problems with NCOMBAT's habit of
printing out entire file names.