Introduction to ASCREEN 3.2 =========================== Preface ------- ASCREEN is a DVI previewer for Atari computers. Refer to the ANNOUNCE and README files to find out how magnificent it is :-) This short document explains some aspects of ASCREEN. Its main purpose is to soothe the author's conscience about not providing a proper English manual. (Most software products have English manuals only and no German. So there!) Installing ASCREEN ------------------ ASCREEN is adaptable enough to fit into just about any TeX installation on the Atari. However, it must be adjusted to your system. This is how: 1. Copy the disk. I mean it. COPY THE DISK. NOW. 2. You need to put the program (ASCREEN.PRG) where your TeX wants to find DVI drivers. Look for where your other previewer is and put ASCREEN.PRG right beside it. 3. You also need a resource file. If you're reading this document instead of the German manual, you don't want ASCREEN.RSC. It's all in German. Use ASCRNENG.RSC instead. That one's going to make sense to you. Put it right beside ASCREEN.PRG and call it ASCREEN.RSC. 4. Depending on which TeX implementation you're using, select a setup file and put it near ASCREEN.PRG under the name of ASCREEN.SET. Use ASCREEN.SET if you're using Stefan Lindner's TeX ASTRUNK.SET if you're using Christoph Strunk's csTeX The point of the exercise is that ASCREEN needs to know how font names are constructed in the TeX you're using. For example, cmr10 at 12pt is ...\res101.scr\mag____1.200\cmr10.pk in Lindner's TeX ...\font0115\cmr10.pk in csTeX Wilder schemes exist, too. Look at ASCREEN.SET to see a couple of them. 5. The ellipsis in the example stands for `wherever fonts are on YOUR system'. You have to fix that as well. Either look at ASCREEN.SET (the one you just created) with an editor, locate the line that says `fontpath' and insert the appropriate path there. Or start ASCREEN.PRG, select the `Paths' form from the `Options' menu and edit the font path. 6. Now you should be all set. There's loads of stuff that you can customise either using the forms in the `Options' menu or by editing the setup file. We'll be looking at some of that later. Running ASCREEN --------------- You can invoke ASCREEN from the desktop and then `Open' a DVI file from the `File' menu. You can also install ASCREEN as an application for DVI files so it is run whenever you double click on a file that has the .DVI extension. You can run ASCREEN from a command line shell that lets you run GEM programs (many of them do, e. g., GEMINI/Mupfel). Or you can call ASCREEN from a TeX shell if you're using one (like the CSTEX program in csTeX). First of all, ASCREEN reads a setup file, commonly called ASCREEN.SET. The name of this file is taken from the ASCREENSET environment variable if it exists. Or you can specify the setup file name on the command line, like `ascreen &foo.set bar'. This lets you have different setup files for various circumstances. Everything you can say in a setup file, you can also say on the command line, and vice versa. Previewing DVI files with ASCREEN --------------------------------- Once you have started ASCREEN and loaded a DVI file, the first page of the file will be displayed in a window. Use the following procedures to move about: - Scroll bars and arrows operate as usual. - The cursor keys are equivalent to the scroll arrows. Shifted, they are equivalent to clicking into the grey areas on the scroll bars. - For organ players, the 1,2,3,5 keys on the keypad are equivalent to the shifted cursor keys. The 7,8,9,) keys are equivalent to the unshifted cursor keys. The Clr/Home key warps to the top left corner of the page. - You may also drag the window contents directly by holding down the Alternate key while you're clicking the left button inside a window. Hold down Shift instead of Alternate for accelerated scrolling. You can go from page to page by the following methods: - Clicking and holding down the left button inside a window pops up a menu. The first two entrys let you move forward or back a page. The third will pop up a form which will let you enter a page number to go to. - Use the + and - keys on the keypad to move forward or back. Use the 0 key on the keybad to pop up the form. If you're at the bottom of a page and move forward, you'll end up at the top of the next page. Similarly, if you're at the top of a page and move back, you'll be put at the bottom of the previous page. This is called `smart paging', and you can switch it off if you don't like it. The Enter key will move down just like the 2 key until you're at the bottom of the page. Then it'll move over to the next page like the + key. The . key on the keypad does the same backwards. This is called `magic Enter' and you can switch that off as well. Now for some special tricks: - Use the popup menu to shrink the page you're looking at by a factor of 2 or 3. You're not going to be able to read anything but you'll be able to have a look at a complete page. The shrunken page will be displayed in a new window where you can move around, back and forth and so on independently. (You can't shrink it any further, though.) - You can also shrink two adjacent pages to look at how your document might look in a book. This is on the menu as well. - You can use the ( key on the keypad for single-page and the 4 key for double page shrinking from the keyboard. (Mnemonic: the 1 key & co. move a lot. The 4 key shrinks a lot.) - The shrink factor can be selected from the DVI options menu. The / and * keys on the keypad select a factor of 2 and 3, respectively. - A special `recto-verso mode' can be enabled for double-page shrinking by either selecting it from the popup menu or toggling it with the 6 key on the keypad. It will try to sensibly page backward and forward in steps of two pages instead of one, just like in a book or journal. The default mode can be selected from the DVI options menu. The menu bar ------------ These are the menu bar entries and what they do: About ASCREEN... You know that one. Open... Open a new DVI file, replacing the one currently displayed, if any. Reread Reread the current DVI file. Most useful in a multitasking environment. Quit program You know that one, too. New window Open a new window on the page currently in the top window. Window on page... Prompt for a page number, then open a new window on that page. Next window Put another window on top. Eventually this cycles through all windows. Close window Close the top window. Statistics Display memory statistics. Help Display a help dialog. GEM Options... Forms showing various options you can DVI Options... customise. Page Format... Form to override (enlarge) DVI page size Memory... Form to set memory usage parameters Paths... Form to set file access paths and parameters Restore... Restore setup from file Save... Save setup to file Options ------- Here's a list of all the things you can customise in the setup file, together with the equivalent command line options. Setup file Command line Remarks ------------------------------------------------------------------------- cacheahead [N, 1, D] -A Cache 1 page ahead of current cachepages [N, 5, M] -p # maximal number of pages cached colors [N, 1, G] -c # Colors; 256*background+foreground dvibuflimit [N, 20000, M] N/A max length of DVI files that will be read whole on opening dvibufsize [N, 8192, M] N/A buffer size when reading DVI file dvipath [dir, d:\texout, P] -D dir Standard directory for DVI files emergencyfont [font, cmr10] N/A font used if nothing else found emergencysize [dimen, 10pt] N/A `at size' of emergencyfont extension [string, scr] -e str %e in fontname template feeponerror [N, 1, G] N/A feep when printing error message? focus [Window/Pointer, Window, G] N/A Where keyboard commands go: active Window or window with Pointer in it fontname [template,, P] -z Template for font names. See below fontpath [path, d:\prtfonts, P] -F path List of font directories/FLIBs glyphmem [N, 64000, M] N/A Memory for unpacking glyphs grafpath [path, d:\graphics, P] -G path List of IMG file directories hresolution [N, 101, P] -r # horizontal resolution of fonts hypertex [N, 1, D] N/A HyperTeX \special cmds interpreted leftmargin [dimen, 0pt, S] -H dim Width of left margin logging [N, 0, D] -l write messages to log file? magnification [mag, magstep0], -M mag override DVI file magnification maxfonts [N, 32, M] -Z # max number of simultaneous PK files memcheck [N, 0, G] N/A display free mem in menu bar missingfile [file, missing.fnt, P] N/A file name for missing fonts list missingstyle [Lindner/Strunk, Lindner, P] N/A style for missing fonts list movebyenter [N, 1, D] -m use `magic Enter' movements msgraise [N, 1, G] N/A raise message window on output msgwindow [geometry, 256x160+320+154] -w geo geometry of message window nokeypress -J ignored for compatibility pageheight [dimen, 0pt, S] -y dim maximal height of bitmap or 0 pagetable [N, 1, D] N/A remember DVI page positions? pagewidth [dimen, 0pt, S] -x dim maximal width of bitmap or 0 rightbutton [N, 1, G] N/A use right button to drag pages rvmode [N, 0, G] N/A r/v mode default for 2-page shrinks? savemem N/A ignored for compatibility showgraphics [N, 1, D] -I actually show IMG graphics? shrinkfactor [2/3, 2, D] -f # default shrink factor smartpaging [N, 1, D] N/A see above stats N/A ignored for compatibility tfmpath N/A reserved for future expansion topmargin [dimen, 0pt, S] -V dim Size of top margin usedesk [N, 0, G] -d first page in borderless big window? verbose [N, 0, D] -v lots of explanations? vfpath N/A reserved for future expansion vresolution [N, 101, P] -r vertical resolution of fonts Information in brackets: [type, default, form] where `type' is N for a number, dimen for a dimension (as in TeX), dir for a directory name, font for a font name, template for a font name template (see below), path for a list of directory names separated by commas, mag for a magnification (as in TeX), file for a file name, geometry for a geometry specification (width x height [+/-] xoffset [+/- yoffset], as in X11). `form', if present, is where you can set the value from within ASCREEN: G: GEM options form, D: DVI options form, S: page dimensions form, M: memory form, P: paths form. `N/A' as a command line option means that this value is not accessible directly from the command line. However, any setup variable may be set using the special `-s' option, as in `-s rvmode=1'. A font name template works like a printf() format string (for those of you who know C). The idea is that certain magic `escapes' are replaced by bits that help in constructing a font name. Look at the original ASCREEN.SET to get the idea. The escape sequences are: %f font name (sans .pk suffix) %m magnification in per mille as an integer %M magnification as a real number (e. g., 1.728) %r (horizontal) device resolution in dots per inch %R %r times 5 %p (horizontal) device resolution in dpi multiplied by the magnification %P %p times 5 %e value of the `extension' variable A field width and precision may be interpolated between the % and the letter. A tilde (~) at the beginning of the template is substituted by the current directory from the font path. So, for example, the default value of `fontname', ~\res%r.%e\mag____%5.3M\%f.pk evaluates to `d:\texfonts\res101.scr\mag____1.200\cmr10.pk' for a 10pt Computer Modern Roman font at magstep 1, if `d:\texfonts' is being searched. Extras ------ Some programs and files are included with the distribution. These are: ALAUNCH This program demonstrates how to control ASCREEN via the GEM message pipe. It is designed to run under MultiGEM and can be installed as the application for DVI files. If a DVI file is double-clicked, ALAUNCH checks whether an ASCREEN process is running. If so, it is sent a message to open the new file instead of the one it currently displays. If not, an ASCREEN process is launched. Includes C source code. FONTLIST Lists the fonts used in a document. A variety of formats can be selected. Includes portable C source code. RESOURCE Helpful things for resource hackers, such as an RCS definition and C header file. ASCRNIC.RSC contains the official ASCREEN icons. HYPERTEX Demonstrates the experimental hypertext support in ASCREEN. Have fun. And don't forget that postcard!