% Program MNU -- The Documentation written in plain \TeX % ====================================================== % January 1993 Petr Ol¨ k \hsize=159.2mm \vsize=239.2mm \raggedbottom \font\titl=cmbx10 scaled \magstep2 \font\bigit=cmti10 scaled \magstep2 \font\mflogo=logo10 % font for METAFONT logo \def\CS{$\cal C\kern-.1667em\lower.5ex\hbox{$\cal S$}\kern-.075em $} \def\CSTUG{\CS TUG} \def\METAFONT{{\mflogo META}\-{\mflogo FONT}} \def\LaTeX{L\kern-.36em\raise.5ex\hbox{\sevenrm A}\kern-.12em\TeX} \def\sect #1\par{\vskip30pt\line{\titl #1\hfil}\nobreak\bigskip} \def\subsect #1\par{\ifdim\lastskip=\bigskipamount \else\vskip 20pt\fi \line{\bf #1\hfil}\nobreak\medskip} \catcode`\"=13 \def"{\hbox\bgroup\let"=\egroup\setverb\tt} \def\setverb{\def\do##1{\catcode`##1=12}\dospecials\obeyspaces} \def\dd{{\tt\char34}} \catcode`\<=13 \def<#1>{\leavevmode\hbox{\rm\it\lowercase{#1}\/}} %\def \uv#1{\vbox to0pt{\kern-.33ex\hbox{''}\vss}\kern-.1ex#1\kern-.1ex``} \def\begitems{\medskip\bgroup\catcode`\*=13 \narrower\narrower} \def\enditems{\par\egroup\medskip} {\catcode`\*=13 \gdef*{\par\noindent\llap{$\bullet$\ }\ignorespaces}} \def\quest{\medskip\indent\hangindent\parindent \llap{\frame{\bf ?}\kern8pt}\ignorespaces} \def\answ{\medskip\indent\hangindent\parindent \llap{\frame{\bf !}\kern8pt}\ignorespaces} \def\frame#1{\lower4pt\vbox{\hrule \hbox to14pt{\vrule height10pt depth4pt\hfil #1\hfil\vrule}\hrule}} \def\bull{\medskip\indent \llap{$\bullet$\ }} \def\toa{$\to$} \def\m{\hskip1em\relax} \def\begtt{\par\medskip\bgroup\setverb\catcode`\"=12\obeylines\startverb} {\catcode`|=0 \catcode`\\=12 |gdef|startverb#1\endtt{|tt #1|egroup|medskip}} {\obeyspaces\gdef {\ }} % usage: \begtab{width}, width ... the width of right column \def\begtab#1{\medskip\line\bgroup\hfil \vbox\bgroup\offinterlineskip \def\title{\vrule height15pt depth8.5pt width0pt\cr \noalign{\hrule} \vrule height15pt width0pt} \def\:{\hfill &&} \hrule\halign\bgroup\vrule## &\vrule height12pt width0pt\hfil\quad##\quad\hfil&&\vrule## &\quad\hbox to #1{\vtop{\hsize=#1\noindent##\unskip\strut}}\quad\cr \vrule height15pt width0pt\relax} \def\endtab{\vrule depth9pt width0pt&\cr \egroup\hrule\egroup\hfil\egroup\medskip} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% begin of text \null\vskip 30pt \centerline{\titl Program MNU} \bigskip \centerline{\titl A configurable menu for starting applications under DOS} \bigskip \centerline{\bigit Petr Ol\v s\'ak} \bigskip \centerline{Prague, January 1993} \bigskip\hrule\medskip \sect 1. A brief description %%%%%%%%%%%%%%%%%%%%%%%%%%%% The program MNU allows, together with its control batch (".bat"), repeated starting of various application programs. It has been developed for the \TeX\ packages, nonetheless, it can be utilized elsewhere. The batch "demotex.bat" starts an exhibition of possibilities of the program MNU itself. The second batch "demotex.bat" shows a more complicated example of configuration of emTeX used in \CS\TeX package. This example exhibits possibilities of MNU program itself on the one hand, and of its suggested configuration "cfg.mnu" suitable for the emTeX packages with DOS on the other hand. These examples are documented in chapter 5. The documentation is intended for the users, who wish to change the existing configuration of the system, where the program is applied, or who wish to develop a new one. Therefore some deeper knowledge of DOS is assumed, esp. some advanced skills in batch (".bat") programming. The program keeps up appearances of an integrated environment for starting of various processes. This environment is fully configurable, including window colours and shapes, names and ways of application of individual menu items, context help, etc. The process is controlled by the batch. In a definite moment, the batch starts the MNU program with a single parameter -- the configuration file name (e.g. "cfg.mnu"). The program MNU reads a full description of menu structure from this file and displays menu items on the screen. Now the user can choose the particular item comfortably. When the item is chosen, the program MNU terminates and the control batch evaluates the error code corresponding to the respective item. In the batch, the chosen item number is determined using a set of "if errorlevel" commands, and the batch branches to separate application processes. When the application ends, the batch calls the MNU program again, and the user can choose a new item, and so on. The batch can also communicate with the MNU program by means of DOS ``environment variables'', and of input and/or output files. The program can display and edit the content of these variables (if this is given in the configuration file). Moreover, there exists a special environment variable called ``MNU'' influencing the start of the program -- the item specified in this variable is offered as active when the program starts. Seeing that, the user does not need to choose tediously the next item, provided his activity proceeds in the ``normal'' sequence. For example, after the \TeX\ program run it is possible for the batch to examine (using the "if errorlevel" command) whether the translation ended without errors. If so, then the variable ``MNU'' can be set in such a way that the item "View" is active in the next call of the menu. In the menu environment, the user can do nothing but "Enter" pressing. The advantage of this ``batch'' philosophy is that the MNU program does not occupy the memory during the application run. Furthermore, concerning the system configuration, there are practically no limitations on variability in setting the behaviour of particular processes. The only limitations are due to the DOS itself. Only a batch allows to express all configuration possibilities of separate application programs. \medskip The list of files contained in the MNU program package is given in the following table: \begtab{25em} & "readme.txt" \: Basic information about the program &\cr & "mnu.doc" \: Detailed documentation of the program &\cr & "examples.doc" \: Description of some tricks used in the batches &\cr & "mnu.tex" \: Contents of three previous files in plain \TeX\ -- this text &\cr & "mnu.exe" \: The MNU program itself &\cr & "demo.bat", "demo.mnu" \: A simple example of program MNU possibilities &\cr & "demotex.bat", "cfg.mnu", \: &\cr & "sorry.mnu", "*.bat" \: A more complicated example of em\TeX configuration &\cr & "totext.exe", "totext.c" \: Switches the screen to the text mode $80 \times 25$ &\cr & "dupcent.exe", "dupcent.c" \: Duplicates {\tt\char37} (utility program) &\cr & "kalk.exe", "kalk.hlp" \: The calculator -- an illustration of an application program \endtab \medskip The software contained in the files listed above is in the public domain. The author transfers it to the \CSTUG\ association (Czechoslovak \TeX Users Group) and expects that they will care about its popularization and further distribution. It is not allowed to utilize these programs and/or their modifications for commercial purposes. That means, it is not allowed to sell this software (with the exception of a diskette copying fee), nor to include it in systems designed merely for commercial purposes. Since of the first public distribution of this product (Euro-\TeX\ 92) some unimportant improvements were made. This changes keep full compatibility with the old configuration files and offers some new possibilities (see the end of the documentation). The author will not more change or improve this software, esp.\ its basic conception. However, he welcomes all suggestions leading to elimination of errors, which can, unfortunately, appear in any software. The source code of the MNU program (written in C language) is not public. \medskip \noindent\halign{\bf #\hfil &\quad #\hfil\cr address: & Petr Ol\v s\'ak \cr & Department of Mathematics \cr & Faculty of Electrical Engineering \cr & Czech Technical University \cr & $\underline{\strut \hbox{166 27 PRAGUE}}$ \cr & Czech republic \cr & \cr email: & {\tt\char60}"olsak@csearn.bitnet>" \cr} \sect 2. Description of the program %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsect 2.1 Start of the program %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The MNU program operates in the $80 \times 25$ 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. \subsect 2.2 Data in the configuration file %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The following data are read from the configuration file: \begitems * 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 \enditems There is a lot of other information in the configuration file. For more details see para 3. \subsect 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: \begtt set MNU=17 mnu config.mnu \endtt 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. \subsect 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''. \medskip There are three possibilities of the "Enter" key reactions: \begitems * 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. \enditems 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. \subsect 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). \sect 3. Format of the configuration file %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Inspect the content of the file "demo.mnu" or "cfg.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. \subsect 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: \begtt 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. \endtt 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. \subsect 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: \begtab{16em} & Character && Condition && Meaning & \title & "^" && in the first column && window-defining line &\cr & "~" && in the first column && global or local definition &\cr & "|" && anywhere in the text of the window && marks off the beginning and/or the end of the item &\cr & "#" && immediate following the~character~"|" opening an item && this item is editable &\cr & "^" && immediate following the~character~"|" opening an item && this item is ``auto-run item'' &\cr & "!" && immediate following the~character~"|" opening an item && marks the highlighted text &\cr & "^" && inside an item && marks the highlighted letter &\cr & "{" && immediate following the~character~"|" closing an item && the action after the item selection is defined and close in braces &\cr & "[%" && in any place && introduces the requirement for a text substitution \endtab This table implies several restrictions on the window texts: \begitems * No ``common'' line can begin with the characters "~" or "^" . * The character "|" cannot be included in the window text. If necessary, the~character~\vrule\ 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 "#"~. \enditems The active characters were chosen so as to minimize the restrictions. \subsect 3.3 Requirements for text substitutions %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Anywhere in the text of the configuration file, the following construction can appear: \medskip \indent "[%%]", where the parameter is optional. \medskip This construction is substituted by the content of the environment variable . The length of the corresponding string counts . 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 is not given, the length of the corresponding string is set equal to the length of the content of the environment variable. \medskip There is another possibility of a text substitution---to substitute a text from another file. That construction is of the form "[%% , , ]". The text from the ``-th file'' is substituted for this construction. The -th file is that given as the -th parameter in the command line of the MNU program call. Further, is the line number, and the column number of the position in the file, where the text is to be read from, and 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 = is 0, then the length of the resulting string is equal to the length of the -th line in the file (or of its part if $ > 1$). The parameter is the only optional one; if it is not present, the program reads the file from the position , to the end of file (more than only one line can be read). {\bf Examples.} We suppose the program to be called in the following situation: \begtt set ENVIN=babble mnu config.mnu myfile.txt \endtt and that the file "myfile.txt" contains the following two lines: \begtt experimental text in two lines containing [%ENVIN%] \endtt In the following table the reader can find various examples: \begtab{20em} & construction && result & \title & "[%ENVIN%3] " && "bab" &\cr & "[%ENVIN%] " && "babble" &\cr & "[%2% 1, 1, 5] " && "exper" &\cr & "[%2% 10, 1, 9]" && "tal text " &\cr & "[%2% 1, 1] " && "experimental text "\hfil\break "in two lines containing babble" &\cr & "[%2% 14, 2, 0]" && "containing babble" \endtab 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. \medskip 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: \begtt mnu input next input > output \endtt \noindent A utilization of this program mode is possible for making installation batches and environment handling. {\catcode`\~=12 \subsect 3.4 Definition "~param" %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% } The definition begins with the character "~", and its format is as follows: \begtt ~param {} "" ; \endtt The parameters \dd\dd\ and "; " are optional. \bull -- are integers separated by spaces or commas. These numbers are arranged in the order \begtt {, , , , , , , , , } \endtt \noindent and their meaning is as follows: {\narrower\parindent=0pt , -- x and y coordinates of the upper left corner of the window (incl. the frame if exists) , -- window width and height (incl. the frame) -- 0 : no frame, 1 : a simple frame, 2 : a double frame -- basic text color attribute for the window (0~to~255) -- text color attribute of inactive items for the window -- highlighted letter color attribute for inactive items , -- similar as , , but for active items } \medskip 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. \bull -- text (heading) to overwrite the middle of the window frame top line. When not present, the frame is not interrupted. \bull -- the text separated by a semicolon is ignored. \medskip 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: \begtt ~param {10, 5, 62, 17, 1, 31, 30, 30, 14, 14} \endtt i.e. a blue window approximately in the middle of the screen with a simple frame and yellow items. \subsect 3.5 Window-defining line %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% is of the form \medskip\noindent " ^() [] "{\tt\char60}"> \ ; " \medskip 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 , are optional; the shortest window definition is of the form: "^ ". \bull "("")" -- if this parameter is present, a window for help is defined. Be aware: The left parenthesis should immediately follow the character "^" . 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 is present, the parameter is also optional. \bull -- 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 ``''. 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 ``'' 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 is defined). \bull "[""]" -- is a number defining the ``parent'' item for the window. If the parameter 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. \bull {\tt\char60}">" -- 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 is not present, the right/up arrows (as well as the left/down arrows) have the same meaning. The parameter allows to configure the ``pull-down'' menu, where the left and the right arrows ``switch sub-menus''. \bull "\" -- 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. \subsect 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. \subsect 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: \begtab{26em} & command syntax && meaning & \title & "$" && program terminates with given error-code number &\cr & && a ``goto'' command -- jump to the item with number . If the new item is in a not yet open window, the window is opened (incl.~the substructure, if necessary). &\cr & "\" && The character "\" closes an active window. &\cr & "*" && Closing of all windows on the screen. &\cr & \dd\dd">" && If $ = 0$, is called as a DOS line. \hfil\break If $ = 1$, an error is reported.\hfil\break If $ > 1$, is added as the last line into the -th file. \hfil\break If is the name of an environment variable, is stored in it. &\cr & "!>" or {\tt\char37>} && is to be $\null > 1$: reset of the -th file for writing. The contents of this file (if any) is erased. \endtab {\bf Remarks.} \bull 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. \bull 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. \bull 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. \bull 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: \nobreak\medskip\noindent " {\, 17} " or " {\ 17} " or " {\17}" \bull Before calling a DOS line by the command \dd\dd">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: \begtt {*"dir a:">0, 17} \endtt This construction first closes all windows, then executes "dir a:", and finally opens again all windows up to the item 17. \bull The command \dd\dd">" ($ > 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 "!>" at first. \bull 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. \bull Commands "!>" and {\tt\char37>} both reset the -th file. The difference is in the way of storing the {\tt\char37} character to the file. The second command invokes the special mode of writing to the file---all occurrences of characters {\tt\char37} is duplicated. This is useful for auxiliary batches mentioned above because DOS requires the per cent sign to be duplicated while batch processing. \bull 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 "[%%...]" will return a blank string in such case. \bull Strings \dd\dd\ 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. {\catcode`\~=12 \subsect 3.8 Global definitions "~hotkeys", "~start", "~final", "~beep", "~mouse" %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% } The definition "~hotkeys" is of the form \medskip " ~hotkeys F{}, ... " \medskip \noindent where is number of function key (in interval 1 to 10) and 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''. \medskip The definitions "~start" and "~final" can contain in braces the same commands as possible in the item starting action definitions. \bull The definition "~start" introduces a list of commands, that are executed when the program starts. It is senseful to use e.g. commands "!>" 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". \bull 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. \bull The definition "~beep" is of the form: \begtt ~beep {, } \endtt \noindent where defines the frequency of the sound, and 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). \bull In the case that the definition "~mouse" is present with the syntax: \begtt ~mouse {, } \endtt \noindent then the mouse cursor is re-coloured in agreement with your wish by calling the system service\m "int 33h"\m with the registers state:\m "AX=10", "BX=1", "CX=", "DX=".\m 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 \m "~mouse {255, 20224}". \medskip The five preceding global definitions have to be stated prior to the first window-defining line. Otherwise they are ignored. \subsect 3.9 Editable item, auto-run item and highlighted text in the window %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% An editable item is of the form: \begtt |#|{} \endtt where \bull -- is the text offered for editing. \bull -- 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 \dd\dd, defined in these commands, can contain the character "#", for which the result of editing is substituted. For example, \dd"copy # c:"\dd">0" means, that the result of editing should be a file name, which is to be copied to the disk "c:". \medskip \vbox{ {\bf Example.} The construction \begtt |#[%FILE%8]|{"set FILE=#">2, \17} \endtt 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\m "set FILE="\m 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. \medskip {\bf The auto-run item} is in the form \begtt |^|{} \endtt \noindent where is the text of the item and is definition of reaction to be immediately processed. More exactly: the 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. \medskip {\bf A highlighted text} in the window can be defined in the form: \begtt |!|{} \endtt 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. \sect 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\m "'}' expected"\m, 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. \medskip Let us discuss only those error messages, that are connected with some program restrictions. \bull "! out of memory"\m 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. \bull "! maximal number of open windows is out"\m The maximum number of simultaneously opened windows is 25. \bull "! the head is too long"\m The maximum length of the window heading is 35 characters. \bull "! max 25 items in one window is allowed"\m 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. \bull "! the file number in interval 2..9 expected"\m The number of input/output files is limited to 8 (not counting the configuration file). \bull "! stack of input files overflow"\m 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. \bull "! the SIZE parameter is too long"\m The parameter in the substitution construction is so long that the maximum length of the input line, i.e.~255 characters, is exceeded. \sect 5. Examples %%%%%%%%%%%%%%%%% In the demo batches you can find some methods and tricks used with the MNU program. There are two examples. \subsect 5.1 The first simple example %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The first example shows a basic MNU program principles. This example describes not really application, but the basic principles of program MNU is clearly shown. The files used in the example are listed in the following table: \begtab{20em} & "demo.bat " \: The control batch &\cr & "demo.mnu " \: The configuration file &\cr & "envir.bat" \: The auxiliary batch (it will be created) \endtab \noindent{\bf Remarks} \bull The batch "demo.bat" controls the main loop of application processes. After terminating the MNU program the batch branches next executing by set of commands \begtt if errorlevel ... goto ... \endtt \noindent One should have in mind that these "if errorlevel" commands must have a decreasing order of constants ("if errorlevel" does mean ``if errorcode is greater or equal to''). \bull Instead of the really application calls there are the "echo" commands in the control batch "demo.bat" only. You can remove this word ("echo") and write the really applications. \bull If the user changes the file name (value of the "FILE" environment variable), the program MNU writes the line \begtt set FILE= \endtt \noindent into the file "envir.bat" (see file "demo.mnu", line 26). After terminating of the MNU program the control batch "demo.bat" calls this auxiliary batch (see line 44 in "demo.bat"). This is a way to set new value to environment variable globally. \bull The MNU variable is set to the probably next used item number after each applications. So that the user can press only the "Enter" key repeatedly to make the loop "Edit"---"Compile"---"Execute". \bull After the ``executing of compiler'' the line with test of error code of compiler is included (see line 29 in "demo.bat"). If the compiler does not end successfully, the batch sets the value 10 (instead 30) to MNU variable and this setting influences the next state of MNU program (the Edit item offers instead the Execute item). This command is commented out ("rem") because the really compiler run does not preceded. \bull If user press the "Esc" key, the MNU program searches the item with number zero and the "Quit" item offers. \subsect 5.2 The second more complicated example %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% This is the example of em\TeX\ configuration using the MNU program. The files listed below are really used in \CS\TeX\ package. In this package distributed by \CS TUG (Czechoslovak \TeX\ Users Group), the em\TeX\ programs and MNU configuration are included. The MNU configuration is separated from the \CS\TeX\ package and included as the example here. \begtab{24em} & "demotex.bat " \: This batch starts the example &\cr & "texset.bat " \: Initialization batch &\cr & "texbat.bat " \: The main loop &\cr & "texrun.bat", \: &\cr & "others.bat", \: &\cr & "prints,bat", \: &\cr & "metafont.bat" \: The applications batches (called from "texbat.bat") &\cr & "cfg.mnu " \: The configuration file for menu &\cr & "sorry.mnu " \: The configuration file for ``sorry-messages'' &\cr & "texcfg.bat " \: User's configuration &\cr & "mfbat.bat " \: The auxiliary batch (it can be changed) &\cr & "gfbat.bat", \: &\cr & "dos.bat", \: &\cr & "envir.bat " \: The auxiliary batches (they will be created) &\cr & "dupcent.exe " \: Duplicates the "%" character (utility program) &\cr & "totext.exe " \: Sets the screen to text mode (utility program) &\cr & "kalk.exe " \: Calculator -- a simple application program &\cr & "kalk.hlp " \: help texts for "kalk.exe" &\cr & "dupcent.c", \: &\cr & "totext.c " \: The source codes for utility programs \endtab Unfortunately, this example cannot show the applications in really action, because application programs are other matter and they are not included in this small MNU package. If you are interested in this problem, you can take the whole \CS\TeX\ package from public international network archives. Note that the installation program of this package is based on MNU program too. You can run the staring batch "demotex.bat" and try the menu. The helps are translated from Czech language to English (more exactly to my poor English and bad English). So, the sense of individual items can be read from this helps. The files listed here can be used in various configuration of \TeX\ systems, but some modifications are needed. If you intend to use these files as a motivation when designing the \TeX\ configuration for your computer, you will have to modify some parts as your needs can be. In any case, the files listed here can serve as a source of inspiration. At least you can find the key to a better understanding the philosophy of the communication between the control batch and the MNU program there. The remarks to individual tricks and most important parts of files used in this example follow here. \subsect Remarks to "demotex.bat" \bull There is only one line here---the call of the batch "texset.bat" via the command "command". The environment variable "COMSPEC" will be expanded to command "command" including path. The command "command" enlarges the system environment. Many environment variables will be used. \bull The "texset.bat" has four parameters. First: the format file name ("csPLAIN" in the example in "demotex.bat"), second: the item text for \TeX\ executing ("PlainT^eX" in the example), third: the working and main filename ("%1" in the example) and fourth: the working filename if different ("%2" in the example). \bull The ``starting batch'' "demotex.bat" has others names in original \CS\TeX\ package. For example "plain.bat", "latex.bat" etc. This batches are placed in directory where the system "PATH" points. So that the user can call the \TeX\ system from his own current directory by the command (for instance) \begtt latex \endtt \noindent All working files (".tex", ".dvi", ".log", etc.) will be created in the current directory. \subsect Remarks to "texset.bat" \bull There are "set" commands here to set the environment of em\TeX\ variables and others. Some variables are used only in batches. The field signed as ``system dependent variables'' includes variables dependent on disk structure. Note that the first settings are nonstandard in demo-version of "texset.bat" because only demonstration without special path handling is done. The really settings can look as following: \begtt set TEXDIR=c:\emtex set TEXDIRCFG=c:\emtex\cfg set RAM=e:\temp set EDIT=c:\editors\ne set SHELL=c:\nc\nc \endtt \bull After environment settings the "texset.bat" calls the "texcfg.bat" if present (see line 57). So that the user can change the default setting in his own ``configuration batch'' "texcfg.bat" if this file is placed in current directory. \bull Some batches and configuration files ("texbat.bat", "cfg.mnu", "texrun.bat", "mfbat.bat") are copied into RAM disk to increase the speed (see lines 50--53 in "texset.bat"). This process is skipped in demo version because the environment variable RAM does not point to RAM disk. (see line 50: ".. goto start"). \bull The "texset.bat" calls the "texbat.bat"---the main loop of applications (see line 61). \subsect Remarks to main loop "texbat.bat" \bull The MNU is called here (compare with "demo.bat" from previous example). Then the process branches to individual applications or application batches. \bull The auxiliary batch "envir.bat" is called after each MNU run to restore the global environment setting (see line 5). \bull If the typical file of application is not found the process go to "sorry" label (line 139) and calls the MNU program with "sorry.mnu" configuration file to display a message about no-installed program (see line 80 for instance). This handling is included to control batches because no all applications may be installed---the installation program of \CS\TeX\ offers many variabilities that no all programs can be installed. \bull The "texbat.bat" calls directly only some applications, others are called via application batches. You can compare this batches to ``procedures'' in programming languages. \subsect Remarks to application batches "texrun.bat", "others.bat", "prints.bat" and "metafont.bat" \bull The error code from MNU is still stored and the process branches to individual applications again. \bull The ``sorry handling'' is similar as in the "texbat.bat". \bull The individual application will not work in demo version because they are not installed. \bull Some tricks are used here. These tricks are related to em\TeX\ configuration itself and they are not in our first interest while we are studying the MNU philosophy. \subsect Remarks to "cfg.mnu" configuration file By means of questions and answers, we are going to look into some constructions in the file "cfg.mnu" installed. We focus on those parts of the file which need not be quite comprehensible even after reading the documentation through. \quest Where to look for the item 100 defined in the line " ^ 100 \" (see line 10). \answ This item does not exist. It is the case when there are less items (zero in this place) in the window than set in the definition line of the window. The window opens if the item is called, but there is no item active. The window is called as a parent window by the window with the basic menu (see line 16). Pressing the key "Esc" at the moment when only the basic menu is offered does not cause a jump to the non-existing item 100, because the window is defined as automatically closeable (the character "\"). \quest Why is the result of choosing (e.g.~"amstex") in\m "Formats menu"\m stored not only in the environment variable, but also in the file 2 in the form\m \dd"set FMT=amstex"\dd">2" (see line 122). \answ The command\m \dd"csAMSTEX"\dd">FMT"\m has a local character within the MNU program, and because the next command (i.e.~"*") means closing all windows and a jump onto the item 61, also the contents of the window with the non-existing item 100 is restored; it bears information about the chosen format. On the other hand, the command\m \dd"set FMT=amstex"\dd">2"\m enables to forward the information about the chosen format to the control batch via the file 2, i.e.~the file "envir.bat". \quest How to make sense of definitions of items in the "Diskette menu" (lines 172--179). \answ The environment variable "AR" means the direction of copying (from or onto the disk), and the variable "D" is the letter of the chosen diskette drive (either A or B). The batch works with both variables, and therefore the values as stored in the file "envir.bat" in the form of a command "set". Moreover, the value "D" is stored also locally, because it is used when opening the window with the item 105 (there is a variable text reading "Insert diskette to drive [%D%]" ). \quest In the window with ``final question'', the numbers in the window definition do not match with the number of items. Unlike the window 100, there are less numbers then items (lines 186--189). \answ The program jumps to the item 0 (i.e.~"Yes") when closing all windows, that is if "Esc" was pressed in the main menu. The item "No" does not need to have a number, because the program does not leave it, but the window with the item 3 is opened. \quest How to arrange the final question, where "No" is implicitly offered. \answ In the window definition, we write e.g.: " ^ 1, 0 "; and in the control batch, we use the commands "if errorlevel" to ensure that the batch terminates in the case of "errocode=1". \quest Why is the item "DOS" solved intricated using the file 3 (i.e. the auxiliary file "dos.bat", see line 203). Is it not sufficient to call a line process by a definition: "{*"\dd"#"\dd">0} "? \answ Yes, it will do. But there is a little defect here. The user would like to find the last edited value under the item "DOS". We cannot guarantee it other way than to store this value in a file. The MNU program should terminate and restart several times before the user wishes to use the item "DOS" again. \quest Why are items with the same number in "Print menu" ? (See line 49.) \answ Why not? If user chose the item, the error code of program terminating is set to the number of chosen item and this does not make any conflict. The batch "print.bat" branches next process by the environment setting and not only by the error code. \quest There is an error in the definition of the editable variable in "METAFONT parameters"! The line 210 \begtt METAFONT |#[%4% 31, 1, 66]|{!>4, "[%4% 1, 1, 30]#">4} \endtt \hangindent\parindent means that the program first reads 66 characters of the text from the file 4 ("mfbat.bat") and opens the window with editable item. After editing, the file 4 is reset by the command "!>4". Thus, the following construction "[%4% 1, 1, 30]" returns a blank string from the resetted file instead of first 30 characters of the old contents of file as intended by the programmer of this definition. \answ Congratulations. If you have succeeded to discover this discrepancy by yourself, it is evident that you are an attentive reader of the documentation. The moment, when the substitution in the constructions "[%...]" is performed, is not stressed there. The substitution is done during opening the window, and all the text related to the opened window is kept in the memory in the substituted form. The commands defining the item reaction are performed only when the item has been chosen by the key "Enter". These commands are not read from the file, but from the memory, where the substitutions have been done. Therefore it works properly. \sect 6. History %%%%%%%%%%%%%%%% \noindent Euro-\TeX-92: The first public version. \begitems * 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) \enditems \noindent The last change: January 1993. \bye