home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The CDPD Public Domain Collection for CDTV 4
/
CDPD_IV.bin
/
utilities
/
editors
/
textra
/
docs
/
textra.doc
< prev
next >
Wrap
Text File
|
1994-06-24
|
50KB
|
1,143 lines
This document describes TEXTRA, a very user-friendly text editor. So
user-friendly, I hope, that you could use it without reading a manual.
Good learning philosophy: play with it. One of the easiest, that's the
goal.
TEXTRA is SHAREWARE. For $25.00, I will send you a personalized
executable that does not contain the 60-second startup-delay screens that
are in the otherwise-identical UN-registered version.
The UN-registered version is freely-distributable. However, please
insure that the unaltered 'doc' files & rexx scripts accompany the
executable if you do pass it around.
If you are using TEXTRA to read this file, just Press F4 to view the
next page. F5 to review the previous page.
TEXTRA was written in JForth Professional, which I recommend highly. As
far as I know, TEXTRA is enforcer-clean under WB 2.04 and later.
26-Apr-89 v1.01 executable size 60148
29-May-89 v1.02 " " " 60864
22-Jul-89 v1.03 " " " 61080
21-Oct-89 v1.04 " " " 65208
05-Jan-90 v1.05 " " " 69836
18-Feb-90 v1.06 " " " 69400
18-Apr-90 v1.07 " " " 70520
06-Jun-90 v1.08 " " " 71544
15-Dec-90 v1.09 " " " 79404
26-Aug-91 v1.10 " " " 98976 ARexx, horiz scroll bar, help kbd
23-Oct-91 v1.11 " " " 100500 WB2.0 graphics, fix GET CURSOR CHAR
16-Mar-92 v1.12 " " " 108920 Undo, SmartLaunch, 1st shareware
" " " " " " 111280 -- v1.12 Freely-Distributable version
10-Jan-93 v1.13 " " " 127124 Fonts, Multi-Processing, lots more
07-Jan-93 v1.13 " " " 129252 -- v1.13 Freely-Distributable version
29-May-93 v1.14 " " " 135200 -- v1.14 Status Line, User-define kybd
" " v1.14 " " " 137260 -- v1.14 Freely-Distributable version
(see the 'WhatsNew.doc' file for better history/features information)
---------------------------------------------------------------------------
T A B L E O F C O N T E N T S
---------------------------------------
Suggestions...
o If using Textra 1.15 or later to read this, pull down the
"Utilities, Go To Mark..." menu item. (If disabled,
you are missing a file called "}Textra.doc").
o In any version of Textra...
1. Double-click on the section number ( for example, 10.4.8 )
2. "Find" it by using Right-Amiga-F (press RETURN in the requester)
3. If necessary, use Right-Amiga-N (Find Next) to locate the next
occurence of the same text (most likely a cross-reference).
1. INSTALLING TEXTRA
1.1 The Textra Package
1.1.1 The Program and Icon
1.1.2 The ARexx Scripts
1.1.3 The Documentation
1.2 The Provided Installation Program
1.2.1 Installation of the program and icon
1.2.2 Installation of the Textra-ARexx Scripts
1.2.3 Installation of the Documentation
1.2.4 Final Verification before Installation
1.3 Manual Installation
2. INVOKING TEXTRA
2.1 General
2.2 Invoking from Workbench
2.3 Invoking from CLI or SHELL
2.4 TEXTRA as the Default Tool for "Project"-type icons
2.5 Launching more than once.
2.6 Automatic gadget imagery selection
3. THE TEXTRA CURSOR
3.1 Cursor appearance
3.2 Positioning the cursor with the mouse
3.3 Positioning the cursor with the keyboard arrow keys
3.4 Quickly finding the cursor (function key F3)
4. ENTERING TEXT INTO THE DOCUMENT
4.1 Inserting text at the cursor location
4.2 The RETURN key
4.2.1 The "Auto-Indent" mode
4.3 The BACKSPACE key
4.3.1 The "Auto-BackSpace" mode
4.4 The DEL key
4.5 The TAB key
4.6 The control-key filter and defeat feature (Function key F2)
4.7 The HELP key
5. SELECTING A RANGE OF TEXT
5.1 Using the mouse to select a range of characters
5.2 Selecting text by double and triple clicking
5.3 Operations on selected ranges
5.4 Selecting more than the visible screen
5.5 Extending a select range by SHIFT-clicking
5.6 Identifying balanced parenthesis or brackets
6. VIEWING PAGES
6.1 The vertical scroll arrow gadgets
6.2 The vertical scroll thumb gadget
6.3 Scrolling the page with the keyboard arrow keys
6.4 Keys that PAGE-up or PAGE-down
6.5 The horizontal scroll gadget
7. TEXTRA WINDOWS
7.1 Limitations
7.2 The title bar
7.2.1 The optional Status Line
7.3 The close gadget
7.4 The sizing gadget
7.5 The Window-Size-Toggle feature (Function key F1)
7.6 The 'Previous Window' feature (Function key F6)
7.7 The Window's font
8. THE TEXTRA AREXX INTERFACE ("TREXXTRA" -- hoo boy!)
8.1 General AREXX Information
8.2 Executing TEXTRA/AREXX Scripts or Commands
8.3 Running scripts in the background
8.4 Writing Your Own TEXTRA/AREXX scripts
8.5 The TEXTRA "Tutorial" ARexx script
8.6 Aborting TEXTRA-ARexx Scripts
8.7 User-definable keyboard via the CTRL key
9. THE MARKS FACILITY
9.1 General Description
9.2 Accessing the MARKS facility
9.3 How MARKS info is stored
9.4 Special "MARK"-ed file considerations
9.4.1 Copying MARK-ed files
9.4.2 Maximum MARKed-file name length
10. TEXTRA MENUS
10.1 Accessing the menus
10.2 The "Project" menu
10.2.1 Open A File...
10.2.2 Open By Name...
10.2.3 New File
10.2.4 Insert File...
10.2.5 Revert To Saved
10.2.6 Save File
10.2.7 Save File As...
10.2.8 Save All Files
10.2.9 Close File
10.2.10 Print File
10.2.11 Print Selected Lines
10.2.12 Printing Preferences...
10.2.13 About TEXTRA...
10.2.14 Quit
10.3 The "Windows" menu
10.3.1 Dynamically-changing items
10.3.2 Additional information
10.4 The "Edit" menu
10.4.1 Undo
10.4.2 Cut
10.4.3 Copy
10.4.4 Paste
10.4.5 Find
10.4.5.1 String...
10.4.5.1.1 Wrap-around search option
10.4.5.2 Next Occurence
10.4.6 Replace
10.4.6.1 String...
10.4.6.2 Next Occurence
10.4.6.3 Then Find
10.4.7 Case
10.4.7.1 lower
10.4.7.2 UPPER
10.4.7.3 Capitalize
10.4.8 Go to Line...
10.4.9 Editing Preferences...
10.5 The "Utilities" menu
10.5.1 File Protections...
10.5.2 Write-Protect/Enable Window
10.5.3 Help on Keyboard...
10.5.4 ARexx...
10.5.5 Set Window Font...
10.5.6 Font Preferences...
10.5.7 Mark Selected Text......
10.5.8 Go To Mark...
10.5.9 Delete Mark...
11. TEXTRA GENERAL INFORMATION
11.1 TEXTRA's use of Path and File names
11.2 TEXTRA String Gadget Shortcuts
11.3 TEXTRA String Gadgets and the RETURN key
11.4 TEXTRA Requesters
11.4.1 Use of the Asl library
11.4.2 The Asl file requesters vs. Native TEXTRA file requesters
11.5 TEXTRA Preferences File
11.6 TEXTRA behavior when reading in files
11.6.1 MSDOS text format compatibility
11.6.2 Checks file type when reading in a file.
11.7 Operation under low-memory conditions
11.8 TEXTRA Keyboard Summary
---------------------------------------------------------------------------
1. INSTALLING TEXTRA
1.1 TEXTRA may be run without any installation at all. The
installation procedure simply copies the program and a set of support
files (none required) to your hard disk.
1.1.1 The program and icon file are supplied at the root of the
installation package. They may be used to view any and all
documentation. All supplied text files default tool fields point to
this TEXTRA.
1.1.2 The TEXTRA package includes a variety of macro files, executable
under its powerful ARexx interface. General page/paragraph-formatting
macros, useful utilities, and scripts that allow TEXTRA to act as an
integrated editing environment for JForth Professional, HSPascal and
SAS/C are provided.
1.1.3 The accompanying documentation, of which this is a part of, is
detailed and complete. It includes separate files covering Textra as
editing environment, its ARexx interface and command set, detailed
version history, and list of known gotchas.
1.2 The package provides an installation program with icon that will
prompt the user through the installation process. When the installer
prompts for a destination location for anything, it will create the
specified directory, if it doesn't already exist.
1.2.1 The user is asked for the location for the program and icon.
1.2.2 If ARexx is running on the system, it will automatically copy
the ARexx scripts in the REXX: directory, if assigned. (If REXX: is
not assigned, the user is prompted to specify their location.)
If Arexx does not seem to be running at all on the system, then the
user is give the option of installing the scripts.
1.2.3 The user is asked if he/she wishes the Documentation files to be
copied, and prompted for a location if so.
1.2.4 Finally, all choices are listed, ending with a prompt to either
continue, retry or exit the installer.
1.3 If desired, the package can be installed from CLI with the
following commands (assuming the Textra package is on a floppy in df0:)...
copy df0:Textra#? "<wherever-you-want-program+icon>"
If you want the docs...
copy df0:docs/#? "<wherever-you-want-the-docs>"
If you want the ARexx macro files...
copy df0:scripts/#?.textra rexx:
If you want the JForth-oriented ARexx macros...
copy df0:scripts/JForth_Scripts/#?.textra rexx:
If you want the HSPascal-oriented ARexx macros...
copy df0:scripts/HSPascal_Scripts/#?.textra rexx:
If you want the C-oriented ARexx macros...
copy df0:scripts/C_Scripts/#?.textra rexx:
If you want the SAS/C-oriented ARexx macros...
copy df0:scripts/SASC_Scripts/#?.textra rexx:
(See also docs/SASC.Readme)
---------------------------------------------------------------------------
2. INVOKING TEXTRA
2.1 TEXTRA may be launched from Workbench, Shell or ARexx.
2.2 When launched from Workbench (probably the most common means of
starting it), Extended-Selection mode is implemented to provide
opening a specific set of document icons. For information about this
mode, refer to your Workbench manual.
2.3 "TEXTRA" may be typed into the CLI or SHELL, with as many optional
filenames as the AmigaDOS command line will allow. For example...
1> RUN TEXTRA <filename1> <filename2> ... <filenameX>
2.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.5 Normally, TEXTRA will not launch twice. If a TEXTRA B is launched
and finds TEXTRA A already running, B will send to A the names of the
files that B was passed via the mechanisms described above in sections
2.2, 2.3 or 2.4. TEXTRA B will then exit. This feature allows users
to "get that file open" in the whatever means is most convienient.
(Note that enough memory must be available for TEXTRA B and TEXTRA A
to momentarily reside in the machine. Also, ARexx must be running for
'Smartlaunch' to work.)
2.5.1 To satisfy the "keep-control-until-finished-editing"
expectations of some external programs such as mail readers, Textra
1.15 introduced both an Rexx command as well as a command-line option.
If one configures their mail reader to launch Textra in either of the
2 following forms...
run Textra -wait <filename>
...or...
rx 'address TEXTRA "OpenFileWait <filename>"'
...Textra will not return control to the calling program until the
window for <filename> is closed. See RexxCommand.doc for more info
on the OpenFileWait ARexx command.
Note that the latter form (the use of the Rexx command) is recommended
as the former actually runs another copy of Textra for as long as the
editong session is active. Also, note that ARexx is required for either
method.
2.6 At startup, TEXTRA checks the relative average color intensities
of the active intuition screen and if same as wb 2.0+, (color1
darkest, color0 medium, color2 brightest), it will use shaded gadgets
and 2.0-style checkbox imagery (even if under 1.3 and earlier).
If the colors are not found suitable for shadowing, TEXTRA will render
it's requester and gadget imagery primarily in monochrome (colors 0
and 1). Boolean gadgets (checkboxes) are also rendered differently.
---------------------------------------------------------------------------
3. THE TEXTRA CURSOR
3.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. The cursor marks the place where newly-typed
characters will be inserted (characters following will 'shift right')
or backspace or forward delections will occur.
3.2 The cursor may be positioned by simply single-clicking the LEFT MOUSE
BUTTON on the text where you want the cursor to be.
3.3 The cursor may also 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.
3.4 If the cursor or select range is not on the visible part of the
screen, it can be located and displayed via the F3 key.
---------------------------------------------------------------------------
4. ENTERING TEXT INTO THE DOCUMENT
4.1 As text keys are typed at the keyboard, they are entered in the file
at the current cursor location, and the cursor is advanced by one.
4.2 The RETURN key inserts a new line, and moves the cursor there.
4.2.1 If the Auto-Indent mode is enabled (see section 10.4.9), the
cursor will align with the line above when the RETURN key is pressed.
4.3 The BACKSPACE deletes the character to the immediate left of the
cursor and backs the cursor up one column. If the cursor is at the
leftmost column, the line is joined with the previous one.
4.3.1 When the cursor rests on the 1st non-blank character of a line,
the Auto-BackSpace mode (section 10.4.9) comes into play, if enabled.
The BACKSPACE key will"back-up" the line text by whatever it takes to
line up with the beginning of the text on the line above. If the
previous line does not start to the left of the cursor position, the
alignment is made to the next line above that does.
4.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 next line is joined with
the cursor line.
4.5 The TAB key advances the cursor to the next column that is an
even multiple of the TAB width value (section 10.4.9).
4.6 Normally, the TEXTRA CTRL key, when used with alphabetic keys (a-z and
A-Z), is used to execute user-definable ARexx scripts (see section 8.7).
This feature can be temporarily defeated, for 1 character, by pressing
F2. Following F2, the next character will be accepted into the window
as the appropriate ASCII control-code.
4.7 The HELP key will display an informational requestor, displaying
information about the keyboard-activated functions. The HELP key
can also be user-defined (see section 8.7).
---------------------------------------------------------------------------
5. SELECTING A RANGE OF TEXT
5.1 It is possible to mark a series of characters for the next
operation by "dragging" with the mouse. Just press and hold the
left mouse button, then drag to the desired selection end-point.
5.2 A series of characters will become selected when the LEFT MOUSE
BUTTON is double-clicked while the mouse cursor is positioned over
them. Based on the setting of the EDITING PREFERENCES (section
10.4.9), the series will consist of either contiguous non-white-space
or aplha-numeric characters. If the LEFT MOUSE BUTTON is
triple-clicked, that entire line will become selected.
5.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, that text 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, as well as many of the provided ARexx scripts
also operate on the current selection.
5.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.5 A select range may be established or size changed by holding
down the SHIFT key when clicking in the window. If the click occurs
outside the current select range, the range is extended to there.
If inside, the end-point of the select range is adjusted to the
click-point.
5.6 If you double click on any of these characters... ( ) < > [ ] { }
Textra will search through the file in the appropriate direction for a
"balanced match" and it (handles (nested (substrings))). This is
great for example, when programming C and you want to see everything
that the { you're staring at encompasses. Textra will highlight
everything forward to the balancing } character.
Note that you can also find corresponding double-quote characters
"like around this", but TEXTRA assumes you are clicking on the LEADING
double-quote. (In other words, it will only conduct a forward search
for a corresponding double-quote).
---------------------------------------------------------------------------
6. VIEWING PAGES
6.1 The easiest method for moving through the file is to use the vertical
scroll bar on the right side of the window. Clicks of the left
mouse button on the arrows at either end move the document vertically
in continuous scroll fashion.
6.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.
6.3 Another method by which text may be scrolled into view is by moving
the cursor...attempts to move the cursor "off the window"
will cause text in that direction to scroll.
6.4 Function keys F4 and F5 will PAGE the display down and up,
respectively. The Shift-UP/DOWN-arrow-key combinations will also PAGE
the display in the appropriate direction AND position the cursor
to the middle of the new page.
6.5 The horizontal scroll gadget works similarly to the vertical
scroll gadget. It becomes functional when a line is being displayed
that exceeds the current width of the window. When typing, the display
will auto-scroll to center the cursor when it reaches a window edge.
---------------------------------------------------------------------------
7. TEXTRA WINDOWS
7.1 TEXTRA allows any number of windows, limited by the amount of
memory in your computer (most limiting is possibly the amount of
available CHIP ram, at least in early 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).
7.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 FILE AS..." menu option is chosen, section 10.2.7). If the
file has been modified since last saved, the filename will be
preceeded by a '*'.
7.2.1 A Status Line may optionally be presented immediately below the
title bar. It displays the current cursor location or select range in
column, line coordinates (zero-based).
7.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" (section 10.2.9) for more information.
7.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.
7.5 Function key F1 may be used as a "window-size-toggle" between
default size (when F1 was first hit) and that size specified in the
"Edit Preferences..." requester (10.4.9). This preference setting
defaults to full-screen.
7.6 Function key F6 will re-select the previously-selected window.
This a handy "toggle between 2 windows" mode, facilitating convienient
evolutions such as successive Cut, Copy & Paste sequences (sections 10.4.2,
10.4.3 and 10.4.5).
7.7 If the asl.library is available (usually means WB2.0 or later),
the font in which a window is initially rendered is configurable via
the "Font Preferences..." requester (10.5.6). A windows font may be
changed at any time via the "Set Window Font..." asl requester
(10.5.5).
In WB1.3 and earlier, Textra assumes the system default font, so
use of a utility such as setfont just before opening a window will
allow various font displays. Without the asl library, changing the
font of an already-opened window is not possible.
---------------------------------------------------------------------------
8. THE TEXTRA-AREXX INTERFACE
8.1 When TEXTRA starts up and finds AREXX available, it opens a
message port called "TEXTRA". This port listens for AREXX messages
from other programs, and allows you to control the editor both from
other applications or from AREXX "scripts", many of which are supplied
with TEXTRA (they should be copied to your 'rexx:' directory). These
scripts may contain a mixture of AREXX and TEXTRA commands; they allow
access to many internal TEXTRA editing functions which may be
performed on the 'current' window.
After opening the "TEXTRA" message port, it searches to see if
a script called "Startup.textra" is available, and if so, executed.
No such script is supplied with the package, the feature is available
soley for user customization.
The AREXX menu item is dimmed if AREXX is not available when TEXTRA
is launched.
8.2 TEXTRA/AREXX scripts or commands may be executed via the
"AREXX..." item in the Utilities menu (section 10.5).
The ARexx requester will be presented. It contains ten string
gadgets, 8 with an accompanying button describing the function key to
execute the gadgets contents without having to bring up the requester.
All string gadgets may be executed by selecting them and pressing
ENTER.
Some string gadgets will assume default strings when initially
installed. Gadget contents are executed or saved as separate,
independant operations and if executed, the ARexx requester will close
before any ARexx commands are carried out. The string gadget contents
are saved in "S:TEXTRA.CMDS" which is only as large as the length of
the strings plus an EOL character for each. The CANCEL button allows
the requester to be closed and reverted to it's original state upon
opening.
Into any string gadget, you can enter the name of a Textra-ARexx
script that exists in the rexx: directory (followed by any required
arguments), as in...
slide 8
Optionally, you can directly enter ARexx and Textra commands into the
string gadgets, but they should be preceeded with an '@' character.
Examples...
@notify "Hello world!"
@prefs autoindent on
@options results; get file name; notify result
8.3 Normally, while a script is executing, another window may be made
frontmost and edited. (It should be noted that some system global
resources, such as the cut, copy & paste buffer, are shared between
the script and the edited window. While none of the supplied
scripts use the CUT, COPY or PASTE commands, it is worth keeping in
mind if you write your own.)
8.4 Please refer to the accompanying file "RexxCommand.doc" for a
description of the TEXTRA/AREXX command set as well as general
information about writing your own scripts.
8.5 Using section 8.2 as a guide, execute the "Tutorial" ARexx script
for an interactive 'training session' for beginners. In one of the
ARexx requester string gadgets, simply enter:
tutorial
8.6 While an ARexx script is executing, the 'ARexx...' menu text
changes to "Cancel ARexx Script". This feature tries to tell the
running script that the user wishes it to terminate, but will only
have an effect if the running script uses the CHECKCANCEL Textra-ARexx
command. (All appropriate supplied scripts utilize the CHECKCANCEL
command).
8.7 By default, CTRL+any alphabetic key will execute an ARexx script
named after the key. For example: CTRL-A will look for and execute a
script called CTRLA.textra. CTRL+HELP will try to run
CTRLhelp.textra. EVERY ALPHABETIC KEY ON THE KEYBOARD IS THEREFORE
USER-DEFINABLE.
No CTRL scripts have been supplied with the package; this feature
is provided soley for user customization. (Note: the v1.15 release
added some CTRL scripts as part of the SAS/C integration. See
'docs/SASC.ReadMe'.)
---------------------------------------------------------------------------
9. THE MARKS FACILITY
9.1 The MARKS facility allows you to assign any selected text to a
logical name of up to 31 chars long. Any number of assignments can be
made. Textra keeps the list for you on disk (more about how it is
stored below) ... this information is updated each time the file is
SAVE...'d or SAVE AS...'ed.
IF YOU ADD/DELETE MARKS FROM A FILE, YOU MUST "SAVE..." OR "SAVE
AS..." THE FILE FOR THE CHANGES TO BECOME PERMANENT. TEXTRA will
prompt if a file is about to be closed with unsaved changes to the
MARKS list.
9.2 Textra provides 3 menu items to access the MARKS facility (see
10.5.7, 10.5.8 and 10.5.9), two of which have keyboard equivalents.
Also, 3 ARexx commands have been added to mirror the menu interface
(see docs/RexxCommand.doc).
9.3 Textra saves all of the MARKS information for the associated text
file in a 'shadow' file in the same directory.
This 'distant cousin' will be given the same name as the original text
file, except that a '}' character will be placed before it. (This
arrangement causes the '}file' to appear last in dir listings, etc.).
For example, if your term paper is called...
term.doc
...Textra will name the shadow file...
}term.doc
(There is an initial 8 byte overhead for the file setup, and each mark
adds 48 bytes, so the minimum shadow file size is 56 bytes. Shadow
files tend to be MUCH smaller than their associated text file).
9.4 There are a few special considerations when using MARK-ed files...
9.4.1 Note that if you copy a MARK-ed file to another place, you
should also copy the }filename file if you wish the marks information
to be preserved in the new location.
9.4.2 Because Textra will add a character to the filename, marks
cannot be saved for files if their name is the full 31-character
AmigaDOS limit in length. 30-character filenames and less will work
fine.
---------------------------------------------------------------------------
10. TEXTRA MENUS
10.1 Four 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. When the HELP
key is pressed (section 4.7), a list of such menu "key equivalents"
is included.
10.2 The "Project" Menu
10.2.1 OPEN FILE... opens a new window with a full file-selector
requester and buttons that allow quick access to the top 8 disk
devices (like DF0:). 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.
10.2.2 OPEN BY NAME... opens a new window, then presents a string
requester for specifying the filename from the keyboard, bypassing
the directory scan for the list of names (which can take time on
large directories, especially on floppy drives). The current
directory of the requester is that of the spawning window. If a
pathname is typed into this requester, the "OPEN FILE" selector
requester is opened, presenting a list of the files in that directory.
10.2.3 OPEN NEW FILE opens a window without specifying a filename; the
default name "Untitled" is assigned, at the directory level of
the spawning window. (No actual disk file will be written until
the SAVE AS... function is invoked.)
10.2.4 INSERT FILE... presents the TEXTRA file-requester allowing
selection of a file to INSERT at the current cursor location (as
though the entire file were typed in). Any select range will be
deleted prior to the insertion.
10.2.5 REVERT TO SAVED causes the read-in version of 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.
10.2.6 SAVE FILE causes the currently-selected file to be written to
disk, if modified. If the file has not been changed (no '*' before
the title), this menu item is disabled.
Before you SAVE a file over an existing disk file, Textra performs
a check that the size of the disk file is the same as it was when the
file was read in by Textra. If the size is different, the user is
notified and given the option to CANCEL the SAVE. Note that this
behavior does NOT apply to the SAVE AS menu pick (10.2.7), nor
commands issue from the ARexx interface which overwrite a file on disk
(for example, SAVEAS "*").
10.2.7 SAVE FILE 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.
If a directory name is entered (or no name at all), the SAVE AS...
file requester is presented. The FILE SAVE AS... requester contains a
unique feature... in the lower-left corner is a checkbox permitting
one to elect to save the file in MSDOS text format.
10.2.8 SAVE ALL FILES causes all files that have been modified and not
saved to be written to disk. If there are no modified files, this
menu item is disabled.
10.2.9 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. After the window
has closed, TEXTRA will select and front another TEXTRA window if any
remain. Right-Amiga-W is a keyboard menu-equivalent for the CLOSE
FILE menu item.
10.2.10 PRINT FILE prints (to the printer.device) the currently selected
window using the current preference settings (section 10.2.12). While
a print job is in progress, other windows may be edited or have ARexx
scripts executed in them, but not printed. Print jobs may be cancelled
at any time by using the CANCEL button on the "Printing in progress..."
requester. (Any delay experienced is the amount of time it takes your
printer to respond to the RESET command). If the window to be printed
is the only one open, TEXTRA will ask if you want to open another.
10.2.11 PRINT SELECTED LINES prints any and all lines, in their
entirity, if any part of it is currently selected. The current
preference settings (section 10.2.12) are observed. The same 'print
job' behavior described in section 10.2.10 applies.
10.2.12 PRINTING PREFERENCES... presents a dialog to allow the user to
enable/disable the following print job behavior...
1). Print a one-line page header at the top of each page noting the
date, filename and page number.
2). Print sequential line numbers at the beginning of each line.
3). Skip over perforated page boundries of fanfold paper.
4). Eject the page (form-feed) after printing an entire file (10.2.10)
5). Eject the page (form-feed) after printing selected lines (10.2.11)
Note that TEXTRA also observes the system 'Preferences' settings for
left & right margin, characters-per-line, and lines-per-page (use your
system 'Preferences' tool to set these). The USE button causes the
currently displayed settings to go into effect. The USE+SAVE button
does the USE function, and also saves the current settings in the
Textra Preferences file (section 11.5). The CANCEL button causes any
currently displayed settings that have been changed to be discarded.
If the PRINT PREFERENCES requester is active, this menu item is
disabled from other windows.
10.2.13 ABOUT TEXTRA provides the author's address and describes
distribution information. Also, if the TEXTRA is registered, the name
and address of the honest person who has earned my thanks and respect
is displayed in this requester.
10.2.14 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. Right-
Amiga-Q is the keyboard menu-equivalent for the QUIT menu item.
10.3 The "Windows" Menu
10.3.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.
10.3.2 Additionally, the text will include a "*" character before the
filename if the file has been modified since but not saved to disk.
A checkmark preceeds the item representing the current file.
10.4 The "Edit" Menu
10.4.1 UNDO reverts all changes since the cursor was last
re-positioned.
10.4.2 CUT removes the selected range of characters from the
currently-selected file, but saves them in the Amiga Clipboard Device
(unit 0). The previous contents of the clipboard are lost. If there
is no select range, this menu item is disabled.
10.4.3 COPY moves the selected range of characters of the
currently-selected file to the Amiga Clipboard Device (unit 0), but
does not remove them from the file. The previous contents of the
Amiga Clipboard Device (unit 0) are lost. If there is no select
range, this menu item is disabled.
10.4.4 PASTE inserts whatever is in the Amiga Clipboard Device (unit
0) 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
Amiga Clipboard Device.
10.4.5 FIND presents a sub-menu with 2 choices:
10.4.5.1 STRING... presents a requester prompting for the string to
search for, ignoring character case. The string gadget will, as a
default, contain the previous string searched for (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.
10.4.5.1.1 WRAP... On the FIND STRING requester is a checkbox that
allows you to enable "wrap-around" search. Normally, if the search
string is not found, TEXTRA terminates the search at the end of the
document. With the "wrap" box checked, the search will continue from
line 1, and end when either the text is found, or the starting line
is reached. This mode also applies to the "FIND NEXT OCCURENCE" menu
item (section 10.4.5.2).
10.4.5.2 NEXT OCCURENCE conducts another case-insensitive search for
the same text string that had previously been searched for. If no
search had yet been conducted the "STRING..." requester is presented.
10.4.6 REPLACE presents a sub-menu with 2 choices:
10.4.6.1 STRING... presents a double-string-requester, prompting for
both the string to conduct a case-insensitive search for and a
string to replace the it with. The RETURN key will
toggle the selected string gadget. The user may optionally:
1). replace all instances of the found string (with the "ALL"
button)
2). replace just the next one found (via the "ONCE" button)
3). abort (via "CANCEL").
The search begins just past the current cursor location
or selected range of characters.
10.4.6.2 NEXT OCCURENCE conducts another "REPLACE" operation, using the
same strings that were used last time. If none exist, the "STRING..."
requester is presented.
10.4.6.3 THEN FIND allows the user to decide which instances of
the specific text will be REPLACEd, and which will not. This feature
is usually used thusly:
1). Bring up the REPLACE STRING Requester (via menu or
Right-Amiga-R).
2). Enter the appropriate strings in the 2 string gadgets.
3). Click on the SEARCH button. The first instance of the "Search
for:" text will be located and highlighted (text must occur
AFTER the cursor in the file, so if you want the entire file
checked, put the cursor at the beginning of the document).
4). If you want to REPLACE the highlighted text, press
Right-Amiga-Y. If not, Right-Amiga-N. (like Yes and No)
5). The editor will respond accordingly and locate the next instance
of the text.
10.4.7 CASE presents a sub-menu with 3 choices:
10.4.7.1 LOWER exhibits 2 behaviors depending on whether an area
is selected or not. If there is, the entire selected area is converted
to lower case. If not, the next word after the cursor is searched for
and converted to lower case if found.
10.4.7.2 UPPER exhibits 2 behaviors depending on whether an area
is selected or not. If there is, the entire selected area is converted
to upper case. If not, the next word after the cursor is searched for
and converted to upper case if found.
10.4.7.3 CAPITALIZE exhibits 2 behaviors depending on whether an area
is selected or not. If there is, each word in the selected area is
located and capitalized. If not, the next word after the cursor is
located and capitalized.
10.4.8 GO TO LINE... presents a string requester prompting for the
desired line number, with the initial string gadget contents being
equal to the current cursor line (or the beginning of any selected
range). First line of file is considered line 1.
10.4.9 EDITING PREFERENCES... presents a requester allowing configuration
of:
1). "Auto-Indent" mode (section 4.2.1)
2). "Auto-BackSpace" mode (section 4.3.1)
3). Display Status Line or not (section 7.2.1)
4). Use Asl file requester or internal (section 11.4)
5). TAB WIDTH value (section 4.5)
6). AlphaNumeric OR Non-Whitespace double-click highlighting
(section 5.2)
7). Operation of the F1 Window Size Toggle function key.
(section 7.5).
The USE button causes the currently displayed settings to go into effect.
The USE+SAVE button performs the USE function, and also saves the current
settings in the Textra Preferences file (section 11.5). The CANCEL button
causes any currently displayed settings (that have been changed), to be
discarded. If the EDITING PREFERENCES requester is active, this menu item
is disabled from other windows. (Right-Amiga-E is a keyboard equivalent
for this menu item.)
10.5 The "Utilities" Menu
10.5.1 FILE PROTECTIONS... provides the ability to set the 6 relevant
file protection bits that are stored and processed by AmigaDOS. These
include Deletable, Executable, Writable, Readable, Archived and Script
(particularly handy when writing AmigaDOS scripts). The SAVE button
causes the currently displayed settings to become active. The CANCEL
button is self-explanatory.
10.5.2 WRITE-PROTECT/ENABLE WINDOW... This is a dual-purpose
menu-item; it toggles in text and function each time it is used. When
used, it alternately write-protects or write-enables the currently
selected window. The normal Textra editing/Arexx mode is considered
write-enabled. There are two ARexx commands that allow scripts and
external programs to control this state.
When a window is write-protected, a '-' character appears in the
window title bar (much as the '*' character to indicate a changed
file). A window which contains changes cannot be write-protected; it
must be saved first.
Note that while write-protected, functions which change window textual
content are not accessible. This includes Insert-file, Undo, Cut,
Paste, Replace, the Case-changing functions, File protections, ARexx
(the only ARexx command that will work is WRITEENABLE), Mark Selected
Text and Delete mark. Similarly, the keyboard cannot be used to
insert text. One CAN still select text, copy text from the window,
print the window, etc.
10.5.3 HELP ON KEYBOARD... performs the same action as the HELP key
(section 4.7).
10.5.4 AREXX... presents a requester affording access to the Textra-
ARexx Interface. See section 8 for more information.
10.5.5 SET WINDOW FONT... allow the user to change or find the name
of the currently selected window's font. This function requires the
asl.library. The selection is completely independant of the selected
font used for Newly-Opened Windows (10.5.6).
10.5.6 FONT PREFERENCES... presents those aspects of the font display
facility which provide save-able configuration parameters. This
version (v1.13) only has one; the selection of which font will be used
for all subsequent newly- opened windows. The consistant USE,
USE+SAVE, CANCEL interface of the other TEXTRA preferences dialog is
preserved.
10.5.7 MARK SELECTED TEXT... becomes active when anything is
selected. Presents a requester prompting for the name under which to
MARK the text selection under. The program will prompt for
verification if a name redefinition is attempted.
IF YOU ADD MARKS TO A FILE, YOU MUST "SAVE..." OR "SAVE
AS..." THE FILE FOR THE CHANGES TO BECOME PERMANENT.
10.5.8 GO TO MARK... active when any Marks have been defined in the
current file. It presents a scrolling list gadget allowing selection
of the MARK to display.
10.5.9 DELETE MARK... active when any Marks have been defined in the
current file. It presents a scrolling list gadget allowing selection
of the MARK to delete.
IF YOU DELETE MARKS FROM A FILE, YOU MUST "SAVE..." OR "SAVE
AS..." THE FILE FOR THE CHANGES TO BECOME PERMANENT.
---------------------------------------------------------------------------
11. TEXTRA GENERAL INFORMATION
11.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.
11.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.
11.3 For most string gadgets, the RETURN key will perform the same
action as the "OK" button. One exception is the "REPLACE"
double-string requester, where the RETURN key toggles between the two
string gadgets.
11.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 one or more open requesters. Note that a TEXTRA
window will automatically increase in size to accomodate a given
requester, and will return to it's original position/size when the
requester is closed.
11.4.1 Textra makes special use of the asl library, if found. It will
use the asl font requester to allow selection of font modes (section
7.7). Textra will also use the asl file requester and even allow you
to choose between it and a Textra native file requester. Besides
the obvious functional differences, there is a subtle but possibly
important way in which the editor behaves when each file requester is
presented:
11.4.2 Because of the manner in which the asl library works, Textra is
"blocked" when an asl requester is presented. The editor is "frozen"
(even print jobs and background ARexx script operation will pause)
until the asl requester is closed. One may optionally elect to NOT
use the asl file requester via the Edit Preferences (section 10.4.9).
Doing so will activate the use of the internal Textra file requester.
(Textra does not contain an internal font requester).
By default, Textra uses the Asl file and font requesters. If the
asl.library is not available, the Textra internal file requester is
used and cannot be changed and no font requesters are available.
11.5 TEXTRA maintains certain user-settable parameters in the file
"devs:Textra.prefs". If your system disk is of the floppy variety,
you may therefore be asked to insert this disk if you elect to save
it. Normally, TEXTRA looks for this file only once, at startup.
11.6 TEXTRA performs certain operations when reading in a file from
disk...
11.6.1 OS2.1 introduced CrossDOS as a standard AmigaDOS feature,
providing access to the MSDOS file-system. Even prior to 2.1, that
capability was available in a prolifera of products, including the
commercial version of CrossDOS. TEXTRA 1.15+ will successfully read
and write such files automatically. If desired, the user may change
between the two formats via the SAVE FILE AS... menu item (section
10.2.7).
11.6.2 Whenever TEXTRA reads in a file, it examines the first 32
characters in an effort to evaluate the file's "text-ness". If TEXTRA
thinks it may not be a text file, it will give you the opportunity to
abort and read in another file.
11.7 As of V1.15, Textra is low-memory-failure-proof! ANY MEMORY
REQUEST FAILURE WILL FLASH THE SCREEN 3 TIMES in 1 second, then wait
until the memory comes available. The editor is "frozen" until then,
but will resume operation when the request succeeds. The intention is
to give the user a chance to close the terminal program or paint
program that they left running in the background. Note that this
aplies only to memory allocations made by TEXTRA itself and Textra CAN
fail to open a window, for example (it is Intuition which allocates
that memory. ARexx shares similar responsibilities), but possible
failures are checked for.
11.8 Keyboard Summary:
F1 - Window Size Toggle (7.4)
F2 - Keyboard Filter Defeat (4.6)
F3 - Page to Cursor or Beginning of Select Range (3.4)
F4 - Display next page (6.4)
F5 - Display previous page (6.4)
F6 - Present previous file (7.6)
F7 - AREXX string (10.5.4)
F8 - " " "
F9 - " " "
F10- " " "
Help - Displays this information (Keyboard Summary)
Shift-Left-arrow - Cursor to beginning of current line (3.2)
Shift-Right-arrow - Cursor to end of current line (3.2)
Shift-Up-arrow - Display previous page, cursor to middle (6.4)
Shift-Down-arrow - Display next page, cursor to middle (6.4)
Right-Amiga-O - Open existing file via file requester (10.2.1)
Right-Amiga-P - Open existing file by typing its name (10.2.2)
Right-Amiga-[ - Open a new file (10.2.3)
Right-Amiga-S - Save the current file (10.2.6)
Right-Amiga-W - Closes the current window (10.2.9)
Right-Amiga-Q - Quits Textra (10.2.14)
Right-Amiga-Z - Undo (10.4.1)
Right-Amiga-X - Cut selected text, save in clipboard (10.4.2)
Right-Amiga-C - Copy selected text into clipboard (10.4.3)
Right-Amiga-V - Paste clipboard into file (10.4.4)
Right-Amiga-F - Find string in any case (10.4.5.1)
Right-Amiga-N - Find the next occurance of same string (10.4.5.2)
Right-Amiga-R - Replace string with another (10.4.6.1)
Right-Amiga-T - Find & replace same string again (10.4.6.2)
Right-Amiga-L - Set text or next word to lower case (10.4.7.1)
Right-Amiga-U - Set text or next word to upper case (10.4.7.2)
Right-Amiga-K - Capitalize words or next word (10.4.7.3)
Right-Amiga-G - Go to a specific line (10.4.8)
Right-Amiga-E - Display the Editing Preferences requester (10.4.9)
Right-Amiga-- - Write Protect/Enable window (x.x.x)
Right-Amiga-/ - Select/enter/execute a Textra-Arexx script (x.x.x)
Right-Amiga-M - Mark Selected Text (10.5.7)
Right-Amiga-, - Go To Mark (10.5.8)
Requester control...
Right-Amiga-X - Clear text in string requester (11.2)
Right-Amiga-Q - Restore original string requester text (11.2)