path: root/support/mnu/mnu.doc

     *****************************************************************
     *                                                               *
     *                          Program MNU                          *
     *                                                               *
     *    A configurable menu for starting applications under DOS    *
     *                                                               *
     *                   ( English documentation )                   *
     *                                                               *
     *****************************************************************
     Prague, January 1993                                   Petr Olsak


1. A BRIEF INTRODUCTION
%%%%%%%%%%%%%%%%%%%%%%%

See the file README.TXT


2. DESCRIPTION OF THE PROGRAM
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

2.1  Start of the program
%%%%%%%%%%%%%%%%%%%%%%%%%

The MNU program operates in the 80x25 text screen mode. If the screen is
switched to another mode, the program can display incorrectly. In that
case, it is recommended first to call the program "totext.exe", which
redefines the screen mode.

In the text mode, the MNU program does not depend on the way, how
nonstandard ASCII characters (national specialities) are represented. All
displayed texts are being read from the configuration file, which is to be
prepared in agreement with the implemented coding. The correct display of
national characters is not a part of the program, so that other technical
means are to be used.

The program is to be called with at least one parameter---the name of the
configuration file (incl. the path if necessary). The other parameters are
optional. These are the names of input and/or output files, and the program
can use them following the commands from the configuration file.

If the program is started without any parameter, it displays an error
message, and terminates returning the error code 255. The same occurs if the
configuration file cannot be opened for reading.

A rule: Whenever the program terminates because of any error, an error
message is displayed and the error code 255 is returned.


2.2  Data in the configuration file
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The following data are read from the configuration file:

 * Item texts
 * Highlighted letters in item texts
 * Item numbers---each item is assigned a number (a positive integer)
 * Program action after choosing each item
 * Item sequence in each window
 * Structure of mutual calling of items
 * Type of items (editable or non-editable)
 * Explanatory texts in the windows
 * Window sizes and their allocation on the screen
 * All necessary colour attributes
 * Help texts and their relation to individual items
 * Sizes, allocations and colours of help windows
 * Way of communication with the outer environment (input/output files,
 environment variables)
 * The hot keys definition

There is a lot of other information in the configuration file. For more
details see para 3.


2.3  Starting item
%%%%%%%%%%%%%%%%%%

When started, the MNU program presents the item, the number of which
corresponds with the content of the environment variable ``MNU''.

An example of calling the MNU program:

    set MNU=17
    mnu config.mnu

In this case, the item with number 17 is presented when the MNU program is
started. (We suppose that such an item is defined in the file
"config.mnu".)

If the starting item belongs to a partial sub-menu involved in the
mutual linkage of windows and items, all ``parent'' windows are opened
automatically before the window with the particular item is opened.

If the environment variable ``MNU'' does not exist or if its content is not
of the type integer, it is considered as having the value zero.

If there is no item defined with the number equal to the content of the MNU
variable in the configuration file, the program displays an error message
and is terminated.


2.4  Selection of the item from the keyboard
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Within a window, the user switches the active item by arrows. Pull down
menus are the exception -- left/right arrows cause a jump to the
neighbouring window there (this is to be defined precisely in the configuration
file).

The key "Esc" returns the selection process to the ``parent'' window. If
there is no such window (the active window is the ``root'' of the
structure), then the program finds the item corresponding to the number 0.
In the case such an item is not defined the program is terminated and the
control is returned to DOS with the code 0. If the item exists, the program
opens the corresponding window and offers this item as active. This
procedure allows to configure the window with the last question of the type
``Do you really want to finish?'', when the item with number 0 can contain
the text ``Yes''.

There are three possibilities of the "Enter" key reactions:

 * The next window with items opens. More precisely: the specified item in
   the next ``child window'' is offered as active.
 * The program terminates its operation, closes all open windows, and
   returns the error code equal to the number of the selected item. If the
   item number is greater than 254, the programs returns the code 255.
 * The program calls the process defined by a single DOS line (so-called
   line process calling). In this case, the program resides in the computer
   memory, calls the process required, and at the end of this process offers
   the next specified item as active.

The way of the "Enter" key reaction is defined in the configuration file.

A special type is the so-called ``editable'' item. It allows to do a line
editing right in the place of the item. The result of this editing is
stored in a special buffer for later utilization in the ``line process
calling'' or for including into output files. This way, it is possible to
change the content of DOS environment variables, arrange parameters for a
line process, etc.

The built-in item editor works in the ``insert'' mode only. The keys "Del",
"Backspace" and right/left arrows work as usual. If the first pressed key
is an arrow key, the offered text is edited. Otherwise, the original text
disappears and a new text can be entered. The "Esc" key returns to the
original text, the "Enter" key keeps new text in the buffer and starts the
``item actions'' defined in the configuration file. If the editation process
does not begin the up/down keys can be used to select the required editable
item else up/down keys does not work because it is not specified whether
to confirm ("Enter") or to cancel ("Esc") of the edited text.

The "F1" key calls the help corresponding to the active item. The help
windows are configured in the configuration file, and they can contain,
in any place, further items (highlighted notions), which allow jumping to other
help windows. Thus, a structured help can be defined. The "Esc" key quits
the help. In the case that the help window does not contain any item, the
"Enter" key has the same meaning as the "Esc" key.

If there is a ``highlighted letter'' defined in the item, the item can be
selected by simple touching the key with this letter. The program reaction
is the same as when arrows and the "Enter" key are used.

In the case of any inconsistency in the configuration file (e.g. the number of
the consequential item cannot be found) the error message occurs and the
program terminates.

2.5  Selection of the item by the mouse
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

If the mouse driver is installed, the mouse cursor appears on the screen.
Pressing the left mouse button causes the selection of the item under the
cursor (the same function as "Enter"). Pressing the same button outside the
window acts similarly as "Esc", i.e. the last opened window is closed. The
right button calls and cancels the help. The middle button has no function.

The program was tested with the ``Genius mouse'' only. It is possible that
other mice could disobey (e.g. the Mickey mouse).


3. FORMAT OF THE CONFIGURATION FILE
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Inspect the content of the file "texcfg.mnu". It can serve as an
illustrative example. The following text may be difficult to understand
without parallel keeping the content of that file in view.


3.1  The basic structure
%%%%%%%%%%%%%%%%%%%%%%%%

The whole configuration file divides into sections, where attributes and
make-ups of individual windows are defined. Such a section begins with the
character "^" in the first column of the first line. We call this line a
``window-defining line''. The window-defining line is followed
(optionally) by the definition "~param", which is local for the
particular window. The text to be displayed in the window follows. In this
text, individual items, incl. corresponding program actions after a selection
of any of them, are given. The end of the section is in the place of a new
window-defining line, or (not very often) of a global definition
"~param".

Prior to the first window-defining line, there may be arbitrary text
(comment lines), and, next to it, global definitions "~param", "~start",
"~final", "~hotkeys", "~sound", and "~copy". These definitions are written
on separate lines introduced with the character "~".

Accordingly, the structure of the configuration file is as follows:

  comment lines (optional)
  ~global definitions (optional)
  ^the first window-defining line
  ~param -- parameters for the first window
  text of the window incl. description of items and actions
  ~param -- global parameters (optional)
  other comments (optional)
  ^the second window define line
  ... etc.

The text of the window may exceed number of lines of the window. The
exceeding lines (in the bottom) are ignored. It is possible to use them for
further comments.

It is not recommended to utilize this place for larger comments. The program
searches data from the configuration file sequentially (line by line), so
that extensive comments could result in a slow-down of the program execution.
It is sensible to locate definitions of more frequent windows at the
beginning. For instance, it is advisable to put helps at the end of the
file.

3.2  Active characters
%%%%%%%%%%%%%%%%%%%%%%

Active are those characters that mark off the structure of the
configuration file. The other characters are usually to be displayed in a
window, or they serve as a comment.

Most of the characters are active only under some conditions. For instance,
the character "~" is active only if in the first column. In another place
it is interpreted as any other text character.

The following table gives the list of the active characters:

 Character     Condition                Meaning
 ----------------------------------------------------------------------
  "^"      in the first column          window-defining line
  "~"      in the first column          global or local definition
  "|"      anywhere in the text
           of the window                marks off the beginning
                                        and/or the end of the item
  "#"      immediate following the character "|"
           opening an item              this item is editable
  "^"      immediate following the character "|"
           opening an item              this item is ``auto-run item''
  "!"      immediate following the character "|"
           opening an item              marks the highlighted text
  "^"      inside an item               marks the highlighted letter
  "{"      immediate following the character "|"
           closing an item              the action after the item selection
                                        is defined and close in braces
  "[%"     in any place                 introduces the requirement for a
                                        text substitution

This table implies several restrictions on the window texts:

 * No ``common'' line can begin with the characters "~" or "^" .
 * The character "|"  cannot be included in the window text. If necessary,
   the character ³ with the extended ASCII code 179 can be used.
 * Inside an item it is impossible to type the character "^" .
 * In the whole configuration file you cannot use the pair  "[%" -- this
   starts an requirement for a text substitution anywhere.
 * The text of a non-editable item cannot begin with the characters "!" or
   "#" .

The active characters were chosen so as to minimize the restrictions.


3.3  Requirements for text substitutions
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Anywhere in the text of the configuration file, the following construction
can appear:

  [%<NAME>%<LENGTH>]

where the parameter <LENGTH> is optional.

This construction is substituted by the content of the environment variable
<NAME>. The length of the corresponding string counts <LENGTH>. It means that
the superfluous characters (to the right) are omitted, if the content is
longer, or the string is completed with blank characters, if the content is
shorter. If the parameter <LENGTH> is not given, the length of the
corresponding string is set equal to the length of the content of the
environment variable.

There is another possibility of a text substitution---to substitute a text
from another file. That construction is of the form

  [%<N>% <X>, <Y>, <LENGTH>]

The text from the ``<N>-th file'' is substituted for this construction. The
<N>-th file is that given as the <N>-th parameter in the command line of
the MNU program call.

Further, <Y> is the line number, and <X> the column number of the position
in the file, where the text is to be read from, and <LENGTH> is the length of
the resulting string. The text is being read only from the indicated line,
and is, if necessary,  completed with blank characters to the right. If <LENGTH> =
is 0, then the length of the resulting string is equal to the length of the
<Y>-th line in the file (or of its part if <X> is greater than 1).

The parameter <LENGTH> is the only optional one; if it is not present, the
program reads the file from the position <X>, <Y> to the end of file (more
than only one line can be read).

EXAMPLES.
We suppose the program to be called in the following situation:

   set ENVIN=babble
   mnu config.mnu myfile.txt

and that the file "myfile.txt" contains the following two lines:

   experimental text
   in two lines containing [%ENVIN%]

In the following table the reader can find various examples:

  construction        result
  --------------------------
  [%ENVIN%3]          bab
  [%ENVIN%]           babble
  [%2% 1, 1, 5]       exper
  [%2% 10, 1, 9]      tal text
  [%2% 1, 1]          experimental text
                      in two lines containing babble
  [%2% 14, 2, 0]      containing babble

If the environment variable does not exist, the result of the construction
is blank. The program does not report any error at that moment. For
example, "[%%80]" means 80 spaces.
Similarly, if the file cannot be opened for reading, the result of the
construction is blank.

For security reasons, the program does not allow any construction including a
call of the file with the numbers 0 or 1 (the configuration file calls itself).

The input files can contain the next requirements for text substitution.
A never-ending recursive call of files is treated (for security) in such a
way, that during the eighth attempt to open a new file the program displays
an error (stack overflow), or an attempt to open a file for reading fails
(number of open files is limited in DOS).

If the text substitution construction calls a file containing
other defining lines in its text, then such a construction is to be
situated at the beginning of a line. The program reads only first
characters on each line when scanning the definitions, and does not waste
time with substitutions required in the middle of lines. Such substitutions
are accomplished only when the program needs to read the whole line or the
text of the window.

If the global definition "~copy" precedes the first defining line, then all
lines of the configuration file following this line are copied at the
screen. The definition "~copy" does not contain parameters, so that its
format is simply "~copy".

When copying (by "~copy"), text substitutions are performed in agreement
with the above rules. The MNU program finishes its activity when copying
has been accomplished. That means that the definition "~copy" switches the
program into a special mode, when no commands or definitions of the
configuration file are performed, and no items or windows are treated. Only
the character pair "[%" is active there.

Such copying is reasonable particularly when the output is directed not to
the screen, but into a file. This can be reached by an easy command:

     mnu input next input > output

A utilization of this program mode is possible for making installation
batches and environment handling.


3.4  Definition "~param"
%%%%%%%%%%%%%%%%%%%%%%%%

The definition begins with the character "~", and its format is as follows:

  ~param {<NUMBERS>} "<HEAD>" ; <COMMENT>

The parameters "<HEAD>" and ; <COMMENT> are optional.

*** <NUMBERS> -- are integers separated by spaces or commas. These numbers
are arranged in the order

{<X>,<Y>,<WIDTH>,<HEIGHT>,<FRAME>,<GROUND>,<ITEM>,<LETTER>,<A-ITEM>,<A-LETTER>}

and their meaning is as follows:

<X>, <Y> -- x and y coordinates of the upper left corner of the window
(incl. the frame if exists)

<WIDTH>, <HEIGHT> -- window width and height (incl. the frame)

<FRAME> --  0 : no frame, 1 : a simple frame, 2 : a double frame

<GROUND> --  basic text color attribute for the window (0 to 255)

<ITEM> -- text color attribute of inactive items for the window

<LETTER> -- highlighted letter color attribute for inactive items

<A-ITEM>, <A-LETTER> -- similar as <ITEM>, <LETTER>, but for active items

If less than 10 parameters are given, the other parameters to the right
keep their global or implicit values. If more than 10 numbers are given,
the superfluous numbers (to the right) are ignored.

The wildcard "*" used instead of a parameter leaves the parameter unchanged
with the global or implicit value.

*** <HEAD> -- text (heading) to overwrite the middle of the window frame
top line. When not present, the frame is not interrupted.

*** <COMMENT> -- the text separated by a semicolon is ignored.

A global definition "~param" is valid for all windows until another global
definition "~param" appears. More exactly, the next global definition
"~param" overwrites some (or all) parameters of window defined here.

On the other hand, a local definition "~param" influences parameters (all
or some of them) only for the particular window.

If neither global nor local definition determine the parameters, they keep
their values predetermined as follows:

  ~param {10, 5, 62, 17, 1, 31, 30, 30, 14, 14}

i.e. a blue window approximately in the middle of the screen with a simple
frame and yellow items.


3.5  Window-defining line
%%%%%%%%%%%%%%%%%%%%%%%%%

is of the form

  ^(<HELP>)  <ITEMS>  [<PARENT>] <<L-R>>  \ ; <COMMENT>

The types of parameters  are identified by the shape of the brackets. The order
of the parameters cannot be changed.

All parameters (incl. brackets), with the only exception of the parameter
<ITEMS>, are optional; the shortest window definition is of the form:
"^ <ITEMS>".

*** (<HELP>) -- if this parameter is present, a window for help is defined.
    Be aware: The left parenthesis should immediately follow the character
    "^" . <HELP> is a list of item numbers (separated by commas or spaces),
    showing where you can call the help window from. For instance, the active
    item is 17, and the user hits "F1". Then the program opens such a window,
    which has the number 17 given (among others) in parentheses. If no such
    window is defined, the program does not report any error, but merely
    gives an acoustic signal (see the definition of "~beep" in para 3.8).

If the parameter <HELP> is present, the parameter <ITEMS> is also optional.

*** <ITEMS> -- a list of item numbers (non-negative integers),
    corresponding to the item definitions in the window text. The items
    follow in the same order.

    If there is less numbers than items in the window text, the superfluous
    items have a number given by the last number in the list ``<ITEMS>''.
    This implies that more items with the same number can appear without
    problems. The search algorithm searches only first item with given
    number. If the list ``<ITEMS>'' is empty then the items are without
    number (it is possible only in help window).

    If there is more numbers than items, the superfluous numbers are
    ignored. If the jump to an item with such an ignored number is
    requested, the window opens, but no item is active there. The key
    "Enter" gets the same function as the key "Esc", and the arrows work
    only to the right or to the left (and only under the assumption that
    the parameter <<L-R>> is defined).

*** [<PARENT>] -- is a number defining the ``parent'' item for the window.
    If the parameter <PARENT> is given, the program checks, whether the
    window with the parent item is open, prior to opening of the particular
    window. If the parent window is not open, the program opens it at
    first. Thus a tree structure for the menu is given.

*** <<L-R>> -- Two numbers of items, where the program jumps in the case
    that the left, resp. the right arrow is pressed. The active window is
    closed before the jump. If the parameter <L-R> is not present, the
    right/up arrows (as well as the left/down arrows) have the same
    meaning.

    The parameter <L-R> allows to configure the ``pull-down'' menu, where the
    left and the right arrows ``switch sub-menus''.

*** "\" -- the presence of this character defines the so-called
    ``automatic closing window''. If the parameter is present then the
    window is closed automatic when its ``child window'' is being closed.
    Poetic expressed, the parent, having given life to a child, cannot live
    longer than his child.


3.6  Window and item texts
%%%%%%%%%%%%%%%%%%%%%%%%%%

The text following the window-defining line is copied line by line into the
window, starting immediately with the first line of the window (except the
local definition "~param"). If the line is longer than the inner width of
the corresponding window (have the frame in mind!), the rest of the line is
ignored.

If there are more lines than the inner height of the window, the
superfluous lines are ignored.

If there are less lines, the window has blank lines in the bottom. Such a
situation can appear also in the case that the program comes across the end
of the configuration file, or across a line beginning with the character
"~" or "^" . Such lines can terminate the copying of the text into the
window.

Copying of item texts to the window is not standard. The copying starts
when the character "|", introducing the item text, is first found. This
character is not copied. If the character "#" resp. "^" resp. "!" follows
immediately, the item is editable or co called ``auto-run item'' or
highlighted text is to be set respectively (see para 3.9). Otherwise, the
text which follows is copied. If the character "^" appears inside an item,
this character is ignored, and the preceding (attention! not the following)
character is marked as the highlighted letter. Retyping of the item ends,
when the closing character "|" is found; this character is not copied.

The item text can be followed by the character "{" (immediately after the
closing character "|"). Inside the braces, the action in case of the item
selection is given. This definition (incl. braces) is not copied.

If the carriage return character appears inside the item text, the program
displays an error massage and terminates.


3.7  Definition of the action after the item selection
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The action, which is to be performed after the selection of the item, can be
defined in braces after the closing character "|" of the item.
This definitions is composed of some commands separated by commas or
spaces. There can be no command at all (then the braces can be omitted).
The list of possible commands is given in the following table:

 command syntax     meaning
 ----------------------------------------------------------------------------
 $<CODE>         program terminates with given error-code number
 <NUMBER>        a ``goto'' command -- jump to the item with number <NUMBER>.
                 If the new item is in a not yet open window, the window
                 is opened (incl. the substructure, if necessary).
  \              The character \ closes an active window.
  *              Closing of all windows on the screen.
  "<TEXT>">N     If N = 0, <TEXT> is called as a DOS line.
                 If N = 1, an error is reported.
                 If N > 1, <TEXT> is added as the last line into the
                 N-th file.
                 If N is the name of an environment variable, <TEXT> is
                 stored in it.
  !>N  or  %>N   N is to be greater than 1: reset of the N-th file for
                 writing. The contents of this file (if any) is erased.

REMARKS

*** The ``goto'' command is to be the last one in the action definition. The
commands are executed in the order from the left to the right, and the
``goto'' command passes the control to the next item, so that the commands
given after it are never executed.

*** If there is no ``goto'' command (there is no item to take on the control),
the program closes all windows and terminates with the code equal to the
current item number.

*** The command "\" is equivalent to pressing the "Esc" key. If the
active window is different from the latest opened window, some difficulties
can appear. Such a situation appears if the programmer of the configuration
file does not observe the tree menu structure, and without closing the
windows in question, he jumps somewhere to the middle of the tree
parent-child structure of windows. Then closing of a window gives automatic
cause for closing all windows opened later.

*** The commands "*" a "\" need not be separated from the others by a
space nor by a comma. Thus, the following notations are equivalent and
cause closing the window and jump to the item number 17:

     {\, 17}   or   {\ 17}    or    {\17}

*** Before calling a DOS line by the command "<TEXT>">0 (the ``line
process calling''), it is senseful to use the command "*". The started
process could scroll down the screen, and thus also all open windows would
be scrolled together. The program MNU would then display objects chaotic on
the screen. A correct example of calling a DOS line follows:

       {* "dir a:">0, 17}

This construction first closes all windows, then executes  "dir a:", and
finally opens again all windows  up to the item 17.

*** The command "<TEXT>">N  (N greater than 1) only adds a new line to
the already existing text in the file. If you wish to overwrite the old
contents of the file, use the command  !>N at first.

*** The storing of new value in environment variable is local only during
the MNU program run. If you can set global value of environment variable
then you must open the auxiliary batch file and first you must store
the text "set NAME=value" to this file. After terminating the MNU program
the calling this auxiliary batch implies the setting "value" to the
"NAME" globally.

*** Commands "!>N" and %>N both reset the N-th file. The diference is in
the way of storing the "%" character to the file. The second command
invokes the special mode of writing to the file---all occurrences of
characters "%" is duplicated. This is usefull for auxiliarity batches
mentioned above, because DOS requires the per cent sign to be duplicated
while batch processing.

*** Once a file is used as an output one, it cannot be used for an input
any more. A requirement for an input such as "[%N%...]" will return a
blank string in such case.

*** Strings "<TEXT>" can contain the special character "#". The latest
edited text is substituted for this character. This way the results of
editing of items can be passed to the output. See also para 3.9.


3.8 Global definitions "~hotkeys", "~start", "~final", "~beep", "~mouse"
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The definition "~hotkeys" is of the form

"  ~hotkeys Fn{<REACTION>}, ... "

where n is number of function key (in interval 1 to 10) and <REACTION> is
a list of commands to be executed if associate function key is pressed.
The list of commands has the same syntax and semantic as in action after
the item selection, mentioned above in para 3.7. You can define at the most
10 ``hot keys'' using the single "~hotkeys" definition line (separated by
space or comma). If you define the "F1" key by "~hotkeys" definition you
cannot use the help feasibility of the program MNU but, for example, you can
call a special and better help program by the ``line process calling''.

The definitions "~start" and "~final" can contain in braces the same
commands as possible in the item starting action definitions.

*** The definition "~start" introduces a list of commands, that are
executed when the program starts. It is senseful to use e.g. commands
"!>N"  for the output file reset.

If there is a ``goto'' command in the definition "~start", the program jumps to
the given item regardless the contents of the environment variable "MNU".
If there is no ``goto'' command there, the program jumps in agreement with the
contents of the environment variable "MNU".

*** The definition "~final" introduces a list of commands, that are executed
when the program terminates without any error, after closing all windows.
That's why some commands are senseless there. The ``goto'' command, as well
as the commands  "*", "\", are ignored.

When the commands from the definition "~final" are executed, the symbol
"#" represents the number of the selected item (hexadecimal number as
text). This information can be saved in an output file.

*** The definition "~beep" is of the form:

  ~beep {<FREQUENCY>, <DURATION>}

where <FREQUENCY> defines the frequency of the sound, and <DURATION>
is its duration in milliseconds. A sound defined this way beeps always when
the user hits a key, which the program is not able to interpret. If the
definition is omitted or if at least one parameter is equal to zero, we get
no sound (which is often better).

*** In the case that the definition "~mouse" is present with the syntax:

  ~mouse {<REG-CX>, <REG-DX>}

then the mouse cursor is re-coloured in agreement with your wish by calling
the system service "int 33h" with the registers state: "AX=10", "BX=1",
"CX=<REG-CX>", "DX=<REG-DX>". If this definition is not present, the
mouse cursor is red with white ink in any place (the cursor color is not
changed with changing background colors). This implicit value corresponds
to the definition  "~mouse {255, 20224}".

The five preceding global definitions have to be stated prior to the first
window-defining line. Otherwise they are ignored.


3.9  Editable item, auto-run item and highlighted text in the window
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

AN EDITABLE ITEM is of the form:

  |#<TEXT>|{<ACTION>}

where

*** <TEXT> -- is the text offered for editing.

*** <ACTION> --  is a list of commands to be performed, when the editing
is terminating by the key "Enter" (see para 3.7). Strings of the type
"<TEXT>", defined in these commands, can contain the character "#",
for which the result of editing is substituted. For example,

  "copy # c:">0

means, that the result of editing should be a file name, which is to be
copied to the disk "c:".

EXAMPLE. The construction

   |#[%FILE%8]|{"set FILE=#">2, \17}

creates an item, offering the contents of the environment variable "FILE"
(of the length of 8 characters) as the initial text for editing. The text
"set FILE=" followed by the result of editing is then saved in the file
number 2. Finally, the window is closed and the program jumps to the item
number 17.

REMARK. When the item is editable, the closing character "|" is to be
followed by the character "{"; thus if there is no action defined, it is
necessary to write: "{}". This difference from non-editable items is
meaningful: the closing sign of the text to be edited is the pair "|{", so
that there can appear the character "|" in the offered text. This increases
the ability of the program to be ``foolproof''. The offered text is
usually variable -- the result of the last editing. The user would cause
the program collapse only if he entered the pair "|{" or "[%". Taking into
account that the user can input from the keyboard about 100 characters, the
probability of the program collapse due to user's mistake is roughly
2/10000.

THE AUTO-RUN ITEM is in the form

  |^<TEXT>|{<REACTION>}

where <TEXT> is the text of the item and <REACTION> is definition of
reaction to be immediately processed. More exactly: the <REACTION> is
processed in case that the item is highlighted. No "Enter" pressing is
required. This situation can be occurs in three cases: first, the program
activates this item as first offered item, second, the item is highlighted by
``goto'' command, third, the item is highlighted using arrow keys.
This possibility can be useful for configuring of complicated structures of
windows.

A HIGHLIGHTED TEXT in the window can be defined in the form:

  |!<TEXT>|{}

The text is displayed in the window colored as an inactive item. In fact,
it is a common text, no item. To be used if we need a two-color text in
the window.

Notice that also here the closing pair "|{" is necessary; it has the same
reason as in the case of an editable item. It is supposed that the
highlighted text can be variable, for example the value of environment
variable.


4. ERROR MESSAGES AND PROGRAM RESTRICTIONS
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The MNU program performs a syntax check when reading the configuration
file. About 40 errors can appear there; the program displays an error
message. It is not necessary to list all the error messages here; e.g. if
the message reads "'}' expected", we should easy recognize the error.
Moreover, the program displays the line number in the configuration file,
where the error has appeared, and the error line is displayed on the screen
in such a way, that in the place of the error the line is broken, and the rest
of the line continues one line below.

If the error occurs in another operation than reading the configuration
file, the error line with its number are not displayed.

Let us discuss only those error messages, that are connected with some
program restrictions.

"! out of memory"
The error occurs if, opening more larger windows one over the other, the
data memory of 64 kB is overflowed. This memory is sufficient for about 7
simultaneously open windows of a full-screen size, which should be
satisfactory, because it is senseless to open full-screen windows one over
the other.

Adding the length of the program and the memory preassumed for its data
structures, we get 88 kB of the memory, i.e. the space occupied by the
program in the operation memory. One should be aware of it if calling
one-line DOS processes when  the program resides in the memory.

"! maximal number of open windows is out"
The maximum number of simultaneously open windows is 25.

"! the head is too long"
The maximum length of the window heading is 35 characters.

"! max 25 items in one window is allowed"
The maximum number of items in a window is exceeded. Because there are no
more lines on the screen and the items should not be arranged in a matrix
(the program would misinterpret the arrow key control), this limitation is
not important.

"! the file number in interval 2..9 expected"
The number of input/output files is limited to 8 (not counting the
configuration file).

"! stack of input files overflow"
The maximum number of hierarchically open files (i.e. files, where for a
construction is substituted another file with a construction, substituted
by a further file, etc.) is limited to 8.

"! the SIZE parameter is too long"
The parameter <LENGTH> in the substitution construction is so long  that
the maximum length of the input line, i.e. 255 characters, is exceeded.


5. EXAMPLES
%%%%%%%%%%%

See the file EXAMPLES.DOC


6. HISTORY
%%%%%%%%%%

Euro-TeX-92: The first public version.

* User can select between editable items by up/down arrows. (2.4)
* The mouse cursor takes the same place as the highlighted item, when the
  program starts.
* Hot-keys definitions F1 to F10. (3.8)
* Explicit error code, when program terminates (the "$" command, 3.7).
* All items has a number now. If there are more items then length of the
  list of item numbers, the last number of the list is used. (3.5)
* Special mode for writing files---duplicating per cent sign. (3.7)
* Auto-run items. (3.9)

The last change: January 1993.