% % This is the source for the AmigaTeX manual. This manual is % (C) 1986 Radical Eye Software, All Rights Are Reserved. % It may not be duplicated in any form without the express % written permission of Tomas Rokicki or other Radical Eye % Software representative. % % The fonts are 10 point fonts with halfstep magnification. % % A few simple macros to handle sections and a table of contents: % \magnification=\magstephalf \hsize=6truein\hoffset=0.5truein \raggedbottom \def\cbanner{(C) Copyright 1987 by Radical Eye Software-{-}-All Rights Reserved} \def\banner{This is CTeX, Amiga Version 2.9c (preloaded format=plain 88.2.21)} \newcount\secno\newcount\subsecno \newread\tocf\newwrite\indx \def\sec#1{\global\advance\secno by1\global\subsecno=0 \vfill\eject \message{*\the\secno*} \write\indx{\noexpand\t #1\noexpand\\\the\pageno\noexpand\\} \noindent{\Bigf\number\secno.\ #1}\nobreak} \def\sub#1{\global\advance\subsecno by1 \write\indx{\noexpand\u #1\noexpand\\\the\pageno\noexpand\\} \par\medbreak \noindent{\bigf\number\secno.\number\subsecno\ #1}\nobreak} \def\toc{\secno=0 \def\leaderfill{\leaders\hbox to 1em{\hss.\hss}\hfill} \def\t##1\\##2\\{\global\advance\secno by1\global\subsecno=0 \vb\line{{\bf\number\secno.\ ##1}\leaderfill {\bf ##2}}} \def\u##1\\##2\\{\global\advance\subsecno by1 \vb\line{\hskip\parindent{\bf\number\secno.\number\subsecno\ ##1}\leaderfill {\bf ##2}}} \ct{Table of Contents} \vb \openin\tocf=\jobname.toc \ifeof\tocf\message{Table of contents file nonexistent} (none yet)\closein\tocf\else \closein\tocf\input\jobname.toc\fi \openout\indx\jobname.toc \global\secno=0 \vfill\eject} % % A few minor macros for convenience % \def\vb{\vskip\baselineskip} \def\ct#1{\centerline{\Bigf #1}} \def\ti#1{\leftline{\bigf #1}} \def\AT{Amiga\TeX} \def\.#1{\hbox{\tt #1}} \def\\{\hskip 0pt plus 1fill minus 1in\break} \def\cmd#1{\vb\vbox{\leftskip=\parindent\parindent=0pt\tt#1}\vb} \def\mcmd#1{\cmd{#1}\endgroup} \def\ttcmd{\begingroup\def\t{\strut\ \ \ } \catcode`\^=12 \catcode`\$=12\catcode`\~=12 \def\!{\ttbackslash}\mcmd} \def\ttbackslash{\char92} % % The manual is outlined; each outline line is preceded by a % pair of percent signs to be distinguished from comments. % % But first, the title page. % \font\Bigf=cmbx10 scaled 1577 \font\bigf=cmbx10 scaled 1315 {\null\vfil \centerline{\Bigf \AT} \vskip 5pt \centerline{\bigf An Implementation of \TeX} \vskip 2pt \centerline{\bigf for the Amiga} \vskip 12pt \centerline{Version 1.5} \message{AmigaTeX Manual, Version 1.5} \vskip 2pt \centerline{21 February 1988} \vfil \centerline{Copyright \copyright\ 1986, 1987, 1988 Radical Eye Software} \vskip 2pt \centerline{All Rights Reserved} \vskip 80pt \nopagenumbers \eject} % % License, use and release information % \ti{Software Licensing} \vb \noindent \AT\ is not a public domain software package. Use of \AT\ without a valid license is prohibited. Nothing included with \AT\ is copy-protected in any form both for the convenience of the user and because of the author's personal feelings on copy protection. Copies may be made of the components of \AT\ (which includes the programs \.{tex}, \.{initex}, \.{bibtex}, \.{preview}, \.{gftopk}, \.{pxtopk}, \.{pktype}, \.{unamiga}, and \.{set}) only as required for backup and convenient use on a single Amiga personal computer; any further distribution is strictly prohibited. \vb \ti{Manual Copyright} \vb % % A short message to warn the reader against printing out this % manual. % \message {This manual is supplied as one of the examples for TeX on the Amiga.} \message {It may be used as an example TeX file; it can be run through TeX and} \message {displayed with the preview program. However, it may not be printed out} \message {or transmitted in any form, source, dvi, or otherwise. This manual is} \message {Copyright 1986-8 by Radical Eye Software, and all rights are reserved.} \message { ---Tomas Rokicki, Radical Eye Software} % % Don't forget to register this copyright! % \noindent Copyright \copyright\ 1986, 1987, 1988 by Radical Eye Software. All rights are reserved. No part of this publication may be reproduced, transmitted, transcribed, or otherwise distributed, without the prior written permission of Radical Eye Software. The \TeX\ source for this manual is stored on the distribution diskettes as one of the examples; this does not imply the right to print it out or transmit it in any form. \vb \ti{Disclaimer} \vb \noindent Radical Eye Software makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Radical Eye Software reserves the right to revise this document and the enclosed software without obligation of Radical Eye Software to notify any person of such revision. \vb \ti{Trademarks} \vb \noindent % % Register this trademark, and then remove this comment! % %\AT\ is a trademark of Radical Eye Software. \TeX\ is a trademark of The American Mathematical Society. Amiga is a trademark of Commodore-Amiga, Inc. Unix is a trademark of Bell Laboratories. IBM is a trademark of International Business Machines. HP and LaserJet are trademarks of Hewlett-Packard Incorporated. PostScript is a trademark of Adobe, Incorporated. Dr.~Pepper is a trademark of the Dr.~Pepper Company. \vfill \eject % % A table of contents % \toc % % Now we have the introduction % %% %% AmigaTeX manual outline %% \null\vb\vb \ct{\AT} \vb \ct{Users Manual and Installation Guide} \vb\vb\vb\vb Welcome to the world of \TeX\ on the Amiga. If you have used \TeX\ on other computer systems, you will feel at home with \AT. If you are a newcomer to \TeX, welcome! You will find the Amiga to be a powerful machine on which to learn \TeX\ and develop your documents. \vb We want to hear from you! Positive comments inspire further work on the product, and negative comments indicate a direction to proceed. If you have any difficulty getting the package up, let us know! It is preferred that you write to Tomas Rokicki at Box 2081, Stanford, CA~~94309; if you must call, the telephone number is (415) 326-5312. Do not let the complexity of the package intimidate you; if you can't get something to work, either we haven't explained things correctly, or there is a bug. \vb If this is an update of the previous release for you, you might want to skip ahead to the `recent changes' section and simply read that. \vb To run \AT, you need at least 512K of RAM and at least two floppy drives, one floppy drive and 1.5M of RAM, or one floppy and a hard disk, and version 1.2 or later of the Amiga operating system. Before we jump in, a few comments must be made about conventions used in this manual. %% I. Manual organization and conventions \vb All commands and file names will be set in typewriter type. Commands are separated from the accompanying text by blank lines, and are preceded by any prompts that are not typed by the user. For instance, to list the size of the file \.{foo.bar}, you would type \cmd{1> list foo.bar} \noindent In this example, `\.{1> }' is the CLI prompt (yours may be different), and you would not type those letters. (CLI stands for Command Language Interface.) The word \.{tex} refers to the program \TeX\ as it has been ported to the Amiga; the word \TeX\ refers to the more general software package and typesetting language that runs on a wide variety of machines. Any unfamiliar terms may be looked up in the glossary at the end of this manual. %% II. First run %% A. Backup the supplied disks! \sec{First Run} \vb Before you run any of the supplied software or even examine the contents of the disks, you should back them all up. There are two ways to back up floppies on the Amiga: using the CLI and using the workbench. \vb \sub{Copying Floppies Using the CLI} \vb If you are familiar with the CLI, the easiest way to back up floppies is to type \cmd{1> diskcopy df0:\ to df1:} \noindent The system will prompt you to insert the floppies. Insert the original floppy into the drive on the main system; insert a blank floppy into the external drive, and hit carriage return. The system should copy the disk and give you another prompt when it is done. If the system responds instead with: \cmd{1> diskcopy df0:\ to df1:\\ Unknown command diskcopy\\ 1>} \noindent First, insure that you typed the command name correctly. If you did, then your system does not have a CLI diskcopy routine; so you will have to use the following procedure for the workbench. Even if it did work, if you are unfamiliar with the Amiga, you might read the following description to understand how to interact with the Amiga using the mouse, icons, and menus. \vb \sub{Copying Floppies Using the Workbench} \vb Copying floppies using the workbench is easy, despite the length of the following description. Insert the original floppy into the internal drive and a blank disk into the external drive. After a second or two, an icon (small symbol above a name used to represent a file or device on the amiga) should appear on the screen for both disks. The blank disk might have an icon with the name \.{DF1:BAD}. Don't let that worry you. The floppy is simply unformatted, and the diskcopy operation will format it as it copies. Now, using the mouse, move the arrow until its tip is over the icon representing the original disk. Hold down the left mouse button (the select button) and `drag' that icon until it rests on top of the icon for the blank disk. Now release the select button. \vb The machine might now prompt you to replace the workbench floppy into any drive. The prompt is called a `requester' because it requests something from the user before the operation can proceed. In this case, it needs to load the diskcopy program into memory, and that program resides on the workbench disk. Remove the floppy from the internal drive and re-insert the workbench floppy. After a few seconds, the system will prompt you to replace the disk from which you are copying into the internal drive. Remove the workbench floppy and re-insert the disk it replaced. \vb {\bf NEVER REMOVE A DISKETTE WHILE THE DRIVE LIGHT IS ON. This can destroy any data on the floppy. Even when the system puts up a requester, wait until the drive light goes out before removing the floppy. This is important; you might consider re-reading this paragraph.} \vb If everything went as it should, you should now have another requester on the screen titled \.{Disk Copy}. Move the mouse pointer over the {\it Continue\/} option, and hit the select button. The copy operation should start and finish a few minutes later. You have just backed up a floppy. Remember this operation; you should use it often to guard against bad floppies, electrical storms, and three-year-old popsicle eaters. \vb We are not done yet. If you look at the icons on the workbench, you will notice that the new floppy is called \.{copy of foo.bar} if the original disk was called \.{foo.bar}. If you are making copies of the distribution floppies from which to work, this name will not do, since \AT\ will often request a specific floppy by name. Therefore, you will need to rename the floppy. To do this, move the mouse pointer over the icon for the new copy, and press and release the select button. The icon should turn from white to black. Now hold down the right mouse button (the menu button). The title bar on the workbench should change to show \.{Workbench}, \.{Disk}, and \.{Special}. Move the pointer (still holding down the menu button) over the word \.{Workbench}. A menu should appear. \vb Now, still holding the menu button down, drag the mouse pointer down until it is over the word \.{Rename}, and release the menu button. This is how menu selections are made on the Amiga. A thin box should appear in the middle of the screen with the name of the selected icon in it. (If you are using version 1.1 of the operating system, you will need to move the mouse pointer until it lies within this box, and hit the select button. Anything you type before this will be ignored.) Now, simply hit the {\it DEL\/} key on the keyboard (in the upper right) eight times, until \.{copy of} disappears and the cursor is on top of the first character of the original name. Now hit the {\it RETURN\/} key, and the name of the icon should change. Appropriatel label the new copy you just made, with a paper floppy label, put the original disk away in a safe place, and repeat for all of the distribution floppies. \vb %% B. Set the Amiga to 80-column mode, CLI on \sub{Setting up Preferences for \AT} \vb \AT\ must be run in the 80-column mode and using CLI. If this is not how your system is configured, or you are not sure, you should go into preferences. \vb To go into preferences from CLI, type \cmd{1> df0:preferences} From the workbench, move the pointer over the \.{workbench} icon, and double click (hit the select button twice rapidly). Next, double-click over the \.{Preferences} icon that should appear inside the workbench window. Your screen should change into the \.{Preferences} screen. \vb Look in the middle of the left side of the screen; you should see the words \.{Text} and \.{CLI}, each with two little boxes to the left of them. The selected box should be \.{80} for \.{Text}, and \.{On} for \.{CLI}. If they are not set correctly, simply select the appropriate box with the mouse and select button. If they needed changing, you now need to select the \.{Save} option in the lower right corner of the screen and reboot; if the options were correct, you can select the \.{Cancel} option. To reboot, simply hold down the {\it CTRL} key (middle left of the keyboard) and the two Amiga keys (fancy `A' keys on either side of the space bar) at the same time. \vb %% D. Get in a CLI, open to full width of screen \sub{Getting Into a CLI} \vb Now you need to get a CLI window to work with. If you already have opened a CLI, fine; you are in good shape. Otherwise, the following procedure will open a CLI window for you. \vb Double click on the \.{workbench} icon if the \.{workbench} window is not already open. Within the \.{workbench} window, you should see an icon labeled \.{CLI}. If you don't see this icon, double click on the \.{system} icon to open its window; the \.{CLI} icon should be in this window. If it is not, check preferences again to insure that the \.{CLI} has been turned on. If all else fails, reboot, and when the screen first turns blue, hold down the {\it CNTRL\/} key and hit the `d' key until the word {\it BREAK\/} appears. Now you are in a CLI. \vb If the CLI you are in does not extend to the full width of the screen, you will need to resize it. This is done by first selecting the title bar of the CLI window (where the word \.{CLI} or \.{AmigaDOS} is) and dragging the whole window until it is flush with the left of the screen. Next, select the sizing gadget in the lower right of the window, and drag it until it is flush with the right of the screen. \vb %% Stack requirements \sub{Stack requirements for \AT} \vb \AT\ requires more stack space than is provided by default on the Amiga. This is also true of a lot of other programs for the Amiga, so this paragraph may cure some problems you may have been having on your system. In the CLI window you created, type \cmd{1> stack} \noindent If the number displayed is 4000, then you need to set your stack to a larger value. To do this at the command line, simply type \cmd{1> stack 10240} \noindent This is sufficient for almost all programs. If another application requires a larger stack, you should increase that number. Note that in general, this command should go into your \.{s:startup-sequence} file. \vb %% C. 512K system? Move some files around. \sub{Setting Up a 512K System} \vb If your Amiga has 512K of RAM, you will need to make some changes to the supplied disk to start. Before you read any further, make sure that you have backed up the distribution diskettes, and are working from your own copies. The following step, if run on the distribution floppies, will destroy a file that you will need if you ever get more memory. With that caveat, please continue. \vb To set up \AT\ for a 512K system, insert the floppy labeled \.{TeX} into the external drive. From the CLI, type \cmd{1> execute tex:s/to-512} (Note that the Amiga is case insensitive; upper and lower case in file names are equivalent. Thus, though the floppy is really named \.{TeX}, it can be referred to as \.{tex}.) After a few seconds, it should prompt you to insert the disk labeled \.{TeXfiles} into the internal drive, and then to reinsert the workbench disk. After the operation is complete and the floppy drive lights have gone out, reboot the machine. %% E. Run TeX on samples/story.tex \vb \sub{Running \TeX} \vb Now you are ready to run \TeX. If you are ambitious and familiar with \TeX, you may choose to prepare a short sample file at this time. For those not familiar with \TeX\ and for those in a hurry, we have prepared a few sample files. At this point, you should be at a CLI prompt. Insert the disk labeled \.{TeXfiles} into your external drive, and type \cmd{1> texfiles:c/tex} The disk will grind for a while, and then a requester for the floppy labeled \.{TeX} will appear. Remove the \.{TeXfiles} floppy and insert the \.{TeX} floppy in its place. After a few seconds, \TeX\ should appear with the following hello: \cmd{\cbanner\\ \banner\\ **} \noindent If instead you get the message \cmd{Out of memory during allocation!} \noindent then there are several possibilities. If you are running on a system with more than 512K of RAM, you must have too many things in memory at the moment. Shut down some other programs and try again. Or possibly you have not told the system about your extra memory; the Amiga 1.1 operating system does not automatically recognize expansion memory, and some memory boards are not recognized under 1.2. Amiga\TeX\ requires the 1.2 operating system. Consult the documentation supplied with your memory boards. If you are running on a 512K system, perhaps you didn't follow the above instructions that pertain to you. Alternatively, you might have some files in RAM disk. Try rebooting. \vb The double asterisk (\.{**}, also referred to as double splat) prompt is \TeX's way of asking you for a file name. Type your own file name if you have prepared a file, or type \cmd{**story} \noindent if not. There will be a pause of approximately five seconds, after which the screen should look like this: \cmd{\cbanner\\ \banner\\ **story\\ (tex:inputs/story.tex [1])\\ *} The single asterisk prompt indicates that it is finished, and is waiting for more commands. At this point, simply type \cmd{*\ttbackslash bye} A few more seconds should go by, and then \TeX\ should reappear with another double splat prompt. This is because of the `loop mode' that will be explained later. For now, just hold down the {\it CNTRL\/} key and press the `F' to get the CLI prompt back. Congratulations! You have just finished your first \TeX\ job on the Amiga! \vb %% F. Run preview on story \sub{Running Preview} \vb Now you are probably anxious to see what the output looks like. To see, insert the \.{TeXfiles} disk into the external drive, and type \cmd{texfiles:c/preview story} \noindent Wait for the external drive light to go out, and insert the \.{TeX} disk. Your file should appear on the screen. If you are ambitious, you might try figuring out how to work the preview program at this point, using what you know about gadgets and menus. Otherwise, you can exit the program by selecting the square gadget in the upper left corner of the screen with the select button, or simply by hitting the `Q' key on the keyboard. If all else fails, reboot and read further. \vb Do not be discouraged by the apparent awkwardness of this process. Setting up an interactive, multitasking \TeX\ environment is described later. You might care to take a breather here, so you can enjoy the descriptions of \TeX\ and the Amiga which follow. %% III. What is TeX? %% A. Purpose \sec{What is \TeX?} \vb \TeX\ is a typesetting language and system developed by Professor Donald Knuth of Stanford University over the period 1977 to 1986. It was designed to be used in typesetting books and manuscripts, especially those containing much mathematics. The current version of the language has been stable since 1982, and is currently in use at thousands of computer installations all over the world. \vb %% B. User interface The input to \TeX\ is somewhat free format; it is emphatically not a \hbox{WYSIWYG} (what you see is what you get, often rephrased as what you see is all you get) system. The source can be created with any typical text editor, and for the most part spacing and line breaks in the input are ignored. Interspersed with the text are various typesetting commands that might, for instance, change fonts or skip to the next page. \TeX\ is programmable with paramaterized macros and user variables of a number of types, allowing the creation of macro packages that extend the power of \TeX\ or make it more accessible. \vb \TeX\ is not the solution to all the world's ills. As a document preparation system, it has three major deficiencies. First, it does not directly support graphics. You can use horizontal and vertical rules, and do some limited graphics using a variety of methods: La\TeX\ supports some graphics operations, and most PostScript printer drivers allow inclusion of graphics commands. Secondly, \TeX\ does not easily do complicated page layout, as might be required for newspapers, for instance. And finally, \TeX\ does not allow interactive editing and viewing of the document as it is being developed. \vb All of these are design decisions; \TeX\ was never intended to address any of these concerns. What \TeX\ does, however, \TeX\ does well. It supports a huge library of fonts, and additional fonts can be purchased from a number of companies. It supports full kerning and ligatures in its fonts. It has no equal when typesetting complicated mathematical formulas and displays. Its hyphenation algorithm is among the best in typesetting systems, and its line- and page-breaking algorithms are nothing short of incredible. \vb \TeX\ is a complicated system, because typesetting is not a simple task. It is easy to generate quality documents without knowing much about \TeX, but as your experience and requirements grow, you will find that \TeX\ has the power, programmability and expandability to handle your most demanding needs. \vb %% C. Device and computer independence One of the primary objectives of Knuth in writing \TeX\ was computer and printer independence; the output you display on your Amiga screen should appear (within the resolution limits of the device) exactly the same as the output on the professional typesetting equipment of Addison-Wesley, for instance. The same source should work and generate identical output on all computer installations that run \TeX. \vb %% D. Processing; explanation of file types To illustrate \TeX, the processing of our sample \.{story.tex} above is going to be examined, and each file used by \TeX\ in the creation of the document will be explained. The source was typed in by hand from the first example in {\it The \TeX book,} page 24, and as all source files for \TeX\ should, it has the extension \.{.tex}. \vb Some of the commands used in \.{story.tex} are not a part of primitive \TeX; primitive \TeX\ is very primitive indeed. Therefore, \TeX\ by default loads a set of macros called `plain \TeX' into memory. Rather than load these macros in as \TeX\ source (which it could), it instead loads them in a pre-digested form called a `format file', with the extension \.{.fmt}. This \.{plain.fmt} file contains essentially a memory image of \TeX\ after all of the macros in plain \TeX are loaded. \vb Primitive \TeX\ does not know any characteristics of any fonts, either. Therefore, a number of font metric files with the extension \.{.tfm} were loaded while the \.{plain.fmt} file was created. These files contain information about individual characters in the font and the font as a whole, such as the height, width, and depth of each character, what ligatures the font contains, and what kerning is necessary between which characters. There is one of these files for each font accessible to \TeX, and they contain only information about the fonts that is independent of the output device. \vb As \TeX\ was processing \.{story.tex}, it created two files, one with the extension \.{.log} and one with the extension \.{.dvi}. The log file contains essentially a listing of the run as it was seen from the terminal, including any error messages that were displayed. This file is useful if an error message was too long and scrolled off the display, for instance; various switches can also be turned on inside \TeX\ to display more information about what is happening during the typesetting process. The main output file of \TeX\ is the device-independent file, with the extension \.{.dvi}. This file contains a description of the final document, including the location and font of each character used. The units used in this file are not based on any particular device, and the actual characters themselves are not described. It is up to another program, the `driver', to interpret this \.{.dvi} file, look up the appropriate raster representations of the individual characters, and create the final document. \vb The preview program is one such program. It `drives' the Amiga screen, loading font raster information from a collection of packed, or \.{.pk}, files. There is one of these files for each font at each size, since the raster description of a character is by its very nature dependent on the resolution of the output device. \vb %% E. Reference to TeXbook, LaTeXbook This was intended to be a simple description of \TeX; for more information, please refer to {\it The \TeX book\/} by Donald Knuth and {\it La\TeX\ User's Guide and Reference Manual\/} by Leslie Lamport, both published by Addison-Wesley Publishing Company and available in most college bookstores. \sec{Introduction to the Amiga} \vb The Amiga is an impressive computer system that is well suited to \TeX\ for a number of reasons. The high-resolution graphics built into the machine allow high-quality preview of the output. Multitasking and a large memory capacity allow the editor, previewer, \TeX, and even other programs to be concurrently resident and active, yielding a much more interactive environment than is possible on any other microcomputer. Intuition, the Amiga windowing software, ties these and other packages together into a unified, convenient, natural interface for the user. \vb The section title is somewhat of a misnomer, since if you have run the sample, you are probably familiar with the Amiga by this time. Nonetheless, there are a few things that have not been covered yet. \vb %% IV. Introduction to the Amiga %% A. Mouse %% B. Gadgets The mouse is the primary input device for the Amiga. The point and click approach is easy to master. The Amiga mouse has two buttons, the select button on the left and the menu button on the right. The select button is used for selecting data, operations, windows; the menu button is used to select among a number of alternative actions or settings. Gadgets are graphic images that are associated with a particular action; moving the mouse pointer over them and clicking the select button starts the operation. Note that for most gadgets, the mouse must remain over the gadget while the button is both pushed and released; it is the release on the gadget that actually signals the operation to begin. \vb %% E. Menus Menu items are selected by pressing and holding the right mouse button as the pointer is moved first to the title bar to select the particular menu, and then down the menu (and possible sub-menus) until the appropriate action is found. It is the release of the menu button that starts the operation. \vb Windows and screens help separate the input and output of programs from one another, and to bring to display the information currently being worked with and hide irrelevant data. Screens occupy the full width of the video display and can only be dragged up and down. A typical screen is the workbench screen. Windows reside in screens, and can be an arbitrary rectangular portion of a screen. A window cannot be moved from screen to screen; once created, it is permanently associated with a particular screen. A window can be moved horizontally or vertically so long as it remains on the screen. \vb A window inherits the video characteristics of a screen, but each screen can have its own characteristics. For instance, the workbench screen is a four-color high-resolution non-interlace screen; the preview screen is a two-color high-resolution interlace or non-interlace screen. Many graphics programs run in a 32-color low-resolution non-interlace screen. At any given time, either zero or one window is active. A screen is only `active' if a window on that screen is active. Inactive windows have their title bar cross-hatched over to indicate their status; the active window does not have this cross-hatch pattern. To select a window, you simply place the pointer inside that window and hit the select button. \vb %% C. Screens %% D. Windows To drag a window or a screen, select the title bar and move the mouse with the select button held down. A screen will move as the mouse moves; for a window, an orange outline of the window will move, and when the mouse stops moving, the window will be redrawn in its new position. The two gadgets in the upper right hand corner of a window or screen are the to-front and to-back gadgets; selecting the right-most gadget (to-front) brings the corresponding window or screen in front of all other window or screens, selecting its neighbor (to-back) pushes it in back of all others. Note that a window might cover the screen's to-front and to-back gadgets; full-sized CLI windows are typical culprits. You probably want to resize a full-sized CLI window to make it slightly shorter, and then drag it down a bit to expose the screen gadgets; otherwise, you cannot move among the various screens easily. \vb Windows usually have a sizing gadget in the lower right hand corner. This is used to change the size of a window; simply select and drag it. They also usually have a close gadget in the upper left hand corner; selecting this gadget terminates the program running in the window. Menus are associated with the active window, but are displayed on the screen title bar. Thus, one screen might have many possible menus, depending on which window is the active one. \vb An icon is a graphics image that represents a file or device. On the workbench screen, for instance, there is an icon for each disk. Files may or may not have an icon associated with them; currently, the \AT\ system does not use icons. Icons are selected with the select button; they are activated (if a program, it is run; if a directory, it is opened) by double-clicking on them. \vb %% F. CLI %% G. Multitasking %% H. Never punch out disk while light is on Another nice feature of the Amiga is that it doesn't restrict you to use the desktop metaphor (icons, menus and windows); you are free to use the more conventional CLI, or command language interface, under which you type commands with the keyboard. This is the primary environment \AT\ runs in. The Amiga CLI is a simple shell to the underlying TRIPOS-based operating system. As with any command-based interface, there are commands and conventions that must be learned. For instance, \.{cd} changes the current working directory; \.{dir} displays the names of all of the files in that directory, and \.{type} displays the contents of a file. For a description of these commands, refer to the {\it AmigaDOS User's Manual\/} published by Addison-Wesley, available where you purchased your Amiga. \vb If your Amiga makes annoying clicking noises every second or so, it is because your disk drives do not have floppies in them; insert blank floppies into the disk drives when not in use to keep the Amiga happy. %% V. Installation instructions \sec{Installation} \vb Now you are ready to install \AT\ onto your system. The next few sections each pertain to a certain part of the installation; read only those sections that pertain to you. \vb %% A. 512K system? Move files \sub{Installation on a 512K System} \vb \AT\ will run on a 512K system, but you will not be able to take full advantage of the package without additional memory. Normally \TeX\ alone requires 700K of RAM. In order to run \TeX\ on a 512K machine, several restrictions must be observed. The RAM disk cannot be used or even created. Note that any reference to the RAM disk will create it if it does not exist. To see if it exists, simply type \cmd{1> info} \noindent If it exists, it will be listed as a mounted disk, and you must reboot before you can run \AT. No other applications can be run at the same time as \AT; it needs all of the memory in the machine. La\TeX\ and other extensive macro packages cannot be run. Even with these restrictions, it is quite possible that you will eventually create a document that \AT\ cannot process because it runs out of memory internally. However, most typical documents should present little difficulty; \AT\ itself and this manual were both fully developed and run on a 512K Amiga. \vb %% 1. Procedure The version of \AT\ that runs on a 512K system is identical to the version that runs on a larger system, but the format files are different because of the different array sizes. In addition, a special file must be installed that informs \TeX\ of the sizes to make its internal arrays. Make sure that you have followed the procedure outlined in {\bf 1.5} above to move the files to their correct places. \vb %% 2. Upgrade procedure when you get more memory If you later get more memory and wish to use the full power of \AT, you will need to re-install the original format file. To do this, simply make a fresh backup copy of the first distribution diskette and use it instead of the \.{TeX} disk you used with 512K. \vb %% B. Floppy system? \sub{Installation on a Dual-Floppy System} \vb \AT\ runs comfortably on two floppies. The floppy that resides in the internal drive is the workbench floppy and contains all of the files for the Amiga operating system and all of your personal \TeX\ files. The floppy in the external drive contains all of the files \TeX\ requires to run, including the font metric, format, and packed raster files. This second floppy must be labeled `\.{TeX}' and is usually just a copy of floppy one of the distribution. \vb %% 1. Make TeX workbench Usually the workbench floppies as supplied with the Amiga are very full, restricting the amount of working file space for your \TeX\ files. There are a lot of files on the workbench that are not used much, though, and can be deleted to make more space. This is a list of some of the files and directories on the distribution floppy that can be deleted, in order from largest to smallest. The colon on the front of each name indicates the root directory of the floppy. To delete an entire directory and its contents, type \cmd{1> delete :fonts all} \noindent to delete the fonts directory and all of the files in it. To delete only a file or two, type \cmd{1> delete :Preferences :Preferences.info} \noindent Note that you can specify a maximum of ten files to the delete command. To list the contents of a directory, type \cmd{1> list :Utilities} {\tt :Utilities}~~This directory contains two programs, a calculator, and a notepad, totalling some 72K. If you never use either program, delete the entire directory; otherwise, just delete whichever program you don't use. The associated \.{.info} files can go as well. {\tt :devs/printers}~~In this directory is a driver for all of the printers the Amiga supports, totalling 54K. After selecting your printer type with preferences, delete all of the drivers you don't use. For instance, if you are using an HP LaserJet, delete all of the files in this directory except \.{hp\_laserjet}. If you don't have a printer, you might want to delete the entire directory. {\tt :Preferences}~~This program is used to configure the system to your tastes and hardware, but is 52K huge. After becoming comfortable with the Amiga and tweaking all of the knobs this program has, you might want to delete it. If you choose to run preferences at a later date, you can simply insert another workbench floppy with preferences intact into the external drive, and type \cmd{1> df1:preferences} {\tt :libs/translator.library, :devs/narrator.device, :c/say} (and {\tt :system/say} under 1.2)~~Three files that total 43K give your Amiga the amazing capacity of speech. Luckily, the Amiga is easier to shut up than most people are. {\tt :fonts}~~This directory contains several different fonts that the Amiga can use. Since \AT\ uses its own set of fonts, and the default system fonts are built into the hardware, you can feel free to delete all 40K in this directory. {\tt :c/edit, :c/ed}~~Most people need only one editor, and usually choose to use a commercial editor rather than the supplied Amiga editors. Either one or both of these files can be deleted, saving you about 19K apiece. You might wander around in the \.{:c} directory looking for other, unfamiliar commands to delete as well. A minimum subset might be \.{run}, \.{dir}, \.{list}, \.{delete}, \.{copy}, \.{execute}, \.{diskcopy}, \.{rename}, \.{cd}, \.{date}, \.{makedir}, \.{echo}, \.{endcli}, \.{newcli}, \.{type}, and \.{stack}. In addition, under 1.2, \.{:system} contains several cute programs you might not need. {\tt :system/iconed}~~This is a great program to play with; it allows you to redefine the imagery of an icon. On a typesetting system, however, it has little use. This gem uses 34K. {\tt :demos}~~This directory has a few cute demonstrations of the Amiga's graphics abilities. Once you are finished impressing your friends, wipe all 20K. {\tt :Clock}~~This is another neat program that you may never use; deleting it reclaims 17K. \vb There are other things you can delete on the workbench, but these are the major ones. The above instructions can free up approximately 370K of disk space to be used for \AT. What do you do with all this space? Well, the first thing you should probably do is copy the \.{set} and \.{preview} programs to the workbench by inserting the \.{TeXfiles} floppy into the external drive and typing \cmd{1> copy texfiles:c/set c:\\ 1> copy texfiles:c/preview c:} \noindent %% 2. Putting or not putting TeX on WB disk You might also want to copy the actual \.{tex} program itself with the command \cmd{1> copy texfiles:c/tex c:} \noindent The \.{tex} program is approximately 129K, though, so it will put a large dent in the available disk space. The advantage of placing \.{tex} on the workbench disk is that you can invoke \.{tex} simply by typing \cmd{1> tex} \noindent The alternative, if you don't copy \.{tex} to the workbench disk, is to insert the \.{TeXfiles} floppy into the external drive, and type \cmd{1> texfiles:c/tex} \noindent On a 512K system, since \TeX\ cannot run with other programs, each time you invoke \TeX, you will need to repeat this command and swap the \.{TeXfiles} and \.{TeX} floppies. On a system with more memory, this needs to be done only once, since \AT\ will stay resident using the loop mode described below. \vb %% C. Hard disk system? \sub{Installation on a Hard Disk System} \vb On a hard disk system, \AT\ really shines. To install it, first insert the \.{TeXfiles} directory into the external drive, and type \cmd{1> copy texfiles:c/tex c:\\ 1> copy texfiles:c/preview c:\\ 1> copy texfiles:c/set c:} \noindent Next, create a directory on the hard disk named \.{TeX}, by \cmd{1> makedir dh0:TeX} \noindent (replacing \.{dh0:} with the actual device name of your hard disk.) Now insert the \.{TeX} floppy into the external drive, and type \cmd{1> copy tex:\ dh0:tex all} %% 1. Make directories %% 2. Install what is necessary \noindent This will copy the entire contents of the floppy onto the hard disk, and it will take several minutes. You might go get a Dr.~Pepper while it is running, and relax. Before running \AT\ on the hard disk, you should type \cmd{1> assign tex:\ dh0:tex} \noindent to tell \AT\ where to find the files. When you type this command, the \.{TeX} floppy should not be in either drive, because the system might get confused as to what \.{tex:} refers to. If you are familiar with the \.{s:startup-sequence} file, that is a good place for this command. \vb %% D. Sample startup-sequence file \sub{Running \AT} \vb Now everything should be in place to run \AT. A few scenarios for running \AT\ from a cold boot will be illustrated, so you might want to reboot at this point. \vb If you are running on a 512K system with two floppies, you will need to run the editor, previewer, and \TeX\ separately. To run \TeX, you will either type \cmd{1> tex} \noindent (if you installed \.{tex} on the workbench disk) or insert the \.{TeXfiles} floppy into the external drive and type \cmd{1> texfiles:c/tex} \noindent In either case, insert the \.{TeX} disk into the external drive when prompted for it. To exit from \TeX at any time, you simply need to hit {\it CNTRL\/}-F. \vb If you are running on a machine with more memory, you can load \TeX, the editor, and the previewer all into memory at the same time and switch among them quickly and easily. If you are using a hard disk, you might need to type \cmd{1> assign tex:\ dh0:tex} \noindent before you run \.{tex} or \.{preview}. At this point, you are ready to open a window for each program you will run. Type the following command to the CLI: \cmd{1> execute tex:s/openwindows} \noindent Three new CLI windows should open on top of the one you are currently running. They should be labeled \.{TeX}, \.{preview}, and \.{edit} respectively. First, select the \.{edit} window, and invoke your favorite editor from it. For example, you might type \cmd{1> ed myfile.tex} \noindent After the editor comes up, select the \.{tex} window (you may have to hide the editor screen or window to expose the \.{tex} window) and type \cmd{1> tex} \noindent to invoke \TeX. If you are prompted for the \.{TeX} floppy, insert it. Wait for the \TeX\ prompt. Next, select the \.{preview} window, and type \cmd{1> preview} \noindent to bring up the previewer. Congratulations! You are running all three programs simultaneously! Practice switching back and forth among the windows and screens; you will be doing this a lot. You might move the windows or screens around to suit your tastes. \vb Note the instructions to wait until the disks stop before typing the next command. This is because under the 1.2 version of the operating system, if two files are being accessed off the same floppy simultaneously, the system slows down to a crawl while the disk head seeks back and forth. \vb %% E. Caveat about the run command Another caveat is appropriate here. Another way to run multiple programs at the same time is to invoke them with the \.{run} command, rather than to open a new CLI window for each program. The \.{run} command automatically lowers the priority of the program it is running, and this can keep it from getting any processor time. Use \.{run} with care. \vb A final digression. At this point, the screen might be flickering because the \.{preview} program is running in interlace mode. To eliminate this shaking, bring the preview screen to front and select (click inside) its screen. Select the \.{non-interlace} option in the \.{Modes} menu, and the flicker should go away. Now you can comfortably continue. \sec{Using \TeX} \vb %% VI. Using TeX %% A. Same as on any mainframe True to the spirit of computer independence, which is an integral idea in \TeX, the \AT\ implementation performs exactly as any other port of \TeX. If you invoke \AT\ with a file name given on the command line, it will process that file and return with a prompt. For example, to process the file \.{tex:inputs/story}, the user dialog would appear as follows: \cmd{1> tex story\\ \cbanner\\ \banner\\ (tex:inputs/story.tex [1])\\ *\ttbackslash bye\\ Output written on story.dvi (1 page, 672 bytes).\\ Transcript written on story.log.\\ 1>} \noindent The user typed only the original command line and \.{\ttbackslash bye}; the remaining output is from \TeX. \vb Often when running \TeX, you may find yourself wanting to exit from it for various reasons. \AT\ supports four levels of interrupts for this purpose, ranging from the normal {\it CNTRL}-C which \TeX\ traps, to an emergency {\it CNTRL}-F which aborts immediately. \vb While \AT\ is running over a file and not waiting for user input, the user can type {\it CNTRL}-C. \AT\ will respond with a \.{? } prompt. The user can now type `x' to exit, `i' to insert some tokens, or `h' for further help. Typing {\it CNTRL}-D instead of {\it CNTRL}-C automatically types the `x' for the user, exiting. If loop mode is being used, the format file will be reloaded, and a new double asterisk prompt displayed. \vb It is possible to get \AT\ into a mode in which it does not respond to such interrupts. In this case, typing {\it CNTRL}-E should suffice. This interrupt does not exit loop mode, however; {\it CNTRL}-F is required for that. These are even useful when \TeX\ is displaying a prompt waiting for further input. These last two interrupts should be used with some care. They may leave a malformed \.{dvi} file around; the previous two interrupts will never do this. \vb %% B. Loop mode special for Amiga \sub{The Amiga Loop Mode} \vb A significant part of the time spent processing \.{story} was spent loading the \.{tex} executable into memory. To help eliminate this wasted time, \AT\ runs in a loop if it is not given a file name on the Amiga. For instance, if we had wanted to process \.{story.tex} but leave \TeX\ in memory for the next time we needed it, we could have simply typed \cmd{1> tex\\ \cbanner\\ \banner\\ **story\\ (tex:inputs/story.tex [1])\\ *\ttbackslash bye\\ Output written on story.dvi (1 page, 672 bytes).\\ Transcript written on story.log.\\ \banner\\ **} \noindent Note that this time, the banner message and double splat prompt returned, waiting for the name of the next file we want \TeX\ to process. It will continue to wait patiently as you preview the output from the previous run and make any changes to the editor source, after which you can simply retype the name of the file to run \TeX\ again. \vb There is an even simpler way to run the same document again. Simply hit carriage return at the double splat prompt. Amiga\TeX\ remembers what your last file name was (or any command, typed to the double splat prompt) so a simple carriage return will suffice. \vb If you want to run \TeX\ in the loop mode and give it the name of the first file to process, you can do that with the \.{-r} option, as follows: \cmd{1> tex -r story\\ \cbanner\\ \banner\\ (tex:inputs/story.tex [1])\\ *\ttbackslash bye\\ Output written on story.dvi (1 page, 672 bytes).\\ Transcript written on story.log.\\ \banner\\ **} \sub{Memory Fragmentation} \vb On almost any system, after a period of extended use, memory can become fragmented. Some of the symptoms of fragmented memory include windows that refuse to resize or move or the refusal of \AT\ to run with the message \cmd{Out of memory during allocation!} \noindent If this occurs, there is little you can do. You might try closing down some programs you are running and selecting `release memory' in the project menu of the previewer first. If this does not work, you will have to reboot. \vb The loop mode of \TeX\ helps to reduce system memory fragmentation by grabbing the memory \TeX\ needs once, and then never releasing it until you exit the loop. For this reason, and to reduce the amount of time it takes \TeX\ to start, it is recommended that you use the loop mode if you have more than a megabyte of RAM. %% D. Do not write file while TeX is reading it \sub{Writing and Reading the Same File} \vb The editor creates the source file, with the extension \.{.tex}. This file is read by \TeX, which writes a \.{.dvi} file, which is then read by the preview program and displayed on the screen. There are restrictions on reading and writing a file at the same time, however; chaos can easily result. Therefore, it is not wise to ask the editor to update or write out the source file while \TeX\ is processing it. The same restrictions apply to the previewer; you must close the file with the `close file' option of the project menu or by hitting the `C' key while the previewer window is selected before running \TeX\ again. \vb If you violate this restriction, the editor might complain that it cannot write your file, or \TeX\ might complain that it cannot write the \.{.dvi} file. If the editor complains, finish running \TeX, and then reexecute the save-file command from the editor. If \TeX\ complains, close the file from the previewer and type the name of the\.{.dvi} file again. %% C. set options \vb \sub{The Null Source File} \vb When \TeX\ gives you the double splat prompt, it is requesting a file name to process. If it can't find the file you specify, it says so, and asks for another name. \cmd{1> tex\\ \banner\\ **lksaj\\ ! I can't find file `lksaj.tex'.\\ <*> lksaj \vb\noindent Please type another input file name:} \noindent Sometime you may decide that you don't want to process a file at that point, but it keeps giving you this annoying error message. There are two ways to get out of the loop; hit the abort character ({\it CNTRL\/}-F), which gives you a fatal error and \TeX\ exits, or simply give it the name \.{nul}, which exists in the \.{tex:inputs} directory. \TeX\ will then respond with a single asterisk prompt, at which point you can type \.{\ttbackslash bye} or \.{\ttbackslash end} to exit. \vb \sub{The Quick Loop Mode} \vb In the loop mode above, you may have noticed that each time \AT\ printed its banner line, it accessed the floppy for a while before printing the double asterisk prompt. It used this time to reinitialize itself with the \.{plain.fmt} file. If you have more than 512K of memory, there is a way to eliminate this annoying delay. If you invoke \AT\ with a \.{-R} option (that's capital \.{R}, not little \.{r}) then it will save away the parts of the format file that it needs to reload in memory. Subsequent times around the loop, it will simply copy this information from its internal copy, rather than loading it from the floppy. This requires less memory than copying the entire format file to the ram disk because portions of the format file do not need to be read again. In addition, it is faster. \vb \sub{Amiga Special Characters} \vb This release of \AT\ supports most of the Amiga special characters. These are the characters accessed through foreign keymaps, or using the `ALT' key. For instance, with the standard US keymap supplied with the Amiga, if you type `ALT'-K followed by `u', you will get the character \"u. (Not all editors support these characters.) With \AT, these characters are recognized and automatically transformed into the appropriate \TeX\ macros (in this case, `{\tt\ttbackslash"u}'. All of the special characters that have a correspondence within \TeX\ are supported. The characters that are not supported are translated into question marks. \vb Unfortunately, this feature adds some amount of incompatibility between \AT\ and other \TeX\ implementations, since the other implementations do not support these special characters. For this reason, a program called \.{unamiga} is supplied, which will perform the identical transform that \TeX\ is using on an Amiga text file, created a standard ASCII file that can be uploaded and run through other \TeX's. To use this program, you would type, for instance, \cmd{1> unamiga myfile.tex toupload.tex} \noindent This command will take the file \.{myfile.tex}, complete with Amiga special characters, and create a file called \.{toupload.tex}. This second file will be identical with the original, except the special characters will be replaced with their \TeX\ macro equivalent. \vb You cannot use these special characters in file names or macro names within \TeX. In addition, because the translation is fixed, if you redefine some of the accents, you may not get what you expected. For instance, the character `\"\i' is translated into `{\tt\ttbackslash "\ttbackslash i}', so if you redefine {\tt\ttbackslash i}, this character will no longer work. \vb The umulauts are by default the German umulauts. If you need Hungarian umulauts, you should use a command such as \cmd{\ttbackslash let\ttbackslash"=\ttbackslash H} \noindent at the beginning of your \TeX\ document. \vb \sub{Amiga Environment Variables} \vb There are several files \TeX\ must look for when processing a document; these include format files, font metric files, and auxillary input files. Since people might choose to move these files from their default places, or rename the volume on which they are stored, \TeX\ reads several environment variables and uses them to search for these files. \vb An environment variable consists of two strings of characters: a name, and some contents. Included with the \AT\ package is a program \.{set} that can be used to examine and change these environment variables. Invoke this program now by typing: \cmd{1> set} \noindent The program should simply return with no output; this is because no environment variables are set. If you invoke the program with no arguments, it displays all of the current environment variables. Now, type \cmd{1> set foo=bar\\ 1> set\\ foo=bar\\ 1>} The first command set the environment variable \.{foo} to \.{bar}, and the the second simply displayed the current variables. Now, set \.{foo} to \.{mung}: \cmd{1> set foo=mung\\ 1> set\\ foo=mung\\ 1>} \noindent exactly as expected. You can delete an environment variable by not following it with an equals sign or a string: \cmd{1> set foo\\ 1> set\\ 1>} \noindent \TeX\ examines the following environment variables. If they are not set, it uses the given default. \cmd{texmacros=tex:macros\\ texfonts=tex:fonts\\ texinputs=.,tex:inputs\\ texformat=plain\\ texopts=} \noindent The first three are paths. They are the devices or directories that contain the appropriate files. For instance, when \TeX\ needs to load a format file, it searches the directory \.{tex:macros}. When it is looking for a source file, it searches the current directory first (the `\.{.}', borrowed from Unix) and then the directory \.{tex:inputs}. The fourth environment variable is the \.{texformat} variable; this is used to set the default format file that \TeX\ loads in. If you create your own format file called, for example, \.{plane.fmt}, you can tell \TeX\ to load it rather than \.{plain.fmt} by simply setting this variable to \.{plane}. This is handy if you use La\TeX\ rather than plain \TeX, since you can simply set this variable to \.{lplain} and voila! \TeX\ becomes La\TeX. The last environment variable can be used to automatically run \TeX\ in the quick loop mode by setting it to \.{R}. This is recommended if you have sufficient memory. \vb If \TeX\ requests the Workbench disk when you think it should not, it might be because \TeX\ is trying to determine the value of some environment variables. Environment variables on the Amiga are implemented as a library. If no environment variables are set, the Amiga attempts to load the file \.{libs:environment.library}, which is usually on the workbench disk. To prevent \TeX\ from requiring the Workbench disk, simply `set' some random environment variable, and \TeX\ will be happy. For instance, the command \cmd{1> set foo=bar} \noindent should suffice. This is also true of \.{preview} and all of the Amiga\TeX\ printer drivers. %% VII. Using preview \sec{Using Preview} \vb The preview program allows you to display your \TeX\ output on the Amiga monitor in a highly interactive fashion. Its primary purpose is to shorten the edit-\TeX-print cycle, to allow you to create your documents more quickly and more conveniently. \vb As the preview program goes through its operations, its pointer will change. When preview is idle and waiting for a user action, the pointer will appear a small arrow, similar to the workbench pointer. When preview is redrawing a page, the pointer will appear to be a pencil drawing a black line. Finally, when preview needs to load a font, the pointer will become a large black lower-case `a'. By watching the pointer, you can follow the operations of the preview program. \vb If a font that the previewer needs is not found, the screen flashes and an error message appears on the screen title bar. In addition, the font metric file for the font will be loaded, and the information contained there used to create rectangular `characters' of the size and shape of the actual font characters. Thus, though these fonts will certainly not be readable, they will give you some idea of layout and style. \vb Note that at very low resolutions, like those required for preview, some small characters might degenerate badly, or even disappear entirely. The typewriter font is a particularly good example of this. \vb Unlike \TeX, where the user input is strictly through the keyboard, the user supplies input to the preview program mainly through the gadgets and menus of the screen. A few keys on the keyboard duplicate the function of the gadgets for expert users. \vb %% A. Gadgets (screen) \sub{Preview Gadgets} \vb %% 1. Drag gadget %% 2. Hide screen/show screen The preview program may be run either on a custom screen or the workbench screen. The default is a custom screen. If it is running on a custom screen, the top of the preview screen will contain the three default screen gadgets. In the upper right corner will be the screen-to-front and screen-to-back gadgets; the rest of the title bar will be the screen drag gadget. \vb %% 3. Close gadget Now we progress to the gadgets on the window title bar. The close gadget is a little square with a dot in the middle in the upper left corner. Selecting this gadget will terminate the program, freeing all of its memory. Normally you would use only this gadget if you are through with \TeX\ for the day, or if you have only 512K and want to run \TeX. The previewer will peacefully coexist with other well-written Amiga programs. Another way to exit the program is with the `Q' key on the keyboard. \vb %% 4. File name gadget %% 5. Page number gadget Next consider the file name gadget. This gadget is the blank area in the left portion of the window title bar. When have selected this gadget, a cursor will appear on the title bar; you can now type the name of a file to preview (less the \.{.dvi} extension). (If a file name is already in the gadget, you will need to clear it by hitting the DEL key a few times.) Hit carriage return, and the file will be opened. If the file does not exist, the screen will flash and an error message will appear on the screen title bar. Another way to select the file gadget is to simply hit the `F' key on the keyboard; the current file name will be cleared and the cursor will be positioned in the gadget ready for your file name. \vb The previewer buffers information about the current job in memory to make redrawing the page faster. If you make changes to the document and rerun \TeX, this information is no longer valid and must be flushed. To do this, simply select the file name gadget and hit carriage return. All information about the file will be flushed, and the file will be reopened as if you had started preview fresh. Hitting the `F' key and then carriage return has the same effect. If you use the tracking mode described later, this will not be necessary. \vb The page number gadget is the blank area next to the file name gadget. As you scan around through the document, this gadget will contain the current page number. To go to a random page, simply hit this gadget and type a new page number; if the page exists, it will be displayed. Again, the `P' key provides a convenient shorthand for selection of this gadget. \vb The portions of the window title bar that are not gadgets are used as a window drag gadget. You can drag the window around on the screen by selecting and dragging on the title bar. \vb \TeX\ allows more than one page to have the same number. For instance, if you turn page numbering off, all of the pages will be numbered zero. Subsequent occurrences of the same page will be numbered, for instance, 0.1 for the second occurrence, 0.2 for the third, etc. The first occurance will always be numbered just 0. \vb %% 6. Zoom/unzoom gadget The next gadget, which has two small rectangles, one larger than the other, is the zoom/unzoom gadget. At any time the previewer is either in a zoom state or an unzoom state; the zoom state usually displays the document at a higher resolution than the unzoom state. Selecting this gadget will toggle between the zoom and unzoom states. The default unzoom resolution is 91 dots per inch; the default zoom resolution is 120 dots per inch. Note that the units are screen pixels per document inch, not screen pixels per screen inch, which is of course fixed. The `S' key duplicates the function of this gadget. \vb %% 7. Back page gadget %% 8. Forward page gadget The next two gadgets, which appear as arrows pointing to the left and right, are the forward and back page gadgets. Selecting the arrow pointing left displays the page before the current one; selecting the one pointing right displays the next page. The left and right arrow keys on the keyboard also provide this functionality. In addition, the space bar may be used to go to the next page, and the delete and backspace keys go to the previous page. These latter combinations (space and backspace) also go to the top of the new page. \vb %% 9. Scroll bar gadgets The long, narrow gadgets on the left and bottom of the screen are the scroll bar gadgets. These gadgets are very similar to the scroll bar gadgets in other Amiga applications, and it is worthwhile to get familiar with their operation. The scroll bar appears as a long, thin rectangle inside a longer, slightly thicker rectangle. The length of the larger rectangle represents the size of the page in one dimension, and the length of the shorter rectangle is proportional to the amount of that page that is currently displayed on the screen. Thus, if one third of the vertical length of the document fits on the screen, then the scroll bar body (the inner rectangle) will be one third of the length of the scroll bar. The position of the scroll bar body within the scroll bar is also proportional to the position of the displayed text on the entire page. \vb To move the scroll bars and thus the page, you need to select the scroll bar body, and drag it in the direction you want the page to move. If you are currently looking at the middle third of the page and you wish to see the top third, you must move the pointer to the vertical scroll bar (on the right), select the body and hold the select button down, and move the mouse up. The scroll bar body will follow. When the position is correct, release the select button. The page will then be redrawn. \vb Alternatively, if you click the select button above or below the scroll bar body, the body will move its length in the appropriate direction. This is a quick way to get to the top of the page; simply move the mouse to the top of the vertical scroll bar, and click several times. The up and down arrow keys also move the page up and down on the screen. If you hold the shift key down while you press the up and down arrow keys, the page will move up or down one-half of the screen height. \vb In the lower-right hand corner is the resize gadget. Select and drag this gadget to resize the previewer window, either on the workbench screen or a custom screen. $$\vbox{\halign{\strut\vrule\quad\hfil #\hfil\quad\vrule\quad&#\hfil\quad\vrule\cr \noalign{\hrule} \multispan2{\vrule\hfil\strut Previewer Keyboard Commands \hfil\vrule}\cr \noalign{\hrule} (backspace)&Go to top of previous page\cr (delete)&Go to top of previous page\cr (space)&Go to top of next page\cr $\leftarrow$&Go to previous page\cr $\rightarrow$&Go to next page\cr $\uparrow$&Move up one screen\cr $\downarrow$&Move down one screen\cr (shift)-$\uparrow$&Move up one half screen\cr (shift)-$\downarrow$&Move down one half screen\cr C&Close {\tt dvi} file\cr F&Enter new file name\cr P&Go to specified page\cr Q&Exit previewer\cr S&Toggle size selection\cr \noalign{\hrule} }}$$ %% B. Menus %% 1. Project menu \sub{Preview Menus} \vb There are seven main menus on the preview program. The first is the `project' menu, and it has five items on it. The first item is `colors', which allows you to change the foreground and background colors for preview. On a custom screen, selecting this item brings up a colors requester with several gadgets on it. While the colors requester is on the screen, all other input to the program is blocked; you must select the `use' (to retain your color changes) or `cancel' (which restores the colors to their previous state and exits) gadgets to use the program further. The `background' and `foreground' gadgets select which color is currently being modified. The `reset' gadget sets the colors back to what they were when the requester first appeared on the screen. Finally, the three scroll-bar gadgets allow you to change the intensities of red, green, and blue in the current color. \vb On the workbench screen, the `colors' item brings up a submenu with the twelve possible combinations of foreground and background colors available on the workbench. Select the one you prefer. \vb The second option is the `close file' option, which is used to close the \.{.dvi} file so \TeX\ can be run again. If this option is not used before \TeX\ is rerun, it will complain that it can't open the \.{.dvi} file because the previewer has it open for reading. The key `C' on the keyboard duplicates this menu selection. Again, this option is not necessary if you select one of the tracking modes. \vb The next option on the project menu is the `release memory' option. As the previewer needs fonts to draw the pages on the screen, it loads them off the disk. When memory starts running low, preview starts to delete the fonts it loaded on a least-recently-used basis. However, preview can easily use a lot of memory for font storage. This second option instructs the program to delete all of the fonts from its memory. This is useful if you want to run another program and you suspect memory is low. \vb The fourth option on the project menu is the `save configuration' option. This option saves the current state of the preview program, including screen mode, zoom and unzoom values, window size and placement, colors, page size and margins, and tracking mode. The next time the preview program is run, the settings of these values will be read from this configuration file. \vb The last option on the project menu is the `quit' option; it behaves exactly as if you had selected the close gadget on the window by exiting the program. \vb %% 2. Zoom/unzoom menus The next two menus are the `zoom' and `unzoom' menus; these are used to select the resolution for these two modes. Either may take on values between 58 and 189 dots per inch, and the `zoom' mode does not necessarily have to have a higher resolution than the `unzoom' mode. If the mode corresponding to the menu you select is the currently active mode, the page will be immediately redrawn at the new resolution; otherwise, the new resolution will simply be stored for the next time you hit the zoom/unzoom gadget. \vb In addition to the sizes from 58 to 189, there is a new `full' size option which will attempt to display the entire page in the previewer window. Normally, fonts at such a small resolution will not exist, so the page will not be readable, but this mode should give you an idea of what the page will look like. If you resize the window, you must select this option again to get the previewer to calculate a new size. \vb %% 3. Borders menu The fourth menu is the borders menu; the border consists of the lines that represent the edges of the paper on the screen. By default, preview (and \TeX\ itself) assumes that the size of the paper is 8 1/2 by 11, and that there are one inch margins at the top and left. The first option on this menu allows you to toggle the borders on or off. The second option allows you to `reset' the borders back to the default values, in case they get changed. The third option sets the page size to `landscape', that is, 11 by 8 1/2, with one inch margins. (If the \.{.dvi} file contains a \TeX\ `special' command consisting of the word `landscape', this is selected automatically.) \vb The fourth option of the `borders' menu allows you to change the size and margins of the paper arbitrarily. When you select the `set size' option, a window will be opened on the workbench screen, and the current size and margins displayed (in inches). Simply enter new values, or hit carriage return to keep the old values. As you enter the values, they will be checked for consistency; if any of the values you enter are unreasonable, the program will prompt you for another value. To exit quickly, simply hit the carriage return key four times. \vb The fifth option of the borders menu allows you to display two facing pages of the current \.{dvi} file at the same time. This is usually most useful when running in the full page magnification. All of the remaining keys retain their meanings, so selecting the right arrow gadget will move you forward only one page; to move forward two pages, you simply select it twice. (You don't need to wait for the previewer to redraw the window between selections.) \vb %% 4. Modes menu The fifth menu, `display', allows you to change the operating mode of the preview. There are currently three modes, each with advantages and disadvantages. \vb The first and default mode is the interlace mode. In this mode, the page is drawn on a 640 by 400 pixel screen with interlace on. This high resolution allows fairly readable characters with a correct aspect ratio, but the flicker caused by the interlacing might be annoying. There is a section following this one that describes how to deal with this flicker. The second mode is the stretched mode. Here, the page is drawn on a 640 by 200 pixel screen, using the same fonts as for the interlace mode. The characters are still well defined, but the aspect ratio is off by a factor of two; hence the name. The screen is rock steady in this mode. The screen is also rock steady in the third mode, non-interlace, that is also drawn on a 640 by 200 screen. The aspect ratio is corrected by modifying the fonts as they are loaded; this creates much cruder but generally acceptable characters. Which of the three modes you use depends largely on which bothers you the least; the interlace mode and flickering, a bad aspect ratio, or crude characters. \vb The fourth selection on the `display' menu allows you to move the preview window to the workbench screen, or back to a custom screen. By default, the previewer opens on a custom screen. It runs faster on a custom screen, and usually takes less memory as well. In addition, you can select any of the three modes on a custom screen. Running on a workbench screen allows you easier access to your other windows, however. If you run the previewer on your workbench screen, you will only be able to use the interlace mode if your workbench is interlaced (this is selectable in Preferences), and you will only be able to use the stretched mode and the non-interlace mode if your workbench is not interlaced. \vb The sixth menu is the `tracking' menu. This feature allows the previewer to follow \AT\ in its processing of \TeX\ files, automatically displaying the new file as \AT\ finishes processing the first page. There are three selectable modes. The first is `independent', in which the previewer and \AT\ are independent programs with no communication. In this mode, you must explicitly close and reopen the \.{dvi} file to redisplay it. \vb In the second mode, `track file', as \TeX\ finishes the first page in a \.{dvi} file, it notifies the previewer. The previewer then automatically displays that new file. You still maintain full control over the previewer, and can preview any page that \AT\ has finished. For instance, if you are working on a thirty page report, and \AT\ has finished twenty pages, you can preview any page from one through twenty. This is the recommended mode of operation. \vb The third mode, `track page', displays each page as \AT\ finishes it. In this mode, you no longer control which pages are being previewed. This mode is most useful in trying out small math equations or such, typing them directly to the single splat prompt of \TeX\ and typing \.{\ttbackslash vfill\ttbackslash eject} after each. %% 5. About menu The last menu is the `about,' or `blurb,' menu. It displays a copyright notice and the version number of the software. Please let us know what this version number is when reporting bugs or missing features in the preview program. %% C. Coping with the interlace mode \vb \sub{Coping With Interlace} \vb When the Amiga uses a display mode with 400 dots vertically, it redraws the screen thirty times a second rather than the normal sixty. This is called `interlace mode' because of the way the screen is redrawn. To the human eye, the screen appears steady when redrawn at sixty frames per second, but unfortunately, the human eye notices the redrawing at the thirty frames per second. In the interlace mode, the screen appears to shake; this is called flicker. The Amiga's flicker may be handled or reduced in several ways. The first and best way is to buy a long-phosphor monitor. These are relatively expensive at the moment, but the price is dropping slowly. (Commodore will release a long-phosphor monitor soon for approximately \$500.) On a good long-phosphor monitor, the flicker should be non-existent. Another suggestion is to wear sunglasses while working in interlace mode. Don't laugh until you have tried it. Turning down both the room brightness and the monitor brightness helps a great deal, as does selecting the right combination of colors. If none of these suggestions works for you, the stretched and non-interlace modes eliminate the flicker altogether. \vb \sub{MoreRows} \vb For those with screens that are larger than 640 by 400, such as PAL users or people familiar with the \.{morerows} program, the previewer will work just fine, automatically. \vb %% D. Set options \sub{Preview Environment Variables} \vb The preview program reads the settings of two environment variables: \.{texfonts}, which is used in the same way as \TeX\ uses it, and \.{texpacked}, which contains a list of the directories to search for packed files. The default value of \.{texpacked} is \.{tex:pk}. \vb % \sub{Font Caching} \vb Supplied with \AT\ are approximately 1500 previewer fonts, occupying six of the ten distribution floppies. Typically, most of these fonts will never be used by a typical user; yet, which fonts are actually used varies widely. To help handle this large number of fonts, a font caching scheme has been implemented in the previewer. \vb Please note that with the release of February, 1988, a new caching scheme has been implemented which is incompatible with the old one. This coincides with the release of new, improved fonts as well. So, if this is an update for you, you should read this section carefully and only use the new distribution. \vb The previewer will look for fonts in the places specified in the \.{texpacked} environment variable. If the required font is not found in any of the specified directories, the previewer will try to locate the font. To help it locate the font, a file called \.{tex:pk/fontvols} should exist. (It is supplied on the \.{tex} distribution floppy.) This file might look something like this: \cmd{cache 40 tex:pk\\ Red.Green=100d.69.76.83\\ Red.Yellow=100d.91.100.110\\ Red.Black=100d.120.131.144\\ Red.White=100d.144.158.173\\ Red.Purple=100d.189.207.227\\ Red.Red=100d.227.249.273.299.327.358} \noindent (Note that this file is just an example, and may not correspond to the floppies actually distributed.) The first line must start with the word `cache' or `nocache'. If the word is `cache', then font caching is enabled, and if a font is found on one of the listed volumes, and there is room in the cache directory, it is moved there. Otherwise, the font is just loaded off the distribution floppy to be used. Next on the first line should be an number which specifies how many blocks to leave free in the cache directory. If the number of free blocks falls below this number, caching will be disabled. It is usually nice to leave a few blocks free, in case a program decides to write a configuration file to the \.{tex} directory. The third part of the first line is the directory to use for caching. Note that this must be a directory; it cannot just be a logical name. For instance, \.{ram:{}} is an invalid cache directory. Typically, \.{tex:pk} is used for the cache directory. It is recommended that you not change this until you have tried using \.{tex:pk} and you are comfortable with the operation of the caching. \vb The remaining lines contain the names and contents of the distribution floppies. If you buy a printer driver, it will have some more font floppies which should be added to this list. The names of the floppies must be in a very specific format, to help the previewer and other drivers know on which floppy to find a font. For fonts that have the same vertical and horizontal resolutions, as the previewer fonts do, the line should be of the form \cmd{{\it d\/}={\it n\/}{\it A}.{\it n}.{\it n}} \noindent for instance, where each {\it n\/} is replaced by a number, and the {\it A\/} is replaced by a sequence of letters (typically just the single letter `d'.) In addition, the {\it d\/} is the actual name of the floppy, which corresponds to the colors on the label. The first number specifies the dots per inch of the device that the fonts on this floppy are intended for. The remaining numbers are important. For each, there must be a directory on the floppy with that number as a name, in which are a set of fonts at that resolution. \vb So, when the previewer cannot find a font in the default directories, it searches the cache directory. If the font is not there either, it looks for a file in the subdirectory of the cache directory corresponding to the appropriate resolution called {\tt pk.direct}. This file has information on which floppies contain exactly which fonts. If this file is not found, some of the font floppies are requested, and this file is built. Then, the previewer reads this file to find which floppy that font is on, if it exists at all, requests that volume, and copies the font into the cache directory. If caching is turned off, the font is not copied; it is just used directly off the floppy. \vb Thus, when the previewer or a printer driver first needs a font at a certain resolution, the Amiga will request font floppies and spend some time reading them. Please be patient as it builds up the necessary directory information; it should not take longer than a minute or so. \vb For this reason, if you rename some of the font floppies, add your own fonts to the floppies or introduce a floppy of your own, you should type the command \cmd{1> delete tex:pk/\#?/pk.direct} \noindent to delete all of the directory files, so new ones can be automatically constructed which reflect the new state of the floppies. \vb It is tempting, if you have a hard disk, to copy all of the font files from the supplied font disks to your hard disk, so you don't ever need to swap disks. This is not necessary, and consumes a large amount of disk space (about 4 megabytes.) Nonetheless, if you must, the proper way to do it is to type, for each font floppy supplied, \cmd{1> copy Red.Green:\ TeX:pk} \noindent for instance, after you have set up your \.{TeX:{}} directory on your hard disk. You should then delete the \.{TeX:pk/fontvols} file to turn caching off and to disable all reading from the distribution floppies. \vb \sub{Cleaning the \TeX\ Disk} \vb Between font caching, extra input files and large format files, the \.{TeX} disk will sometimes fill up. The first thing you can do to help prevent this is to remove all of the files from the \.{TeX} disk you do not need. You should remove \.{TeX:macros/tex.pool} unless you run \.{initex} a lot. You should probably only have one format file on your \.{TeX} disk as well; if you use multiple format files, it is recommended that you make multiple \.{TeX} disks, one for each format file. Finally, you may choose to delete all of the files in \.{TeX:inputs} and move them back only as you need them. \vb If the cache directory fills up, the previewer (or printer driver) will print a warning, and turn caching off. At this point, it is probably a good idea to clean out your \.{TeX:pk} directory. An easy way to clean the cache is to just remove all of the fonts from the cache directory. This can be done with the command \cmd{1> delete tex:pk/\#?/\#?pk} \noindent (I'll bet you didn't know AmigaDOS was that smart.) You should not use the command \cmd{1> delete tex:pk/\#? all} \noindent as this will also delete the file \.{tex:pk/fontvols} and the font directory files, which you will then have to recreate. \vb It is somewhat dangerous to use the ram disk as your font cache. A number of Amiga programs will crash if run on a machine with low memory, and \.{preview} and the printer drivers can potentially move a lot of fonts into the cache directory. The previewer will automatically cache fonts in ram during its normal run. However, if you really must use \.{ram:}, you can. Because the ram device allocates its blocks on demand, however, it will always appear full. Thus, you should set the number of reserved blocks (in the first line of \.{tex:pk/fontvols}) to a negative number, say, $-40$, to insure that the files are copied. You should never use a negative value here when you are caching fonts to a fixed size device, such as the ASDG recoverable ram disk, a hard disk, or a floppy; doing so is guaranteed to crash the system at some point. \vb \sec{Printer Drivers} \vb ``That's all very well and good,'' you might be saying to yourself at the moment, ``but how do I get printed output?'' The standard Amiga\TeX\ package does not include the ability to output to any printer. And there is good reason for this. \vb Each printer requires its own set of fonts. There is no easy way to take a font at one resolution and scale it to another resolution; the output of some Amiga word processors makes this evident. Each printer requires a specific set of fonts tailored for its resolution. These sets of fonts vary from three to seven full Amiga floppies; a distribution of fonts and drivers for even a reasonable set of printers would require on the order of fifty floppies! \vb For this reason, and several others, printer drivers must be available separately. These drivers are available for a price of \$100 apiece, from the same people who distribute the Amiga\TeX\ package. \vb If you are looking for a printer to use with Amiga\TeX, please consider a laser printer, preferably a PostScript printer. The HP LaserJet Plus is a good printer to consider. The QMS KISS retails for \$1900, but can be had for \$1700, and generates excellent quality output. PostScript machines start at around \$3500, but are possibly the most versatile and usable printers available. PostScript will give you the greatest compatibility with both current software and future software for anything requiring a printed page. If you do not wish to spend the money for a laser printer, try purchasing a 24-pin printhead printer, such as the Epson LQ series or the NEC P6/P7 series. These printers all deliver superb print quality at a reasonable speed. On the other hand, do not expect the Okimate 20 (and some similar printers) to deliver reasonable output quality; they simply do not have the resolution or clarity required. \vb Printer drivers are currently available for the QMS KISS, QMS SmartWriter, HP LaserJet Plus, and PostScript laser printers; the Epson LQ series, the Epson MX series (including the JX, FX, EX, PX, RX, TX, etc.) and compatibles, the Citizen 150-D, the NEC P6/P7 series, and the ImageWriter II. Other drivers are being developed on demand; if you have a printer not on the list and not compatible with any on the list, call us. \vb If we cannot satisfy your printer driver requirements immediately, and you have Manx C and are comfortable with the C programming language, we can send you a package with which you can develop your own printer driver. For dot-matrix printers, this typically takes a day or two and involves at most a few pages of code (we supply the other 3500 lines.) Laser printers are typically more difficult, but we are pleased to help with them as well. % % Changing the size of TeX % \sec{Making \TeX\ Larger or Smaller} \vb Occasionally, \TeX\ will complain with a message like \cmd{! TeX capacity exceeded, sorry [main memory size=18000].} \noindent (This particular message will only occur on a 512K Amiga.) \AT\ allows some limited control over internal array sizes with a file called \.{tex:sizes}. The variables you can modify are: $$\vbox{\halign{#\hfil&&\quad\hfil#\hfil\cr Variable&512K&Default&Maximum&Minimum&Size\cr memmax&18000&65500&65500&5800&4\cr memtop&18000&65500&65500&5800&(4)\cr triesize (initex)&8000&8000&30000&7500&13\cr triesize (tex)&6100&6100&6100&4\cr poolsize&30000&50000&65500&27000&1\cr maxstrings&2000&5000&30000&1780&2\cr fontmemsize&6300&25000&65500&4900&4\cr}}$$ \vb The 512K column contains the default values for a 512K machine, as supplied in \.{texfiles:512/sizes}. The default column indicates the value used if no \.{tex:sizes} file is found. The maximum values are strict maximums; you cannot supply values greater than this without dire consequences. The minimum values are minimum to load plain \TeX. The size column indicates how much memory each element takes. Memmax should always be greater than or equal to memtop, and is usually equal for maximum flexibility. Ini\TeX\ ignores memmax, and uses the memtop value instead. The memtop size value is in parentheses because it is just a position in a array of memsize elements. \vb The \.{tex:sizes} file must consist of just a list of seven numbers, in the order given in the table above. No error checking is performed, so you must insure that you have created the file correctly and that you have not exceeded the maximums listed above. \vb If you change \.{memtop}, you {\it must\/} create a new format file. This is why a separate plain format file is supplied for the 512K version of \AT. This is because the format file is just a memory dump of \TeX's internals, and some internal pointers depend on memtop. A format file created with an Ini\TeX\ which used a different \.{tex:sizes} file than the current \TeX\ is the most common reason for the error message \cmd{(Fatal format file error; I'm stymied)} \noindent All other values can be changed with no change to the format file. For instance, if you are running out of font space, you could easily increase the fontmem value to load more fonts. (On a 512K machine, you cannot increase it much without running out of room, however.) %% VIII. LaTeX \sec{La\TeX\ and Sli\TeX} \vb La\TeX\ and Sli\TeX\ are supplied with \AT\ on the third and fourth distribution diskettes. La\TeX\ is a macro package designed by Leslie Lamport that makes \TeX\ easier to use by pre-packaging a number of document formats. It is a large package, however; it will not run on a 512K Amiga. The rest of the documentation describes La\TeX; Sli\TeX\ is but a variation of La\TeX. To change the instructions to those for Sli\TeX, simply change each occurance of \.{lplain} to \.{splain}; no other changes are necessary. \vb %% A. Installation To run La\TeX, there are several files you will need to move onto your \.{TeX} floppy or hard disk. The first of these is the La\TeX\ format file, called \.{lplain.fmt}. If you use La\TeX\ exclusively, you might want to delete the \.{plain.fmt} file to make room for this file. You will probably have to delete some \.{.pk} files off the \.{TeX} floppy to make room if you are running from floppies. I recommend deleting the fonts starting from the higher resolutions, since these fonts are used less often and take more space. \vb You will also need to move all of the style files (with the \.{.sty} extension) from the La\TeX\ floppy into the \.{tex:inputs} directory. This can be accomplished with the following command: \cmd{1> copy latex:inputs/\#?.sty tex:inputs} Again, you might have to delete some files to make room. Alternatively, to bring things up with a minimum of fuss, the following two environment variable defines will allow you to run LaTeX by simply swapping floppies as they are requested: \cmd{1> set texinputs=latex:inputs,tex:inputs\\ 1> set texmacros=latex:macros,tex:macros} To tell \TeX\ to load the \.{lplain.fmt} file rather than the \.{plain.fmt} file, you will need to execute the following set command: \cmd{1> set texformat=lplain} Alternatively, you can simply give \TeX\ the format file name followed by an ampersand before the file name, as in \cmd{\banner\\ **\&lplain foo} \noindent if \.{foo.tex} is the name of your La\TeX\ source. This can be slower, however, as the \.{plain.fmt} file is loaded into \TeX\ by default before the double splat prompt is given. If you give the ampersand on the command line which invoked \TeX, the \.{plain.fmt} file will not be loaded. Using the environment variable mentioned above is the recommended method for running La\TeX. %% B. Necessity for multiple runs \sec{Ini\TeX} \vb %% IX. IniTeX The program \TeX\ has only about 312 control sequences built in. These control sequences are very primitive and thus quite difficult to use. Therefore, before processing a document, \TeX\ loads in by default a macro package called plain that contains approximately 596 more control sequences built up from the primitives. \vb Parsing and processing the large amount of source in plain takes a long time. To eliminate this delay, the program Ini\TeX\ can be used to create a `format file' that contains essentially a memory image of \TeX\ after all of the macros have been loaded. This format file loads relatively quickly, since it needs only to be copied into memory. \vb To illustrate the process of creating a new format file, we shall assume that we want to create a preloaded \.{plain.fmt} file augmented with the verbatim macros supplied in \.{tex:inputs/verb.tex}. You will substitute your own macro package for \.{verb.tex}. \vb Before we get started, note that you cannot run Ini\TeX\ on an Amiga with less than a megabyte of RAM. If your Amiga does not have enough memory, borrow a friend's. To create your format file, you must make sure that you have at least 150K free on your working disk. \vb First, you must move the file containing your macros and the \.{tex.pool} file to your current directory. The following commands should do the trick: \cmd{1> copy tex:inputs/verb.tex verb.tex\\ 1> copy tex:macros/tex.pool tex.pool} Insert the disks as requested. Now you have to tell \TeX\ to look on the \.{TeXfiles} disk for some of its input files; specifically, the \.{plain.tex} and \.{hyphen.tex} files. This can be accomplished by: \cmd{1> set texinputs=.,texfiles:inputs} Now you can invoke IniTeX, and load the basic macros of plain: \cmd{\advance\hsize by 1in % So no overfull messages 1> texfiles:c/initex\\ \cbanner\\ This is CTeX, Amiga Version 2.9c (INITEX)\\ **plain\\ (texfiles:inputs/plain.tex Preloading the plain format:\ codes, registers,\\ parameters, fonts, more fonts, macros, math definitions, output routines,\\ hyphenation (texfiles:inputs/hyphen.tex))\\ *} The macros of plain have been loaded, so now you load your own: \cmd{*\ttbackslash input verb\\ (verb.tex)\\ *} Once all of the macros you wish to include have been loaded, you can create the actual format file by typing the command \.{\ttbackslash dump} to the splat prompt. Ini\TeX\ will create the format file and exit. \vb In this case, the format file will receive the name \.{plain.fmt}, since that is the first file we specified. If you replace the supplied \.{plain.fmt} file (in \.{tex:macros} with this one, all of your \TeX\ documents will have access to your new macros automatically. However, if you want to use the regular plain package in addition to your augmented plain, you will have to rename this format file, and copy it to \.{tex:macros}. Then, to use it, you will have to specify on the command line \cmd{1> tex \&foo bar} \noindent if you renamed the format file \.{foo.fmt} and you want to process the \TeX\ source in \.{bar.tex} with those macros. Alternatively, you can omit the \.{\&foo} part by executing the command: \cmd{1> set texformat=foo} \noindent which will tell \TeX\ to use the \.{foo.fmt} file by default. %% A. Required files %% C. Making TeX larger or smaller % % BibTeX % \sec{Bib\TeX} \vb Bib\TeX\ is a bibliography database system for use with La\TeX. For basic documentation, please refer to the {\it La\TeX\ User's Guide and Reference Manual.} Bib\TeX\ is supplied on six files. The first is \.{TeXfiles:c/bibtex}, which is the executable; if you use Bib\TeX, you will probably want to move this into your \.{c:{}} directory. The remaining files are in \.{LaTeX:inputs}, with the extension \.{.bst}; these are the standard bibliography styles. To use these, move the files corresponding to the styles you will use into the directory \.{TeX:inputs}. That is all you need to do. \vb Bib\TeX\ uses two environment variables. One is \.{texinputs}, which is used just as in \TeX. The other is \.{texbib}, and it tells Bib\TeX\ where to find your bibliography data base. By default, this is set to the same thing as \.{texinputs}. \vb \sec{AMS\TeX} \vb AMS\TeX\ is another macro package made available through the American Mathematical Society. Like La\TeX, it requires a megabyte or more of memory to run. It is supplied in source form only; if you wish to use it, you will need to create a format file for it. (See the section on \.{initex} for details.) To create such a format file, you will need add \.{LaTeX:AMSTeX} to your \.{texinputs} path at least temporarily, and then run \.{initex} over \.{aplain.tex}. Remember to reset the \.{texinputs} path to what it was originally afterwards. %% X. Speeding up TeX using the ram disk \vb \sec{ARexx Support} \vb ARexx is a general purpose scripting and macro language for the Amiga. It is functionally identical to REXX on IBM mainframes, but has many additional features, allowing such uses as management of interprocess communication. Instead of making each application on the Amiga understand every other application, the developer simply adds an ARexx port to his application, and provides a certain set of primitives which other applications can use. As more and more programs become ARexx compatible, you will be able to combine and use Amiga applications in incredible ways. \vb With this section of the manual and some documentation from the editor you intend to use, you should be able to construct a fairly nice integrated environment for \TeX. If you are not familiar with ARexx, I recommend that you read the ARexx manual before embarking on this; this document takes no pains to explain ARexx. \vb Please note that neither ARexx nor the \.{mg} editor used here are supplied with the Amiga\TeX\ package. ARexx is available from William Hawes, Box 308, Maynard, MA~~01754. One ARexx compatible editor, TxED Plus, is available from MicroSmiths, Box 561, Cambridge, MA~~02140. The \.{mg} editor illustrated here, complete with source, is available from Tomas Rokicki, Box 2081, Stanford, CA~~94309; simply send a blank disk and an SASE. If you have ideas for more ARexx primitives to be added to \TeX, the preview program, and drivers, please let me know! \vb \sub{\AT\ ARexx Primitives} \vb This section is the main reference portion of the ARexx port. The rest is simply examples of ARexx scripts. The Amiga\TeX\ Arexx port is called (surprisingly enough) \.{AmigaTeX}. It is strictly a server port; it never makes requests of ARexx. Amiga\TeX\ makes four primitives available to ARexx. These four primitives are: {\vb\leftskip=30pt\parindent=-30pt {\tt Abort} This command aborts the current \TeX\ job, if one exists, and goes back to the \.{**} prompt the quickest way possible. It returns 0 if it didn't need to do anything (i.e., \TeX\ was waiting for another file) or 1 if it had to interrupt \TeX. \vb {\tt Prompt} This command sets up \TeX's current prompt into the cliplist in a variable by the name of \.{AmigaTeX.Prompt}. If \TeX\ is working, then it makes this variable the null string. If \TeX\ couldn't open a file and is waiting for a new name, it returns the value `\.{file}'. Otherwise, the prompt should be one of `\.{**}', `\.{*}', `\.{? }', `\.{insert>}', or `\.{=}'. \vb {\tt ErrorLoc} This command sets the current error file name, line number, and character position in the cliplist variable \.{AmigaTeX.ErrorLoc}. This value has the form `file line char'. If there is no error, then this string should be empty, but you might check the prompt. \vb {\tt TeXify} {\it filename} This command sticks the rest of its command line into the \.{**} prompt, and tells TeX to start. Only valid at the \.{**} prompt. If any other prompt is displayed, it returns a 1 and does nothing. \vb} Don't worry if this isn't all perfectly clear at the moment; a few examples should illustrate it sufficiently. \vb \sub{Invoking \TeX\ on a Buffer} \vb We shall start by illustrating how you might invoke \TeX\ over a buffer. For an editor we will use a version of \.{mg}, an editor similar to GnuEmacs, modified to add ARexx capabilities. The startup file (\.{s:.mg} in this case) of the editor might look something like this: \ttcmd{^X( ^X^S $x 'rexx' 'TeXify' ^X)\\ $x 'global-set-key-macro' \!f1\\ ^X( $x 'rexx' 'ToError' ^X)\\ $x 'global-set-key-macro' \!f2} The first line of this file defines a macro which saves the current file, and then sends a message of \.{TeXify} to ARexx. The second line binds this macro to the first function key. The third line defines a macro which sends a \.{ToError} message to ARexx, and the fourth line binds this to the second function key. Your initialization file for your editor will almost certainly be more readable. \vb In order to run the following macro, you should have loaded the ARexx support library \.{rexxsupport.library}. This can be loaded with the command \cmd{1> rx "say addlib('rexxsupport.library',0,-30,0)"} \noindent When ARexx gets the \.{TeXify} message, it first checks to see what extension the application is telling it to use for the file name. Our editor passes the extension \.{.mg}, so ARexx looks for the file \.{rexx:TeXify.mg} and tries to load it as a ARexx script. This file looks like: \ttcmd{/* This file texify's its argument */\\ options failat 5\\ filename = getclip('mg.BufferName')\\ if showlist('Ports','AmigaTeX')=0 then do\\ \t address command "newcli from s:StartTeX"\\ \t do i=1 to 10\\ \t\t if showlist('Ports','AmigaTeX') ~= 0 then leave i\\ \t\t address command 'c:Wait 5' \\ \t end\\ \t if showlist('Ports','AmigaTeX')=0 then exit\\ end\\ address 'AmigaTeX'\\ do i=1 to 10\\ \t 'Abort'\\ \t if RC=0 then leave i\\ \t address command 'c:Wait 5'\\ end \\ 'TeXify' filename\\ exit} \noindent The \.{failat} option is necessary so that the error returns from Amiga\TeX\ don't make the script abort. (If Amiga\TeX\ gets a command it doesn't understand, it returns error code 10, which will still make the script fail.) The first thing the script does is get the file name from the editor. Whenever \.{mg} invokes an ARexx macro, it stuffs the file name of the current buffer into the cliplist. Then our macro sees if it can find an existing \TeX\ port. If it cannot, then it runs \TeX\ by getting a new CLI and reading its input from the file \.{s:StartTeX}, which looks like: \ttcmd{cd vd0:\\ tex} \noindent Note the \.{cd} command; this is necessary because by default, the new CLI has as its current directory \.{df0:{}}, and we do all of our work from the \.{vd0:{}} recoverable ram disk. We then iterate a few times, waiting for \TeX\ to come up, and if it doesn't come up after approximately a minute, we bail out. \vb Finally, once we have an Amiga\TeX\ port, we set the default host environment to it. Then, we send the Amiga\TeX\ \.{Abort} command until the return code of 0 indicates success. After this, we send the \.{TeXify} command to Amiga\TeX, and return. \vb \sub{Finding An Error} \vb If Amiga\TeX\ finds an error, then it stops with a `\.{? }' prompt, and waits for user interaction. Within the editor, it is possible to go to the location of the error with a single keystroke. This is our second illustrative ARexx macro, called \.{rexx:ToError.mg}. \ttcmd{/* Now we try to determine the error location */\\ options failat 5\\ address 'AmigaTeX' 'ErrorLoc'\\ errorloc = getclip('AmigaTeX.ErrorLoc')\\ if errorloc = "" then exit\\ else parse var errorloc filename linenum charpos\\ address 'mg' "^X^F '"||filename||"'"\\ address 'mg' "$x 'goto-line' '"||linenum||"'"\\ address 'mg' "^U "||charpos-1||" ^F"\\ exit} \noindent This script is shorter and even easier to explain. Again, we need the \.{failat} option. After setting that, we send Amiga\TeX\ an \.{ErrorLoc} call. This places into the ClipList the location of the error. We pull this from the cliplist, and exit if it is null. If it isn't, we parse it into a filename, line number, and character position. Then we send the editor commands to visit that file (if it already isn't), and to go to the correct line and character position. % \vb \sec{Using the RAM disk} \vb Judicious use of the RAM disk or one of the available recoverable RAM disks can speed up \TeX\ processing on the Amiga significantly. You will probably only be able to take advantage of some of the tricks illustrated in this section if you have at least one megabyte of RAM. \vb \sub{Moving the Format File to RAM} \vb To reduce the delay involved in loading the format file each time \TeX\ is run, you might want to copy it into RAM. This will require approximately 111K of RAM for plain and 260K for La\TeX. A typical sequence of operations to perform this might be \cmd{1> makedir ram:macros\\ 1> copy tex:macros/plain.fmt ram:macros\\ 1> set texmacros=ram:macros,tex:macros} \noindent With the new \.{-R} option to \AT, this is no longer the best way to get this effect. \vb \sub{Moving Your Working Directory to RAM} \vb Another possibility is to move your working directory to the RAM disk. This will reduce disk traffic dramatically. The only potential problem is that if the machine crashes or loses power, all of your files in the RAM disk will be destroyed. Therefore, you always want to edit your source file off the floppy, and only create the \.{.dvi} and \.{.log} files on the RAM disk. To do this, before you invoke \TeX\ or the previewer, type \cmd{1> makedir ram:tex\\ 1> cd ram:tex} \noindent The \.{makedir} command need only be executed once, but the \.{cd} command should be executed from both the preview and the \TeX\ window. Let us say that your normal working directory is \.{df0:mysource}. You should also execute the following command before entering \TeX, so it knows where to look for your input files: \cmd{1> set texinputs=df0:mysource,.,tex:inputs} \noindent Now \TeX\ will look first on your working directory on the floppy, then on the current RAM directory, and finally in the \.{tex:inputs} directory. The editor should be invoked with \.{df0:mysource} as the current working directory so files will be read and written to the floppy rather than the volatile RAM disk. \vb \sub{Moving Everything to RAM} \vb If you have a lot of extra memory, you might consider moving all of the \TeX\ files to RAM disk. You can move all of the files on the standard distribution disk and set things up to work entirely off RAM disk with the following sequence of commands: \cmd{1> makedir ram:tex\\ 1> copy tex:\ ram:tex all} \noindent Now go out and get a cup of coffee; this will take a while. When it is complete, remove the \.{TeX} floppy and type \cmd{1> assign tex:\ ram:tex} \noindent and follow the instructions in the previous section to move your working directory to RAM. % % Using foreign fonts % \sec{Importing Font Files} \vb Amiga\TeX\ is fully compatible with all versions of \TeX. (An implementation cannot be called \TeX\ unless it is fully compatible with the standard.) This allows you to import font files you have created on a mainframe with METAFONT, for instance. The \.{.tfm} file must be moved into the \.{tex:fonts} directory, and any \.{.pk} files must be moved into the appropriate subdirectory of \.{tex:pk}. Since METAFONT creates \.{.gf} files, a program to convert these files to \.{.pk} files is included. It is called \.{gftopk}; to run it, put the \.{.gf} file in your current directory, and invoke \.{gftopk} with the name of the \.{.gf} file. The conversion will be performed. \vb Likewise, if you have some old \.{.pxl} font files, you can convert those to \.{.pk} files with the program \.{pxtopk}; it is invoked in the same way as \.{gftopk}. \vb To use your local fonts with the previewer, you must create them at a magnification of 100 dots per inch, multiplied or divided by some power of $1.2^{1/2}$. Thus, for a full set of previewer fonts, you must create font files at resolutions of 69.44, 76.07, 83.33, 91.29, 100, 109.54, 120, 131.45, 144, 157.74, 172.8, for instance. Actually, you can select the resolutions you use most often and just create them. \vb When you download any font files, whether \.{.tfm}, \.{.pk}, \.{.gf}, \.{.pxl}, or whatever, you must be careful to download them as binary files. Refer to the documentation for the software you use to download files for details. \vb You should then create a floppy containing all of your new fonts, in the appropriate subdirectories. For instance, a font called \.{script} created at 131 dots per inch on a font floppy you named \.{myfonts:{}} should be stored as \.{myfonts:131/script.131pk}. You should copy the \.{tfm} files to \.{TeX:fonts}. Then, you need to add a line to the \.{TeX:pk/fontvols} file such as \cmd{myfonts=100dpi.69.76.83.91.100.110.120.131.144.158.173.207} \noindent if you have fonts at all of those sizes. Finally, you should type \cmd{1> delete tex:pk/\#?/pk.direct} \noindent to delete all of the directory files, so they can be recreated with information about your new fonts. Your fonts will then be automatically cached in. % % History of AmigaTeX; its origins and development % \sec{History} \vb \AT\ is a \TeX\ which functions exactly like the \TeX s on any other machine, from DEC-2060s to IBM-PCs. There is no difference; a \TeX\ source file developed on one machine is fully compatible with the \TeX s on any other machine. How was the huge \TeX\ program, whose user manual is almost 500 pages long, crammed into a 512K Amiga? This section describes the history of \AT; how it was developed and ported to the Amiga. It assumes that the reader is conversant about programming languages, \TeX, and some computer operating systems. \vb \AT, as all current implementations of \TeX, started life as the original source file of \TeX. \TeX\ was written by Donald Knuth in \.{WEB}, a system of structured programming and documentation. \.{WEB} is mostly a macro preprocessor for both \TeX\ and Pascal, allowing one to program in Pascal and document in \TeX, and providing publication quality program documentation. The program \.{tangle} takes a \.{.web} file and converts it into a \.{.pas} Pascal source file. \vb Unfortunately for those running Unix, few good Pascal compilers exist for Unix, and those that do are typically very expensive. Most Unix sites running \TeX, therefore, were paying a significant performance penalty. Most Unix systems have good C compilers, though, so Tomas Rokicki and $n^2$ Computer Consultants decided to translate \TeX\ into C. This translation was done automatically using the compiler tools available under Unix, and it was not long before C\TeX\ came into existence. This version of \TeX\ has been ported to almost everything running any brand of Unix, and almost invariably shows a marked speed improvement over the Pascal version. \vb When Tom Rokicki got his Amiga, it was natural that he wanted to run \TeX\ on it. So he ordered a beta copy of the Manx C Compiler and moved all of the source files for C\TeX\ onto floppies. (At that time, and even as this is being written, no good Pascal compilers exist for the Amiga.) Then he set to work. \vb There were bugs in the compiler. These had to be gotten around. Certain modifications had to be made to the source to make it work under the Amiga operating system. But finally, everything worked. Even then, hundreds of hours were invested in optimizing and rewriting major sections of code in 68000 assembly language to make the final program small and fast. \vb And then the real work started---writing the preview program. This program was coded completely from scratch. It had to manage the dozens and dozens of fonts that might be used, interpret \.{.dvi} files and \.{.pk} files, handle user interaction through gadgets and menus, and be fast. It was a significant effort, but things finally fell into place. And that is the story of \AT. \sec{Software Support} \vb %% XII. Support %% A. Updates Updates and revisions will be made available at a cost of \$10 per floppy required for the update. Notification of updates will be sent to all licensed owners of \AT. \vb %% B. Bug reports If you suspect you have found a bug in \AT, please mail a complete description of the error, including any commands and source files necessary to duplicate it, to us. Include your telephone number and when you can be reached, and we will get back to you as soon as possible. \vb %% C. Software support If you have any questions about the operation of this program, please re-read the manual carefully. Then, reboot and start again. If you have trouble, we'll be happy to help answer any questions you might have. Our address is \vb \leftline{\hskip2\parindent\vbox{\hbox{\AT} \hbox{$n^2$ Computer Consultants} \hbox{Box 2736} \hbox{College Station, TX~~77841}}} \vb Bug fixes will get faster response if you send them to \vb \leftline{\hskip2\parindent\vbox{\hbox{\AT} \hbox{Radical Eye Software} \hbox{Box 2081} \hbox{Stanford, CA~~94309}}} \vb Tomas Rokicki, the author of the program, is available to answer questions. Simply leave a message on the answering machine at (415) 326-5312, and he will get back to you as soon as possible. %% D. Getting TeX on another system \TeX\ has been ported to dozens of computer systems, and currently runs on everything from the IBM-PC to the CRAY. For microcomputer versions of \TeX, check out the advertisements in {\it BYTE\/} and other microcomputer magazines. For mainframe distributions, contact Maria Code at (408) 735-8006; she handles the distribution of \TeX\ tapes. Note that she is not familiar with \TeX, she only distributes the tapes, so please do not ask her technical questions. The cost for the tapes is nominal. %% E. Joining TUG \vb The \TeX\ Users Group (TUG) is an organization dedicated to the exchange of information about \TeX\ and its implementations. General meetings are held once a year, and short courses at several levels of `\TeX pertise' are given at several sites during the year. Tapes of these courses are available for rental. Site coordinators for implementations of \TeX\ on particular machines help those with similar configurations, and the {\it TUGboat}, featuring articles on \TeX, is published at least semiannually. Information is available from \vb \leftline{\hskip2\parindent\vbox{\hbox{\TeX\ Users Group} \hbox{c/o American Mathematical Society} \hbox{P.~O.~Box 6248} \hbox{Providence, RI~~02940}}} \sec{Distribution File List} \vb %% XIII. Distribution disk and file list, and explanation This is a list of all of the files on the ten distribution diskettes, and a brief explanation of their purpose. (This list may not be complete because of last minute changes to the distribution.) {\def\start{\vb\begingroup\parindent=0pt\tt\obeyspaces\obeylines} \def\trats{\vb\endgroup} \start \ TeX: (disk 1 of 10) \trats These are all the font metric files that contain resolution independent information about each font. They include the standard 102 \TeX\ fonts, with a couple extras thrown in to keep certain macro packages happy. \start \ fonts (dir) \ circle10.tfm circlew10.tfm \ cmb10.tfm cmbsy10.tfm \ cmbx10.tfm cmbx12.tfm \ cmbx5.tfm cmbx6.tfm \ cmbx7.tfm cmbx8.tfm \ cmbx9.tfm cmbxsl10.tfm \ cmbxti10.tfm cmcsc10.tfm \ cmdunh10.tfm cmex10.tfm \ cmff10.tfm cmfi10.tfm \ cmfib8.tfm cminch.tfm \ cmitt10.tfm cmman.tfm \ cmmi10.tfm cmmi12.tfm \ cmmi5.tfm cmmi6.tfm \ cmmi7.tfm cmmi8.tfm \ cmmi9.tfm cmmib10.tfm \ cmr10.tfm cmr12.tfm \ cmr17.tfm cmr5.tfm \ cmr6.tfm cmr7.tfm \ cmr8.tfm cmr9.tfm \ cmsa10.tfm cmsl10.tfm \ cmsl12.tfm cmsl8.tfm \ cmsl9.tfm cmsltt10.tfm \ cmss10.tfm cmss12.tfm \ cmss17.tfm cmss8.tfm \ cmss9.tfm cmssbx10.tfm \ cmssdc10.tfm cmssi10.tfm \ cmssi12.tfm cmssi17.tfm \ cmssi8.tfm cmssi9.tfm \ cmssq8.tfm cmssqi8.tfm \ cmsy10.tfm cmsy5.tfm \ cmsy6.tfm cmsy7.tfm \ cmsy8.tfm cmsy9.tfm \ cmtcsc10.tfm cmtex10.tfm \ cmtex8.tfm cmtex9.tfm \ cmti10.tfm cmti12.tfm \ cmti7.tfm cmti8.tfm \ cmti9.tfm cmtt10.tfm \ cmtt12.tfm cmtt8.tfm \ cmtt9.tfm cmu10.tfm \ cmvtt10.tfm dummy.tfm \ icmex10.tfm icmmi8.tfm \ icmsy8.tfm icmtt8.tfm \ ilasy8.tfm ilcmss8.tfm \ ilcmssb8.tfm ilcmssi8.tfm \ lasy10.tfm lasy5.tfm \ lasy6.tfm lasy7.tfm \ lasy8.tfm lasy9.tfm \ lasyb10.tfm lcmss8.tfm \ lcmssb8.tfm lcmssi8.tfm \ line10.tfm linew10.tfm \ logo10.tfm logo8.tfm \ logo9.tfm logobf10.tfm \ logosl10.tfm manfnt.tfm \ trip.tfm \trats The \.{nul.tex} file is used to get out of \TeX's `could not open file, type another file name' loop. The \.{verb.tex} file has a set of macros for verbatim mode; the \.{testfont.tex} file allows you to sample particular fonts. The \.{plain.fmt} file is the default plain \TeX\ format file for a machine with more than 512K. The \.{tex.pool} file has all of \TeX's strings for Ini\TeX; you should probably delete this file from your working \.{TeX} disk. \start \ inputs (dir) \ nl.tex nul.tex \ null.tex testfont.tex \ verb.tex \ macros (dir) \ plain.fmt tex.pool \trats The \.{pk} directory contains the cache for all of the packed files. Supplied on the \.{TeX} disk are a few sample fonts; the rest will be loaded on demand from the font distribution disks. The file \.{TeX:pk/fontvols} contains a list of the distribution fonts and a few other caching parameters. \start \ pk (dir) \ fontvols \trats The openwindows command file is a typical way to open three windows in which to run \TeX, the preview program, and an editor. The samples directory contains a very short, very simple \TeX\ example---the default \.{story.tex} from the \TeX book. \start \ s (dir) \ openwindows to-512 \ samples (dir) \ story.tex \trats The second disk contains the executables, all of the special files necessary on a 512K system, and the files necessary to recreate a \.{plain.fmt} file. It also contains this manual. Execute the \.{to-512} command file to install \TeX\ on a 512K system. It also contains a few sample files for \TeX. \start \ TeXfiles: (disk 2 of 10) \ 512 (dir) \ plain.fmt sizes \ c (dir) \ bibtex gftopk \ initex pktype \ preview pxtopk \ set tex \ unamiga \ inputs (dir) \ hyphen.tex plain.tex \ manual (dir) \ amigatex.tex fontlist.tex \ samples (dir) \ heart.tex primes.tex \ story.tex \trats The third floppy contains everything necessary to run La\TeX, Sli\TeX, and AMS\TeX. The first group is the distribution of AMS\TeX\ (sources only). To run AMS\TeX, you must create an \.{aplain} format file. If you do not plan to use AMS\TeX, it is highly recommended that you delete these files. \start \ LaTeX: (disk 3 of 10) \ AMSTeX (dir) \ amsppt.mor amsppt.sty \ amstex.tex aplain.tex \trats To run La\TeX, all of the files in the \.{inputs} directory should be accessible, and the \.{lplain.fmt} file from the \.{macros} directory should be loadable by \TeX. Sli\TeX\ is similar, but requiring the \.{splain.fmt} file. \start \ inputs (dir) \ abbrv.bst alpha.bst \ art10.sty art11.sty \ art12.sty article.sty \ bezier.sty bk10.sty \ bk11.sty bk12.sty \ book.sty fleqn.sty \ ieeetr.bst ifthen.sty \ leqno.sty letter.sty \ makeidx.sty openbib.sty \ plain.bst proc.sty \ rep10.sty rep11.sty \ rep12.sty report.sty \ showidx.sty slides.sty \ suthesis.sty titlepage.sty \ twocolumn.sty unsrt.bst \ macros (dir) \ lplain.fmt splain.fmt \trats The fourth disk contains the files necessary to create new style files and recreate the \.{lplain} and \.{splain} format files, and some La\TeX\ samples. \start \ LaTeXfiles: (disk 4 of 10) \ format (dir) \ latex.tex lfonts.tex \ lplain.tex sfonts.tex \ slitex.tex splain.tex \ samples (dir) \ addendum.tex lablst.tex \ local.tex sample.tex \ small.tex testpage.tex \ docs (dir) \ art10.doc art11.doc \ art12.doc article.doc \ bezier.doc bk10.doc \ bk11.doc bk12.doc \ book.doc fleqn.doc \ ifthen.doc leqno.doc \ letter.doc makeidx.doc \ openbib.doc proc.doc \ rep10.doc rep11.doc \ rep12.doc report.doc \ showidx.doc slides.doc \ suthesis.doc titlepage.doc \ twocolumn.doc \trats The remaining six floppies contain fonts. Each floppy contains two or more sets of fonts of one size. The names of the floppies correspond to the colors of the labels, for easy location during font caching. Thus, a floppy named \.{Red.Green} might contain fonts at size 100 and 110 dots per inch, such as \.{Red.Green:100/cmr10.100pk} and \.{Red.Green:110/cmr10.110pk}. In the file \.{TeX:pk/fontvols}, this floppy might be identified with a line such as \cmd{Red.Green=100d.100.110}.} \vb \sec{Changes From 1.3 Release} \vb Thank you for purchasing the update to the \AT\ package. I think you will be pleased with the changes that have been made to the package in the last few months. \vb The current distribution includes the latest La\TeX, Sli\TeX, and AMS\TeX, as well as the latest \.{plain.tex} and other files. In addition, a number of minor bugs were found and corrected in the standard Stanford \TeX; these bugs were also corrected in \AT, so this release corresponds fully with all other \TeX\ implementations up to version 2.9. \vb The fonts have all been regenerated and improved as well, and a larger set of fonts is distributed with this release; over 1500 fonts for the previewer, and 770 fonts with each printer driver. This is the full standard set of \TeX\ fonts, including those for La\TeX\ and Sli\TeX. \vb Another useful improvement is the communication between \AT\ and the previewer. If the previewer is running when \TeX\ attempts to open a \.{dvi} file, and one of the previewer tracking modes is selected, the previewer will be notified of the new file, and this file automatically displayed. Thus, the commands needed in the edit-\TeX-preview cycle have been reduced. You no longer need to close the file in the previewer, re-\TeX\ it, and reopen the file in the previewer; you simply re-\TeX\ it and the previewer knows about it. This is covered in the description of the `tracking' menu of the previewer. \vb A bug in the preview and printer drivers has been squashed; this bug showed up if \.{TeX:pk/fontvols} did not terminate with a carriage return, and sent the above programs into an infinite loop. Many small and large improvements have been made to all of the printer drivers. \vb Some other changes to \TeX\ have been made as well. User input typed to a double asterisk prompt is saved for the next such prompt. Thus, you no longer have to retype the file name to \TeX\ on subsequent times; simply hit carriage return. The quick loop mode has also been added for extremely quick format file loading; this is the \.{-R} option to \AT. Four levels of user interrupt have been added; {\it CNTRL}-F will always exit the program. Some minor bugs have also been found and swatted. Support for the Amiga special characters has been added. Note that with the current version of \AT, you can no longer exit the program with {\it CNTRL}-$\backslash$ unless you are running \.{conman}. \vb A major bug has been found and fixed in \.{bibtex}, concerning use of negative arguments to the \.{substring} operator. \vb The previewer has undergone the most dramatic changes. These changes include cosmetic changes so that it resembles other Workbench windows more closely and some very minor bug fixes. Menus now stay on even while the page is being redrawn. If the window is on the workbench screen, you can now select the foreground and background color. You can now see the entire page on the screen at once, although you probably won't be able to read it. The space and backspace now go to the top of the new page instead of retaining the old position. The ability to view facing pages was added. Environment variables are now reexamined each time a \.{dvi} file is opened, so you can change the font paths and have it take effect without exiting and reentering the previewer. System requesters now come up on the previewer's custom screen, if one is in use. The up and down arrow keys, when combined with the shift key, move the page up or down one half of a screen, for those cases when only half a paragraph is on the screen. \vb The font caching scheme has been changed incompatibally. This means that you should not use any of your old executables, and you should update the \.{TeX:pk/fontvols} file according to the instructions in this new manual. The changes were introduced to allow color-keying of the font disks, to allow use of resolutions with more fonts than would fit on a single disk, to allow the use of incomplete resolutions (such as magstep 9, at which resolution only the Sli\TeX\ fonts are supplied) and to pack the distribution font disks more tightly. If you are using a printer driver, you must also update the printer driver. %% XIV. Glossary \sec{Glossary} \vb This section contains the definitions of some of the more obscure terms used in this manual. \vb {\leftskip=\parindent\parindent=-\parindent \def\d#1:{\par{\bf #1}} %% boot \d boot: To start or restart the Amiga by pressing down the {\it CNTRL\/} key and both Amiga keys (the fancy `A's on either side of the space bar). Used as either a verb or a noun; comes perhaps inappropriately from the phrase `lifting one by one's bootstraps'. %% CLI \d CLI: Command Language Interpreter; a program that takes the user's input and parses it into commands and arguments, loads the commands and executes it. This is the traditional mode of operation of a computer, in contrast with the desktop metaphor. %% desktop metaphor \d desktop metaphor: A method of user interface where files are represented as icons, programs as windows, and the user `executes' commands by selecting, dragging, and pointing with the mouse. For instance, to delete a file using the desktop metaphor, you would click on the icon you want to delete, and drag the icon over to the trashcan, where you would let go of the select button. %% double click \d double click: Two rapid presses of the select button; this is the way an icon is activated in the Amiga. If the icon represents a program, the program is run; if the icon represents a directory, the directory is opened and a window showing the contents of the directory is displayed. %% driver \d driver: A program that takes a \TeX\ device-independent (or \.{.dvi}) file and interprets it, loading the rasters for the fonts as necessary, and sends the required commands to a particular printer or other output device to produce the document described. %% dvi file \d{\tt .dvi} file: A device-independent file is the output of the \TeX\ program; it contains a description of the typeset document in a compact form that is resolution and output device independent. %% environment variables \d environment variables: Global variables that the user can set and which are accessible to programs in the machine. An environment variable can be used to set some option or convey some information to a program; for instance, they might be used to tell \TeX\ where to find font files in a user-configured system. %% fmt file \d{\tt .fmt} file: A format file is a compact form of a set of \TeX\ macros that is loaded in every time \TeX\ is run to make those macros available. The \.{fmt} file is created by ini\TeX\ and consists of essentially a memory image of \TeX\ after the macros have been loaded. The default \.{fmt} file is called plain \TeX; La\TeX\ uses another format file called \.{lplain.fmt}. The format files must reside in the \.{tex:macros} directory. %% font \d font: A collection of printing characters of one style or size; for instance, \.{cmr10} is Computer Modern Roman at 10 points. The word font is used to refer to both a particular style, independent of size, and a particular style at each individual size. \AT\ is currently supplied with the standard \TeX\ 91 fonts; many different sizes of these fonts are distributed for the previewer. %% gadget \d gadget: Some graphics imagery that, when selected with the mouse, starts some operation. For instance, the window-to-front gadget is in the upper right hand corner of a window, and when you select it, it brings that window in front of any other windows that might overlap it. %% icon \d icon: Some graphics imagery that represents a file, program, device, or directory. These can be activated or opened by double-clicking on them with the mouse. %% info file \d{\tt .info} file: A small file containing the graphics imagery of the icon; associated with an executable, directory, or data file. When the executable, directory, or data file is copied, renamed, or deleted, this file should also be copied, renamed, or deleted, to keep the desktop metaphor consistent. %% IniTeX \d ini\TeX: The ini\TeX\ program is a larger version of \TeX\ that takes more memory to run; its purpose is to create format files from a set of macros. %% interlace \d interlace: The process of refreshing a video screen at half the normal rate by drawing alternate lines in each scan. The Amiga uses interlace for the screen modes that use 400 lines vertically; with a normal monitor, interlace can cause flicker that can be annoying. %% Intuition \d Intuition: The set of routines in the Amiga that controls the user interface, including the windowing, gadget, and menu routines. A properly written program on the Amiga will follow certain guidelines established by Intuition to allow the simultaneous and convenient use of many several different programs in the Amiga operating environment. %% kerning \d kerning: The addition or removal of spaces between characters due to their shape. For instance, in the word `AVAILABLE', the `A' and `V' are moved closer together; compare this with `A{}V{}A{}I{}L{}A{}B{}L{}E', with the kerning turned off. \TeX\ handles kerning automatically. %% LaTeX \d La\TeX: A macro package intended to both make \TeX\ easier to use and more powerful, La\TeX\ was written by Leslie Lamport. It is supplied with \AT, but requires more than 512K to run. %% ligatures \d ligature: A ligature is the combination of two or more characters into one character. For instance, the `f' and `i' in `file' is a ligature; compare this with `f{}i{}l{}e', using separate characters instead. \TeX\ handles ligatures automatically; no special characters need be typed. %% log file \d{\tt .log} file: A file that contains all of the terminal output during a run of \TeX; it is created automatically along with the device-independent file for later perusal of any errors. It serves no purpose other than user enlightenment, so it can be safely deleted at any time. %% loop mode \d loop mode: When \TeX\ is run on the Amiga in loop mode, the program does not exit after finishing a job. Rather, it restarts, and waits for another file name. This is to eliminate the delay in loading the \TeX\ executable off the disk. \TeX\ runs in the loop mode when it is invoked with no file name, or when it is given the \.{-r} option before the file name. %% menu button \d menu button: The right mouse button. This is called a menu button because pressing it displays the menus for the currently active window on the screen title bar. To select a particular menu item, you hold the menu button down, move the mouse to the menu name and then to one of the items that will appear, and then release the menu button. %% pk file \d{\tt .pk} file: A packed file contains raster information for a particular font at a particular resolution in a compressed format. \TeX\ does not use these files at all, but the preview program and any other drivers require them at certain resolutions. %% plain format \d plain format: A basic macro package that contains several hundred predefined macros; \TeX\ loads these in at the start of each job unless another format file is specified. %% pool file \d pool file: \TeX\ has over 25000 characters worth of error and other messages. Rather than place these in the executable image, they are put into a special \.{tex.pool} file that ini\TeX\ reads and places in every format file. If ini\TeX\ complains about not being able to find the \.{tex.pool} file, this file should be placed in the current working directory. %% RAM disk \d RAM disk: A `disk' whose files are stored in the computer's memory rather than on magnetic media. It is generally faster than floppies or hard disks, but is volatile; if the computer is booted or powered down, all of the files in the RAM disk are destroyed. It is usually used for fast, temporary storage. Proper use of the RAM disk can make the computer system run noticeably faster, especially on a system with a lot of memory. %% raster \d raster: A graphics image stored as actual pixels rather than an analytical description. For instance, the \TeX\ packed files contain the raster, or pixel by pixel representation, of each character in a particular font. Raster graphics are by their very nature resolution dependent; analytical graphics are not. %% reboot \d reboot: To boot again; see {\it boot.} %% requester \d requester: A window opened when a program or the operating system requires some response or action from the user. With a requester, all further input to the program is blocked until the requester is answered. Requesters might require you to insert a particular disk or ask you to change the colors of the screen. %% resolution \d resolution: In raster graphics, the resolution refers to the number of dots (or pixels) per unit measure, usually per inch. For instance, a dot matrix printer might print at a resolution of 72 dots per inch, a laser printer at 300 dots per inch, and a typesetting machine at 720 dots per inch. %% screen \d screen: Under Intuition, a screen is a display memory region in which one or several programs may operate. Each screen has its own video characteristics, such as number of colors and resolution. Screens can overlap each other vertically, but each must be the full width of the video monitor. Preview opens up its own custom screen, while \TeX\ runs in the standard workbench screen. %% select button \d select button: The left mouse button; used to select gadgets or icons. Gadgets are selected by moving the pointer over the gadget and hitting the select button. Icons are selected the same way, but are activated by hitting the select button twice rapidly. The select button can be used to drag screens or windows around, or to resize them, by selecting the proper gadget and holding the select button down while moving the mouse. %% SliTeX \d Sli\TeX: A macro package written to create slides; part of the standard La\TeX\ distribution by Leslie Lamport. It requires the \.{splain.fmt} format file and more than 512K to run. %% splat \d splat: Another name for the asterisk (\.{*}). %% sty file \d{\tt .sty} file: An auxillary file read in by La\TeX\ that describes the layout of a particular document style; \.{rep10.sty} describes a ten-point version of the report style. These must reside in the \.{tex:inputs} directory when running La\TeX. %% tfm file \d{\tt .tfm} file: A font metric file contains resolution-independent information about a particular font, such as character sizes and ligature and kerning information. \TeX\ reads these files when you declare a new font; they must reside in the \.{tex:fonts} directory. %% title bar \d title bar: The top portion of a window or screen that contains the title of the window or screen and usually the to-front and to-back gadgets. The drag gadget is usually all portions of the title bar not occupied by other gadgets. Menus will appear in the title bar of a screen. %% TRIPOS \d TRIPOS: An English message-based operating system on which AmigaDOS is based. %% window \d window: An Intuition window is a rectangular section of a screen that a program uses for user interaction. Several windows may all reside on one screen, and can overlap each other arbitrarily. Each window must share all video attributes of the screen on which it resides; for instance, you cannot open a thirty-two color window on the four color workbench screen. %% workbench \d workbench: The name of the standard screen on which Intuition runs its desktop metaphor user interaction. \par} % % That's all for now, folks! % \bye