summaryrefslogtreecommitdiff
path: root/support/mnu/mnu.doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/mnu/mnu.doc
Initial commit
Diffstat (limited to 'support/mnu/mnu.doc')
-rw-r--r--support/mnu/mnu.doc842
1 files changed, 842 insertions, 0 deletions
diff --git a/support/mnu/mnu.doc b/support/mnu/mnu.doc
new file mode 100644
index 0000000000..0c39e01164
--- /dev/null
+++ b/support/mnu/mnu.doc
@@ -0,0 +1,842 @@
+
+ *****************************************************************
+ * *
+ * 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.
+
+