System Booster

home *** CD-ROM | disk | FTP | other *** search

/ System Booster / System Booster.iso / Texteditors / Textra116 / Docs / Textra.doc < prev next >

Wrap

Text File | 1996-09-27 | 50.1 KB | 1,153 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 " " " 111280 Undo, SmartLaunch, 1st shareware 10-Jan-93 v1.13 " " " 129252 Fonts, Multi-Processing, lots more 29-May-93 v1.14 " " " 137260 -- v1.14 Status Line, User-define kybd 20-Jan-94 v1.15 " " " 155088 -- v1.15 Marks, SAS/C interoperability 04-Jan-95 v1.16 " " " 164144 -- v1.16 Columnar Cut/Pst, C= Installer (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 Commodore-compatible Installation Script 1.3 The Proprietary Installation Program 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.2.1 Double-Clicking Alphanumeric strings and options 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 5.7 Establishing a COLUMNAR selection for Cut or Copy. 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.4.1 Performing a Columnar Paste 10.4.5 Find 10.4.5.1 String... 10.4.5.1.1 Wrap-around search option 10.4.5.1.2 Reverse 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 a script for the standard Commodore 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.3 If the user does not have the Commodore Installer program, a proprietary one is provided. Do the following: 1. Open the 'Scripts' drawer 2. Drag the 'Install_Textra' icon out of the 'Scripts' drawer, placing it at the same level as the 'Textra' program. 3. Double-Click on the 'Install_Textra' icon and follow the instructions. --------------------------------------------------------------------------- 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.2.1 When the Alpha-Numeric mode is selected, up to 16 non- alphanumerics may specified in the accompanying string gadget. For example, if you enter an underscore '_' in this string gadget, then alpha-numeric double-clicks will select right through that character as though it were an alpha-numeric. 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). 5.7 Drag-select a columnar range - Hold down the ALT key when you first click the LEFT MOUSE BUTTON when beginning to drag-select. When you finish the drag-select (let the mouse button up), the select range will change to a "square" Most usually, you will then Cut or Copy the area into the clipboard, in preparation for doing a columnar Paste (section 10.4.4.1) in another location or window. A columnar select, however, can also be deleted, replaced, etc... just like a normal select range. NOTE: When drag-selecting a columnar range, the finally-selected "square" can extend past the end-of-lines. If a "copy" of the selected text is performed, such "short" lines will be padded with blanks in the clipboard data such that all lines are the same length. Caveats... In this initial version, the ALT key and the mouse are the only interface to establishing and working with columnar ranges. In other words, there is no ARexx command for "holding down the ALT key", and one MUST use the mouse with the ALT key (the Right-Amiga keyboard equivalent mechanism traps the ALT key, so keyboard-only columnar pastes are not possible). Because of some of these problems, I'll probably change the ALT key to something else in the not-too-distant-future. Feedback is always appreciated. --------------------------------------------------------------------------- 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. A 'SYSTEM' button is provided at the top of the requester which will open your printer preferences tool. If the System Preferences do not come up, make sure they have not been moved from where originally installed. 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.4.1 Perform a Columnar Paste - Hold down the ALT key when you pull down the "Edit, Paste" menu item to have Textra execute a paste in columnar fashion. (In other words, Textra will begin the paste at the same column on each line.) Currently, the menu item is the only interface to the columnar paste function. 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.1.2 REVERSE... On the FIND STRING requester is a checkbox that permits Reverse-searching to be enabled. As long as this checkbox is senabled, searched will be conducted backwards through the file. 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)