Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/244.lha/Textra.README

Text File | 1989-05-07 | 18.8 KB | 446 lines

   This document describes TEXTRA, a very user-friendly text editor.
TEXTRA makes no claim at being the most powerful editor around, or the
fastest, smallest or any-OTHER-est.  Just pretty easy to use, that's
the goal.  And free.

   TEXTRA is public domain.  I request, however, that this README file
accompany the executable, if possible, if passed around.

   If you are using TEXTRA to read this file, just point the mouse
at the arrow in the lower-right corner, and hold the left mouse button
down for a little.  You'll know when to let up.

   TEXTRA was written in JForth Professional V2.0, which I recommend
highly.

                                            Thanx,  Mike H.

26-apr-89 executable size 60148

---------------------------------------------------------------------------


              T A B L E     O F     C O N T E N T S
             ---------------------------------------

1.  INVOKING TEXTRA
    1.1  Invoking from Workbench or CLI
    1.2  Optional filename argument usage
    1.3  Shift-Double-clicking with "project"-type icons
    1.4  TEXTRA as the Default Tool for "Project"-type icons
2.  THE TEXTRA CURSOR
    2.1  Cursor appearance
    2.2  Positioning the cursor with the keyboard arrow keys
    2.3  Positioning the cursor with the mouse
3.  ENTERING TEXT INTO THE DOCUMENT
    3.1  Inserting text at the cursor location
    3.2  The RETURN key
    3.3  The BACKSPACE key
    3.4  The DEL key
    3.5  The TAB key
    3.6  The control-key filter and defeat feature (Function key F2)
4.  SELECTING A RANGE OF TEXT
    4.1  Using the mouse to select a range of characters
    4.2  Selecting text by double-clicking
    4.3  Operations on selected ranges
    4.4  Selecting more than the visible screen
5.  VIEWING PAGES
    5.1  The vertical scroll arrow gadgets
    5.2  The vertical scroll thumb gadget
    5.3  Scrolling the page with the keyboard arrow keys
6.  TEXTRA WINDOWS
    6.1  Limitations
    6.2  The title bar
    6.3  The close gadget
    6.3  The sizing gadget
    6.4  The Window-Size-Toggle feature (Function key F1)
7.  TEXTRA MENUS
    7.1  Accessing the menus
    7.2  The "Project" menu
         7.2.1  Open A File...
         7.2.2  Open By Name...
         7.2.3  New File
         7.2.4  Revert To Saved
         7.2.5  Save
         7.2.6  Save As...
         7.2.7  Save All Files
         7.2.8  Close File
         7.2.9  About TEXTRA...
         7.2.10 Quit
    7.3  The "Edit" menu
         7.3.1  Cut
         7.3.2  Copy
         7.3.3  Paste
         7.3.4  Find...
         7.3.5  Find Next
         7.3.6  Replace...
         7.3.7  Replace Next
         7.3.8  Go to Line...
         7.3.9  Set TAB Width...
    7.4  The "Windows" menu
         7.4.1  Dynamically-changing items
         7.4.2  Additional information
8.  TEXTRA GENERAL INFORMATION
    8.1  TEXTRA's use of Path and File names
    8.2  String Gadget Shortcuts
    8.3  TEXTRA String Gadgets and the RETURN key
    8.4  TEXTRA Requesters

---------------------------------------------------------------------------


1. INVOKING TEXTRA

1.1 TEXTRA, if double-clicked from WorkBench, will ask you to
select a filename soon after opening its first window.  TEXTRA
may be launched from CLI or SHELL with multiple filenames
as follows:

    1> TEXTRA <filename1> <filename2> ... <filenameX>

            OR

    1> RUN TEXTRA <filename1> <filename2> ... <filenameX>

1.2 If the optional filenames are not given, TEXTRA will ask you to
select one, as if double-clicked.  Select "CANCEL" if you do not
want to edit an existing file; the default name "Untitled" will
be assigned.

1.3 From Workbench, "Project" icons that are also selected when TEXTRA
is "SHIFT-Double-Clicked" will each be opened in their respective window.

1.4 A "Project" icon that has TEXTRA specified in its "Default Tool"
field will invoke TEXTRA, when double-clicked, and be opened in its
own window.

---------------------------------------------------------------------------


2. THE TEXTRA CURSOR

2.1 The current cursor location (where text will be inserted) is
represented by a thin line, of a different color than either text
or background.  If placed inside a text string, the cursor is
always BETWEEN two characters, showing clearly the sections that will
"spread apart" if something is typed into the window.

2.2 The cursor may be moved with the "arrow" keys on the keyboard; a
SHIFT-left-arrow or SHIFT-right-arrow will move the cursor to the
beginning or end of the current line, respectively.

2.3 The cursor may also be positioned by clicking the LEFT MOUSE
BUTTON, while the mouse cursor is over a part of the windows text area.

---------------------------------------------------------------------------


3. ENTERING TEXT INTO THE DOCUMENT

3.1 As keys are typed at the keyboard, they are entered in the file
at the current cursor location, and the cursor is advanced by one.

3.2 The RETURN key inserts a new line, and moves the cursor to the
beginning of it.

3.3 The BACKSPACE deletes the character to the immediate left of the
cursor.  If the cursor is at the leftmost column, the preceeding newline
is removed and the cursor moves up one line.

3.4 The DELETE key removes the character to the immediate right of the
cursor.  If the cursor is at the end of a line, the newline is removed
and the next line moves up to merge with the current.

3.5 The TAB key advances the cursor to the next column that is an
even multiple of the TAB width value (discussed later).

3.6 Normally, TEXTRA will not allow control characters into the
window, permitting only visible or white-space characters.  This
feature can be temporarily defeated, for 1 character, by pressing F2.
Following F2, the next character will be accepted into the window
unfiltered.

---------------------------------------------------------------------------


4. SELECTING A RANGE OF TEXT

4.1 It is possible to mark a series of characters for the next
operation by "dragging" with the mouse.  The sequence is:

  a. Position the mouse over the 1st character of the desired series.
  b. Press the left mouse button and, while holding it down, move the
     mouse to the last character of the series (even if it is on another
     line).  Note that the characters between that clicked-on and wherever
     you move the mouse become "highlighted" (selected).
  c. Release the left mouse button when the desired range of characters
     is selected.

4.2 Any series of non-white characters will become selected if the
LEFT MOUSE BUTTON is double-clicked while the mouse cursor is
positioned over them.

4.3 When a range of text is selected, a subsequent operation will
affect the entire selected area.  For example, if a key is typed while
a range is selected, the range will be cut from the file, replaced by
that key.  Other examples are the BACKSPACE and DEL keys, which both
act to simply delete any selected area.  Certain items under the EDIT
menu, described later, also operate on any current range.

4.4 If, while selecting text, the mouse is moved near the bottom or top
of the window, available text in the appropriate direction will scroll
into view, becoming selected in the process.  Therefore, a select range
can extend past the visible limits of the window.

---------------------------------------------------------------------------


5. VIEWING PAGES

5.1 The easiest method for moving through the file is to use the vertical
scroll bar on the right side of the window.  Single clicks of the left
mouse button on the arrows at either end move the document vertically,
one line at a time.  Holding the left button down on either yields a
continuous scroll.

5.2 The "thumb" in the middle of the scroll bar not only indicates the
visible-page-area relative to the total-file-size (by it's height),
but also the position within the file (by its vertical positioning).
It can also be "selected" with the left mouse button and moved as
a "coarse adjust".  The area immediately above and below the "thumb"
may be clicked with the left button as a "page-scroll" mechanism.

5.3 Another method by which text may be scrolled into view is to move
the cursor, via the keyboard "arrow" keys, to either the top or bottom
of the visible window.  Attempts to move the cursor "off the window"
will cause text in that direction to scroll.

---------------------------------------------------------------------------


6. TEXTRA WINDOWS

6.1 TEXTRA allows any number of windows, limited by the amount of
memory in your computer (probably the 512K available CHIP ram
in MOST Amigas!).  Textra lines can be up to 255 characters long,
number of lines limited by your total available memory (entire file
is kept in ram, FAST is grabbed first).

6.2 The title of each TEXTRA window is set to the full-pathname
of the file that was read in (or created).  This is also the name
of the file that will be written during a SAVE operation (unless
the "SAVE AS..." menu option is chosen, discussed later).  If the
file has been modified since last saved, the filename will be
preceeded by a '*'.

6.3 Each window includes a standard Intuition close gadget, which
performs the same action as the "CLOSE FILE" menu option.  See the
discussion on "CLOSE FILE" for more information.

6.4 The "sizing" gadget in the lower-right hand corner of each window
may be used to adjust the dimensions of that window, up to the
full-screen limitations of the Workbench.

6.5 Function key F1 may be used as a "window-size-toggle" between
default size (when F1 was first hit) and full-screen (as per current
Preferences screen resolution settings).  This is particularly
useful when Workbench is in 400 line interlace.

(NOTE: if F1 is used to expand the screen, and the size gadget is
       then clicked without actually changing size, the default-size
       becomes equal to the full-screen-size.  This will make F1
       non-functional until the size gadget is used to actually
       change window size.  To avoid this, don't click on the
       sizing gadget when the window is full-size.  Use F1 to
       get back to normal size).

(PROGRAMMERS NOTE: Sorry about all the commotion on the screen when
       you hit F1...after all the gyrations, it ends up where it oughta
       be.  I don't see how, under Intuition, to do this any cleaner...
       Must this be a two-step process (combinations of MoveWindow()
       and SizeWindow()), with all the extra drawing and overhead from
       the layers.library a necessary evil?  Gurus???)

---------------------------------------------------------------------------


7. TEXTRA MENUS

7.1 3 menus are available and present themselves when the RIGHT
MENU BUTTON is depressed and held.  Some menu items may also
be activated by simultaneously pressing the RIGHT AMIGA key
and the one that is specified in the menu item text.

7.2 The "Project" Menu

7.2.1 OPEN A FILE... opens a new window with a full file-selector
requester and buttons that allow quick access to the top of DF0:,
DF1:, VD0: and RAM:.  The PARENT button changes the current directory
to the level above the one being displayed.  The KEYBOARD button
presents the user with a string requester into which a file or
directory specification may be typed.  The CANCEL button exits the
requester with no other action while the OK button enters the file
or directory selected in the list box (the same as CANCEL if nothing
is selected).  Double-clicking one of the names performs the same
action as the OK button.

7.2.2 OPEN BY NAME... opens a new window, then presents a string
requester for specifying a filename (directory names are invalid
in this requester) from the keyboard.  This bypasses the directory
scan for the list of names, which can take time on large directories,
especially on floppy drives.  Note that the current directory of
the requester is that of the spawning window.

7.2.3 NEW FILE opens a window without specifying a filename; the
default name "Untitled" is assigned, at the directory level of
the spawning window.

7.2.4 REVERT TO SAVED causes the read-in version of a the selected
file to be discarded, replaced by the version that was last-saved
to disk.  A verification requester is presented to make sure this
is not done accidently.

7.2.5 SAVE causes the currently-selected file to be written to disk,
if modified.  If the file has not been changed since last-saved (no
'*' before the title), the write is not performed.

7.2.6 SAVE AS... allows saving the currently selected file under a
different name.  After this operation, the title bar will contain
the new name, and it will have been created on disk.  If the
specified file already exists, the user is warned and given a
chance to abort.  The "USE LIST" button will present a full
file-requester through which an existing file may be selected with
the mouse.  This requester is very similar in operation to the
"OPEN FILE..." requester; all buttons work the same, except the
OK button will overwrite the selected file (as does double-clicking
a filename).

7.2.7 SAVE ALL FILES causes all files that have been modified and not
saved to be written to disk.

7.2.8 CLOSE FILE will check if the file has been modified but not
saved and warn the user if so.  Note that closing TEXTRA's last window
will cause it to exit; a requester will notify you if you are closing
the last window and give you the chance to abort.

7.2.9 ABOUT TEXTRA is self-explanatory.

7.2.10 QUIT will exit TEXTRA, closing all files in the process.  All
files that have been modified but not saved will issue a notification
requester, providing the opportunity to save at that time.

7.3 The "Edit" Menu

7.3.1 CUT removes the selected range of characters from the
currently-selected file, but saves them in the TEXTRA clip area
(TEXTRA does not interface with the standard Amiga Clipboard
Device...future versions may do so).  The previous contents of
the TEXTRA clip area are lost.  If there is no select range,
no action is performed.

7.3.2 COPY moves the selected range of characters of the
currently-selected file to the TEXTRA clip area, but does not
remove them from the file.  The previous contents of the TEXTRA
clip area are lost.  If there is no select range, no action
is performed.

7.3.3 PASTE inserts whatever is in the TEXTRA clip area into the
currently-selected file, at the current cursor location.  If a select
range is active in this file, it is deleted before the insertion takes
place.  There is no effect on the contents of the TEXTRA clip area.

7.3.4 FIND... presents a string requester, prompting for the string
to search for, ignoring character case.  The string gadget will, as
a default, contain the previous string searched for IN THAT WINDOW
(empty if none).  However, if a range of characters is selected that
is ALL ON ONE LINE, it will supercede any previously-searched-for
string as the default for the string gadget.  The search begins just
past the current cursor location or selected range of characters.

7.3.5 FIND NEXT conducts another case-insensitive search for the same
text string that had previously been searched for.  If no search had
yet been conducted the "FIND..." requester is presented.

7.3.6 REPLACE... presents a double-string-requester, prompting for
both the string to conduct a case-insensitive search for, and a second
string, to replace the first with, when found.  The RETURN key will
toggle the selected string gadget.  The user may optionally replace
all instances of the found string (with the "ALL!" button), just the
next one found (via the "ONCE" button), or abort (via "CANCEL").  The
search begins just past the current cursor location or selected range
of characters.

7.3.7 REPLACE NEXT conducts another "REPLACE" operation, using the
same strings that were used last time.  If none exist, the "REPLACE"
requester is presented.

7.3.8 GO TO LINE... presents a string requester prompting for the
desired line number.  First line of file is line 1.

7.3.9 SET TAB WIDTH... provides a way of changing the default TAB
width (8).  A string requester is presented, with the currently
installed size.  Maximum width accepted is 16.  The setting applies
to all windows.

7.4 The "Windows" Menu

7.4.1 One item exists in the "WINDOWS" menu for each open file, the
menu item text being the same as the title bar for the associated
window.  Selecting an item makes it the current window, if not
already.

7.4.2 Additionally, the text includes the "*" character before the
filename if the file has been modified since last written to disk.
A checkmark preceeds the item representing the current file.

---------------------------------------------------------------------------


8. TEXTRA GENERAL INFORMATION

8.1 TEXTRA always fully expands a specified file or directory name
and uses that form to again find the file, if necessary.  For example,
you may have typed in "DF1:MyFile" as the filename, but the window
title will substitute the name of the volume, possibly "MyDisk:MyFile".
This is almost always desirable, because if TEXTRA saved "DF1:", you
might unknowingly save it to the wrong disk, just because you switched
the disk in that drive.  TEXTRA will ask you specifically for the same
name.
   The only situation you should be aware of is WHEN YOU HAVE TWO
DISKS OF THE SAME NAME in your system.  In this case, AmigaDOS can
sometimes choose the wrong disk when TEXTRA passes the full-pathname
to it.
  In the above example, we could save it to the wrong disk if the disk
in DF0: is also named "MyDisk:" (a backup, perhaps???).  This is not
caused by TEXTRA, but can happen anytime in AmigaDOS that you use the
full-pathname to specify a file.

8.2 Intuition provides two String Gadget shortcuts that can be
useful to the TEXTRA user.  TEXTRA string gadgets that provide
a default text string when they appear will revert back to this
string whenever "Right Amiga-Q" is pressed.  The "Right Amiga-X"
combination will clear any displayed string.

8.3 For all string gadgets but one, the RETURN key will perform
the same action  as the "OK" button.  The one exception is the
"REPLACE" double-string requester, where the RETURN key toggles between
the two string gadgets.

8.4 TEXTRA Requesters are attached to (drawn in) the window that they
have been spawned from.  The advantage is that multiple requesters
are possible...you can select and work in another file even if
the previous window is waiting for you to answer a question.  Every
window can, in fact, have an open requester.  Note that, if your
window is too small, you may have to expand its size to inter-operate
with a given requester.  Unfortunately, since the Intuition requester
mechanism locks out my console events from that window, I can't process
the F1 key, and you have to do this with the mouse.
  (Intuition should give the application a looksee at the keys before
using them in a string gadget, throwing them away or whatever.  The
application could reply with a boolean, whether it wants the requester
to use it or not.  This could even default to NO_BOOLEAN if not specified
previously by the caller as a requester mode.  Maybe a REQ_KEY_VERIFY
event. Oh well, let's re-design Intuition another time).

---------------------------------------------------------------------------