path: root/systems/msdos/tx/tx.doc

        ************************************************
        TX: A flexible menu system for TeX users in a pc
        ************************************************

Tx provides a system of interrelated menus intended primarily to be used
with TeX. However, since the menus are completely definable by the user,
tx could, in principle, be used as a front end for any other application.

The program occupies about 80Kb of RAM. It uses Ralf Brown's "spawno" 
library to swap out of dos memory when executing other programs.

                     ********************
		     COMMAND LINE OPTIONS
		     ********************

The syntax of the command line is:

             tx [-h] [-e num] [-m] [@cnfname] [wfname]

where square brackets indicate that an item is optional.
"-h" prints a usage message and exits.
"-e num" sets the environment size for child processes. This may be
   necessary, for instance, if you want to execute a program that
   tries to define some environmental variable. If you receive 
   messages like "out of environment space", set "num" to a high
   enough value. The program will exit if "num" is smaller than
   256. (Note: when spawning a new process or command processor, 
   dos ignores the environment size you currently have; modifying 
   the config.sys to set up a higher value in the shell statement 
   does not help---you still have to use the -e option here.)
"-m" sets a monochrome display.
"cnfname" denotes the configuration file name (see explanation below).
"wfname" indicates the working file name.

For instance, the following are all valid calls:

               tx 
               tx -e 4096 @c:\dos\myconf.cnf mypaper.tex
               tx -m -e 1024

If you hit "tx -h" a brief message will appear and the program will exit.


                     ******************
		     CONFIGURATION FILE
		     ******************

Tx requires a configuration file to start working. The configuration file
contains the menu entries and the commands associated with each entry.

There are three ways of specifying the configuration file to the program.
In order of descending precedence, they are:

  (1) Type the configuration file name in the command line, preceded by an
      `at' sign @. For instance, if `$' is your prompt, either

                $ tx @c:\thing\config.ego mytex.tex
      or
		$ tx mytex.tex @c:\thing\config.ego
      or
		$ tx @c:\thing\config.ego

      are valid commands. The two first commands are equivalent, and 
      tell tx that the configuration file is "c:\thing\config.ego", and 
      the working file name is "mytex.tex". The third call sets the 
      configuration file to c:\thing\config.ego, and lets tx use the 
      default working file name, which is "work.tex". By preceding the 
      configuration files with an @ sign, we follow emTeX standards.

  (2) If the configuration file has not been entered in the command 
      line, the program looks for the default configuration file 
      "tx.cnf" in the same directory where "tx.exe" resides. For instance, 
      if both programs are in c:\emtex\bin, you don't need to type 
      the name each time you run tx. (NOTE: If you rename "tx.exe" to, 
      say, "menu.exe", then the default configuration file name becomes 
      "menu.cnf".) This should be the usual procedure, as it does not
      require any specific user input.

  (3) If neither of the two previous methods worked, then tx checks whether
      the environmental variable "TX" has been defined.  For instance,
      if you type

                $ set TX=c:\thing\config.ego
                $ tx mytex

      the effect is the same as you would get in the first and second
      examples above, provided you do not have a file named "tx.cnf" in 
      the directory where the executable resides.  If you want to use 
      this option permanently, you can write the "set 
      TX=c:\thing\config.ego" command in your autoexec.bat file.  
      (NOTE: Renaming "tx.exe" does NOT change the name of this 
      environmental variable. You can change it by editing "txdefs.h" 
      and recompiling the program.)

If everything else failed, a brief help message is shown and the program
exits. This structure allows the user to have multiple configuration files;
the usual configuration file can be the default (tx.cnf), and alternative
configuration files can be entered in the command line. 

From now on, we will refer to the text of the menu entries as `text', and
to the corresponding commands to be executed as `actions'.

The limits imposed by the program are the following:

    (1) There is a maximum of 10 menus, numbered from 0 (main menu) to 9.

    (2) There is a maximum of 10 entries per menu, numbered from 0 to 9.

    (3) Each menu entry can have a maximum width of 60 characters. Commands
        in the configuration file have a DOS limit of 128 characters. Typed
	commands have a limit of 80 characters.

(NOTE: You can change the above, as well as many other, things in the
program by editing the header file "txdefs.h" and recompiling.)

The format of the configuration file is as follows:

--> The lines must appear in pairs. The first line is a `text' entry, and
    the next line contains the command (`action') that corresponds to it.

--> Each `text' line must be numbered, starting at 0. These entries will
    appear literally in the menus the program shows, provided they do not
    exceed the 60 character limit. `Action' lines should NOT be numbered.

--> A `text' or `action' entry terminates with the linefeed (ASCII 10)
    character that marks the end-of-line. If an action extends more than
    the 80th position, you must configure your text editor so it allows
    you to continue typing beyond that limit.

--> Comments may be inserted anywhere with a percent (%) sign, following
    the TeX conventions: whatever appears from the % (including it) till
    the end-of-line is ignored. Empty lines and extra spaces are also
    ignored.

--> Inside `text' and `action' entries, the following conventions are
    used:

    #name         Will be replaced by the working file name, without
		  path or extension.

    #ext          Will be replaced by the extension of the working file.

    #path         Will be replaced by the working drive and directory.

    #/path        This works exactly as in the previous case, with the
                  only difference that the backslashes used by DOS to
                  separate directories will be replaced by forward
		  slashes.

    #menu <n>     In an `action', the choice of that option will cause the
		  appearance of the nth menu. If n is not given (or is
		  invalid), the main menu (number 0) will appear. Inside of
		  `text', the string is interpreted literally (that is, it
		  has no effect).

    #find         In an `action', the choice of that option will be
		  followed by the appearance of a window displaying the
		  files in the current directory. You can navigate
		  through your file system and choose a new working
		  file.  Inside of `text', the string is
		  interpreted literally.

    #new          In an `action', the choice of that option will be
		  followed by a prompt asking the user to enter a
		  new working file name. This new name can be entered
		  with a full path.

    #dos          In an `action', the choice of that option will be
		  followed by a message prompting the user to type in a
		  DOS command, which will be executed immediately in a
		  subshell. Inside of `text', the string is interpreted
		  literally.

    #end          In an `action', the choice of that option will end the
		  program. Inside of `text', the string is interpreted
		  literally.

    +             A plus sign at the beginning of a line, indicates that
                  a new menu is going to start. You cannot have any other
		  entries in the same line. Inside a text or action entry,
                  a plus sign is interpreted literally.


Sample configuration file:

%  Beginning of sample configuration file
%
% Menu 0: main menu
%
0. Edit #name#ext
jed #name#ext
1. LaTeX #name.tex
tex386 &latex2e #name
2. View #name.dvi
dvidrv dviscr @c:\emtex\data\lj.cnf /ocr=1 /o3 /fl=-1 #name
3. Create #name.lj
dvidrv dvihplj @d:\emtex\data\lj.cnf /po=#name.lj #name
4. Find new working file name
#find
5. Type new working file name
#new
6. DOS command
#dos
7. Auxiliary programs
#menu 1
8. Exit
#end
%
% Menu 1: auxiliary programs
%
+
0. Send #name.lj to printer
copy /b #name.lj lpt1
1. Create #name.ps
dvips -o #name.ps #name
2. View #name.ps
gs386 #name.ps
3. Send #name.ps to postscript printer
copy /b #name.ps lpt2
4. TeXEdit #name.tex
te /l#name #name
5. Plain TeX #name.tex
tex386 &plain #name
6. LaTeX-2.09 #name.tex
tex386 &latex209 #name
7. DOS command
#dos
8. Go back to main menu
#menu 0

% A new menu could follow now, preceded by a + sign.
% Tx allows up to a maximum of 10 menus (0 to 9) to be defined.
% Each menu can have a maximum of 10 options (numbered 0 to 9).
%
% End of sample configuration file.

                           ***********
		           TX COMMANDS
		           ***********

The program is very simple: each time a command is not being executed, a
menu appears and prompts you to choose the number that corresponds to
one of the options listed. If you press the space bar, the menu will
disappear and the screen will be restored, so you will be able to see,
for instance, any error messages or warnings issued by the last program
you ran; any keypress will restore the menu.

If you press a key that does not correspond to any of the listed options,
the default action will follow: "go back to main menu" (menu 0) if you are
at menu n > 0, of "exit the program" if you are at the main menu.
In the previous sample configuration file there was no need to have in
each menu an option to return to the main menu: this is the default, and
will therefore happen whenever you press any key that does not
correspond to one of the options listed; you could, for instance, press
the escape key to go back to menu 0 from any other menu. If you press
the escape key in menu 0, this will end the program.

If you like the program, use it or modify it to suit your needs.

                                            Ricard Torres
                                            torres@upf.es

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; version 2.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

    You will find a copy of the GNU General Public License in the file
    COPYING, that comes along with the tx source and executable files.

As mentioned above, this program has now been compiled using
Ralf Brown's "spawno" library, so that the program swaps out
of dos memory when running other processes. Here is the relevant
part of the documentation file that came along with the spawno
library:

-----------------  Excerpt from Ralf Brown's documentation -------------

SPAWNO v4.13   12/12/91   disk/EMS/XMS/INT15 swapping replacement for spawn()
(c) Copyright 1990,1991,1992 Ralf Brown.  All Rights Reserved.


-----------------
LICENSE

The source and/or object code comprising the public SPAWNO distribution
may be incorporated at no charge into programs which are distributed or
sold to others provided that:
     1) credit is given in the documentation.  A mention such as
	   "This product uses the SPAWNO routines by Ralf Brown
	    to minimize memory use while shelling to DOS and
	    running other programs."
	is sufficient.
     2) you drop me a line telling me that you are using SPAWNO and
	in which product(s) you are using it (see addresses at the
	end of this file).  I'm interested in finding out how wide-
	spread the use of SPAWNO becomes.


-----------------
DISCLAIMER

Although both I and others have tested the code which comprises SPAWNO,
it is entirely possible that SPAWNO may malfunction in environments or
under circumstances in which it has not been tested.  This code is
provided AS IS, and the author disclaims any and all responsibility for
damages (both consequential and incidental) resulting from the use or
misuse of SPAWNO.  Sole responsibility for determining the suitability
of the code rests with the user.

------------- End of excerpt from Ralf Brown's documentation -------------

In this case the direct user, the author of this program, disclaims
in his turn all responsibility and passes it along to the final user,
as specified in the GNU General Public License.