33mLeggi0m A Multi-Font Text Reader By Sebastiano Vigna (c) 1990 You may ask: why should I consider another text reader? There's really no reason, unless you want a multi-window, multi-font, configurable, flexible, powerful text reader. If you do 33mLeggi0m may be the Amiga text reader for which you have been waiting! 33mLeggi0m can read simple IFF FTXT, ANSI and ASCII files, and open an unlimited number of windows with different fonts and styles. It auto-configures itself smartly. No fixed size window!. No hard-coded fonts in menus & text! ARexx, of course! Expert options to tuneup the program to suit your tastes and your system in a config-file. Freely distributable under the widest conditions possible. Pure and residentable. Fast and easy to use. Before you ask: "33mLeggi0m" in Italian means "read", and I am told is pronounced "leeji" in English. 33mLeggi0m needs ARP to run (not under the future 2.0-OS-only version). It likes req.library, too, but it's not necessary: simply, if you have it you will be able to use many functions without involving ARexx or the CLI. This condition will also be removed with the 2.0-OS-only version. Both the arp.library and req.library are in the distribution archive. Starting 33mLeggi0m is really simple: double-click on its icon, or just type "33mLeggi0m" at the Shell/CLI prompt. A full-WB-size window will pop up (except a pixel line at the very top will be saved to make it easier to drag around your screen). Play with the menus, they're easy to understand, and follow Commodore's guidelines. If you aren't reading this with 33mLeggi0m, why not start 33mLeggi0m and then load 33mLeggi0m.doc by selecting the "Open" option (or Right Amiga-O) and double clicking on 33mLeggi0m.doc in the ARP file requestor window. 33mLeggi0m's Menus 33mLeggi0m has menus, to be easy to use, and powerful shortcuts, to be fast for the experienced user. General Notes (*): The menu items marked with this symbol are available from the menus only if you have the system library named "req.library". Otherwise, you'll have to use the CLI command line. The menu items ending with "..." bring up a requester. This can be either the ARP file requester (very easy to use), or the req.library string requesters (very easy to use, too). 33mLeggi0m has three menus-- "Project", "Commands" and "Options". The Project Menu This menu manages files and windows. 33mLeggi0m has been designed to be almost limitless (i.e., as many windows can be opened as available memory allows), and this means several files can be displayed without having to run another copy of 33mLeggi0m. New: (Right Amiga-N) Opens a new window, and makes it the principal one (read on to see what it means). Open...: (Right Amiga-O) Loads a new file in the current window. Close: (Right Amiga-C) Closes the current window (same as the closing gadget). Save As ASCII...: Saves the file in the current window as a plain ASCII file. TABs are converted to spaces following the current settings. Quit: (Right Amiga-Q) Closes all windows and quits. The Commands Menu This menu's items direct 33mLeggi0m to do something. Font...: (Right Amiga-F) Changes the basic font for this window (33mLeggi0m allows upto 8 fonts). Free All Fonts: Closes all fonts used in this window (freeing memory) and picks up the system default font. Search... (*): (Right Amiga-S) Asks for a string to search for (max 79 characters); the search is case-insensitive and will start from the line following the very first one in the window; if a match is found in a line, it becomes the top screen line. Repeat Search Forwards: (Right Amiga-A) Repeats the last search looking forward. Repeat Search Backwards: (Right Amiga-B) Repeats the last search looking backward. Select: Selects the current window as the principal window (keep reading to find out what this means). Refresh Window: (Right Amiga-R) Refreshes the contents of the current window; this can be useful if, a simple refresh window has been scrolled behind another window---usually this will cause a lot of trash to be displayed (system design, not 33mLeggi0m's fault...). Jump To... (*): (Right Amiga-J) Jumps to a specified line in the file. The Options Menu This menu affects the way 33mLeggi0m acts. There are many switches, in order to fully configure the program to suit the user's tastes. All of the switches can be included in a configuration file (discussed below). Smooth Scrolling: (Right Amiga-H) Turns on a smooth type of scrolling, really slow, but some people like it because they can read while the window is scrolling. Grossier Scrolling: (Right Amiga-G) Turns on a raw scrolling, decently fast but absolutely unreadable during scrolling. Simple Refresh: Smart Refresh: Set the refresh type of the window 33mLeggi0m uses. These are rather difficult technical details of interest mainly to programmers, so I won't explain them in detail, only recall that Simple Refresh windows don't use Chip memory and are slower. Smart Refresh windows are faster but they use Chip memory (the wider the hidden part of the window, the more memory used). Please note that you can't scroll a Simple Refresh window that's partially hidden, or a lot of trash will appear. Line Numbers On: (Right Amiga-1) Line Numbers Off: (Right Amiga-0) Switch on and off the line length/line number indication in the window title. The updating of the line numbers tends to slow down the scrolling (at least under 1.3), so maybe you wouldn't want to keep it on all the time. Set Tabs... (*): (Right Amiga-T) Specifies a number of spaces that will be substituted for a TAB in the current window. Set Wordwrap... (*): (Right Amiga-W) Specifies the max length of a line, after which there will be an automatic wordwrap. "0" means no wordwrap. Please note that wordwrap is done at loading time (so a file must be re-loaded if you see it needs wordwrapping after loading). The breaking algorithm is rather stupid: it tries to break the line at the first space after the column number specified has been passed. Set Line Spacing... (*): (Right Amiga-L) Sets the interline spacing in pixels. You can get a much more readable file by inserting a few blank pixels between a row and another one. Eight pixels equal about one line in the default Topaz 8 font. Set Page Key... (*): (Right Amiga-K) Sets the page key to a specified string (max 39 characters). The key will be searched forwards each time you press CTRL-DOWN, and backwards each time you press CTRL-UP. There are some subtle differences between the switches, however. More precisely, Simple/Smart Refresh are global switches (i.e., common to all of the windows). They go in effect from the next window you open (it's impossible to change the refresh type of an already opened window). The other switches are local, i.e., setting Smooth Scrolling in a window won't change it in another window. But they are inherited, i.e., if you open a new window and the current windows has Smooth Scrolling, the new window we'll have it, too. 33mLeggi0m Keys Once a file is loaded, you can move around in it in many different ways. The simplest is to click and hold down the left mouse button on the top or bottom part of the window: the file will scroll up or down revealing more text. If you click about in the middle of a window vertically, but near the side of the window, the file will scroll horizontally, too! The second method is to use the scroll bar 33mLeggi0m puts at your disposal. Click on the knob and drag it: you'll get a "living" scrolling. You can also click on the bar but not on the knob: you'll move a page (less a line) at a time. The third way is to use the keyboard. The main keys for movement are, of course, cursor keys. They move one line at a time (vertically) or four caracters at a time (horizontally). If ALTed, the movement is greater: a window less one line at a time (both horizontally and vertically). If, SHIFTed the movement will be to the top/bottom of the file (UP/DOWN) or the default horizontal position (both SHIFT-RIGHT/LEFT do the same thing). The CTRL-UP/DOWN combination yields a really special behavior. You'll get the first occurrence in the file of a customizable key. For example, if you set the key to "======", you can skip one BIX message at a time. You can set the key from the CLI/Shell or from your configuration file. For experienced More/Less users, a "More" compatible mechanism is available: SPACE/("B" or BACKSPACE) to go up/down a page, and ESC to close the current window. If many windows have been opened, it could be time consuming searching around for a specified one. 33mLeggi0m lets you press a numeric key (the row on the top of the keyboard-NOT the numeric keypad) to choose a window through its number (0 yields 10). ALT adds 10, SHIFT adds 20, and CTRL adds 40. With a little practice in binary aritmetic, you can instantly get to anyone of eighty windows. In fact: ALT adds 10 SHIFT adds 20 ALT+SHIFT adds 30 CTRL adds 40 CTRL+ALT adds 50 CTRL+SHIFT adds 60 CTRL+ALT+SHIFT adds 70 Invoking 33mLeggi0m from the CLI/Shell 33mLeggi0m can be used and fully configured from the CLI/Shell. The syntax is rather complex, so try to get acquainted with the menus before getting into the deep of it. To get 33mLeggi0m's syntax, simply type "33mLeggi0m ?" at a prompt. Another "?" will give more help. There are many options, but they're grouped under the names "Usage:" and "Line commands". Let's start with "Usage:", because those are the most frequently used options. Files: an unlimited number of files can be specified for reading. You can also use wildcards (#? or *), in which case a window will be opened for each matching file. If too many windows are being opened, quit with Amiga-Q. Font : this command must be followed by font specification in the form /. For instance, "FONT Helvetica/15" will set the font to Helvetica, height 15 points, as the default font. Key : this option describes the pattern to search for when the smart paging feature is used---see below. SMOOTH, GROSSIER: these are exactly like their menu counterparts. NON, NOFF: exactly like Numbers On/Numbers Off. SMART, SIMPLE: we know the trick now, don't we? Please note that the first option is the only way to get the first window opened in smart refresh! Tab, WordWrap, LineSpacing: like the corresponding menu items. These are all of the options you should use when using 33mLeggi0m until you are familiar with 33mLeggi0m's operation. If 33mLeggi0m is invoked while its already running, a new copy of 33mLeggi0m will not pop up: rather, the options specified on the command line will be passed to the copy currently running. This means 33mLeggi0m can be "piloted" from the CLI, and this explains the need for the following options, too. Please note that while you're using menus, 33mLeggi0m knows very well the window you're referring to---it's the active window, the one that's not ghosted. But when giving commands from the CLI to a running copy or while using ARexx, 33mLeggi0m must know where to send the commands. That's why there is a window, called the "principal" window, that's distinguished by the "ยง" sign (instead of "#") in the title bar. It receives all of the commands. You can change it with the "Select" commands, or opening a new window, since the new window becomes always the principal one. New, Save, Close, Quit: exactly like in the menus. Select n : selects the n-th window as the principal one. WindowToFront n: pops up and activates the n-th window. TOP, BOTTOM: set the position in the principal window to the beginning or to the end of the file. BACKWARD, FORWARD: move a page up/down. PREV, NEXT: move up/down following the optional KEY command. UP, DOWN: move a page up/down. Jump n: jumps to the n-th line. LEFT, RIGHT: moves four characters left or right. WLEFT, WRIGHT: moves about a window left or right CENTER: repositions the horizontal margin to 0. Search : searches for the given pattern. If you haven't the req.library, this is the right way to do a search. AGAIN, BAGAIN: repeats the last search forwards or backwards. REFRESH, FREEFONTS: exactly like the menu items. Invoking 33mLeggi0m from the WB 33mLeggi0m can be also invoked from the Workbench. However, the number of options available is restricted to the defaults or those specified in the config file. You can simply double-click on its icon or double click on an icon that has "DefaultTool=33mLeggi0m" and you can use multiple selections. Tool Types are not supported. Please note that if you double-click a file to read while 33mLeggi0m is already active, the file will be loaded into the principal window. Using 33mLeggi0m ARexx Interface 33mLeggi0m possesses a powerful ARexx interface (the port is named '33mLeggi0m'), with which you can completely control the program. The commands available through ARexx are exactly the ones available through the command line. The only real difference is that to open a file you must use "open ". Please note that the "options result" command has no effect, since 33mLeggi0m returns only the error code (the error code will be non-NULL if a movement is impossible, too). I would like to see any AREXX macros written for 33mLeggi0m, so please send them to me on Bix or post them to publicly available BBSs, and they will likely get to me. Let your imagination go! The commands from AREXX are recognized by 33mLeggi0m through the minimun meaningful set of characters. For instance, you need only to type "wri" in order to use the "wright" command. Using 33mLeggi0m's Configuration File There are many options available in 33mLeggi0m, and it would likely be a chore to change everything every time 33mLeggi0m was called because you don't like the default. That's why a configuration file can be setup. The file is named "Startup-33mLeggi0m" and must be in the "S:" directory. It can contain any of the command line options (i.e., the options under "Usage:") excepted, of course, filenames. This will allow you, for instance, to set up a version of 33mLeggi0m that starts with Smart Refresh, Smooth Scrolling windows. Commands can be spread over several lines or gathered together on a single line separated by spaces. Advanced features Here we are, folks! You will learn to prepare your IFF files to submit to 33mLeggi0m in order to get the best results and to produce impressive doc files. 33mLeggi0m is able to parse completely only a small subset of the whole IFF FTXT standard (e.g., it doesn't show pictures) but the subset has been carefully chosen to produce the best results in the littlest space. The basic idea (we go into technical details, but don't get scared) is that the text contained in the CHRS chunks should possess some indication of the font/color/style changing (as from the IFF specs). The IFF standard suggests the ANSI/ISO codes, and this is exactly what was implemented in 33mLeggi0m, so let's take a look at it. Color/Style Specifications [0mnormal char set (all reverts to plain) [3mitalics on [23mitalics off [4munderline on [24munderline off [1mboldface on [22mboldface off [3xmset foreground color to x (from 0 to 9) [4xmset background color to x (from 0 to 9) You can freely mix together indications. For instance, [4;1;31;40m sets underline and boldface on, and sets the color to 1 (fore) and 0 (back). The [ pair can be substituted by the single CSI character (0x9b) but this is usually more difficult to handle in a text editor. Font Specifications (x where x can be any of B,R,K,A,E,H,Y,Z and selects one of the eight fonts 33mLeggi0m can handle. Why these letters? Ask the ANSI committee, I haven't a clue. Putting Together an IFF File OK, now you have your ANSI/ISO coded text, and you want to add fonts to make it beautiful. Here comes IFF.rexx, the little ARexx macro that comes with 33mLeggi0m. All you have to do is to change the first lines of the program, i.e., the fontname.x.y specifications. IFF.rexx creates an IFF file simply putting all of your text in a CHRS chunk, and storing before it a number of FONS chunks, specifying the fonts you want in the text. You can set upto eight fonts, but each of the eight can have more specifications (just in case the user doesn't have the font you asked). The x chooses the font number, e.g., the font number one will be recalled with the (B ANSI sequence. The y, instead, lets you associate to a font number many fonts, on a the-last-is-the-better base. For instance: fontname.1.1='Times/18' fontname.1.2='Helvetica/18' If you code your IFF file with that specification, 33mLeggi0m while reading it will first try to open Times, then it will try to open Helvetica, and, if the latter is found, the former will be closed. Otherwise, Times will be kept. Got it? Once you have modified IFF.rexx to get the fonts you want, type IFF and IFF.rexx will do the conversion. Decomposing an IFF File If, however, you have an IFF file and want to change the fonts in it, you can use the DeIFF program that comes with 33mLeggi0m: it takes as arguments two filenames: the first one will be parsed as an IFF file, and the content of any CHRS chunk will be written to the second one. In other words, DeIFF strips out all of the IFF FTXT stuff from a file and leaves you a clean ASCII/ANSI file that you can pass to IFF.rexx. Acknowledgments I must thank all of the guys who helped me during 33mLeggi0m's development. First of all, thanks to my beta-testers, Vittorio Calzolari, Dan Ten Ton, Bill Hogsett, Luca Spada, Reinhard Spisser and Jon Wolf. Thanks also to the BIX people who often answered to my questions (the silly ones, too) and gave many suggestion in the discussion preceeding 33mLeggi0m's development. Distribution Well, since this should be a text reader for a variety of uses, the distribution conditions will be very wide. 33mLeggi0m is a copyrighted, freely distributable program, in the widest sense, i.e., the only restriction is to selling it by itself. 33mLeggi0m can be included in disk magazines, PD collections, commercial programs, but, including if possible at least these docs. It would be really appreciated if you included also IFF.rexx and DeIFF. They're so small! Sebastiano Vigna BIX: svigna Via Valparaiso, 18 20144 Milano ITALIA