\input amiga \input texinfotimes @c -*-texinfo-*- @setfilename Leggi.guide @settitle @code{Leggi}'s Manual @setchapternewpage off @finalout @titlepage @title Leggi @subtitle An ISO/ANSI text reader @subtitle Version 2.0 @subtitle Copyright @copyright{} 1990,1991,1992 Sebastiano Vigna @author by Sebastiano Vigna @end titlepage @defindex ar @ifinfo @node Top @top This file describes `Leggi' 2.0, a freeware text reader utility featuring unlimited number of windows on any public screen, scrolling with both mouse and keys, full AUISG menus and ARexx commands, clipboard support, AppWindows, fast & residentable activator, full configurability of the keyboard, settings file which stores even the window position and size, preferences editor which lets you directly edit settings files, background mode, standard clock pointer for long operations, fully documented @sc{iff} settings file, support for the ISO/ANSI color/style sequences and for the backspace character, selectable window refresh type, PowerPacked file support and more. @noindent Copyright © 1990,1991,1992 Sebastiano Vigna @menu * Introduction:: * Usage:: * Menus:: * The ARexx Interface:: * Keyboard Macros:: * ISO/ANSI Compliance:: * The Settings Editor and File Specification:: * Acknowledgments:: * Author Info:: * ARexx Command Index:: * Concept Index:: @end menu @end ifinfo @node Introduction @chapter Introduction @code{Leggi} is a rather flexible text reader which I developed some time ago with two main goals in my mind: first of all, supporting a simple subset of the @sc{iff} @sc{ftxt} specification, enough to describe multi-font text files, and secondly being also a good Amiga application---ARexx support, font adaptivity and so on. The former goal turned out to be a dead end: indeed, no one was interested in the @sc{ftxt} support; the latter one was achieved @emph{theoretically}, but a lot of bugs and some misfeature made @code{Leggi} 1.x much less widespread than I would have liked. My fault anyway. On the other hand, @code{Leggi}'s specification was a little bit ahead of its times---there was a real lack of system support for many things (for instance, a simple but transparent system tracking of the allocation sizes, or a system command line parser). With Release 2, Commodore eventually produced a beautiful programming environment in which the routine part of the programmer's work is left to the operating system. This urged a revision of @code{Leggi}. What really happened is that @code{Leggi} was completely recreated. I'm not only meaning rewritten---even the specification and the user interface was radically changed. Since most of @code{Leggi}'s functions were considered in the @cite{Amiga User Interface Style Guide} (@sc{auisg}), Commodore staff's suggestions were taken as the primary source when designing new functions and while updating the old ones. At the same time, dropping the support for 1.2/1.3 brought the power of Release 2 (version 2.04) to the program (just to mention an example, @code{Leggi} had previously to emulate the whole @code{LayoutMenus()} function in gadtools.library). Finally, dropping the @sc{ftxt} support (and consequently the handling of multi-font documents) reduced greatly the size of the code. The result is a fully @sc{auisg}-compliant application, with lots of new Release 2 related features and no more bugs. I can resume in a couple of word what you will miss with @code{Leggi} 2.0: 1.2/1.3 and @sc{ftxt} support. What you will get, instead, is: @itemize @bullet{} @item Faster text rendering/scrolling operations; @item Better keyboard/mouse handling (scrolling with cursor keys is no longer slower than scrolling with the mouse); @item Full @sc{auisg} menus and ARexx commands; @item Dozens of new ARexx commands that allow fine control of the window position and placement, displayed part of the document, etc.; @item Clipboard support---display the content of any clip in a @code{Leggi} window, or copy a displayed file to it; @item AppWindow support---drop a file icon in a @code{Leggi} window and the file will be loaded; @item Public screen support---open each window on a different public screen; @item Fast & residentable activator (ŕ la @code{CED} and @code{TurboText}); @item Full configurability of the ARexx port (both global and local); @item Full configurability of the keyboard---any ARexx command can be assigned to any keystroke; @item Settings file which stores even the window position and size; @item Preferences editor which lets you directly edit settings files; @item Background mode---@code{Leggi} remains active even when the last window is closed, and will restart via the activator or via an ARexx command; @item Standard clock pointer for long operations---if you use an animation utility such as @code{ClockTick} you will get a spinning hand, too; @item Beautiful 3-D scrolling gadget; @item Faster load operations; @item Fully documented @sc{iff} settings file; @item Support for the backspace character; @item Release 3 new look menus support. @end itemize Before you ask: ``leggi'' in Italian means ``read'', and I am told it is pronounced ``leeji'' in English. @node Usage @chapter Usage This chapter describes how to use @code{Leggi}. After a brief, idiotproof introduction a thorough explanation of the various interfaces follows. @menu * First Steps:: * The Workbench Interface:: * The CLI Interface:: * The Activator:: * Keyboard & Mouse:: @end menu @node First Steps @section First Steps The usage of @code{Leggi} is extremely straightforward. Double click on its icon, and then open a file using the @samp{Open...} item of the @samp{Project} menu. You can even drop a file icon over @code{Leggi}'s window, and the file will be automatically loaded (that is, the window is an Application Window). If you prefer to use a Shell, you can type @example Leggi @var{filename} @end example @noindent instead. Once loaded a file, you can move around using the scroll bar, the cursor keys or by clicking in the upper or lower region of the window. The @samp{Settings} menu allows you to customize the text display; in particular, you can try to change the display font using the @samp{Set Font...} item, and to add some interline space using the @samp{Set Line Spacing...} item. @node The Workbench Interface @section The Workbench Interface @cindex Tooltypes @cindex Workbench @cindex Public screen @cindex ARexx port name @cindex Background mode @code{Leggi} is clearly a @sc{gui} based application. It has full support for tooltypes, which can be specified both in the tool icon and in the project icons. This allows to control both global and local settings from the Workbench (@pxref{Settings}). The available tooltypes closely match the keywords available on the command line. They are described shortly here, and more detailed information can be found in @ref{The CLI Interface, The @sc{cli} interface}. @table @code @item PubScreen=@var{public screen name} lets you specify a public screen name. @item Settings=@var{settings file name} lets you override the default settings file name (@file{PROGDIR:Leggi.prefs}). @item Background=On|Off when set to @samp{On} tells @code{Leggi} to not exit definitively when the last window is closed or when asked to quit. Rather, it will wait for a command at its main ARexx port (usually this command will be sent by the activator). This allows you to keep @code{Leggi} always active (possibly by starting it in the startup-sequence or via the @file{WBStartup} drawer) and to activate one of its windows on your preferred public screen when needed. Since leggi uses less than 30K of memory, this can be a very pratical option for users with memory expansions. @item NoGUI=On|Off when set to @samp{On} tells @code{Leggi} to not open the first window, and rather waiting in the background until a command arrives from the activator or from ARexx. It implies a @samp{Background=On}. @item PortName=@var{ARexx port name} overrides the default port name, which is @samp{LEGGI} for the main port, and @samp{LEGGI.@var{n}}, where @var{n} is the window number, for the window ports. You can override the global name (and thus all the subsequently derived window names) by putting this tooltype in the tool icon, or override the local window port name by putting it in the project icon. @end table The @samp{PubScreen}, @samp{PortName} and @samp{Settings} tooltypes are available for inclusion in project icons or in the activator tool icon (@pxref{The Activator}), while the other tooltypes are only available in the @code{Leggi} main program tool icon. Of course, when included in the activator or project icons, they refer to local settings, and when included in the main program tool icon, they refer to global settings (@pxref{Settings}). @node The CLI Interface @section The @sc{cli} Interface @cindex CLI @cindex Template @cindex Wildcards @cindex Public screen @cindex ARexx port name @cindex Background mode While being a @sc{gui} oriented application, @code{Leggi} has a full-featured @sc{cli} interface. By typing @example Leggi ? @end example @noindent you can get the template in standard AmigaDOS format, which is: @example Files/M,PubScreen/K,PortName/K,Background/S,NoGUI/S,Settings/K @end example The template of the activator (@pxref{The Activator}), instead, is @example Files/M,PubScreen/K,PortName/K,Settings/K,Wait/S @end example @table @samp @item Files is filled by an arbitrary number of file name specifications, possibly containing AmigaDOS wildcards. Each file will be loaded in a different window. @item PortName lets you specify an ARexx port name which will override the internal name generation of @code{Leggi}. When included in the main program command line, it sets the global port name, while if included in the activator command line, it sets the local port name. Note that if you open several file via the activator using multiple filename/wildcards and you specify a @samp{PortName} keyword, all opened windows will get the same port name, probably causing confusion when trying to control one of them via ARexx. @item PubScreen lets you specify a public screen name which @code{Leggi} will open its window on (by default, they are opened on the default public screen). The name is set globally or locally, depending on the calling program, just as for the @samp{PortName} argument. An unexisting public screen name will keep @code{Leggi} from opening any window. Note that the name is case sensitive. @item Settings lets you specify a settings file name to open instead of reading the default file at startup or cloning in the standard way global or local settings. @xref{Settings}. @item Background tells @code{Leggi} to stay forever in the background even when the last window is closed or when asked to quit, waiting for a command from the activator or from ARexx. @item NoGUI tells @code{Leggi} to not open the first window, and rather waiting in the background for a command. It implies a @samp{Background} switch, even if not explicitly present. @item Wait tells the activator to not return until the window has been closed (much like the @samp{Wait} switch of @code{TurboText}). @end table @node The Activator @section The activator @cindex LG In the same vein of other Amiga programs, @code{Leggi} has an activator, named @code{LG}. @code{LG} is a very short, residentable program which sends to the main program messages telling it to open certain windows, load certain files et cetera. @code{Leggi} is not residentable, but it doesn't need to be, since just one copy needs to be loaded (you can open different windows, with specific port names on different public screens using a single copy of @code{Leggi}). Unless you have special needs (for instance, you could want to run @code{Leggi} in the background with the @samp{NoGUI} option and some special settings file from your startup-sequence), you should always invoke @code{Leggi} through @code{LG}. @code{LG} checks if a copy of @code{Leggi} is present (it does it by checking for a port name @samp{LEGGI}; if you started a copy of @code{Leggi} with another main port name, you can't use @code{LG} with it), and if so it sends it a series of messages by which @code{Leggi} learns what it has to do (opening windows, loading files, using certain settings files, etc.). If no copy of @code{Leggi} is active, it launches a @code{Run Leggi >NIL: [0m normal char set (all reverts to plain) [3m italics on [23m italics off [4m underline on [24m underline off [1m boldface on [22m boldface off [3xm set foreground color to x (from 0 to 9) [4xm set background color to x (from 0 to 9) @end example You can freely mix together indications. For instance, @example [4;1;31;40m @end example @noindent sets underline and boldface on, and sets the color to 1 (fore) and 0 (back). As a final note, @code{Leggi} supports @sc{tab}s (you can set their size via the corresponding menu item) and backspaces, which move one space backwards the cursor; note that backspaces won't be displayed properly with a proportional font, for obvious reasons. @node The Settings Editor and File Specification @chapter The Settings Editor and File Specification This chapter focuses on the preferences program that lets you edit a settings file, and on the @sc{iff} specification of such a file. @menu * The Settings Editor:: * The Settings File Specification:: @end menu @node The Settings Editor @section The Settings Editor @cindex LeggiPrefs @cindex Macros The @code{LeggiPrefs} program allows you to directly edit each setting in @code{Leggi}'s configuration. In particular, it is the place where you can define the keyboard macros. The usage of the editor is straightforward: simply put in each gadget the value you want, or click on the checkbox gadget to toggle or on off an option. Remember that writing @samp{-1} in the @samp{Width} or @samp{Height} field will make the window fit the whole screen (starting from the @samp{LeftEdge}/@samp{TopEdge} position, of course). Moreover, a @samp{Wordwrap} of @samp{0} means no word wrapping. Note also that when the editor is started, no font is displayed above the @samp{Set Font...} gadget. If you don't select any font, @code{Leggi} will open the system default font when using that settings file (the font selection can be cancelled by hitting the @samp{Set Font...} gadget and then cancelling the @sc{asl} font requester). The editor doesn't currently check for values out of range, so please be careful. The keyboard assignment system is very simple to use: if you activate the string gadget just under the list and type in a keystroke expression (try, for instance, @samp{ALT 80}), the keystroke will be added to the list, and the @samp{Command} gadget will be activated, ready for you to insert a command corresponding to the keystroke. This gadget is also automatically activated whenever you click an item of the @samp{Keyboard Assignments} list. If you select an item from the list and click on the @samp{Delete} gadget, the assignment will be deleted. The keystroke expressions accepted by @code{LeggiPrefs} have the following template: @example Shift/S,Alt/S,Control/S,LAmiga/S,RAmiga/S,Code/N/A @end example The @samp{Code} part is the raw key code assigned to a particular key on the keyboard. For a list of those, you can peek at the @file{KeyCodes} file which is supplied with @code{Leggi}, or at the @cite{Amiga Rom Kernel Manuals}. For instance, the ten function keys have codes from 80 to 89. You can add to the code as many qualifier as you like. @samp{LAmiga} and @samp{RAmiga} refer to the left and right Amiga keys, of course. @code{LeggiPrefs} has a single menu with the basic Open/Save operations, which are rather obvious: @table @samp @item Open opens a settings file (brings up the file requester); @item Save saves the current configuration with the current filename; @item Save As... saves the current configuration with a name (brings up the file requester); @item About... displays some info about @code{LeggiPrefs}; @item Quit exits @code{LeggiPrefs}. @end table @node The Settings File Specification @section The Settings File Specification @cindex Settings file specification The settings file of @code{Leggi} is an @sc{iff} file, namely a @sc{legg} @sc{form} which can contain only two chunk types: @table @sc @item kass a keyboard assignment; you can have many of those; @item sett a settings chunk; there must be just one, and it has to be the last chunk in the @sc{form} (just like the @sc{body} in an @sc{ilbm} @sc{form}). @end table The content of a @sc{kass} is given by: @example typedef struct @{ USHORT Code, Qualifier; char Command[]; @} KASS; @end example @noindent i.e., it's a variable-length structure containing two @code{USHORT}s (@code{RAWKEY} code and qualifier of the macro) and a 0-terminated string which specifies the ARexx command to execute. The @code{Qualifier} field has to contain both or none of the @key{SHIFT} (or @key{ALT}) left/right qualifier flags (i.e., you can't set a macro for the left @key{SHIFT} only). The content of the @sc{sett} chunk is a @code{Settings} structure: @example #define PAGEKEYLENGTH 40 #define FONTNAMELENGTH 64 typedef struct @{ USHORT Flags; USHORT WordWrap; USHORT TabSize; USHORT LineSpacing; WORD LeftEdge, TopEdge, Width, Height; struct MinList KAList; struct TextAttr TextAttr; UBYTE PageKey[PAGEKEYLENGTH]; UBYTE FontName[FONTNAMELENGTH]; @} Settings; @end example The @code{Flags} field can have the following (obvious) flags set: @example #define LEGGIF_SMOOTHSCROLLING (1<<0) #define LEGGIF_SMARTREFRESH (1<<1) #define LEGGIF_LINENUMBERS (1<<2) #define LEGGIF_BACKGROUND (1<<3) #define LEGGIF_MOUSELEFT (1<<4) #define LEGGIF_MOUSERIGHT (1<<5) #define LEGGIF_FASTSCROLLING (1<<6) @end example The @code{WordWrap}, @code{TabSize}@dots{}, @code{Height} and @code{PageKey} fields contain the values for the corresponding options. The @code{KAList} field is irrelevant, and can be set to anything. The @code{TextAttr} field contains information about the desired font, but the @code{ta_Name} field is irrelevant---the font name is stored in the @code{FontName} array. Note that a @code{-1} in the @code{Width} or @code{Height} fields will set them to the screen width or height (minus the @code{LeftEdge} or @code{TopEdge} values, if they're nonzero). @node Acknowledgments @chapter Acknowledgments @cindex Shubentsov Ilya @cindex Tibbett Steve @cindex Walraven Ewout @cindex Noble Gayle Many people contributed to this program: the writers of the @cite{Amiga User Interface Style Guide}, my beta testers, Ilya Shubentsov for designing the icon, Steve Tibbett for giving his @file{StringReq.c} code, Ewout Walraven for useful suggestions, and many others. Thanks to them all, and to the people who sent me bug reports. But a most special thank goes to Gayle Noble, for her outstanding contribution, which exceeds everything I received in my life for my work. @code{Leggi} is Copyright @copyright{} 1990-1994 Sebastiano Vigna and it's freely distributable as long as all of its files are included in their original form without additions, deletions, or modifications of any kind, and only a nominal fee is charged for its distribution. This software is provided @strong{AS IS} without warranty of any kind, either expressed or implied. By using @code{Leggi}, you agree to accept the entire risk as to the quality and performance of the program. Comments, complaints, desiderata are welcome. @node Author Info @chapter Author Info @example Sebastiano Vigna Via California 22 I-20144 Milano MI BIX: svigna@@bix.com INTERNET: vigna@@ghost.dsi.unimi.it UUCP: seba@@sebamiga.adsp.sub.org @end example @page @node ARexx Command Index @unnumbered ARexx Command Index @printindex ar @page @node Concept Index @unnumbered Concept Index @printindex cp @contents @bye