summaryrefslogtreecommitdiff
path: root/support/mnu/mnu.tex
blob: 396511482d36cf35b9650e15b266f04f668c7f3c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405

%  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 "[%<NAME>%<LENGTH>]", where the parameter <LENGTH> is optional.
\medskip

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.

\medskip
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> > 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).

{\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 {<NUMBERS>} "<HEAD>" ; <COMMENT>
\endtt

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

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

\begtt
  {<XMIN>, <YMIN>, <WIDTH>, <HEIGHT>, <FRAME>, <GROUND>, <ITEM>, <LETTER>, <A-ITEM>, <A-LETTER>}
\endtt

\noindent and their meaning is as follows:

{\narrower\parindent=0pt
<XMIN>, <YMIN> -- 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

}
\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 <HEAD> -- text (heading) to overwrite the middle of the window frame
top line. When not present, the frame is not interrupted.

\bull <COMMENT> -- 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
"       ^(<HELP>)  <ITEMS>  [<PARENT>] "{\tt\char60}"<L-R>>  \ ; <COMMENT>"
\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
<ITEMS>, are optional; the shortest window definition is of the form:
"^ <ITEMS>".

\bull "("<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.

\bull <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).

\bull "["<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.

\bull {\tt\char60}<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''.

\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
& "$"<CODE>     &&  program terminates with given error-code number &\cr
& <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). &\cr
& "\"          &&  The character "\" closes an active window. &\cr
& "*"          &&  Closing of all windows on the screen. &\cr
& \dd<TEXT>\dd">"<N>
   &&  If $<N> = 0$, <TEXT> is called as a DOS line. \hfil\break
       If $<N> = 1$, an error is reported.\hfil\break
       If $<N> > 1$, <TEXT> is added as the last line into the <N>-th file.
       \hfil\break
       If <N> is the name of an environment variable, <TEXT> is stored in
       it. &\cr
& "!><N>" or {\tt\char37><N>}   &&  <N> is to be $\null > 1$: reset of the
<N>-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<TEXT>\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<TEXT>\dd"><N>"  ($<N> > 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.

\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 "!><N>" and {\tt\char37><N>} both reset the <N>-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 "[%<N>%...]" will return a
blank string in such case.

\bull Strings \dd<TEXT>\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<n>{<REACTION>}, ... "
\medskip
\noindent
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''.

\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
 "!><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".

\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 {<FREQUENCY>, <DURATION>}
\endtt

\noindent
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).

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

\begtt
  ~mouse {<REG-CX>, <REG-DX>}
\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=<REG-CX>",
"DX=<REG-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
  |#<TEXT>|{<ACTION>}
\endtt

where

\bull <TEXT> -- is the text offered for editing.

\bull <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
\dd<text>\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
  |^<TEXT>|{<REACTION>}
\endtt
\noindent
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.

\medskip
{\bf A highlighted text} in the window can be defined in the form:

\begtt
  |!<TEXT>|{}
\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 <LENGTH> 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=<newname>
\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 <filename>
\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          <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>
\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