summaryrefslogtreecommitdiff
path: root/support/mnu/examples.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/examples.doc
Initial commit
Diffstat (limited to 'support/mnu/examples.doc')
-rw-r--r--support/mnu/examples.doc326
1 files changed, 326 insertions, 0 deletions
diff --git a/support/mnu/examples.doc b/support/mnu/examples.doc
new file mode 100644
index 0000000000..7ce7152eef
--- /dev/null
+++ b/support/mnu/examples.doc
@@ -0,0 +1,326 @@
+
+ *****************************************************************
+ * *
+ * Program MNU *
+ * *
+ * A configurable menu for starting applications under DOS *
+ * *
+ * (The description of Examples ) *
+ * *
+ *****************************************************************
+ Prague, January 1993 Petr Olsak
+
+
+In the demo batches you can find some methods and tricks used with the MNU
+program. There are two examples.
+
+For documentation of MNU program see files README.TXT and MNU.DOC .
+
+
+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:
+
+ ---------------------------------------------------
+ demo.bat The control batch
+ demo.mnu The configuration file
+ envir.bat The auxiliary batch (it will be created)
+ ---------------------------------------------------
+
+Remarks
+-------
+
+** 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
+
+ if errorlevel ... goto ...
+
+ 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'').
+
+** 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.
+
+** If the user changes the file name (value of the "FILE" environment
+ variable), the program MNU writes the line
+
+ set FILE=<newname>
+
+ 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.
+
+** 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".
+
+** 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.
+
+** If user press the "Esc" key, the MNU program searches the item with
+ number zero and the "Quit" item offers.
+
+
+2. The second more complicated example
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+This is the example of emTeX configuration using the MNU program.
+The files listed below are really used in CSTeX package. In this package
+distributed by CSTuG (Czechoslovak TeX Users Group), the emTeX
+programs and MNU configuration are included. The MNU configuration is
+separated from the CSTeX package and included as the example here.
+
+ ----------------------------------------------------------------
+ demotex.bat This batch starts the example
+ texset.bat Initialization batch
+ texbat.bat The main loop
+ texrun.bat,
+ others.bat,
+ prints,bat,
+ metafont.bat The applications batches (called from "texbat.bat")
+ cfg.mnu The configuration file for menu
+ sorry.mnu The configuration file for ``sorry-messages''
+ texcfg.bat User's configuration
+ mfbat.bat The auxiliary batch (it can be changed)
+ gfbat.bat,
+ dos.bat",
+ envir.bat The auxiliary batches (they will be created)
+ dupcent.exe Duplicates the "%" character (utility program)
+ totext.exe Sets the screen to text mode (utility program)
+ kalk.exe Calculator -- a simple application program
+ kalk.hlp help texts for "kalk.exe"
+ dupcent.c,
+ totext.c The source codes for utility programs
+ -----------------------------------------------------------------
+
+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 CSTeX 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.
+
+
+Remarks to "demotex.bat"
+------------------------
+
+** 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.
+
+** 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).
+
+** The ``starting batch'' "demotex.bat" has others names in original
+ CSTeX package: "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)
+
+ latex <filename>
+
+ All working files (".tex", ".dvi", ".log", etc.) will be created in the
+ current directory.
+
+
+Remarks to "texset.bat"
+-----------------------
+
+** There are "set" commands here to set the environment of emTeX
+ 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:
+
+ set TEXDIR=c:\emtex <the main directory with programs>
+ set TEXDIRCFG=c:\emtex\cfg <the directory with configuration files>
+ set RAM=e:\temp <ram disk with directory for temporary files>
+ set EDIT=c:\editors\ne <the main editor>
+ set SHELL=c:\nc\nc <the file manager>
+
+** 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.
+
+** 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").
+
+** The "texset.bat" calls the "texbat.bat"--the main loop of
+ applications (see line 61).
+
+
+Remarks to main loop "texbat.bat"
+---------------------------------
+
+** The MNU is called here (compare with "demo.bat" from previous
+ example). Then the process branches to individual applications or
+ application batches.
+
+** The auxiliary batch "envir.bat" is called after each MNU run to
+ restore the global environment setting (see line 5).
+
+** 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 CSTeX
+ offers many variabilities that no all programs can be installed.
+
+** The "texbat.bat" calls directly only some applications, others are
+ called via application batches. You can compare this batches to
+ ``procedures'' in programming languages.
+
+
+Remarks to batches "texrun.bat", "others.bat", "prints.bat" and "metafont.bat"
+------------------------------------------------------------------------------
+
+** The error code from MNU is still stored and the process branches to
+ individual applications again.
+
+** The ``sorry handling'' is similar as in the "texbat.bat".
+
+** The individual application will not work in demo version because they
+ are not installed.
+
+** Some tricks are used here. These tricks are related to emTeX
+ configuration itself and they are not in our first interest while we
+ are studying the MNU philosophy.
+
+
+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.
+
+? Where to look for the item 100 defined in the line " ^ 100 \" (see
+ line 10).
+
+! 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 "\").
+
+? Why is the result of choosing (e.g. "amstex") in "Formats menu"
+ stored not only in the environment variable, but also in the file 2 in the
+ form "set FMT=amstex">2 (see line 122).
+
+! The command "csAMSTEX">FMT 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 "set FMT=amstex">2
+ enables to forward the information about the chosen format to the
+ control batch via the file 2, i.e. the file "envir.bat".
+
+? How to make sense of definitions of items in the "Diskette menu"
+ (lines 172--179).
+
+! 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%]" ).
+
+? 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).
+
+! 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.
+
+? How to arrange the final question, where "No" is implicitly
+ offered.
+
+! 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".
+
+? 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: {*"#">0} ?
+
+! 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.
+
+? Why are items with the same number in "Print menu" ? (See
+ line 49.)
+
+! 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.
+
+? There is an error in the definition of the editable variable in
+ "METAFONT parameters"! The line 210
+
+ METAFONT |#[%4% 31, 1, 66]|{!>4, "[%4% 1, 1, 30]#">4}
+
+ 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.
+
+! 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.
+