summaryrefslogtreecommitdiff
path: root/systems/msdos/tx/tx.doc
diff options
context:
space:
mode:
Diffstat (limited to 'systems/msdos/tx/tx.doc')
-rw-r--r--systems/msdos/tx/tx.doc324
1 files changed, 324 insertions, 0 deletions
diff --git a/systems/msdos/tx/tx.doc b/systems/msdos/tx/tx.doc
new file mode 100644
index 0000000000..a1da185b07
--- /dev/null
+++ b/systems/msdos/tx/tx.doc
@@ -0,0 +1,324 @@
+ ************************************************
+ 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.
+