Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/426.lha/Leggi/Leggi.doc

IFF Formatted Text | 1990-10-02 | 20KB | 484 lines

                                   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 <fontspec>:  this command must be followed by font specification in
the form <font name>/<point height>.  For instance, "FONT Helvetica/15"
will set the font to Helvetica, height 15 points, as the default font.

Key <pattern>:  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 <pattern>:  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 <filename>".
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

<ESC>[0mnormal char set (all reverts to plain)
<ESC>[3mitalics on
<ESC>[23mitalics off
<ESC>[4munderline on
<ESC>[24munderline off
<ESC>[1mboldface on
<ESC>[22mboldface off
<ESC>[3xmset foreground color to x (from 0 to 9)
<ESC>[4xmset background color to x (from 0 to 9)

You can freely mix together indications.  For instance,

<ESC>[4;1;31;40m

sets underline and boldface on, and sets the color to 1 (fore) and 0
(back).  The <ESC>[ pair can be substituted by the single CSI character
(0x9b) but this is usually more difficult to handle in a text editor.


Font Specifications

<ESC>(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 <ESC>(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 <ASCII file name> <IFF file name>

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