Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d7xx/d768/uedit.lha/Uedit/Documentation/ManualInProgress.lha/new.manual123

Text File | 1992-03-27 | 506KB | 10,699 lines

MANUAL UPDATE:  The normal-Esc command (set PM terminator) was modified as
follows:  If atCursor==locB, it lets you set the PM terminator character as
always.  If atCursor!=locB, it moves the cursor to locB.  locB is the location
marking the last scratch delete(s); moving the cursor to locB is handy
because you can move the cursor somewhere else and long as you don't do a
scratch delete there you can return quickly to your former position.

NOTE:  get config defaults and fix DEFAULTS in manual
NOTE:  update the Color Commands in part1 and any discussion of local/global
screens and colors

MANUAL UPDATE:  Fold (R-\)  can now optionally put in line numbers.  And a new
command, Goto Source (A-\), was added to Config!z and to the folds menu which
works as follows:  The cursor is in a (numbered) line in the fold-file; the
command takes you to that line's source line in the original file.

MANUAL UPDATE:  Startup compiling now lets you switch to tiny window.  It
pops back to the Uedit screen when an error is found or the compiling is
finished.

MANUAL UPDATE:  added new Ctl-f9 Last Search key & menu item.  It lets you
select from up to 10 previously used search strings.  If the search buffer
isn't being stacked, it lets you turn on stacking for it.

MANUAL UPDATE:  A new apropos R-5 command was provided (written originally by
Tony Sumrall).  It allows you to do an instant search that lists and
describes all commands that pertain to "scroll", for instance, or "cursor",
"undo", or "copy".  The apropos command uses a Help-Key file which is created
from the Key-Help file by the MakeHelpKey program that is provided.  The
source MakeHelpKey.c is also provided.



MANUAL UPDATE:  A new match-braces R-4 command was provided (written
originally by Tom Zartler).  It matches parens or curly braces, inverting the
bracketed region in the display.



MANUAL UPDATE:  A new in-use command R-1 was provided (originally written by
Kurt Wessels).  It makes a table showing which key combinations are in use
(have got a cmd assigned to them) and which are available.  This is extremely
useful in deciding to which keys you would like to assign new commands in
your config.



MANUAL UPDATE:  A new R-6 command swaps current file with next file.



MANUAL UPDATE:  A fake (real) scroll gadget mouse command was created which
uses the middle mouse button.  It draws and uses a scroll gadget in the msg
line.



MANUAL UPDATE:  SC-f1 Restore Current File cmd was improved.  After reloading
curFile from disk, it restores the page, cursor, hilite, and invert locations.



MANUAL UPDATE:  MOUSE-BUTTON COMMANDS:

    These have been modified as follows:
        1)  scroll-hiliting, if you double-click the mouse button & move mouse.
            (This cmd was originally written by Ken Perano.)
        2)  auto-padding of lines with spaces if you click the mouse button
            beyond end-of-line when the COLUMNAR FLAG is ON.

    normal-buttonDown:  This still deposits the cursor at the mouse as
        always, and it scrolls the display up/down if you move the mouse
        while holding down the button.  But if instead you double-click the
        mouse-button while holding the mouse stationary and THEN move the
        mouse while holding down the button, it marks a hilite region.  It
        scrolls the display up/down, if you move the mouse to the bottom or
        top of the window.

    shftAltCtl-buttonDown:  This command deposits the cursor at the mouse
        arrow, but if you clicked beyond end-of-line it extends the line by
        padding with spaces up to the mouse arrow.  This is useful when you
        want to type text some distance to the right beyond the current end
        of line.

    The following commands still set start/end of hilite or invert region as
    before.  But in addition if the COLUMNAR flag is ON, they now pad with
    spaces beyond end of line:

    shft-buttonDown:  Set start of hilite region at the mouse.  If COLUMNAR
        flag is ON, pad beyond end of line with spaces, if mouse was clicked
        to right of end of line.

    alt-buttonDown:  Set end of hilite region at the mouse.  If COLUMNAR flag
        is ON, pad beyond end of line with spaces, if mouse was clicked to
        right of end of line.

    shftCtl-buttonDown:  Set start of invert region at the mouse.  If
        COLUMNAR flag is ON, pad beyond end of line with spaces, if mouse was
        clicked to right of end of line.

    altCtl-buttonDown:  Set end of invert region at the mouse.  If COLUMNAR
        flag is ON, pad beyond end of line with spaces, if mouse was clicked
        to right of end of line.



MANUAL UPDATE:  New R-8 Save Key and R-9 Restore Key commands were created
and added to the Keys menu.  When you want to create a command on a key (such
as ESC) which already has a command on it, you can save the key temporarily
and restore it when you are through using the temporary command.



MANUAL UPDATE:  A new R-0 Date-Time-Stamp command inserts a date-time stamp
at the cursor.


MANUAL UPDATE:  A new ctl-gadget2 List Files cmd (submitted by Bob Jenkins)
lists all files in Uedit and lets you click the file you want to see.


MANUAL UPDATE:  Two stack oriented commands were created, which allow you to
keep and use up to 10 Search strings, Replace strings, Undo buffers, copied
Columnar regions, or copied Hilite and Invert regions.  R-2 shows you how
many buffers are on the stacks, how many bytes of memory are used, and lets
you turn on/off stacking for each kind of buffer.  R-3 let you see the
contents of buffers on the stacks, make them the current buffer (such as the
current search or replace string), delete individual buffers, or delete the
whole stack.


MANUAL UPDATE:  A new alt-ESC Tune RGB command was written which uses the
arrow keys to tune the colors.  The new alt-esc cmd is friendlier than the
old one was.  You can restore the original colors before quitting, if you
wish.  Also new L-esc, R-esc, and virtual-esc cmds were created, and an RGB
Colors submenu was created.  The new cmds let you select from 3 sets of RGB
colors.  Note that these keys can only be activated from the menu.


MANUAL UPDATE:  The alt-help command to toggle curFile's colors has been
rewritten.  A new version allows you to set the color usage in a more
friendly and thorough manner.


MANUAL UPDATE:  A new Screen Size lAmiga-f2 was added to the Display menu.
It asks for the new width & height dimensions and reopens the screen using
the new dimensions.  NOTE:  The CL sWidth and sHeight variables don't change
when you go to/from interlace; in interlace, the actual screen height is
2*sHeight.




MANUAL UPDATE:  A new shft-f5 Local Modes command (in the menu) displays the
description of the title bar local flags.

MANUAL UPDATE:  The LOCAL & GLOBAL flags were taken out of Show Vals.  All
local and global flags commands and were eliminated and removed from the
menus.

MANUAL UPDATE:  A new friendly ctl-g Global Modes command was created and put
into the menu.  It lets you set all of the global flag variables as well as
the local ones which are inherited by new buffers.  Local flags already
attached to buffers are not affected.  (Local buffer flags can be changed by
clicking the appropriate letter in the title bar.  The new shft-f5 command
presents help, if you need it.)



MANUAL UPDATE:  A new lAmiga-q command and Files menu entry switches to the
next file marked "Favorite".



MANUAL UPDATE:  A new shftAltCtl-z command loads files based on a filename-
wildcard (*?) mask.  SAC-z is called in the startup cmd when Uedit first
starts.

So if you run in CLI by typing "Run UE util*.?", the SAC-z command causes all
files matching the mask "util*.?" to be auto-loaded.  During an edit session,
you can press SAC-z to auto-load files using a wildcard mask also.




MANUAL UPDATE:  Section 1.30.3 in the manual which discusses leftMargin and
autoIndent needs correction.  A table needs to be provided to cover the
cases.  Note that when autoIndent is off and leftMargin>0, normal typing does
not use leftMargin.  But if you reformat the paragraph, it is indented to the
column specified by leftMargin.  So leftMargin is used in paragraph
reformatting if it is >0 even though during normal typing it is not used when
autoIndent is off.  Note also that the Left Margin (L-m).




MANUAL UPDATE:  Hyper text was modified to allow partial words to be looked
up.  This is not documented in the manual.  When the word buffer argument has
something in it and the flag = 0 or 1, first the word buffer content is
treated as a whole word/phrase in the lookup; if not found, it is treated as
a partial word/phrase.  Thus you can type or click the first few letters of a
hyper word or phrase and the lookup should find the whole word/phrase if it
exists in the table.

MANUAL UPDATE:  The hyper text commands and their keys and menu entry were
changed considerably:

    1.  The Open HT (R-gadget3) and Close HT (R-gadget4) commands were
    dropped.  The manual's discussion of these is now obsolete.  The Hyper
    Text submenu was dropped.  Only the entry for Hyper Text (R-gadget1) is
    now in the menu.

    2.  Hyper Text is now opened by R-clicking a word or by R-clicking
    gadget1 (which solicits a word input).

    3.  Config!H's hyper text commands were modified extensively to make
    hyper text friendlier and nicer.  Virtual keys are no longer used.
    ("Unused" macronum slots are used instead.)

    4.  The hyper text commands now expect you to have the following
    directory structure:
        S:Hyper/Files/HyperSample
        S:Hyper/Tables/HyperSample.tbl

    You can easily edit the DEFINE() near the top of Config!H to use U:
    instead of S:.  Also you can have any number of hyper text files and
    tables in the S:Hyper subdirectory.




MANUAL UPDATE:  Added:  -s CLI command line flag.  Examples:
    run UE -s         .. runs UE & loads in the default state file "uestate".
    run UE -sMyState .. runs UE & loads in state file MyState.

NOTE:  When a state is loaded, it uses the buffers that were in use when the
state was saved.  WARNING:  Files in Uedit may be erased so that the state
can use their buffers; you should save any changes before loading in a state.
Note also that if you type "Run UE -s file1 file2", file1 and file2 may be
erased from Uedit's memory so their buffers can be used by the state being
loaded in.

The -s flag is processed BEFORE the -k & -l CLI command line flags and AFTER
the named files (if any) are loaded in.  You can specify a key or learned
sequence (-k or -l) to act on the loaded state's files.  -s is processed
after the -c and -d flags, of course.  To summarize, the sequence is this:
    process -c and -d, if used
    load files, if any
    process -s, if used
    process -l and -k, if used


ELIMINATE ALL GLOBAL/LOCAL FLAG COMMANDS - use the flag-table versions
(c-g & s-f5)


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



Introduction

Uedit is a programmable text editor for technical people.  Development of
Uedit began in November, 1985.  It first came out in March, 1986.  The aim
has been to develop an editor such that one would:
   û Be able to work without bumping into limits of power, freedom, and capacity;
   û Be able to automate repetitive work, eliminate tedium, save time;
   û Be spared the irritation of unnecessary keystrokes and stodgy performance;
   û Be able to customize the environment fully;
   û Be able to create, on the spot, new capabilities that are needed.

Since Uedit came out, user feedback has been, by far, the principal and best
source of inspiration and ideas for improving the program.

Uedit has no editing commands built into it.  It loads in a data file at
startup which has the configuration it will use.  Novices need not be
concerned about this, as Uedit loads the standard data file, Data!,
automatically unless told to do otherwise.

The standard configuration has a lot of commands and features.  As a new
user, you may:
    o Use the standard configuration, as is.
    o Tweak the standard configuration, swapping keys, changing the default colors,
       line length, etc.
    o Use an emulation of some popular editor or wordprocessor.  Emulations are
       available in the public domain or as extras.
    o Create a custom configuration or emulate a favorite environment.

75% of users use the standard configuration or customize it slightly.  25%
overhaul the standard configuration in a major way or create a personal
configuration or emulation of a favorite editor or wordprocessor.

Uedit has registered users in the USA and in more than a dozen foreign
countries.  A survey revealed that virtually all are technical or scientific.
Most write programs at least part-time.  Nearly half earn their living by
programming.  More than a third have a doctorate in physics, computer
science, math, engineering, medicine, or other discipline.

Getting Started

To start Uedit from the Workbench, double-click its icon.

To start it in CLI, type "Run UE myfile1 myfile2 myfile3...."  To run with a
custom data file, use "Run UE -dMyData".  Once inside Uedit, use the menus,
Help key, and Teach Keys as needed.

FILES UEDIT MAY NEED:
            File Name           Need it?
            ---------           --------
            Data!               YES, at startup, unless you use the -d or -c flag.
            Help!               only if you press the HELP key.
            Key-Help            only if you use Teach Keys.
            NoName.info         only if "Make icons" is active.
            Config!(H,M,P,R,S)  if Data! is not found or you use the -c flag.

Uedit looks for these first in your current directory, and, if necessary, in
the S:  directory.  If you copy them to S:, you can run Uedit from any
directory.

Sometime when you can spare a few minutes, in CLI type "Run UE -c".  Make
sure that the Config!(A-Z) files are in S: or in your current directory.
This should be instructive and may encourage you to look into the
possibilities of the command language.

Specifications

Uedit Program Specifications:
    number of files     max can be set from 1 to 100; can exceed using stack
    buffers             buf0-buf99; actual # limited only by stack memory
    file/buffer size    8 megabytes or memory limit
    tracked locations   20 per buffer
    colored regions     2 per buffer; hilite and invert (regular or columnar)
    other regions       7 per buffer
    number variables    n0-n99; actual # limited only by stack memory
    named number vars   about 50 named number variables, such as lineLength etc
    file names          up to 76 chars in length
    queued file-saves   limited by stack memory, 8 bytes per entry
    queued prints       12; prints in busy mode, if full or low on memory
    learned sequences   200 steps
    command size        8 megabytes uncompiled, 20k bytes compiled
    run-depth           10 levels of commands running commands
    # of commands       1148 online, unlimited using various techniques
    gadget names        up to 19 chars in length
    search strings      delimited search1, search2, & "all-but" strings
    search str size     64 chars in each string, 127 total
    replace str size    8 megabytes or limit of memory
    grep string         /search/replace/ string up to 127 chars
    menu descriptions   up to 17 chars in length
    menus               7
    menu items          20
    menu subitems       12
    total menu items    1680
    submenu offset      0 to 100%, relative to parent menu
    screens             4; regular or interlace, 1 or 2 bitplanes
    scroll types        2; update colors or suppress color updating
    fonts               any non-proportional; speeds up size 8 & 11 fonts
    RGB colors          RGB tuning (0-15) of 4 color registers (0-3)
    4-color combos      16 local & global color settings, each set separately
    window height       128 lines
    window width        128 chars
    split windows       8
    split window size   2 lines min; max is window height minus 2 lines
    tab rulers          5
    tabs per ruler      32
    max tab column      255
    left margin         0 to 255
    top/bottom margins  0 to 255
    lines/page          1 to 255
    line length         1 to 9999

A number of the above specifications may be exceeded using the CL.  For
instance, lineLength, pageLines, and certain other variables may be set
outside the specs using the CL.

Items which are limited by stack memory need 8 bytes per entry in the stack,
so the practical limit is quite large.  Some unlisted specs cannot be
assigned a fixed limit, such as the maximum size of a block of nested
commands, or the maximum number of files that may be auto-edited using a
learned sequence; these need not be limited by available memory.  The actual
max buffer size is really very close to 16 megabytes in Uedit, but only 8
megabytes is claimed.  Most of the features described elsewhere in this
manual, such as typing and printing modes, columnar text operations, and
things you can do using the command language, are not reflected in the above
table of specs.

Organization of this Manual

Every Uedit command is customizable.  Whenever a key command is mentioned in
this manual, it is referring to the standard configuration.  If you customize
the standard config or use a different config, the standard key-bindings
cease to apply.  This manual is divided into 3 parts:

Part 1 is Using the Standard Configuration.

Part 2 is Getting More out of Uedit.  It describes how to get more out of the
program by using Learn Mode, editing tricks, and the command language.

Part 3 is the Command Language Documentation.

Abbreviations and Terminology

"Configuration" and "data" are used often in this manual.  A configuration
file defines all of Uedit's commands and features; it is a readable, editable
command language source file that is compiled by Uedit to create a compact
binary data file.  The data file is what Uedit loads and uses in processing
your editing inputs.

"Configuration" may be called "config".  "Data file" may be called "data".
While stored in memory, it is "data".  When written to disk, it becomes a
"data file".

"Key" may be used in place of "key command" or "key argument".  "Key" is any
input that may run a command, or sometimes "key" means the command itself, as
in "when the new key is run...."  Even mouse button inputs are keys.  The
CloseBox and message-line gadget inputs are keys.  Menu inputs are not keys,
because menus run existing keys.

A "command" is what runs when you input a key.  Commands may be run by other
commands, so commands may be called "routines" or "modules".

The following abbreviations or acronyms may be used in this manual:
    Words                   Abbreviations            Examples
    -----                   -------------            --------
    primitive mode          PM
    Workbench               WB
    command language        CL
    virtual                 virtual or V             virtual-Esc or V-Esc
    Shift                   shft or S                shft-F1 or S-F1
    Alt                     alt or A
    Ctrl                    ctl or C
    Shift-Alt               shftAlt or SA
    Shift-Ctrl              shftCtl or SC
    Alt-Ctrl                altCtl or AC
    Shift-Alt-Ctrl          shftAltCtl or SAC        shftAltCtl-z or SAC-z
    Left Amiga              lAmiga or L              lAmiga-b or L-b
    Right Amiga             rAmiga or R
    numeric keypad          kp                       ctl-kp7 or C-kp7
    end of line             eol
    end of file             eof
    linefeed                LF
    formfeed                FF
    carriage return         CR

Shift-modifiers are abbreviated in two ways:  In the text and in menus SAC-z
would be used rather than shftAltCtl-z, for the sake of brevity.  But in the
command language shift-modifiers must be spelled as follows:  normal shft alt
ctl shftAlt shftCtl shftAltCtl lAmiga rAmiga or virtual.  (Upper and lower
case are valid throughout the CL.)

"File" and "buffer" are used interchangeably, because files are loaded into
buffers and any buffer may be saved as a file.  Instead of saying "the
current file in the window" or "the current buffer", "curFile" is used.
curFile is a CL variable which means the buffer or file in the window.  If
split windows are in use, curFile is in the active window-split.

Where possible the CL names for things are used without explanation or
apology.  CL names are self-descriptive.  For instance, "overStrike",
"wordWrap", "rightJustify", and "lineLength" are CL variables.

"Page" is either a window page or a printed page.  In the CL, "page" is
window page, and "form" is printed page.  But in discussing printing and
paging documents, "page" means printed page.  The context makes it clear
which kind of page is being discussed.


Part 1.  Using the Standard Configuration

1.1  Uedit's Menus

The following are Uedit's menus as defined in the standard configuration,
Config!.  The names in parentheses are command language (CL) flag variables
that are turned on or off by the menu selections:

FILES (MENU #1)                             Grep (submenu)
Next file                  f1                       Grep fwd         L-f9
Prev file                S-f1                       Grep bkwd        R-f9
Open (submenu)                                      Set grep         L-f7
        Open             A-f1                       Grep repl->     L-f10
        File request     L-f1                       Grep repl<-     R-f10
        New file         C-f1               Bookmarks (submenu)
        Insert file     SA-f1                       Goto mark      S-gad1
        Restore         SC-f1                       Goto next      S-gad2
        Rename            A-n       Set mark S-gad3  Init marks S-gad4
Save (submenu)                              BUFFERS (MENU #3)
        Save               f2               Buffers (submenu)
        Save changes     A-f2                        Swap buf #0      A-w
        Save as...       S-f2                        Swap buf #43     C-w
        Save hilite     SC-f2                        See buffers    SC-f6
        Abort save      SA-f2                        Edit buffer    SA-f6
Close (submenu)                                      Free buffers    A-f3
        Close              f3                        Push buffer      L-w
        Auto-close       S-f3                        Pop buffer       R-w
Quit (submenu)                                       Roll stack      SA-w
        Quit               f4               Data file (submenu)
        Auto-quit        S-f4                       Save data        A-f6
        ABORT Uedit!     A-f4                       Load data        C-f6
AmigaDOS (submenu)                          Compile (submenu)
        AmigaDOS          C-y                       Compile            f6
        DOS + result      C-z                       Cfg defalts     AC-f6
        Directory         A-z                       Make command     S-f6
        CD (Chg dir)     AC-z               Keys (submenu)
About...                SAC-a                       Swap keys          f5
SEARCH (MENU #2)                                    Swap mouseUp      A-m
Search (submenu)                                    Kill key       SAC-f6
        Search fwd         f9                       Find key         L-f6
        Search bkwd      S-f9               Learn (submenu)
        Set search         f7                       Start learn       C-s (learnMode)
Replace (submenu)                                   End/Run learn     C-r
        Replace fwd       f10                       Save learn        C-5
        Rpl all fwd     A-f10                       Load learn        C-6
        Rpl bkwd        S-f10                       Load & run        C-7
        Set replace       f8                Name gadget             C-esc
Settings (submenu)                          Speak hilite              A-s
        Case sensitiv     C-8 (searchCaps)
        Wildcards        A-f7
        Either-or        C-f7

EDITS (MENU #4)                        Rexx (submenu)
Col display              SC- (columnar)       Ed out buf35     AC-1
Cut&Paste Hilite (submenu)                     Ed in buf36      AC-2
        Copy              kp.                  Buf35->Rexx      AC-3
        Cut               kp-                  Buf36<-Rexx      AC-4
        Paste         kpEnter                  hilite->Rexx     AC-5
        Clear             C-h                  Cursor<-Rexx     AC-6
Cut&Paste Invert (submenu)                     Reply OKAY->     AC-7
        I-Copy          C-kp.                  Reply text->     AC-8
        I-Cut           C-kp-                  Auto-traffic     AC-9 (userGlobalB)
        I-Paste     C-kpEnter                  Make x.rexx      AC-0
        I-Clear           C-i          MODES (MENU #5)
Columnar (submenu)                     Hyper Text (submenu)
        Col Cut          SC-1                  Hyper text     R-gad1
        Col Erase        SC-2                  Open HT        R-gad3
        Col Copy         SC-3                  Close HT       R-gad4
        Col Insert       SC-4          Teach Keys (submenu)
        Col Overlay      SC-5                  Teach keys     C-help (teachKeys)
        Ins Hil->Csr     SC-6                  Teach one      C-t
        Ovl Hil->Csr     SC-7          Local modes            S-f5
Text reformats (submenu)               Global modes           C-g
        Paragraph         C-3
        Del white-spc     C-4
        Tabs->spaces      L-t
        Spaces->tabs      R-t
Printing (submenu)
        Print select      A-p
        Print hilite      C-p
        Print file       AC-p
        Restart print     L-s
        Abort print       L-a
        Stop all prts     R-a
        Code help       SAC-p
        Bracket hilite    L-p
        Find code         R-g
        Embed code        L-g
        Type formfeed     L-f
Paging (submenu)
        Go to page #      A-3
        Top of page       L-h
        Bottom page       L-b
        Divide page       L-v
        Auto page div     L-r
        Del page div      L-d
        Del page #        L-y
Spelling (submenu)
        Load speller      R-u
        Check fwd         R-c
        Chk&mark fwd      R-m
        Chk & collect     R-l
        Merge w/ dict     R-d
        Del from dict     R-e
        Free Speller      R-f

NUMBERS (MENU #6)                   DISPLAY (MENU #7)
Show vals              S-help          Colors                 A-help
Tab ruler (submenu)                    Tune RGB                A-esc
        See ruler      SA-tab          Hide display              R-h (hideDisplay)
        Set ruler      SC-tab          Scroll type               R-s (scrollType)
        Tab table     SAC-tab          Split windows (submenu)
Line-Page (submenu)                            Next split        L-9
        Line length     C-rtn                  Drop split        L-0
        Lines/page        A-g                  Split lines       L-8
        Left margin       L-k                  Mouse size        L-=
        Top margin        L-u                  Curr buf          L-c
        Bottom margin     L-l                  Undo buf          L-1
        End of line       C-e                  Search buf        L-2
Command mult              C-m                  Replac buf        L-3
Max files               AC-f1                  Hilite buf        L-4
Idle timer              SAC-i                  Invert buf        L-5
PM terminator             ESC                  Columnar          L-6
File size                 C-1                  Directories       L-7
                                               Lace/planes (submenu)
                                                       Toggle          S-esc
                                                       Reg 1 plane      R-f1
                                                       Reg 2 planes     R-f2
                                                       Lace 1 plane     R-f3
                                                       Lace 1 planes    R-f4
                                               Refresh               SC-help
                                               Do menus             SAC-help
                                               Unhilite                  A-h
                                               Uninvert                  A-i


1.2 Things You Should Know

Here are some basic facts about the operation of Uedit that you should know:

No commands are hardwired in Uedit.  Every command is user-customizable.
Whatever happens when you give an input, such as when you click the mouse
button, is governed by a command that was originally written in the CL, can
be found in the Config! file or one of its (A-Z) extensions, and was compiled
by Uedit.  This means that you can change what you do not like about Uedit in
most cases or can create most anything new that you need.  Changes in how
Uedit operates can be made on the fly, without closing the files you are
editing.  Any customizing that you can do by compiling an entire config file
can also be done during an edit session.

Amiga-ESC (left or right Amiga key) is the general purpose abort key.  It is
the only hardwired or dedicated key in Uedit, except for special cases such
as responding to requesters and tab rulers.  Use Amiga-ESC to abort any
operation except spooled prints and file-saves.  Spooled prints and file-
saves must be aborted by their separate commands, which are Abort Print (L-a)
and Abort Save (SA-f2).

Use Amiga-ESC to abort Teach Mode when you are finished using it.  Certain
Amiga-key combinations are not reported correctly to Uedit by the Amiga and
may be internally wired to the abort function.  If Teach Keys aborts
spontaneously because you input such an Amiga-key combination, restart it
using Teach Keys (C-Help) again.  (See Teach Keys, 1.11.2.)

Clicking the window's title bar switches Uedit to its tiny window.  Clicking
in the tiny window returns Uedit to its big screen.  (See Tiny Window, 1.4.).
To slide Uedit's screen up or down, put the mouse in the title bar at the
very top and slide the screen as you would any other screen on the Amiga.
(See Lace/Planes (S-esc), 1.39.1.)

Primitive Mode is used for collecting string and number inputs during
editing.  For example, if you select Set Search (f7) to input a search
string, you are put into Primitive Mode.  PM is unlike normal editing mode in
that no editing commands may be used.  PM allows typing and deleting; the
arrow keys move the cursor, and shift keys increase the power of the cursor
movement.  (See Primitive Mode, 1.7.)

Primitive Mode is terminated using either a mouse click or the current PM
terminator character (pmEsc).  In the Config! defaults, pmEsc is set to the
ESC key (ASCII 27).  This manual may remind you to press ESC or it may just
assume that you know what to do.  If it reminds you to press ESC to terminate
PM, what it really means is that you should either click the left mouse
button or input the current pmEsc character, which you may have changed from
ESC to something else, such as the Return key.  (See Primitive Mode, 1.7.)

Uedit offers 4 choices for the screen it uses, which are regular or
interlace, each using 1 or 2 bitplanes.  1-bitplane screens use only 2
colors; 2-bitplane screens use 4 colors.  Scrolling is faster and less memory
is used with 1 bitplane.  You get more lines per window using interlace.  The
least memory is used in regular (non-interlace) with 1 bitplane, which also
gives the fastest scrolling.  Interlace with 1 bitplane uses about the same
memory as non-interlace with 2 bitplanes.  (See Lace/Planes, 1.39.1.)

When you change anything such as Colors or lineLength or if you compile a new
command, selecting Save Data overwrites the data file so that the change is
saved to disk for future use.  Throughout this documentation, rather than
telling you repeatedly that you may select Save Data (A-f6) to save changes
to Uedit's data, you are expected to know that you may do this.  (See Save
Data, 1.36.1.)

When you have made changes that you wish to recover from, such as swapping or
killing keys or changing colors, you may recover the original data by using
Load Data (C-f6).  (See Load Data, 1.36.2.)

To make Uedit use a particular data file at startup, type the following in
CLI:  "Run UE -dMyData ...", where MyData is the data file that Uedit is to
use.  When no data file is specified, Uedit loads in the standard data file,
Data!, automatically.  Uedit never needs a config file, unless you tell it to
compile a config at startup using the -c flag; or unless it cannot find the
data file either in the current directory or in S:.  If Uedit cannot find the
data file it is supposed to be using, it looks for the standard config
(Config! and its (A-Z) segments) to load in and compile.  (See CLI Command
Line, 2.1.)

Terminating and aborting:

To abort any operation except spooled prints and spooled file-saves, use Amiga-ESC.

To abort a spooled print, use Abort Print (L-a).

To abort a "busy" print (realtime, in foreground, not spooled), use Amiga-ESC.

To abort a spooled file-save, use Abort Save (SA-f2).

To terminate Teach Mode, press Amiga-ESC.

To terminate Set Ruler (setting tab ruler), type any non-applicable key or
click the mouse 2 lines away from the tab ruler.  To abort Set Ruler, use
Amiga-ESC.  (See Set Ruler (SC-tab), 1.26.4.)

To interrupt a startup-compile (when Uedit is compiling an entire config file
at startup), use Amiga-ESC.  To quit Uedit after interrupting the startup-
compile, use Amiga-ESC again.  To resume startup-compiling, put the cursor
where you wish the compiling to resume and press ESC.

1.3 Window Title Bar

The name of the current file (buffer) is displayed at the right in the
window's title bar.  If no name exists, "Buffer-#" is used, where # is the
buffer's number, 0 to 99.

The square brackets [buf#,flags] to the left of curFile's name contain the
current buffer number and status flags.  The status flags are as follows:

    If Learn Mode is active, "L#" appears, where # is the number of inputs
    you have "recorded" using Learn Mode.

    If Teach Mode is active, a "T" appears.  In Teach Mode, instead of acting
    as function keys, keys describe themselves when you input them.

    If prints have been queued up, "P#" appears, where # is the number of
    unfinished print jobs in the queue.

    If file-saves are queued up, "S#" appears, where # is the number of
    unfinished file-saves in the queue.

To the left of the brackets [buf#,flags] is a row of buffer status flags =
"tiokrwjmcabf".  These indicate all of curFile's flag settings.  If the
letter is capitalized, the flag is ON.  The flags can be toggled ON/OFF by
clicking the appropriate letters in the title bar.  The flags are as follows:
    t/T = trueTabs
    i/I = autoIndent
    o/O = Overstrike
    k/K = autobacKup
    r/R = Readonly
    w/W = wordWrap
    j/J = rightJustify
    m/M = Mapchars (map illegal characters)
    c/C = Changed
    a/A = userglobalA (used for Save On Idle)
    b/B = userglobalB
    f/F = Favorite

The window title bar also has the following additional uses:  When in
Primitive Mode, the title bar notifies you that you are in Primitive Mode.
And an "X" flag appears before the square brackets "X[buf#]", and clicking
the "X" toggles the Primitive Mode terminator character between ESC and
Return.  (See Primitive Mode, 1.7.)

When you click the title bar, the big window closes and the tiny window opens
up.  (See Tiny Window, 1.4.)

1.4 Tiny Window

Clicking the title bar causes Uedit to switch to its tiny window.  Using a
tiny window is better than using window depth gadgets for a number of
reasons:  Uedit's tiny window comes up inactive, so you can immediately type
into a CLI or shell window.  The title bar is easier to click than small
depth gadgets are.  The tiny window frees up about 30k or more of graphics
memory.  Going to/from tiny window lets the Amiga reopen the big window in a
better memory location, creating more contiguous free space for graphics.
(See Memory, 1.5.)

To return Uedit to its big window, click inside the tiny window.  If the tiny
window is the active window, any keys that you type are ignored except ESC.
ESC causes a return to the big window.

When you first go to tiny window, if commands are being executed their
execution continues until finished.  Then Uedit finishes any printing or
file-saves that are queued up.  Then it does housekeeping, packing and
reallocating buffers in order to eliminate memory waste and fragmentation.
When finished with its busywork, it sleeps so that other tasks run
efficiently.

The tinyPriority command language variable and Config! default determines the
task priority that Uedit uses when in tiny window.  You may wish to lower the
priority in order to increase the computer resource available to other tasks.

When you try to return to big window but there is insufficient memory for it,
Uedit sleeps until it can reopen its big window.  Normally memory becomes
available when another task finishes running.  If no memory can be had by
waiting, close or shrink the CLI or Workbench windows and Uedit may find
enough graphics memory to reopen its big window.

When the screen is reopened after being in tiny window its vertical
coordinate is the same as before.  That is, you can slide the screen down, go
to tiny window or switch to another screen type and the reopened screen keeps
the original coordinates.  To reset Uedit's screen coordinates to (0,0), go
to tiny window and move it before clicking in it.

1.5 Memory

When you pause for 4 seconds, Uedit does memory housekeeping.  If you resume
typing before it has finished, it interrupts its housekeeping and pays
attention.  To monitor which buffer is being packed during housekeeping,
select Busies (C-b).  Uedit also does housekeeping when in tiny window.  When
it has finished with housekeeping, it sleeps.

Memory housekeeping consists of packing buffers that have been fragmented.
When contiguous memory falls below about 10k, Uedit reallocates each buffer
block, allowing the Amiga to create as much contiguous memory for graphics as
possible.

Uedit monitors the available memory and alerts you if less than 10k of
contiguous memory is remaining; it flashes the screen, displays a "Memory..."
message, and starts housekeeping.  This 10k-warning is helpful when you are
running other tasks, because you can switch to tiny window and free about 30k
or more of memory for the other tasks to use, avoiding a no-memory abort in
tasks such as compiles and links.

If the "Memory...." message keeps coming back, close some files or select
Free Buffers (A-f3) to free all non-file buffers.  Uedit sacrifices memory
for speed in text-inserts.  Large numbers of text-inserts, such as massive
search-replaces, may use up nearly all available memory for a while.  The
memory is recovered 4 seconds later by housekeeping or immediately if memory
runs too low.

1.6 Gadgets

The message-line, just beneath the title bar of the window, contains four
invisible "gadgets" that are activated by clicking the mouse in them.  These
gadgets are "keys" in Uedit, just like keyboard keys.  When gadgets are
clicked, their customizable command is run.  There can be shift-modified
gadget commands also, but none are defined in the standard config.  Gadget
commands may be swapped, killed, used in learned sequences, and so on, just
like other keys.

Mark Gadgets (C-g) turns On/Off the gadget names in the message line.  The
gadget names are defined in the config defaults.  (See the Config! file.)  If
Row/Column (C-2) is turned On, the 4th gadget-name is replaced by the
cursor's page-row-column.

1.7 Primitive Mode

Primitive Mode (PM) is used when string and number inputs are needed, such as
inputting a file name or new lineLength value.

The title bar indicates when you are in Primitive Mode.  The file name is
replaced by a message saying "Primitive Mode string input (ESC = done):"
or "Primitive Mode number input (ESC = done):".  The message line beneath
the title bar gives instructions; for example, when you use Set Search (f7)
the message says "Input search string:".  If the current PM terminator is
Return, the title bar message will instead say "(Return = done):".  (See PM
Terminator, 1.28.1.)

In Primitive Mode, editing commands are disabled and only typing and single
character deletes are permitted; the cursor is moved using the arrow keys.
If overstrike typing mode is On, it is turned Off temporarily.  You can type
Ctrl-characters directly into PM.  Thus you can search on characters like
ctrl-m (carriage return) and ctrl-l (formfeed).  (In normal editing mode you
must use Input Control Character (C-c) to type control characters into the
text.)

Primitive Mode may be aborted with Amiga-ESC.  PM is the bare bones of Uedit
without any commands whatsoever, and so in order to do deletes and move the
cursor certain keys are hardwired:  DEL deletes the character under the
cursor.  BACKSPACE deletes character-left.  The arrow keys move the cursor;
using Shift, Alt, or Ctrl increases the power of the arrow key.

pmEsc is the character that terminates Primitive Mode.  It is set to the ESC
key (ASCII 27) in the defaults in Config!.  But a PM Terminator command (ESC)
is provided to allow you to change pmEsc.  Clicking the left mouse button
also terminates Primitive Mode, no matter what the pmEsc character is.  (See
More About Primitive Mode, 2.2.)

pmEsc can also be changed while inside Primitive Mode.  When in PM, an "X"
flag appears in the title bar just before the square brackets "X[buf#]", and
clicking the "X" toggles the PM terminator between ESC and Return.

1.7.1 PM Terminator (ESC)

pmEsc is the Primitive Mode escape (terminator) character, which must be a
control character, such as Return or ESC.  In the config defaults, pmEsc is
set to ESC (ASCII 27).  Many prefer using Return, however.

By pressing ESC, you can select a different PM terminator (pmEsc) character,
such as the Return key.  If you press ESC by mistake and it asks for the new
pmEsc character, just press ESC a second time.

ESC asks you to input the new pmEsc character.  If you type a control
character (such as ESC or Return or Ctrl-m), it becomes the new pmEsc.

pmEsc should be a character that you are unlikely to want to use in text
inputs in response to questions, because questions requiring a text input
most often use Primitive Mode.  This is why ESC, and not Return, is used as
the standard pmEsc character.

However, as noted above, pmEsc can also be changed while inside Primitive
Mode, by clicking the "X" in the title bar during Primitive Mode.

1.8 Fonts

The font and font size Uedit is to use are specified initially in the Config!
defaults.  If the specified font is invalid, Uedit defaults to Topaz 8.

During a work session, you can change the font using Set Font (SA-f).  Use
Save Data (A-f6) to save the modified data to disk, if you wish to preserve
the new font choice.

Uedit accepts proportional fonts.  However, Uedit calculates the spacing per
letter as though the font were non-proportional.  So mouse-cursor placement
acts strange and other cosmetic side effects may occur.

For the fastest screen updates and scrolling, choose a size 8 or size 11
font, such as Topaz 8, Topaz 11, or Clean 8.

1.8.1  Set Font (SA-f)

SA-f asks first for the font name (such as "Topaz") and then it asks for the
font size (such as "8").  Uedit then reopens its screen and rebuilds the
menus, using the new font.  If the font name or size that you specify is
invalid, Uedit defaults to the Topaz 8 font.

1.9 Help (Help)

Help loads the Help! file into buffer 42 which becomes curFile.  (curFile is
the currently active buffer in Uedit.)  The Help! file must be in the current
directory or in S:.  The Help is set to readOnly status so that you cannot
damage it by mistake, but you may edit it and save it by turning Off its
readOnly flag using Read-only (SA-f5).

When finished looking at the Help, if you press Help again, it erases buffer
42 from memory.  If you instead toggle to the next file using F1 or gadget1
or any other file-toggling input, Help stays resident in buffer 42 and the
next time you press Help it appears instantly.  (See Hyper Text, 1.47.)

1.10 Show Vals (S-Help)

Show Vals shows the values and settings that are global for Uedit and local
to curFile that are not shown in the Local and Global Modes menus.  That is,
to find out whether curFile has its WordWrap flag set, look in the Local
Modes menu.  To find out its file size and the global Print Select value or
current lineLength or pageLines, use Show Vals.

Show Vals displays the following Uedit-global and curFile-local information:
Serial number, Buffer, Size, Max files, Split size, Idle timer, Color bits,
End-of-line, PM terminator, Line length, Lines/page, Left margin, Top margin,
Bottom margin, Tab table, Printer select, Search wildcard, Search multiWild,
Search allBut, Search eitherOr, Search single-white, and Search multi-white.
(See the sections discussing these.  See Global Modes (C-g), 1.19.  Also see
the defaults in Config!.)

1.11 Teach

Teach Mode teaches the purpose of inputs.  In Teach Mode, inputs do not cause
editing commands to be run but merely display their help messages.  An input
may be a mouse click or gadget click or key or menu selection or the
CloseBox.  The input may use shift-modifier keys, such as Shift or Alt.  When
using Teach Mode, try the various shift keys along with the inputs.

When trying shift-modifiers along with inputs, use the left and right Amiga
keys individually, not in combination with other modifiers; however, Shift,
Alt, and Ctrl may be used in any combination together to modify any key or
mouse input.  If the input has a command, its help message appears in the
message line; if it has no command, the message "No help or unused" appears.

The Key-Help file must be in your S: directory in order to use Teach Mode,
unless you customize the defaults in Config! and move the key help file
elsewhere.  When you first use Teach Mode, Key-Help is copied to RAM:uejunk,
so that message response is faster.  When you abort Teach Mode with Amiga-
ESC, the junk file is left in RAM:, in case you need to use Teach Mode again
later.  If you do not plan to use it again, delete RAM:uejunk at some point.
(See the first few defaults in Config!, which are for key-help.  Also see
Building Key-Help for Teach Keys, 2.11.)

While Teach Mode is active, a "T" is shown in the square brackets in the
title bar.  To terminate Teach Mode, press Amiga-ESC.  Certain Amiga-modified
keys are internally wired to Uedit's abort function just as Amiga-ESC is.
This was done, because the Amiga does not report certain Amiga-modified keys
to Uedit reliably.  If an Amiga-modified input causes an abort out of Teach
Mode, the screen will flash, the "T" will disappear from the title bar, and
you must press C-Help to reenter Teach Mode.  (See Valid Key Arguments, 2.29.)

1.11.1 Teach One (C-t)

C-t displays the help message for the (one) next input that you give.  The
first time you use it, there is a delay while the key help is copied to RAM:.
After that, the response is immediate.

1.11.2 Teach Keys (C-Help)

C-Help turns on Teach Mode.  It stays active, displaying the help messages of
all inputs that you give, until you abort with Amiga-ESC.  There is a delay
after the first input you give, as the key help is copied to RAM.  After
that, the response is fast.

1.12 Cursor

The cursor may be placed with the left mouse button or using the keypad keys,
kp2, kp4, kp6 and kp8.  The unshifted keypad's cursor-movement keys are word-
oriented, rather than character-oriented.  This facilitates rapid cursor
movements for fast typists.

A "word" consists of the following characters:  Alphanumeric characters (A-Z,
a-z, 0-9); characters with ASCII value greater than 127 (European umlaut
characters etc); and the apostrophe "'".

In all cursor movements, if the cursor goes offscreen, the text is scrolled
so that the cursor line is centered in the window.

1.12.1 Find Cursor (kp5)

Kp5, S-kp5, A-kp5, and C-kp5 find cursor and center it in window.  Typing any
printable key also finds the cursor.

1.12.2 Place Cursor (buttonDown)

Position the mouse in the text and press the left mouse button.  This
deposits the cursor at the mouse location.  Clicking the mouse button in any
window split activates that window split, making it curFile.  Holding down
the button and moving the mouse causes vertical scrolling.

1.12.3 Cursor Character Left (S-kp4)

S-kp4 moves the cursor left 1 character.

1.12.4 Cursor Character Right (S-kp6)

S-kp6 moves the cursor right 1 character.

1.12.5 Cursor Word Left (kp4)

kp4 moves the cursor left to the start of the next word.  (See the above
definition of "word" characters.)  The cursor is left on the first character
of the word.

1.12.6 Cursor Word Right (kp6)

kp6 moves the cursor right to the end of the current or next word.  (See the
above definition of "word" characters.)  The cursor is left on the first
character after the end of the word.

1.12.7 Cursor Upline (kp8)

kp8 and S-kp8 move the cursor up 1 line.  The cursor stays in its original
column, unless the line above is too short; it regains its original column if
moved up or down to a line at least as long as the cursor's original column.'

Note:  Wordprocessors typically do preserve the cursor column in up/down
cursor movements, even if it puts the cursor beyond the eol.  This hides
information and may result in characters being put into the file that you do
not realize are there.  Also wordprocessors often put their own "spooks" into
files.  Uedit is an editor, and it does not let the cursor rest anywhere
except on a real character or at eof; it puts in no hidden characters of its
own.

1.12.8 Cursor Downline (kp2)

kp2 and S-kp2 move the cursor down 1 line.  See Cursor Upline (kp8) regarding
the cursor's column.

1.12.9 Cursor to Start-of-Line (A-kp4)

A-kp4 and C-kp4 move the cursor to the start of its line.  If the cursor is
already at start-of-line, it moves to the start of the previous line.

1.12.10 Cursor to End-of-Line (A-kp6)

A-kp6 and C-kp6 move the cursor to the end of its line.  If the cursor is
already at end-of-line, it moves to the end of the next line.

1.12.11 Cursor to Start-of-Window (A-kp8)

A-kp8 moves the cursor to the start of the window.  The text is scrolled so
that the cursor-line is centered in the window.

1.12.12 Cursor to End-of-Window (A-kp2)

A-kp2 moves the cursor to the end of the window.  The text is scrolled so
that the cursor-line is centered in the window.  The end of the window is by
definition the first character in the line just below the window.  (Regions
in Uedit are bounded as follows:  The start of any region is the first
character contained in the region.  The end of the region is the first
character after the region.  This approach may at first seem strange, but it
makes sense once you are used to it.  See Hilite and Invert Regions, 1.29.
Also see Locations and Regions, 2.12.)

1.12.13 Cursor to Start-of-Form (C-kp8)

C-kp8 moves the cursor to the start of the current form (printed page), as
determined by line-count and formfeeds in the text.  If already at start-of-
form, the cursor is moved to the start of the previous form.

1.12.14 Cursor to End-of-Form (C-kp2)

C-kp2 moves the cursor to the end of the current form (printed page), as
determined by line-count and formfeeds in the text.  If already at end-of-
form, the cursor is moved to the end of the next form.

1.13 Scrolling

Scrolling does not require moving the cursor.  You can scroll to another
location in a file, take a look, and return to the original cursor page by
typing any printable key or using Find Cursor (kp5).

Scrolling is faster when using a 1 bitplane screen; mouse scrolling is faster
than arrow key scrolling, because key-repeat speed is limited.  Using the
arrow keys, you can scroll to another place in the file, create a hilite
region using the mouse and copy or cut it, and return to the cursor without
losing its original position.  If scrollType is 0, colors are updated during
scrolling; if scrollType is nonzero, scrolling is somewhat faster because
colored regions are not colored during the scroll.  (See Display Modes, 1.39.
See Hilite and Invert Regions, 1.29.  See Scroll Type (R-s).)

1.13.1 Scroll with Mouse (buttonDown)

Hold down the left mouse button and move the mouse up or down in the text.
Moving the mouse upward scrolls the text toward the start of the file.
Moving the mouse downward scrolls the text toward the end of the file.
Releasing the button stops the scrolling.  Clicking the mouse button without
moving the mouse deposits the cursor without causing scrolling.

1.13.2 Scroll Down (gadget3)

Holding down the mouse button in gadget3 in the message line causes the text
to scroll toward the end of the file.  Scrolling continues as long as the
button is depressed, until end-of-file is reached.  (See Mark Gadgets,
1.19.4.)

1.13.3 Scroll Up (gadget4)

Holding down the mouse button in gadget4 in the message line causes the text
to scroll toward the start of the file.  Scrolling continues as long as the
button is depressed, until start-of-file is reached.  (See Mark Gadgets,
1.19.4.)

1.13.4 Scroll Up 1 Line (upArrow)

upArrow scrolls the text up 1 line toward start-of-file.  If upArrow is held
down, scrolling continues until upArrow is released or start-of-file is
reached.

1.13.5 Scroll Down 1 Line (downArrow)

downArrow scrolls the text down 1 line toward end-of-file.  If downArrow is
held down, scrolling continues until downArrow is released or end-of-file is
reached.

1.13.6 Scroll Up 11 Lines (S-upArrow)

S-upArrow scrolls the text up 11 lines toward start-of-file.

1.13.7 Scroll Down 11 Lines (S-downArrow)

S-downArrow scrolls the text down 11 lines toward end-of-file.

1.13.8 Scroll Page Up (A-upArrow)

A-upArrow scrolls 1 page toward start-of-file.  A page is the number of lines
that will fit into the window.

1.13.9 Scroll Page Down (A-downArrow)

A-downArrow scrolls 1 page toward end-of-file.  A page is the number of lines
that will fit into the window.

1.13.10 Scroll to Start-of-File (C-upArrow)

C-upArrow scrolls to the start of the file.

1.13.11 Scroll to End-of-File (C-downArrow)

C-downArrow scrolls to the end of the file, centering the end-of-file in the
window.

1.13.12 Scroll Right 1 Column (rightArrow)

rightArrow scrolls the text right 1 column toward start-of-line.

1.13.13 Scroll Left 1 Column (leftArrow)

leftArrow scrolls the text left 1 column toward end-of-line.

1.13.14 Scroll Right 10 Columns (S-rightArrow)

S-rightArrow scrolls the text right 10 columns toward start-of-line.

1.13.15 Scroll Left 10 Columns (S-leftArrow)

S-leftArrow scrolls the text left 10 columns toward end-of-line.

1.13.16 Scroll Right 20 Columns (A-rightArrow)

A-rightArrow scrolls the text right 20 columns toward start-of-line.

1.13.17 Scroll Left 20 Columns (A-leftArrow)

A-leftArrow scrolls the text left 20 columns toward end-of-line.

1.13.18 Scroll to Start-of-Line (C-rightArrow)

C-rightArrow scrolls the text right all the way to start-of-line.

1.13.19 Scroll to End-of-Line (C-leftArrow)

C-leftArrow scrolls the text left all the way to end-of-line as determined by
the current lineLength value.

1.14 AmigaDOS

You may run AmigaDOS programs by clicking the title bar to go to tiny window
and running them in CLI or Workbench.  You may also run programs from inside
Uedit by using the AmigaDOS menu.  When running Uedit in Workbench, be
selective about which programs you run from inside Uedit.  Some programs
cannot be run safely in Workbench and will hang up the Amiga.  You may have
to find out by trial and error which programs are safe to run from inside
Uedit.  You will need the following programs in your C: directory in order
for certain commands to work:  Execute Run Dir Cd.

1.14.1 Execute AmigaDOS Program (C-y)

C-y asks for the name of the program you wish Uedit to execute using the
Amiga's Execute function.  Type in the program name and ESC.  It runs the
program but does not collect the result, if any, when the program terminates.

To run the Calculator program, you can use C-y and type "Calculator"; that
will run the Calculator, but it will tie up Uedit until you exit from the
Calculator.  Or you can type "Run Calculator".  This is better, because Uedit
isn't tied up and you can edit and use the Calculator at the same time.

Also if you run a program from inside Uedit by typing just "ProgramName",
Uedit will move its screen to the back temporarily so you can type inputs
into the program.  But if you instead type "Run ProgramName", its window is
opened on top of Uedit's screen.  For instance, if you run NewCLI by typing
"Run NewCLI" in Uedit, the new CLI window will be on top of Uedit's screen;
it will be overwritten by Uedit's screen updates, but you can prevent this by
opening an unused split window and putting the CLI (or other) window on top
of it.  Note that Uedit will not let you go to tiny window or close its
screen if there is a window on top of its screen.

1.14.2 Execute AmigaDOS Program and Get Results (C-z)

C-z functions exactly the same as C-y, except C-z collects the results, if
any, when the program terminates.  The results are displayed in buffer 40,
which becomes curFile, after the program terminates.

1.14.3 Get Directory Listing (A-z)

A-z uses the Dir program to get a directory listing.  It asks for a directory
name followed by ESC.  If you give it no name, it gets a listing of Uedit's
current directory.  The directory listing is loaded into a file buffer which
becomes curFile.  A-z accomplishes the same thing as the F2 option in the
S:Directories split window.  (See Click-Load File (C-buttonDown), 1.15.4.)

1.14.4 Change Uedit's Directory (AC-z)

AC-z changes Uedit's Current Directory.  (Note:  This may not work in
Workbench, but it does work in CLI.)  AC-z asks for the directory name
followed by ESC.  AC-z accomplishes the same thing as the F4 option in the
S:Directories split window.  (See Click-Load File (C-buttonDown), 1.15.4.)

1.15 Files

The MaxFiles setting determines how many of the 100 numbered buffers Uedit is
to use as file buffers.  If MaxFiles is 20, Uedit will use buffers 0 to 19
for loading files and will not let you load 21 files.  You can load any
number of files up to the limit of memory by using Insert File or the buffer
stack, however.  (See Buffers, 1.20.)

1.15.1 Next File (f1,gadget1)

F1 and gadget1 advance to the next existing file buffer, making it the new
curFile.  (See Mark Gadgets (C-g), 1.19.4.)

1.15.2 Previous File (S-f1,gadget2)

S-f1 and gadget2 go backward to the previous existing file buffer, making it
the new curFile.  (See Mark Gadgets (C-g), 1.19.4.)

1.15.3 Max Files (AC-f1)

AC-f1 asks how many documents should be allowed (1-100).  Type in the number
you want (typically 20) and press ESC.  If you type in 20, then buffers 0 to
19 become the file buffers.  The remaining buffers are available for
commands.  Unless you overhaul the standard config, you should not set
MaxFiles higher than about 30, because commands use buffers for various
purposes.  (See Buffers, 1.20.)

1.15.4 Click-Load File (C-buttonDown)

Ctrl-clicking the mouse button does a number of things relating to files and
directories.  You are encouraged to use the convenience of click-loading
files rather than tediously typing file names to load in or using a file
requester.

Click-loading a file:  Hold down the Ctrl key and click a file name in any
buffer.  The file is loaded automatically.  If the file doesn't exist, a file
buffer is opened with its name.  If a click-loading directory name was
selected earlier, the directory name is prepended to the file name before the
file is loaded.

Selecting a click-loading directory name:  When you Ctrl-click a directory
name or whitespace in any buffer for the first time, the S:Directories file
is loaded into buffer 38.  If S:Directories does not exist, buffer 38 is
initialized with the following directory names:  DF0:  DF1:  DH0:  RAM:

If you Ctrl-click a directory name in any buffer, the directory name is added
to the list in buffer 38 and becomes the current click-loading directory.
Thereafter, when you Ctrl-click a file name, the directory name is prepended
to the file name automatically before the file is loaded in.  (Directory
names must end with "/" or ":".)

Seeing the Directories list:  Ctrl-click whitespace in the window, and the
Directories list (buffer 38) is shown in a split window.  While the split
window is open, the message line presents the following options:
    Ctrl-mouse=SelectDir.  F1=Edit.  F2=DirList.  F3=Save.  F4=ChgDir.  F5=CD.

To close the Directories split window, click the mouse normally, without
using a shift key.

While in the Directories split window:  If you Ctrl-click a directory name,
it is hilited and becomes the new click-loading directory.  If you Ctrl-click
whitespace in the Directories list, Uedit's current directory becomes the
default click-loading directory.  F1 allows you to edit the Directories list;
then to close the split window, press L-0.  F2 gets a directory listing of
the current click-loading (hilited) directory.  F3 saves the file
S:Directories (buffer 38) which is in the split window, making it available
next time you run Uedit.  F4 changes Uedit's Current Directory to the
currently hilited click-loading directory.  (This may not work in Workbench,
but it works in CLI.)  F5 does a CD, getting Uedit's Current Directory and
displaying it in the message line.

You may find it convenient to keep a NoName file in your working directories
with a comprehensive list of directory and file names in it; clicking these
selects any directory or loads any file you may need.  If you run UE without
naming any files, the NoName file is loaded automatically.

1.15.5 Open File (A-f1)

A-f1 asks for the name of the file to load.  Type in the directory/file name
and press ESC.  No directory is required, if the file is in the current
directory.

1.15.6 New File (C-f1)

C-f1 opens an empty file buffer named Empty.

1.15.7 Insert File (SA-f1)

SA-f1 asks for the name of the file to insert.  Type in the name and press
ESC.  The file is loaded and inserted at the cursor location in curFile.

1.15.8 Restore (SC-f1)

SC-f1 asks whether you want to restore curFile to the original.  If you
answer Yes, it closes curFile and reloads the original file.

1.15.9 Rename (A-n)

A-n displays the name of the current file, allowing you to change the name.
Type in the new file name, deleting or modifying the old name as needed, and
press ESC.

1.15.10 File Request (L-f1)

L-f1 brings up a directory/file requester, allo,ing you to select a directory
and a file to load in.  If a current click-loading directory has been
selected, the file requester is intialized with the current click-loading
directory.  If you select a file using the file requester, the file is
loaded.  If you select just a directory, the directory becomes the new click-
loading directory.  If you select Cancel, nothing is done.  (See Click-Load
File, 1.15.4)

1.15.11 Save State (R-f5)

R-f5 saves Uedit's current state to a state file on disk.  The state includes
all files and buffers, search/replace/grep strings, color settings, cursor
and page positions, colored hilite/invert regions, and so on.  R-f5 first
asks for the state-file name.  The default name is "uestate".  Then it asks
whether you want to overwrite the existing state file (if one exists).

1.15.12 Load State (R-f6)

R-f6 first asks whether you want to save any files in Uedit that have been
changed.  If you select "Yes", it saves all changed files in Uedit to disk.
Then it asks the name of the state file you wish to load in; the default
state file name is "uestate".  Note that loading in a state-file will wipe
out whatever files and buffers you are currently using, if the state file
needs those buffer slots.  So it is important to save your changes, if you
want to keep them, before loading in a state file.

1.16 Save

When files are saved, they are saved under the directory/file name that is in
the window's title bar.  If a file already exists on disk, its attributes are
preserved when it is saved.  When you save a file, the buffer is locked and
put into the file-saving queue.  File saving is spooled and handled in the
background.  Inside the square brackets in the window's title bar an "S#"
appears, where # is the number of file-saves currently queued up.

If you close a file after putting it into the file saving queue, its buffer
is freed automatically after the save is finished.  You can edit a file
that's in the file-save queue, if it isn't the one currently being saved.  If
you edit such a file, when its turn comes in the queue it is not saved.
Instead it is removed from the saving queue.

Any number of file-saves may be pending at the same time.  File-saving
proceeds in the background as you continue editing other buffers or if you
switch to tiny window.  When the file-save is complete, the buffer is
unlocked and can be modified once again.

Quitting Uedit:  When you quit Uedit, any pending file-saves are completed
before the quitting process is carried out.  If you give any input while the
file-saves are in progress, Uedit abandons the quit and returns you to edit
mode.

1.16.1 Save File (f2)

F2 saves curFile to disk using the file name displayed in the title bar.

1.16.2 Save Changes (A-f2)

A-f2 saves all file buffers that have been modified since they were last
saved.  They are locked and cannot be edited until they have been saved.

1.16.3 Save As (S-f2)

S-f2 asks for the new name to save curFile under.  Type in the new name and
press ESC.  curFile is saved under the new name, and the title bar now
displays the new file name.

1.16.4 Save Hilite (SC-f2)

SC-f2 saves the hilite region in curFile to disk.  Type in the file name and
press ESC.  If no hilite region exists, nothing is saved and a warning
message "Read-only, empty, or bad name" appears.

1.16.5 Abort Save (SA-f2)

SA-f2 aborts the file-save that is currently in progress.  Pressing SA-f2
repeatedly aborts all file-saves that are queued up.  Warning:  If you abort
a file-save, the copy on disk is destroyed.  You must be sure to save the
file before leaving Uedit, if you want the file preserved!

1.17 Close

Closing a buffer merely frees the buffer.  If a file buffer has been changed
since it was last saved, the close commands ask whether you want to save the
changes before closing the buffer.

1.17.1 Close File (Closebox)

Clicking the CloseBox closes curFile.  If curFile has been changed since it
was last saved, CloseBox asks whether you want to save the changes or not.
Select Yes, No, or Cancel.  If you select Yes, it saves curFile and closes
it.  If you select No, it closes curFile without saving it.  If you select
Cancel, it aborts and does nothing.

After you have closed the last file buffer, a NoName buffer is opened.  If a
NoName file exists in the current directory, it is loaded in.  If no NoName
file exists, the NoName buffer is empty and you are asked whether you want to
quit or not.  Thus you can close all buffers and quit, using the CloseBox,
unless you happen to have a NoName file in the current directory.  Note:  If
you happen to have a NoName file in your current directory, CloseBox will not
let you quit Uedit and you will have to quit using one of the F4 quit
commands.

1.17.2 Close File (f3)

F3 closes curFile, if it has not been changed.  If it has been changed, F3
asks whether you want to save the changes or not.  Select Yes, No, or Cancel.
If you select Yes, it saves curFile and closes it.  If you select No, it
closes curFile without saving it.  If you select Cancel, it aborts and does
nothing.

1.17.3 Auto Close (S-f3)

S-f3 asks no questions.  It saves curFile, if it has been changed.  Then it
closes curFile.

1.18 Quit

The quit commands may ask whether you want to save changes before quitting
Uedit or may save the changes automatically.  The A-f4 quit command is an
exception; it quits immediately without saving anything.  After any saving of
files is done, and assuming that you do not abort with Amiga-ESC, the actual
quitting is handled by the quit() CL function.  (See the Quit() CL function
in 3.4.)

The quit CL function behaves as follows:  If ARexx is in use and a sent Rexx
message has not received a reply, you are returned to edit mode and cannot
quit until the reply has arrived.  If a received Rexx message hasn't been
sent a reply, Uedit replies to it and to all queued incoming Rexx messages
with a "failed" reply, to alert the senders that Uedit cannot receive anymore
messages.  If you have pushed buffers onto the buffer stack and haven't
popped them off, Uedit asks if it can throw them away.  If you answer No or
Cancel, it returns you to edit mode.  If any prints or file-saves are queued
up, Uedit finishes processing them before quitting.  During the time quit()
is finishing any queued up prints and file-saves, if you give any input, it
returns you to edit mode.

When Uedit quits, it gives a return code to AmigaDOS.  The return code is 0
on all quit commands except ABORT Uedit! (A-f4), which gives a return code of
10 to AmigaDOS.  The return code of 10 looks bad in the CLI window, but it
doesn't mean anything bad happened.  Its purpose is to help those who run
Uedit in execute files and need a meaningful return code.  (The return code
can be customized in the Alt-f4 command in the Config!M file.)

1.18.1 Quit (f4)

F4 asks if you really want to quit.  Select Yes, No, or Cancel.  If you
select No or Cancel, it aborts the quit and returns you to edit mode.  If you
select Yes, and if any file buffers have been changed, it asks if you want to
save the changes.  Select Yes, No, or Cancel.  If you select Yes, it saves
all changed files and quits.  If you select No, it quits.  If you select
Cancel, it aborts the quit and returns you to edit mode.  It gives AmigaDOS a
return code of 0.

1.18.2 Auto-Quit (S-f4)

S-f4 asks no questions.  It saves any file buffers that have been changed and
quits.  It gives AmigaDOS a return code of 0.

1.18.3 ABORT Uedit! (A-f4)

A-f4 quits Uedit FAST, asking no questions and saving no files.  It gives
AmigaDOS a return code of 10.

1.19 Global Modes

The Global Modes menu shows the current status of global flag settings.  If a
check-mark appears, the flag is On.  (See Local Modes, 1.31, and Show Vals,
1.10.)

1.19.1 Speak Messages (SC-f5)

SC-f5 toggles the speakMsgs flag.  When Speak Msgs is checkmarked, message-
line messages are spoken.  (Note:  Text speaking uses the SPEAK: device.  It
must be mounted before speaking will work.  You might want to mount it in
your Startup-Sequence.)

1.19.2 Speak Alerts (AC-f5)

AC-f5 toggles the speakAlerts flag.  When Speak Alerts is checkmarked, the
text in requester boxes is spoken.

1.19.3 Busies (C-b)

C-b toggles the Busies flag.  When Busies is On, a message "...#" appears
when a buffer is being packed, where # is the number of the buffer being
packed.  Buffer housekeeping is done automatically after a 4 second pause in
your typing.

1.19.4 Mark Gadgets (C-g)

C-g toggles the markGadgets flag.  When Mark Gadgets is On, the gadget names
and markings are visible in the message line.

1.19.5 Make Icons (AC-i)

AC-i toggles the makeIcons flag.  When Make Icons is On and a file is saved
to disk, a Workbench icon is created for the file, if none already exists.
The icon is created by copying S:NoName.info into myFile.info, where myFile
is the file being saved.  NoName.info must be in S:, in order for Make Icons
to work.

1.19.6 Use Keys (A-u)

A-u toggles the useKeys flag.  When Use Keys is On, printable keys such as
the keypad keys operate as typing keys and not as function keys.  When Use
Keys is Off, any printable key can operate as a command-key whose command
replaces the typed input of that key.  (See Part 2 sections covering Keys,
InputChar, and MacroNum.)

1.19.7 Invisibles (C-v)

C-v toggles the Spooks flag.  When Invisibles is On, control characters such
as ESC are visible as box characters in the text (depending on the font you
are using).  When Invisibles is Off, control characters are invisible in
text.  When spooks are invisible and you move the cursor through the text and
it lands on a spook, the cursor becomes invisible.  Also, when spooks are
invisible be careful when creating hilite and invert regions, because you may
forget to include an invisible spook in the region.  To see the ASCII value
of any spook ("box") character, put the cursor on it and press C-/.

1.19.8 Row/Column (C-2)

C-2 toggles the rowCol flag.  When Row/Column is On, the cursor's page-row-
column appears in the gadget4 (rightmost) position in the message line.
Following a cursor movement there may be a delay, depending on the size of
the file and how deep in it the cursor is, before the page-row-column info is
updated.

1.20 Buffers

A buffer is a block of memory for holding text files or regions of text.
Uedit has 100 numbered buffers, 0 to 99.  Any number of buffers may be pushed
onto buffer stacks as well, up to the limit of memory.

There are 100 buffer stacks, 0 to 99.  The buffer stack commands in the menu
all use buffer stack 99.

When viewing a buffer in the main window or in a split window, the buffer
number is displayed in the square brackets in the title bar.  In normal
editing, buffer handling is transparent and the user need not think about
buffer numbers or what is in various buffers.  (See Split Windows, 1.42.)

The low-numbered buffers (typically 0 to 19) are used for file editing.
These are called "file buffers".  The maximum number of files you can edit is
determined by the setting of MaxFiles you are using.  It can be changed by
selecting Max Files (AC-f1).  Typically MaxFiles is 20.

In Uedit, all buffers are general purpose.  But there are reasons for having
a MaxFiles setting:  It provides a toggle range, so that you can rotate among
files without having to scan through all buffers.  It establishes an upper
limit so that files are not loaded into buffers that are used for special
purposes in commands in the config you are using.  (File buffers may be used
in commands too, but by convention they rarely are.)

Higher-numbered buffers (MaxFiles and above, typically buf20 to buf99) may be
called "work buffers", and they are used by commands in the config.  They may
contain search & replace text, copy/cut/paste text, scratch deletes, and so
on.  You can examine them using Edit Buffer (SA-f6) or See Buffers (SC-f6).

The lowest file buffer is the "home" buffer.  When you close curFile, Uedit
returns "home" to the lowest buffer that is in use; usually this is buffer 0.
When you load in a file or select New File, Uedit uses the lowest file buffer
number that is available.

Uedit insists that at least one file buffer be open at all times.  If you
close the last file buffer, it opens a NoName buffer.  If a NoName file
exists in the current directory, NoName is loaded automatically when you
close the last file buffer.

At any given time, most buffers are empty and do not exist.  They are created
as needed by the commands that you use, such as inputting a search string or
the name of a file to load in.

Here are the buffer conventions used in the standard configuration:
(NOTE:  The max files setting can be as high as 36 without touching any
buffers that are in use.)

buf65-99 = available for user commands
    (the buf99 buffer stack is used for scratch stacking, but the variable
    buf99 is not in use anywhere)
buf50-59 = used for temporary purposes in commands
buf0-35  = used for loading files

buf36 = holds REXXCOMM File for Rexx interface
buf37 = copied columnar data
buf38 = directory names
buf39 = used for result of AmigaDOS commands (if result selected)
buf40 = used for AmigaDOS commands
buf41 = used in buffer swapping command, ctl-w
buf42 = holds Help, if loaded
buf43 = document names
buf44 = make-command buffer
buf45 = holds scratch deletes for Undo, keypad-0
buf46 = copied invert
buf47 = copied hilite
buf48 = replace string
buf49 = search or grep string
buf60 = names of bookmarks
buf61 = Rexx msg/reply input buffer
buf62 = Rexx msg/reply output buffer
buf63 = hyper text filename
buf64 = hyper text tablename

This buffer convention is not sacred.  All buffers are general purpose.  You
may customize the standard config or create a custom config and use any
buffer convention.

You may use Edit Buffer (SA-f6) to examine and modify buffers freely.
Sometimes it is more convenient to "hand edit" a buffer using Edit Buffer
than it is to input the buffer's contents using a command that uses Primitive
Mode.  Example:  When you select Set Replace (f8) to input a replace string
to use in search & replace operations, it puts you into Primitive Mode.  In
Primitive Mode, you cannot use editing commands, so you cannot paste in the
replace-text.  But using Edit Buffer, you can edit the Replace buffer (buffer
48) and paste in the replace-text.

Saving memory:  It is good practice to select Free Buffers (A-f3) now and
then, when the buffers are not holding anything that you need to keep.
Sometimes you may experience a memory shortage without realizing that a
buffer is holding a huge block of text that you used in a cut & paste
operation earlier and forgot to free up when you were through with it.

1.20.1 Edit Buffer (SA-f6)

SA-f6 asks for a buffer number that you wish to edit.  Enter the buffer
number, 0 to 99, followed by ESC.  The buffer becomes curFile.

1.20.2 See Buffers (SC-f6)

SC-f6 steps through all work buffers which have something in them, as you
press F1.  Pressing F2 quits the command, leaving the buffer in the window so
that you can edit it.  Pressing F3 quits the command, returning you to the
home buffer (usually buffer 0).

1.20.3 Free a Buffer (A-f)

A-f asks for a buffer number.  Enter the buffer number (0-99) and press ESC.
The buffer is freed, if it exists.

1.20.4 Free Buffers (A-f3)

A-f3 frees all work buffers which exist.  This erases all cut or copied
hilite text, scratch deletes, etc, that are currently in the work buffers.
Use A-f3 when you need to recover all the memory that you can.

Note:  Free buffers does not free any buffers that you may have pushed onto
buffer stack 99 using Push Buffer (L-w).  These can only be freed by popping
them off the stack first using Pop Buffer (R-w) or quitting Uedit.

1.20.5 Swap with Buf41 (C-w)

C-w swaps curFile with buffer 41.  Pressing C-w again reverses the swap.
(See Editing Tricks, 2.7, for examples of why this is useful.)

1.20.5.1 Compare with Buf41 (R-7)

R-7 compares the contents of curFile with that of buffer 41, starting from
the cursor forward in each buffer.  The comparison stops when disagreement is
found or end-of-file is reached.  If cursor is left at the stopping place in
each buffer.  When disagreement is found, the start-of-page in both buffers
is at the cursor's line and the two buffers are flash-displayed 2 times.  To
continue the buffer comparison, put the cursor's at the beginning of text
that is in agreement and press R-7 again.  (See Swap with Buf41 (C-w) above.)

1.20.6 Swap to Buffer 0 (A-w)

A-w swaps curFile with buffer 0, making curFile the "home" (0) buffer.  When
a particular buffer is central to the work you are doing, swap it to buffer 0
for convenience.

1.20.7 Buffer Stack

When buffer N is pushed onto a buffer stack, it is no longer accessible using
Edit Buffer or any buffer-accessing command (except Pop Buffer (R-w)).  The
buffer-N slot is now available and a new buffer N may be created.  Any buffer
may be pushed onto the stack.  Buffers may be popped off the stack into any
buffer number slot.

Uedit's buffer stacks are LIFO, "last in, first out."  The following commands
all use buffer stack 99, and the entries of stack 99 may be rotated using
Roll Stack (SA-w).

Buffers are popped off the stack using Pop Buffer (R-w) and may either free
and replace curFile or occupy a new file-buffer slot.

When you quit Uedit, if any buffer stack is not empty, Uedit asks whether it
is okay to throw away the buffer stack.  If you respond No, Uedit will not
quit and it returns you to editing mode.

Buffer stacking uses only 8 additional bytes for each buffer that is pushed
onto a stack.  When you use any buffer-stack command, the message line
reports the number of buffers that are on stack 99.

1.20.8 Push Buffer onto Stack (L-w)

L-w pushes curFile onto buffer stack 99.  If it is the only file buffer in
use, a NoName buffer is opened.

1.20.9 Pop Buffer from Stack (R-w)

R-w asks whether it may delete curFile.  If you answer No, it pops stack 99
into a new file-buffer slot, if one is available; if all file-buffer slots
are in use, it does nothing.  If you answer Yes, it deletes curFile and pops
the stack buffer into curFile's buffer-number slot.  If no buffers are on the
stack, it reports "Buffer stack is empty".

1.20.10 Roll Buffer Stack (SA-w)

SA-w rolls buffer stack 99 so that the bottom buffer is moved to the top.
That is, instead of being the next one that would be popped off, it becomes
the last one that would be popped off.

1.21 Search

Searching uses the following:

1.  One or two search strings, each up to 63 characters in length.

2.  If two search strings are used, they are delimited by the eitherOr
delimiter "$".  Example:  Smith$Jones

3.  Optional single-character "?" and multi-character "*" wildcards in each
of the above strings.  Example:  Sm?th*$Jones

4.  An optional "all-but" string, up to 63 characters in length and delimited
by the allBut delimiter "~".  If an all-but string is used, searching skips
over any matches to it.  Example: Sm?th*$Jones~Smythe

5.  To include an allBut or eitherOr delimiter or wildcard in a search string
literally, precede it with a backslash.  Example:  /\* matches /*

6.  SingleWhite and multiWhite variables determine how the single and multi
wildcards are treated in the search.  If these have value 0, no whitespace is
accepted as a "match" to the wildcard.  If they have value 1, spaces and tabs
are accepted as a match to the wildcard.  If they have value 2, any
whitespace, including eols and formfeeds, is accepted as a match to the
wildcard.

7.  Case sensitivity, On or Off.  (Select Global Modes (C-g) and see whether
searchCaps is On or Off.)

8.  Incremental searching, On or Off.  (Select Global Modes (C-g) and see
whether incremSearch is On or Off.)

The delimiters, wildcards, and singleWhite and multiWhite values are defined
in the config defaults and may be modified using the Search menu.  The
current values of these may be seen by using Show Vals (S-Help).

All search strings, including the all-but string, may use wildcards.  When
Case Sensitive is checkmarked in the menu, searching is case-sensitive.  When
it is not checkmarked, searching ignores upper/lower case.

Forward searching is faster when case sensitivity is used (searchCaps is On)
and when wildcards and the either-or delimiter are not used - i.e., using a
"simple" search string.  Using an all-but string does not affect search speed
measurably, unless many "finds" have to be rejected on account of it.

When searching succeeds, it does the following:  It puts the cursor at the
beginning of the "matched" region.  It makes the matched region a colored
invert region, to emphasize it.  It scrolls the text, if necessary, in order
to show the cursor and matched region in the window.  When doing search &
replace, the inverted region is deleted and the replace text is inserted.
(See Replace, 1.22.)  If searching fails, a "Search failed" message is
displayed.

Incremental searching (the default option) actually begins the instant you
type in the first character of the search string.

(Also see Grep, 1.48.)'

1.21.1 Input Search Text and Search Forward (f7)

F7 solicits a search string input.  If incremental searching is On, searching
begins when you type in the first letter of the search string.  At any time
you can change the direction (forward/backward) of the search using the down/
up arrow keys (or alternatively using f9/S-f9).  Case-sensitivity is normally
Off, but if you type a capital letter it is turned On automatically.  If you
are satisfied with the search, press ESC or click the mouse to end the search
string input.  If you want to abandon the search, press backspace until the
search string is deleted and then press ESC; this restores the cursor to its
original position.

If incremental searching is Off, after pressing F7 merely type in the search
string and press ESC or click the mouse in order to cause the search to occur.

1.21.2 Modify Search Text and Search Forward (S-f7)

S-f7 behaves exactly the same as F7, except the old content of the search
buffer (buffer 49) is not erased; thus, you can modify the existing search
string.

1.21.3 Search Forward (f9)

F9 searches forward using the existing search string(s) that you input
earlier.  If it reaches end-of-file without getting a hit, a "Search failed"
message is displayed.

1.21.4 Search Backward (S-f9)

S-f9 behaves exactly the same as F9, except it searches in the backward
direction.  If it reaches start-of-file without getting a hit, a "Search
failed" message is displayed.

1.21.5 Global Search Forward (A-f9)

A-f9 searches for a match to the current search string(s) starting from the
cursor's position in curFile until end of file and continues through all file
buffers, until it finds a match or fails.

1.21.6 Change Search Wildcards (A-f7)

A-f7 asks, one at a time, for the single wildcard, the multi wildcard, the
singleWhite value, the multiWhite value, and the all-but delimiter.  The
config defaults define the single wildcard as "?", the multiWild as "*",
singleWhite and multiWhite as 0, and the all-but delimiter (allBut) as "~".
If singleWhite and multiWhite are 0, no whitespace is allowed as a "hit"
underneath the wildcards in the search.  If these are 1, spaces and tabs are
allowed as a hit under the wildcards.  If these are 2, any whitespace is
allowed as a hit under the wildcards.

1.21.7 Change Search Either-Or Delimiter (C-f7)

C-f7 asks for the new eitherOr delimiter to use in delimiting two search
strings.  The next character that you type becomes the new eitherOr delimiter.

1.22 Replace

A successful Search marks the "matched" area as a colored invert region.  The
replace commands below require the existence of a colored invert region.  If
there is no invert region, the replace commands do nothing.  Replace strings
may be of any size up to 8 megabytes.  (See Search, 1.21.)

1.22.1 Input Replace Text (f8)

F8 solicits a replace string using Primitive Mode.  Existing text in the
replace buffer (buffer 48) is erased.  When finished inputting the replace
text, press ESC.

1.22.2 Modify Replace Text (S-f8)

S-f8 is identical to F8 except that the existing replace text is not erased.

1.22.3 Replace and Search Forward (f10)

F10 replaces the invert region with the replace text and continues the search
forward.  If no invert region exists, nothing happens.  (See Search, 1.21.)

1.22.4 Replace and Global Search Forward (C-f10)

C-f10 replaces the invert region with the replace text and continues the
global search forward.

1.22.5 Replace and Search Backward (S-f10)

S-F10 is identical to F10, except it continues a backward search after the
replace.

1.22.6 Replace All (A-f10)

A-f10 works the same as F10 except it keeps searching and replacing until
end-of-file is reached.  When eof is reached, a "Search failed" message is
displayed.

1.22.7 Replace All Globally (SA-f10)

SA-f10 works the same as A-f10 except it keeps searching and replacing until
all files have been searched and the cursor has returned to curFile once
again.

1.23 Refresh (SC-Help)

SC-Help refreshes the display.  It is not needed in normal circumstances, but
when creating learned sequences which are "played back" like a tape
recording, Uedit may not update the display until the learned sequence has
played out.  By including a Refresh at selected points in the learned
sequence, you can cause the display to be updated at critical points as you'd
like.

1.24 Do Menus (SAC-Help)

SAC-Help rebuilds the menus by running the startup command.  Use it after you
have changed fonts, so that the menus conform to the new font regime.  If you
kill a command that's in a menu, after using SAC-Help its menu entry will no
longer appear.  (See Kill Key (SAC-f6), 1.38.1.)  Similarly, if you create a
command for a currently invisible menu selection, the selection does not
appear until the menus have been rebuilt.  SAC-Help rebuilds the menus so
that only existing commands are shown in the menus.  (See Customizing the
Menus, 2.17.)

1.25 Scratch Deletes and Undo Deletes

Scratch deletes are deletes that are performed with the keypad 7 & 9 or with
C-d, the Delete Line key.  Scratch deletes accumulate in the Undo buffer
(buffer 45) as long as you keep deleting without moving the cursor.  Then you
can move the cursor elsewhere and press the Undo key (kp0), inserting the
deleted text at a new location.

When you move the cursor elsewhere and do another scratch delete, the Undo
buffer is freed before the new delete is stored in it.  This makes scratch
deleting and Undo the handiest way to cut or copy words and lines of text and
paste them at a new location.  Scratch deleting and Undo should be used as
the method of choice for moving text and correcting mistakes.

The unshifted delete keys, kp7 and kp9, work at word level rather than
character level in order to suit fast typists.  Fast typists can delete the
preceding word and type it back in correctly faster than they can position
the cursor, correct a mistake, and reposition the cursor.  Slower typists may
want to swap the unshifted keypad keys to the Shift position.  (See Swap
Keys, 1.38.3.)

1.25.1 Undo Scratch Deletes (kp0)

kp0 inserts the text in the scratch delete Undo buffer (buffer 45) at the
cursor.

1.25.2 Delete Line (C-d)

C-d deletes the cursor line, including the end-of-line character, and stores
it in the Undo buffer.

1.25.3 Delete Character Left (S-kp7)

S-kp7 deletes the character to the left of the cursor, storing it in the Undo
buffer.

1.25.4 Delete Cursor Character (S-kp9)

S-kp9 deletes the character under the cursor, storing it in the Undo buffer.

1.25.5 Delete Word Left (kp7)

kp7 deletes word-left, storing it in the Undo buffer.

1.25.6 Delete Word Right (kp9)

kp9 deletes word-right, storing it in the Undo buffer.

1.25.7 Delete to Start-of-Line (A-kp7)

A-kp7 deletes to start-of-line, storing it in the Undo buffer.

1.25.8 Delete to End-of-Line (A-kp9)

A-kp9 deletes to end-of-line, storing it in the Undo buffer.

1.25.9 Delete to Start-of-Page (C-kp7)

C-kp7 deletes to the top of the window, storing it in the Undo buffer.

1.25.10 Delete to End-of-Page (C-kp9)

C-kp9 deletes to the bottom of the window, storing it in the Undo buffer.

1.25.11 Delete Line Above Cursor (C-del)

C-del deletes the line above the cursor line, storing it in the Undo buffer.
Note that while this delete is stored in the Undo buffer and can be undone,
it is not a contiguous delete relative to the cursor location as the other
scratch deletes discussed previously are, because the cursor can be anywhere
in the line below the line that is deleted.  Before Undoing this delete, put
the cursor at the start of its current line; do not leave it in the middle of
the line.  You should not include C-del deletes along with contiguous scratch
deletes and expect Undo to restore the text in its proper order.

1.25.12 Delete Line Below Cursor (C-bs)

C-bs (C-backspace) deletes the line below the cursor.  Again, this is not a
contiguous delete relative to the cursor position.  Before Undoing this
delete, put the cursor at the end of the current line; do not leave it in the
middle of the line.  (See discussion in C-del above.)

1.26 Tabs and Tab Rulers

When you select See Ruler (SA-tab) or Set Ruler (SC-tab), curFile's tab ruler
is displayed.  There are 5 tab rulers, numbered 0 to 4.  Buffers may use any
of the 5 tab rulers.  If you adjust the tab stops in a given tab ruler, it
affects the display of all buffers that are using the same tab ruler.

When you type in a tab, if Use Tabs (AC-tab) in the Local Modes menu is
checkmarked, a true tab character (ASCII 9) is input.  If Use Tabs is turned
Off, when you type a tab spaces (ASCII 32) are inserted up to the next tab
stop.

If you are using autoIndent typing mode and Use Tabs is On, when you press
Return or the line word-wraps, true tab characters are used in creating the
auto-indentation.  If Use Tabs is Off, the indentation, if any, is made up of
spaces.

When See Ruler or Set Ruler is used, the tab ruler is drawn just above the
cursor line.  If the cursor is not in the window, the ruler is drawn at the
top of the window.  The ruler's number (0 to 4) is shown in the top left
corner of the ruler.  Tab rulers may have up to 32 tab stops in columns 2
through 255.

Normally tab characters are invisible like spaces are.  When you put the
cursor on a tab character, the cursor is as wide as the column-width of the
tab-spacing.  If there are tabs in the text which fall beyond the last tab-
stop in the current ruler, the tabs are displayed as box characters 1 column
wide.  Uedit does not know how wide the tab-spacing should be when the tab is
beyond the last stop; you may add more tab stops by using Set Ruler.

When typing, if you keep pressing the Tab key, when the cursor reaches the
last tab stop, the next Tab you type puts the cursor at the first tab stop on
the next line.  This facilitates typing columns of material.  (AutoIndent
typing mode is also helpful in typing columns of material.)

When using columnar display mode, tabs are shown as box characters to
facilitate columnar text handling.  Uedit cannot predict what the tab stops
might be at some new location you might move the text to, so the only safe
way to display tabs in columnar display mode is to show them as being 1
column wide.  Showing them as box characters also alerts you that once you
have made the columnar data movement, randomly scattered tabs could destroy
the columnar alignment and it might be a good idea to replace the tabs with
spaces before moving the columnar text.  (See Columnar, 1.40.)

1.26.1 Use Tabs (AC-tab)

AC-tab toggles the useTabs setting for curFile.  If Use Tabs is On in the
Local Modes menu, true tab characters are inserted when you press the Tab
key; if Use Tabs is Off, spaces are inserted up to the next tab stop in the
curFile's tab ruler.

1.26.2 Tab (TAB)

The Tab key types in a true tab character at the cursor, when Use Tabs is On.
When Use Tabs is Off, Tab inserts spaces up to the next tab stop in the
curFile's tab ruler.

1.26.3 See Ruler (SA-tab)

SA-tab displays curFile's tab ruler above the cursor line.  If the cursor is
offscreen, it displays the tab ruler near the top of the window.  To scroll
the tab ruler leftward, to see tab stops beyond the right edge of the window,
hold down the mouse button, drag the mouse to the left, and release the
button.  To scroll rightward, drag the mouse to the right.  To terminate,
give any input; note that the input is used, not thrown away.  This is to
allow you to place the cursor in a column by looking at the tab ruler.

1.26.4 Set Ruler (SC-tab)

SC-tab displays curFile's tab ruler and allows you to set tab stops in the
ruler.  To scroll the tab ruler leftward, hold the mouse button and drag the
mouse to the left.  To scroll rightward, drag the mouse to the right.
Clicking the mouse 2 or more lines above or below the ruler terminates the
ruler adjustments.

To erase a tab stop in the ruler, click the mouse on top of it.  To add new
tab stops, click the mouse in the desired columns.  The last tab stop in the
ruler has an "X" in it.

The DEL key erases all tab stops in the ruler.  The BACKSPACE key shifts all
tab stops to the left.  The SPACE bar shifts all tab stops to the right.  The
TAB key puts in a new tab stop, shifting all tab stops to the right, using
the same spacing as the first tab stop in the ruler.  Thus, if the first tab
stop is in column 5, the Tab key slides all tab stops rightward 4 columns,
putting a new tab stop in column 5.

To save changes made in the tab ruler, click the mouse 2 or more lines above
or below the ruler, or press a key that isn't used in setting tabs.  This
updates the tab ruler.  To throw away changes made in the tab ruler, abort
with Amiga-ESC.

1.26.5 Set Tab Ruler Number (SAC-tab)

SAC-tab asks for the new tab ruler number to use for curFile.  It must be a
number between 0 and 4.

1.26.6 Tabs To Spaces (L-t)

L-t converts all tabs in curFile to spaces.  A "Tab->space" message is
displayed during the conversion.  Converting tabs to spaces may run out of
memory on large files.  If it does, a "Memory...."  message appears while
memory housekeeping is being done.  When conversion resumes, the "Tab->space"
message is redisplayed.

1.26.7 Spaces To Tabs (R-t)

R-t converts spaces in curFile to tab characters wherever spaces happen to
fall upon a tab stop in curFile's tab ruler.  During the conversion, a
"Space->tab" message is displayed.  (See Smart Tabs in the Config! defaults.)

1.26.8 Transparent Tab Forward (S-tab)

S-tab advances the cursor to the next tab stop.  Nothing is typed in.  In
transparent tabbing, column 1 is considered to be a tab stop.  Thus when the
cursor reaches the last tab stop in the current line, it moves to column 1 of
the next line.

1.26.9 Transparent Tab Backward (A-tab)

A-tab moves the cursor backward to the previous tab stop.  Nothing is typed
in or deleted.  Column 1 is considered to be a tab stop in transparent
tabbing.  Thus when the cursor reaches the first tab stop in the line, the
next place it stops is column 1, before moving backward to the last tab stop
in the previous line.

1.26.10 Untab (C-tab)

C-tab deletes white space back to the previous tab column.  Column 1 is
considered to be a tab column in untabbing, so if the cursor is positioned on
or before the first tab stop, white space is deleted to the start of the
line.  C-tab functions as a transparent back-tab when there is no white space
to delete.

1.27 Eol

Text files use different end-of-line characters, depending on where they were
last edited.  The standard config presets the eol to a linefeed (ASCII 10).
Uedit does not alter the eol of files that are loaded in, unless the user
does it purposely.

If a file's eol is not the same as Uedit is currently using, the file is
displayed All On One Line!  The non-standard eols appear as odd looking "box"
characters.

In that event, there are two choices:  You can change Uedit's eol to the one
that the file is using.  This makes the file display correctly, but it makes
all other buffers in Uedit display All On One Line.  Or you can change the
eols in the file to Uedit's current eol character.

First you must find out what the non-standard eols actually are.  Put the
cursor on top of one of the "box" characters and press C-/.  The message line
displays the ASCII value of box character.  Next, use one of the following
two commands.

1.27.1 Change Default Eol (A-e)

Alt-e changes Uedit's current eol.  It does not alter the text in the buffer.
It asks for the ASCII value (normally 10 or 13) of the new eol you wish to
use.  (The default eol in the standard config is the linefeed, ASCII 10).
Type in 10 (lf) or 13 (cr) for the new eol and press ESC.

Note that after changing the default eol, buffers that are not using the new
eol will display All On One Line.  The only line terminators in those buffers
will be formfeeds, if any formfeeds are present.

1.27.2 Change Default Eol and Eols in Text (C-e)

C-e changes both Uedit's default eol and the eols in curFile.  Most of the
time, you will use C-e to convert non-standard eols in files to Uedit's
current eol.  C-e asks first for the ASCII value of the non-standard eols in
the text, so that it can find and convert them.  To find out what they are,
put the cursor on one of the box characters and press C-/.  Then type in
their ASCII value and press ESC.

Next it asks for the ASCII value of the new eol to convert to.  Here you
would typically just type in the current eol value (10) and press ESC.  Then
it searches curFile, changing non-standard eols to the (possibly new) current
eol.

Example:  If you load in a file that uses carriage returns (ASCII 13) as
eols, the file displays all on one line.  Press C-e and answer 13 in response
to the first question and 10 in response to the second question.  C-e
converts the carriage returns (13) to linefeeds (10).  It does not change
Uedit's current eol (10), so other buffers will still display correctly.

CR-LF:  If you require an eol that is both carriage return and linefeed, you
can install the carriage returns in several ways.  One method is to use
search and replace.  Another is to use Learn Mode and C-c.  Another is to
write a simple command that inserts the carriage returns.  Still another is
to insert the carriage returns by hand using C-c.  (See Learn Mode, 1.35, and
Embed Control Character, 1.32.10.)

1.28 Miscellaneous Commands

The following are miscellaneous commands.

1.28.2 Cycle Counter (SA-c)

SA-c counts the number of successful executions of the next function key that
you press.  Example:  Typing SA-c and F9 (to search forward) causes
continuous searching until search fails.  The message line then reports the
number of successful searches.

Another useful example is counting the number of words in a file:  Press SA-c
and then kp6 (Cursor Word Right).  This counts the number of words in curFile
from the cursor to eof.  Using kp2 or A-kp6, instead of kp6, would count the
number of lines to eof.

1.28.3 Command Multiplier (C-m)

C-m asks for the command multiplier value.  Type in a number followed by ESC.
Then the next input you give is multiplied using the command multiplier.
Command multiplier is often used to run learned sequences multiple times, but
it has many other uses.  If you give a very large number and it takes too
long to run out, press Amiga-ESC to abort the multiple executions.

1.28.4 Speak Hilite (A-s)

A-s speaks the hilited region using the SPEAK: device.  The SPEAK: device
must be mounted in order for speaking to work.  (See AmigaDOS, 1.14.)

1.28.5 Name Gadget (C-esc)

C-esc asks for the number (1-4) of a gadget to be named.  Then it asks for
the new gadget name.  Type in the name and ESC.  Gadget names may be up to 19
characters in length.  Use Mark Gadgets (C-g) to turn on/off the gadget names
and markings in the message line.

1.28.6 Set Idle Time (SAC-i)

SAC-i asks for the interval, in tenths of a second, to set idleTime to.
idleTime determines how soon after each pause the Idle command is run.  The
default idleTime is 10 seconds (100 tenths of a second).  If you have
selected Save On Idle (C-f2) for certain files, after a 10 second pause the
changed files are saved to disk.  (See Idle Key and Idle Time, 2.18.)

1.28.7 See Number Variable (A-8)

A-8 asks for the number (0-99) of the number variable you wish to examine.
It displays the value stored in that number variable.  (See Integer Variables
N0 to N99, 2.22)

The number variable usage in the standard configuration is as follows:

n31-n99 = available for use commands
    (the n99 number stack is used for scratch stacking, but the variable n99
    is not in use anywhere)
n0-n19 = scratch variables, used everywhere for temporary purposes

n20 = delay time
n21 = arithmetic total
n22 = #cycles in cycle counter
n23 = macroNum to be run in cycle counter
n24 = split window size for hyper text
n25 = hyper word index value
n26 = used by REXX
n27 = REXX action/result
n28 = REXX flag
n29 = REXX return code
n30 = bookmark number

1.28.8 Set Number Variable (A-9)

A-9 asks for the number (0-99) of the number variable to be set.  Type in the
number (0-99) and ESC.  Next it asks for the value to store in the number
variable.  Type in the value and press ESC.  (See Integer Variables N0 to
N99, 2.22)

1.28.9 About... (SAC-a)

SAC-a displays Uedit's About... message.

1.28.10 Delay (A-d)

A-d causes a delay of n46 tenths of a second, where the value stored in n46
is set using Set Delay (SA-d) below.  Delays may be used in learned sequences
to create desired results, such as preventing printer buffer overflow due to
serial-line handshaking problems or slowing down display updates.  Delays are
also helpful in debugging complicated commands and learned sequences.

1.28.11 Set Delay (SA-d)

SA-d asks for the delay interval, in tenths of a second, to store in n46.
Type in the value and press ESC.  n46 determines how long the Delay (A-d)
command will delay.

1.28.12 Toggle Hex/Decimal (C-x)

C-x toggles the number under the cursor between decimal and hexadecimal
integer format.  This is useful to programmers.

1.28.13 Show ASCII (C-/)

C-/ displays the ASCII value of the character under the cursor and advances
the cursor to the next character.

1.28.14 Goto Line N (C-n)

C-n asks for the line number in the text to go to.  This is useful to
programmers.

1.28.15 Line Sort (SA-s)

SA-s sorts the lines in the current buffer alphabetically.

1.28.16 Init Marks(S-gadget4)

S-gadget4 initializes the 8 bookmarks for curFile to the following locations:
start of file, end of file, start of hilite, end of hilite, start of invert,
end of invert, locA, and locB.  (See Locations and Regions, 2.12.)

1.28.17 Goto Mark (S-gadget1)

S-gadget1 displays the 8 bookmark selections in the title bar and lets you
click the bookmark you wish to go to; you may also press F1-F8 to select the
bookmark.  Press any other key or click below the message line, if you don't
wish to make a selection.

1.28.18 Goto Next Mark (S-gadget2)

S-gadget2 moves the cursor to the next bookmark.  This is useful for browsing.

1.28.19 Set Mark (S-gadget3)

S-gadget3 lets you rename a bookmark and make it point to the cursor's
present location.  It displays the 8 bookmark names.  Click the bookmark name
you wish to edit and move the location of.  Press ESC or click the mouse when
finished.  The bookmark now points to the cursor's present location.

1.29 Hilite and Invert Regions

In the standard config, there are 4 ways of doing cut & paste operations
using the commands provided.  (There could be many more ways, using the CL.)
Most of the time you will do cut & paste using scratch deletes and Undo at
the cursor.  For large regions, you will probably do cut & paste using hilite
or invert colored regions.  And you can do columnar-text cut & paste using
columnar display mode and a hilite region.  (See Scratch Deletes and Undo
Deletes, 1.25.  See Columnar, 1.40.)

Hilite and invert regions use distinct colors, based on the color combination
you are using.  If you are using a 1-bitplane screen, which allows only 2
colors, hilite and invert regions are both displayed in inverse video and are
indistinguishable.  (See Color Combinations (A-Help), 1.30.6.  See Display
Modes, 1.39.)

For a hilite or invert region to exist, the end of the region must come after
the start of the region.  If the locations are equal or the ending location
comes first, no region exists.  When a region is defined, the starting
location is included in the region, but the ending location is the first
character just after the region.  Example:  To hilite a word, mark the first
letter in the word as the start-of-hilite.  Mark the first character after
the word as the end-of-hilite.

If columnar display mode is On, hilite and invert regions are displayed as
rectangular in shape.  You cannot do the regular cut & paste operations
described here, if columnar display mode is On.  To use what is described
here, turn Off columnar display mode.  Also when columnar display mode is On,
non-columnar hilite or invert regions may not be visible, even though they do
exist; this is because for columnar display mode to display a region, the end
of the region must be in a higher column than the start of the region.  (See
Columnar, 1.40.)

Hilite and invert regions may be defined using the mouse or the keypad keys.
When a hilite region is copied, the copy is stored in buffer 47.  (Copied
columnar hilite regions are stored in buffer 37.)  Copied invert regions are
stored in buffer 46.  The contents of these buffers may be monitored
continuously by displaying them in split windows.  (See Split Windows, 1.42.)

1.29.1 Set Start-of-Hilite (S-buttonDown)

Position the mouse cursor in the text where the start-of-hilite is to be.
Press the Shift key and click the left mouse button.

1.29.2 Set End-of-Hilite (A-buttonDown)

Position the mouse cursor in the text where the end-of-hilite is to be.
Press the Alt key and click the left mouse button.

1.29.3 Drag Mouse for Hilite (SAC-buttonDown)

Position the mouse cursor where either end of hilite is to be.  Press Shift,
Alt, and Ctrl.  Press the left mouse button and drag the mouse to the other
end of the desired hilite region.  Release the button.

1.29.4 Set Start-of-Invert (SC-buttonDown)

Position the mouse cursor where the start-of-invert is to be.  Press Shift
and Ctrl and click the left mouse button.

1.29.5 Set End-of-Invert (AC-buttonDown)

Position the mouse cursor where the end-of-invert is to be.  Press Alt and
Ctrl and click the left mouse button.

1.29.6 Set Start-of-Hilite at Cursor (kp1)

Kp1, S-kp1, and A-kp1 each set the start-of-hilite at the cursor location.

1.29.7 Set End-of-Hilite at Cursor (kp3)

Kp3, S-kp3, and A-kp3 each set the end-of-hilite at the cursor location.

1.29.8 Set Start-of-Invert at Cursor (C-kp1)

C-kp1 sets the start-of-invert at the cursor location.

1.29.9 Set End-of-Invert at Cursor (C-kp3)

C-kp3 sets the end-of-invert at the cursor location.

1.29.10 Uncolor Hilite (A-h)

A-h uncolors the hilite region by making the start and end locations equal.
Afterward, no region exists.

1.29.11 Uninvert (A-i)

A-i uncolors the invert region by making the start and end locations equal.
Afterward, no region exists.

1.29.12 Clear Hilite (C-h)

C-h deletes the hilite region.  No copy is made!

1.29.13 Clear Invert (C-i)

C-i deletes the invert region.  No copy is made!

1.29.14 Copy Hilite (kpDot)

kpDot, S-kpDot, and A-kpDot store a copy of the hilite region.  If no region
exists, nothing is done.

If columnar display mode is Off, the region is stored in buffer 47.  If
columnar display mode is On, the rectangular (columnar) region is stored in
buffer 37.  Thus, kpDot, kpMinus, and kpEnter handle copy/cut/paste for
either normal or columnar hilite regions, depending on the setting of
columnar display mode.

1.29.15 Cut Hilite (kpMinus)

kpMinus, S-kpMinus, and A-kpMinus copy and then delete the hilite region.  If
no region exists, nothing is done.

The discussion above for kpDot also applies to kpMinus:  If columnar display
mode is Off, kpMinus cuts the non-columnar hilite region and stores it in
buffer 47.  If columnar display mode is On, kpMinus cuts a columnar region,
if a columnar region exists, and the copy is stored in the columnar buffer
(buffer 37).  Thus kpMinus serves a dual purpose which depends on the setting
of columnar display mode.

1.29.16 Paste Hilite (kpEnter)

kpEnter, S-kpEnter, and A-kpEnter insert the copied hilite region at the
cursor.  After the region is inserted, it is hilited.  Thus it can be removed
by pressing kpMinus (cut) or C-h (clear).

The discussion above for kpDot and kpMinus also applies to kpEnter:  If
columnar display mode is Off, the non-columnar copied hilite in buffer 47 is
inserted at the cursor.  If columnar display mode is On, kpEnter inserts the
contents of the columnar buffer (buffer 37).

1.29.17 Shift Hilite Right (A-r)

A-r shifts the hilite region to the right by one space.

1.29.18 Shift Hilite Left (A-l)

A-l shifts the hilite region left by one space.

1.29.19 Copy Invert (C-kpDot)

C-kpDot stores a copy of the invert region in buffer 46.  If columnar display
mode is On, no copy is made and a requester asks you to turn Off columnar
display mode.

1.29.20 Cut Invert (C-kpMinus)

C-kpMinus copies and then deletes the invert region.  If columnar display
mode is On, no action is taken and a requester asks you to turn Off columnar
display mode.

1.29.21 Paste Invert (C-kpEnter)

C-kpEnter inserts the copied invert buffer (buffer 46) at the cursor.  After
the insertion, the text is inverse-displayed and can be removed by pressing
C-kpMinus (cut) or C-i (clear).  If columnar display mode is On, no action is
taken and a requester asks you to turn Off columnar display mode.

1.30 Local Values

The global values used by Uedit, such as lineLength and Colors, are set
initially using the config defaults when you compile the config or compile
just the config defaults, and they are stored in the data file.  (See the
Config! file.)

The following global values have counterparts which are local to each buffer
in Uedit, so that each buffer can use its own values for these:  lineLength,
pageLines (lines per page), leftMargin, topMargin, bottomMargin, and tabTable
(tab ruler number, 0-4).

Most of the above local values can be set using the Line-Page menu.  To see
the current local values, select Show Vals (S-Help).  For the initial
settings of global numerical values, see the defaults in Config!.  (Also see
the CL argument lists in 3.1.)

When a local value is changed, it does not change the corresponding global
value.  For example, when lineLength is set to 70 in curFile, new files
loaded in and new buffers created will not inherit the lineLength of 70.  To
change the global values inherited by new files loaded in and new buffers,
edit the defaults in the Config! file.

Technical note:  topMargin and bottomMargin are not used internally by Uedit.
Any use of them is strictly by the customizable commands in the config.
Other local and global variables like lineLength, pageLines, and leftMargin
are used internally, however.  See the discussions below.

Technical note:  Whether the corresponding global value is changed or not
when the local value is changed depends on how the customizable commands are
written.  The setLocal() CL function changes only the local value, such as
the local lineLength.  To change the global lineLength, the global variable
lineLength must be given a new value.  This is unlike the case for local
flags, where if you toggle a local flag such as wordWrap using flipFlag(), it
also toggles the corresponding global flag.  However, changing a local flag
by clicking its flag-letter in the title bar does not change the
corresponding global flag.  (See Local Modes, 1.30.  See Local and Global
Integer and Flag Variables, 2.23.)

1.30.1 LineLength (C-Return)

C-Return asks for the new lineLength value for curFile to use.  Type in the
lineLength (1 to 9999 characters per line) and press ESC.  The lineLength
determines when word-wrapping is to occur and is used in paragraph
reformatting and in right-justification.  If lineLength is set too high, the
window jerks, as you type long lines, in order to keep the cursor visible.
By increasing the pixel-width of the Workbench screen, you can display longer
lines.  (See WordWrap, RightJustify, and Reformat Paragraph in 1.31.)

1.30.2 PageLines (A-g)

A-g asks for the new lines-per-page value for curFile to use.  Type in the
pageLines value (typically 66 lines per printed page) and press ESC.
PageLines is used in finding page boundaries when there are no formfeeds to
go by and line-count must be used.  It is used in computing page and row in
the page/row/column display when Row/Column (C-2) is turned On.  It is used
internally in all page-related calculations.

1.30.3 LeftMargin (L-k)

L-k asks for the new leftMargin value for curFile to use.  Type in the
leftMargin value (0 to 255) and press ESC.

When leftMargin is 0, Uedit uses the autoIndent flag if it is On.  When
leftMargin is not 0, Uedit ignores the autoIndent flag and uses leftMargin
instead.

When leftMargin is 0 and autoIndent is On, auto-indenting is used and, after
word-wrapping or if you type Return, the new line gets the same indentation
as the old line.  When leftMargin is not zero, autoIndent is ignored and
leftMargin determines the indentation of the next line; when leftMargin is 1,
the next line gets no indentation.

When trueTabs is On, indentations are created using tab characters up to the
closest tab stop and spaces fill any residual.  When trueTabs is Off,
indentations are created using only spaces.

Paragraph reformatting indents paragraphs using leftMargin, if leftMargin is
non-zero.  If leftMargin is 0 and autoIndent is On, paragraph reformatting
uses autoIndent.  (See Reformat Paragraph, 1.33.1.)

1.30.4 TopMargin (L-u)

L-u asks for the new topMargin value for curFile to use.  Input the new
topMargin value (0 to 255) and press ESC.  TopMargin is used by paging
commands as the number of blank lines to insert after the formfeed when
creating page divisions.  (See Paging, 1.41.)

1.30.5 BottomMargin (L-l)

L-l asks for the new bottomMargin value for curFile to use.  Input the new
bottomMargin value (0 to 255) and press ESC.  BottomMargin is used by paging
commands to determine the number of blank lines to insert before the formfeed
when creating page divisions.  (See Paging, 1.41.)

1.30.6 Colors (A-Help)

There are 16 sets of foreground and background colors, which are used for
displaying normal text, the cursor, hilite and invert regions, etc.  The
following color table appears in the Config! defaults and is displayed when
you use Colors (A-Help):

Colors:  (values must be 0-3, corresponding to RGB color register numbers)
                                fg      bg
    ((local colors for buffers))
    0  normal text              <1>     <0>
    1  cursor                   <1>     <2>
    2  hilite                   <1>     <3>
    3  cursor+hilite            <3>     <1>
    4  inverse                  <0>     <1>
    5  cursor+inverse           <0>     <2>
    6  hilite+inverse           <3>     <1>
    7  cursor+hilite+inverse    <0>     <3>
    ((screen colors))
    8  title bar                <1>     <3>
    9  msg line                 <2>     <0>
    10 menus                    <1>     <3>
    11 tab ruler                <1>     <2>
    12 requester                <1>     <2>
    13 formfeed                 <1>     <2>
    14 spare1                   <0>     <1>
    15 spare2                   <0>     <2>

The color values in the table must be in the range 0 to 3, corresponding to
one of the 4 RGB color register numbers for a 2-bitplane screen.

Each buffer uses its own colors.  When a new file is loaded or a new buffer
is created, it picks up the current color combination, which is the most
recent combination that you have selected.  Different files may use different
color combinations.  When selecting colors, it is helpful to create partially
overlapping hilite and invert regions in the text, so that you can see what
they will look like as you adjust the local colors.  Also, after you change
the menu colors, examine the menus to see their coloring.

When using only a 1-bitplane screen, only 2 colors are available for each
item in the color table.  In that event, Uedit uses colors 0 and 1,
foreground and background, respectively, for normal text and the message
line, and it uses the reverse, colors 1 and 0, for the other 14 items in the
color table.

When satisfactory color settings have been found, the colors can be saved in
the data file by using Save Data (A-f6).

1.30.6.1 Tune RGB (A-esc)

You may use RGB color tuning to adjust each of the 4 color registers, and
this also affects the 2 colors used with 1-bitplane screens.  RGB tuning
affects all screen types.

Alt-esc lets you tune the RGB colors using the unshifted and shifted arrow
keys.  As a color register is modified, the new colors are used and you can
see the results.  ESC or "q" or clicking the left mouse-button ends the RGB
tuning session, and the new colors are used.  Any other key input causes the
original colors to be restored.

When satisfactory RGB colors have been found, the settings can be saved in
the data file by using Save Data (A-f6).  Also you can write down the color
values while using Tune RGB and put them into your config's defaults, so that
they become the standard colors.  The RGB color values currently in Config!
are:  (Note that this may be changed without notice.)

Red     Green   Blue
<0>     <5>     <10>    Register 0
<15>    <15>    <15>    Register 1
<15>    <9>     <0>     Register 2
<0>     <9>     <15>    Register 3

1.30.6.2  Color Sets 1, 2, & 3

In the RGB colors menu are 3 selections for different RGB color settings.
The 3 color settings are assigned to keys which cannot be input from the
keyboard; they must be selected from the menu.  When a different RGB color
setting is selected, it takes effect immediately.

Technical note:  The 3 color settings are assigned to the L-esc, R-esc, and
virtual-esc keys, respectively.  To change the color selections, modify the
setRGB() arguments and recompile the commands in Config!Z.  (See setRGB() in
Part 3.)

1.30.7 TabTable (SAC-tab)

SAC-tab asks for the new tab ruler number for curFile to use.  Input the tab
ruler number (0 to 4) and press ESC.  (See Tabs and Tab Rulers, 1.26.)

1.31 Local Modes

Local modes (flags) are local to each file or buffer.  The Local Modes menu
shows the modes for curFile.  If a mode is On, it is checkmarked in the menu.

Local modes have a corresponding global-flag counterpart.  When a new file is
loaded in, it picks up the current global flags.  The global flags are set
initially in the config defaults.  When a local mode is turned On or Off
during an edit session, its global flag counterpart is set to the same value.
For example, if you turn wordWrap Off, the global wordWrap flag is turned Off
and future files loaded in will not use wordWrap.  You may change the global
flags either by changing the local mode in the Local Modes menu or by
customizing and recompiling the config defaults.  (See the commands discussed
below.  See Compile Config Defaults (AC-f6), 1.37.2.)

Technical note:  The Changed, ReadOnly, Favorite, UserLocalA, and UserLocalB
flags do not have a global-flag counterpart, because they apply strictly to
individual files.  When a file is modified, its Changed flag is automatically
turned On.  When you load a duplicate of a file already in Uedit, its
readOnly flag is turned On automatically.  The Favorite flag enables you to
tag any file as a "favorite" and toggle only through favorites by using the
toggle() CL function.  The userLocal flags are available for custom purposes;
in the standard config the userLocalA flag is used for tagging files to Save
On Idle.  (See Save On Idle (C-f2), 1.31.10.  See the argument lists in 3.1
and the CL functions toggle(), flipFlag(), and getFlag() in 3.4.)

1.31.1 Overstrike (S-f5)

S-f5 toggles On/Off overStrike typing mode in curFile.  When overStrike is
On, typing overstrikes the characters under the cursor until eol is reached.
At eol, it uses insert typing mode until the line wraps (if wordWrap is On)
or you press Return or move the cursor.  (Primitive Mode ignores the
overStrike flag and uses insert mode only.  See Primitive Mode, 1.7.)

1.31.2 WordWrap (C-f5)

C-f5 toggles On/Off wordWrap typing mode in curFile.  When wordWrap is On,
lines wrap automatically when the lineLength value is exceeded.  Word-
wrapping wraps only on a space, tab, hyphen "-", or a slash "/" character.
(See LineLength (C-Return), 1.30.1.)

1.31.3 RightJustify (A-j)

A-j toggles On/Off rightJustify typing mode in curFile.  When rightJustify is
On, lines are right-justified when word-wrapping occurs.  Right-justification
does not occur when Return is pressed, because to do so would cause
inconvenience to programmers.  To restore proper right-justification to
paragraphs that have been modified, use Reformat Paragraph (C-3).

Right-justification is achieved by putting extra spaces between words.
Spaces are added starting from one end, and then on the next line starting
from the opposite end.  If more than one fourth of a line would have to be
space-filled, it is not right-justified.

1.31.4 AutoIndent (A-f5)

A-f5 toggles On/Off autoIndent typing mode in curFile.  When autoIndent is
On, word-wrapping or pressing Return causes the new line to use the same
amount of indentation as the current line.

If Use Tabs is On, Tab characters are used in the indentation where possible
and any residual is filled with spaces.  If useTabs is Off, only spaces are
used.  (See Tabs and Tab Rulers, 1.26.)

If leftMargin is non-zero, it overrides autoIndent and the new line's
indentation is equal to the leftMargin value.  (See Reformat Paragraph,
1.33.1.  See LeftMargin, 1.30.3.)

1.31.5 ReadOnly (SA-f5)

SA-f5 toggles On/Off the readOnly status of curFile.  If a file's readOnly
flag is On, the file may not be changed or saved to disk.  If a duplicate of
a file already in Uedit is loaded in, Uedit sets it to readOnly status
automatically.

1.31.6 Changed (L-f5)

L-f5 toggles On/Off the Changed status of curFile.  Uedit turns On the
Changed flag, when a buffer is modified.  The status of the Changed flag
determines whether you will be asked if you want to save the file when you
close it and whether it will be saved automatically if Save On Idle (C-f2) or
Save Changes (A-f2) is used.  Note:  If you turn Off the Changed flag, be
aware that Uedit will not then save it automatically or even ask whether you
want it saved.

1.31.7 Use Tabs (AC-tab)

AC-tab toggles On/Off the trueTabs flag of curFile.  If trueTabs is On, when
you press the Tab key, a tab character (ASCII 9) is typed in.  When trueTabs
is Off and you press the Tab key, spaces are inserted up to the next tab
stop.  (See Tabs and Tab Rulers, 1.26.)

When trueTabs is On, autoIndent and leftMargin use tabs in creating
indentations.  When trueTabs is Off, only spaces are used.

1.31.8 AutoBackup (SAC-f5)

SAC-f5 toggles On/Off the autoBackup flag of curFile.  If autoBackup is On,
the first time curFile is saved to disk the original file on disk is renamed
with a "BAK" file-name extension; if a "BAK" version already exists, it is
deleted.  Then curFile is saved to disk; curFile's BackedUp (internal only)
flag is turned On, so that the "BAK" version is not disturbed when you save
curFile again later on.

1.31.9 Map Illegals (SA-m)

SA-m toggles On/Off the mapChars flag of curFile.  Uedit reserves 4
characters (ASCII values 0 to 3) for internal use only.  No buffer is allowed
to contain these characters in the text.  These characters are mapped to
legal character values, however, if mapChars is On.

When (the global flag for) mapChars is On, you can load files with illegal
characters in them or type in illegal control characters.  The illegals are
mapped to the legal alternatives that are specified in the map-illegals table
in the config defaults.  When you save a file that has mapChars turned On,
any mapped characters in it are converted back to their illegal ASCII 0 to 3
values as the file is saved; in printing, the mapped characters are converted
as the text is printed.  In the table in the standard config's defaults,
ASCII 0-3 are mapped to ASCII 128-131, respectively.  (See the Config! file.
See Compile Config Defaults, 1.37.2.)

When mapChars is Off, you cannot embed illegal control characters (ASCII 0-3,
which are Ctrl-@ and Ctrl-a through Ctrl-c) using Embed Control Character (C-
c).  And if you try to load a file with illegals in it, Uedit asks whether it
can wipe them or not.  If you answer No, it does not load the file.  If you
answer Yes, it converts illegals to the "@" character.

1.31.10 Save On Idle (C-f2)

C-f2 toggles the userLocalA flag On/Off.  If Save On Idle is checkmarked
(userLocalA flag is On), and if you pause in your typing for idleTime tenths
of seconds, and if the file has been changed, it is automatically saved to
disk.  (See Set Idle Timer, 1.28.6.  See Idle Key and IdleTime, 2.18.)

1.32 Editing

The following commands are useful in general editing.  Also see Scratch
Deletes and Undo Deletes, Miscellaneous Commands, Local Modes, Formatting,
and Paging.

1.32.1 Join Lines (C-j)

C-j joins the cursor line with the next line.  It deletes all leading spaces
and tabs in the next line, adding only one space where the lines are joined.
The cursor is left at the joining of the lines.  (See Reformat Paragraph (C-
3), 1.33.1.)

1.32.2 Trim Spaces (A-c)

A-c trims the extra spaces between the next two words after the cursor,
leaving only 1 space.  The cursor is left at the next non-white character
after the spaces that were removed.

1.32.3 Toggle Case (C-f)

C-f flips the upper/lower case of the alpha character under the cursor and
advances the cursor.  Non-alpha characters are undisturbed.

1.32.4 To Upper Case (C-u)

C-u converts the alpha character under the cursor to upper case and advances
the cursor.  Non-alpha characters are undisturbed.

1.32.5 To Lower Case (C-l)

C-l converts the alpha character under the cursor to lower case and advances
the cursor.  Non-alpha characters are undisturbed.

1.32.6 Clear Leading White (A-1)

A-1 clears the leading white space in the cursor line.  The cursor position
is not changed.

1.32.7 Center Line (A-2)

A-2 centers the cursor line horizontally, based upon the current, local
lineLength value.  The cursor is left at the beginning of the centered text.

1.32.8 Right Align Line (A-5)

A-5 right-aligns the text in the cursor line from the cursor forward.  Text
coming before the cursor is not moved.  The right-alignment uses the current,
local lineLength value.  The cursor is left at the beginning of the shifted
text.

1.32.9 Match Indent (A-4)

A-4 shifts the cursor line to match its indentation with the previous line.
The cursor is left at the beginning of the next line.

1.32.10 Embed Control Character (C-c)

Control characters may be typed-in directly in Primitive Mode.  For instance,
to search for carriage returns, select Set Search (f7) to input the search
text and type C-m to insert an ASCII 13 (CR).  (Note that pressing Return or
Enter instead of C-m would input a linefeed (10), not a CR (13), unless you
have changed the default eol character.)

Control characters cannot be typed directly in normal edit mode, because they
are often used as function keys.  To embed a control character, type C-c and
then the desired character.  The CTRL key need not be used; C-c followed by
"z" does the same thing as C-c followed by C-z; both insert ASCII 26 (Ctrl-z)
at the cursor.

Control characters may appear as a "box" character in the text (depending on
the font).  You may make control characters invisible by turning Off the
Invisibles flag (C-v).  To identify the ASCII value of a any character such
as a "box" character, put the cursor on it and press C-/.  (See Map Illegals
(SA-m), 1.31.9.)

1.32.11 Open for Typing (S-bs, A-bs, S-Del, A-del, C-o)

The following commands open a space, putting the cursor in the opened space
ready for typing:  S-bs (S-BACKSPACE) opens a space in front of the word that
the cursor is in.  A-bs opens a line for typing above the cursor line.  S-DEL
opens a space at the cursor for typing.  A-DEL opens a line under the cursor
line for typing.  C-o opens the cursor line for typing.

1.33 Formatting

For other types of formatting commands, see Tabs To Spaces (1.26.5), Spaces
To Tabs (1.26.6), and Paging (1.41).

1.33.1 Reformat Paragraph (C-3)

C-3 reformats the cursor paragraph, starting at the cursor line.  If the
cursor is in a blank line, the next paragraph after the cursor is
reformatted.  A paragraph is determined by its indentation:  The first line
of the paragraph may have more indentation than the lines after it.  After
the first line, all non-blank lines with equal indentation are taken as part
of the paragraph.  When the indentation changes or a blank line is
encountered, the paragraph is deemed ended.

Paragraph reformatting uses curFile's local values for rightJustify,
lineLength, autoIndent (or leftMargin, if it is not 0), tabTable, and
trueTabs.  Paragraph reformatting turns wordWrap On temporarily, if it is not
already On.  AutoIndent, leftMargin, and trueTabs are used in the same way
that they are for typing:  That is, if leftMargin is non-zero, it overrides
autoIndent.  If trueTabs is On, any indentation that is required is put in
using tab characters; if trueTabs is Off, space characters are used.  (See
Local Modes (1.31), AutoIndent (1.31.4), and LeftMargin (1.30.3).)

To reformat a paragraph with varying amounts of indentation, you must either
adjust the indentation of those lines which have the wrong indentation so
that reformatting includes them, or a much faster way is to use Join Lines
(C-j) until you have put the whole paragraph onto the cursor line.  Then
press C-3 to reformat it.

Paragraph reformatting reacts to the following characters:  period, colon,
question mark, and exclamation point (".:?!").  These are reformatted with 2
spaces after them, if they are followed by 2 or more spaces.  If they are
followed by 1 space or less, the original spacing is kept.  With hyphen or
slash ("-" or "/"), if 1 or more spaces comes before these, a space is put
after them.  If no space comes before them, no space is put after; thus,
hyphenated words are rejoined correctly in reformatting.

Quotes and parentheses:  If there is a sentence terminator such as a period
or questionmark appearing before a quote or right parenthesis, reformat
treats the quote or right parenthesis as it would a sentence terminator.
That is, if there are 2 or more spaces following, it leaves 2 spaces.  If
there is only 1 or no space following, it preserves the original spacing.

1.33.2 Delete Trailing Whitespace (C-4)

C-4 deletes all of the trailing whitespace in curFile.

1.34 Arithmetic

The arithmetic commands add/subtract the number under the cursor to/from the
running total.  They handle whole integers and dollar.penny amounts.  Numbers
may be positive or negative.  Negative numbers are designated by a minus "-"
sign immediately preceding them or by being enclosed in parentheses.

Example:  Select Swap MouseUp (A-m) and press C-=.  This swaps the buttonUp
key with the add-numbers key.  Now go through various buffers clicking
numbers with the mouse.  The numbers are added to the running total, which is
displayed in the message line.  Non-numbers that are clicked do not affect
the total.  Reverse the above key-swap by doing it a second time.  Place the
cursor where the total should go in the text and press C-\ to insert the
total at the cursor.  (The total is stored in number variable n49.)

1.34.1 Zero Total (C-0)

C-0 zeros the running arithmetic total.

1.34.2 Insert Total (C-\)

C-\ types the current arithmetic total into the text at the cursor.

1.34.3 Add to Total (C-=)

C-= adds the number under the cursor to the running total and displays the
new total in the message line.

1.34.4 Subtract from Total (C--)

C-- subtracts the number under the cursor from the running total and displays
the new total in the message line.

1.35 Learn Mode

Uedit can "learn" a sequence of up to 200 key, mouse, and menu inputs and
"replay" them on demand.  It is highly recommended that you take a moment to
learn how to use Learn Mode, because it is extremely easy, versatile, and
powerful.  Learn Mode uses only two keys:  C-s to turn it On; C-r to
terminate it; C-r again to "replay" it as many times as needed.

When Learn Mode is On, "L#" appears in the square brackets in the title bar,
where # is the number of learned steps recorded so far.  If you input more
than 200 steps, a message "Learn buffer is full" is displayed and no more
steps are learned.  To abort Learn Mode, erasing the stored steps, press C-s
a second time.  Learned sequences may be stored as disk files.

Learned sequences may use mouse cursor-positioning; when you click the left
mouse button, the location of the mouse is learned along with the click.

Clicking to go to tiny window is also learned; but clicking in the tiny
window to return to the big screen is not learned; thus the learned sequence
will switch to tiny and stay there until something in the learned sequence
causes it to return to the big screen.

Mouse scrolling is disabled in Learn Mode; scrolling should be done using the
arrow keys.

Requester inputs are not learned; conditional requesters can be avoided by
choosing the right keys.  For example, F3 (Close File) asks whether to save
changes; but S-F3 (Auto-Close) auto-saves changes before closing the file.

Primitive Mode inputs are learned.  Gadget inputs are learned.  (See Editing
Tricks, 2.7.)

Example using Learn Mode:  Press C-s to start Learn Mode.  Press F1 (Next
File) 2 times.  Press C-r to end Learn Mode.  Press C-r repeatedly to run the
learned sequence.

To play back a learned sequence 1000 times, select Command Multiplier (C-m),
type in 1000 followed by ESC, and press C-r.  To make a learned sequence run
indefinitely or until it fails or until you abort with Amiga-ESC, press SA-c
(Cycle Counter) and then C-r.  Note that the cycle counter and command
multiplier may be used to multiply the executions of any command, not just
with running learned sequences.  (See Miscellaneous, 1.28.)

1.35.1 Start Learn Mode/Abort Learn Mode (C-s)

C-s turns On Learn Mode.  Inputs are memorized until you press C-r to end the
learning.  If you press C-s a second time, it aborts the learning and erases
the stored inputs.

1.35.2 End Learn Mode/Run Learned Sequence (C-r)

When Learn Mode is On, C-r terminates learning with Learn Mode.  C-r after
that "replays" the learned sequence.

1.35.3 Save Learned Sequence (C-5)

C-5 asks for the file name for the learned sequence.  Type in the name and
ESC.  The learned sequence is saved to disk.

1.35.4 Load Learned Sequence (C-6)

C-6 asks for the file name of the learned sequence to load in.  Type in the
name and ESC.  The learned sequence is loaded in.

1.35.5 Load and Run Learned Sequence (C-7)

C-7 asks for the file name of the learned sequence to load and run.  Type in
the name and ESC.  The learned sequence is loaded in and run.  To run it
again, press C-r.

1.36 Data File

Uedit's "data" is all of its current flags and numerical values, such as
Colors and lineLength, and all of its editing commands.  In the standard
config, there about 300 commands, including the Startup command which defines
all of Uedit's menus.  (See the Config! file and A-Z extensions.  See Startup
Key and Menus, 2.16.)

At startup, Uedit automatically loads Data!, the standard data file, unless
you tell it to do otherwise by using the -c or -d CLI command-line flags.  If
the flags are not used and it cannot find Data!, it loads in Config!, the
standard config, and compiles it.  Uedit looks for these files in the current
directory or in S:.  If Data! is in S:, Uedit can be run from any directory
by typing "Run Ue" in CLI or by clicking its icon in Workbench.  (See Getting
Started.  See CLI Command Line, 2.1.)

During an edit session, when you compile a command or modify any attribute
such as lineLength or Colors, Uedit's current "data" is changed.  To make the
change permanent, use Save Data (A-f6) to rewrite the data file.  To recover
the original data after making changes, use Load Data (C-f6) to reload the
data file.

For more information about config and data files, see Config, Data, and
Customizing, 2.3.

1.36.1 Save Data (A-f6)

A-f6 asks whether you want to save the data.  If you answer Yes, it asks for
the data file name.  If you type in a name and press ESC, the data is saved
under that name.  If you just press ESC, the current data file name is used,
which is Data! or S:Data!, the standard data file, unless you specified a
different data file name earlier.

1.36.2 Load Data (C-f6)

C-f6 asks whether you want to load a data file.  If you answer Yes, it asks
for the name of the data file.  If you type a name and press ESC, the named
data file is loaded.  If you just press ESC, the current data file is
reloaded, which is Data! or S:Data!, the standard data file, unless you
specified a different name earlier.  After a data file is loaded in, Uedit
Aborts all activity and the screen flashes.  This abort is so that the
current command will stop running; loading in a data file replaces all
commands in Uedit's memory, including the one that is currently running.

1.37 Compiling

A command runs when you give the input that the command is assigned to.  For
example, pressing F2 causes the file in the window to be saved.  Commands
start out as CL source code, such as:
            <normal-f2: saveFile(curFile) >

Commands may be written anywhere in any buffer in Uedit.  Uedit compiles the
command language into binary pcode which then becomes part of Uedit's "data".
The standard config, Config! and its A-Z segments, contains the CL source
code for all of Uedit's standard commands and defaults.  The defaults are the
list of values at the beginning of Config!.  (See the Config! file.  See
Config, Data, and Customizing, 2.3.)

1.37.1 Compile (f6)

F6 compiles the command at or following the cursor.  The cursor must be on or
before the command's left angle bracket "<".  If an error is found during the
compile, the display flashes and the cursor stops just past the offending
portion of the command.  When the compile is successful, the cursor stops on
the ending angle bracket ">" of the command and the pcode size of the
compiled command is reported in the message line.  If the word "Size" is used
in the message, it is a new command for that key.  If the word "Replace" is
used, it is replacing an existing command for that key.  (See Parts 2 and 3
concerning CL control structures, functions, arguments, and compile errors.)

1.37.2 Compile Config Defaults (AC-f6)

The first section in any configuration must be a series of flags and default
values for such things as lineLength, pageLines, and Colors.  AC-f6 compiles
the defaults in the config file.  Load Config! or the root segment of your
custom config, edit the defaults as needed, and select Cfg Defalts (AC-f6) to
compile the customized defaults.  The defaults are compiled and the window is
closed and reopened using the new values.  Use Save Data (A-f6) to save the
values in the data file for permanent use.

If an error is found during the default-compile, the display flashes and the
cursor stops just after the offending value.  Default values are enclosed in
angle brackets "<...>".  Do not remove these brackets or change the order in
which the defaults are presented.  For defaults which require a Yes or No
answer, use 0 for No and 1 for Yes.  If any other range of answers is
required, it is given beside the default.  (See Config Defaults, 2.4.)

1.37.3 Make Command (S-f6)

S-f6 opens buffer 44 so that you can type a command into it.  Commands may be
written and compiled anywhere, but S-f6 is provided as a convenience.  Note
that you could as easily use buffer 44 as a scratch pad and S-f6 as a quick
means of switching to it as needed.

1.38 Keys

A "key" is any input that may run a command.  This includes any keyboard or
mouse input.  Left mouse button inputs are keys, for example; they include
buttonDown and buttonUp, gadget clicks, and closeBox clicks, each with or
without shift-key modifiers.  The right mouse button is a key, if trapMenus
is True; the keys are menuDown and menuUp.  (See the defaults in Config!.)
Menu inputs are not considered keys themselves, because they run existing
keyboard and mouse keys.  For menu inputs, the commands described below act
upon the key the menu is running, not the menu itself.  (See Valid Key
Arguments, 2.29.)

You may swap and kill keys with abandon, in order to make your work as
convenient as possible, and this is definitely encouraged.  But do not select
Save Data (A-f6), after swapping or killing keys, unless you are satisfied
that the keys affected are not borrowed by other keys or by menus.

Dozens of keys are run by the menus.  Swapping or killing a menu selection is
exactly the same as swapping or killing its key.  In addition to the keys
borrowed by menus, the following keys are run by various keys in the standard
config.  If you swap or kill them, the keys running them cannot work
properly.  To see many examples of keys borrowing other keys, load Config!M
and search for "runKey".

The best example of keys running other keys is search-replace.  The Search
Fwd key (f9) is borrowed by the Replace Fwd key (f10), so that after each
replace another search occurs.  The Replace All Fwd key (A-f10) runs f10 in a
loop until the search in f9 fails.  (See the Config!M file and search for
"f9".)

Anytime you use a key a lot, it is convenient to swap it to a favored spot so
that the work is easier; and, again, this is highly recommended.  For
example, Reformat Paragraph (C-3) and Run Learn (C-r) may be used frequently
and may be swapped to ESC, which is easier to hit.

When using Swap Keys, note the following:  (1) If a menu item's key is
swapped, when the menu item is selected it runs the key it was swapped with -
or does nothing, if the key it was swapped with had no command.  (2) If Swap
Keys or Kill Key is selected by mistake, abort with Amiga-ESC or type a
couple of "safe" keys, such as "a".  (3) Do not click the left mouse button
during Swap Keys, unless you intend to swap the mouse's buttonDown and
buttonUp commands.  (4) If you swap a key that is run by other keys, the keys
running it cannot work right until you swap it back or select Load Data (C-
f6) to reload the original data file.

To swap the mouse's buttonDown key, select Swap Keys (f5), press the other
key first, and then click the mouse button.  This allows only buttonDown to
be included in the swap.

To swap the mouse's buttonUp key with another key, use Swap MouseUp (A-m).
In the standard config, no buttonUp command is defined, but it is handy to
swap keys such as C-= (the add-numbers key) to buttonUp, so that you can
click-add numbers in files.  Another example is swapping mouseUp with Run
Learn (C-r); then the current learned sequence is run every time the mouse is
clicked.  The learned sequence could, for instance, bracket clicked lines of
text with printer control codes or copy clicked words into another buffer.
(See Swapping Keys Permanently, 2.9.  See Editing Tricks, 2.7.)

1.38.1 Kill Key (SAC-f6)

SAC-f6 kills the next key that is input.  If it has a command, the command is
deleted and the message "Key command was deleted" is displayed.  If it has no
command, nothing is done.

1.38.2 Find Key (L-f6)

L-f6 enables you to find an "available" key to attach a new command to or
perhaps to swap another key to.  L-f6 stays active until you press Amiga-ESC
to abort it.  If the key you input has a command, "In use" is reported.  If
it has no command, "Available" is reported.

1.38.3 Swap Keys (f5)

F5 displays the message "Next 2 function keys will be swapped!" and waits for
2 inputs.  Give the 2 inputs that you want to swap.  If the swap is
successful, "Keys were swapped" is reported.  If neither input has a command
or the inputs are identical, nothing is done.

1.38.4 Swap mouseUp (A-m)

A-m swaps the next key you input with the mouse's buttonUp command.  In the
standard config, buttonDown deposits the cursor and handles mouse scrolling,
but no buttonUp command is defined.  Swapping a key to buttonUp may be
extremely useful.  You may, for instance, swap C-r (Run Learn) with buttonUp.
Then pressing the mouse button deposits the cursor and releasing the mouse
button runs a learned sequence.  (See the discussion above.  See Editing
Tricks, 2.7.)

1.39 Display Modes

Uedit has 4 display modes (screen types).  The modes use a non-interlace
screen with either 2 bitplanes (lace=0) or 1 bitplane (lace=1), or an
interlace screen with 2 bitplanes (lace=2) or 1 bitplane (lace=3).  (See
Lace/Planes, 1.39.1.  See the CL functions toggle(), flipFlag(), and
setLocal() in 3.4.)

Using 1 bitplane saves memory and gives faster scrolling, but it only shows 2
colors.  Interlace modes require more memory and displays twice as many lines
per window of text.  Interlace using just 1 bitplane (2 colors) uses about
the same amount of graphics memory as non-interlace with 2 bitplanes (4
colors).  If there is a shortage of graphics memory, Uedit will not use
interlace and may use only 1 bitplane (2 colors).

Regardless of which display mode is used, RGB color tuning is possible using
Tune RGB (A-Esc).  Also when using 2 bitplanes (4 colors), the 4 colors may
be rotated using Colors (A-Help).  Each buffer in Uedit may use its own
combinations of the 4 colors.  (See Colors (A-Help), 1.30.6.)

1.39.1 Lace/Planes (S-Esc)

S-Esc toggles to the next screen type among 4 screen types.  The screen type
can also be selected using the following keys:
    Key     Screen type     Bitplanes   Colors   lace CL variable value
    ---     -----------     ---------   ------   ----------------------
    R-f2    regular         2           4        0
    R-f1    regular         1           2        1
    R-f4    interlace       2           4        2
    R-f3    interlace       1           2        3

Using 2 bitplanes with a regular or interlace screen uses twice as much
memory as a 1 bitplane screen.  Also scrolling and screen updates are faster
with 1 bitplane.

1.39.3  Hide Display (R-h)

R-h toggles the hideDisplay CL flag.  If hideDisplay is True, displaying is
suppressed when running learned sequences or multiple operations with the
command multiplier.  Performance is a great deal faster in many cases when
display updates are suppressed.  (See the defaults in Config!.  See
flipFlag() and toggle() in 3.4.)

Technical note:  hideDisplay is turned on automatically, if you examine the
menus during a display update; this keeps the blitter from overwriting a
menu; in the next pause, hideDisplay is turned off and a full display refresh
is done.  Useful side effect:  To speed up the performance of a long process
involving display updates, just display a menu briefly by flicking the mouse
menu button and hideDisplay will be turned on.

Warning:  If you turn on hideDisplay and run a learned sequence that requires
an input, its prompting message will not be displayed!  You will wonder why
the process is taking forever, when in fact Uedit is waiting for an input
from you!

1.39.4 Scroll Type (R-s)

R-s toggles the scrollType CL variable which determines whether colored
regions are colored during scrolls or not.  If scrollType is True, they are
not updated and scrolling is slightly faster; if scrollType is False, colored
regions are updated during scrolls.  (See the defaults in Config!.  See
flipFlag() and toggle() in 3.4.)

1.40 Columnar

When you mark a hilite or invert region, you may also be marking a columnar
region without realizing it.  To see, after marking a colored region select
Col Display in the menu.  This turns On columnar display mode, so that
colored regions are displayed as rectangular in shape, if they happen to
correspond to a columnar region.  Example:  A regular hilite region exists,
if the end-of-hilite comes after the start-of-hilite in the text; this is the
only requirement.  But a columnar region has the added requirement that the
end-of-hilite must be in a higher column number than (to the right of) the
start of hilite; otherwise, no columnar hilite region exists.

Tab characters may be "unclean" to handle in columnar text operations,
because tabs may be scattered randomly throughout a columnar region.  A
region with tabs in it that are not perfectly aligned vertically could be
copied and inserted at another location where the tabs would have different
widths than they did originally, and this would destroy the rectangularity of
the region.  To overcome this problem, in columnar display mode tabs are
displayed as "box" characters that are only 1 column wide.  This makes it
easier to see tab characters and handle them cleanly.

When Use Tabs (AC-tab) in the Local Modes menu is Off, typing the Tab key
normally puts in enough spaces to move the cursor to the next tab stop; but
in columnar display mode, typing the Tab key puts in only one space, because
tab spacings are considered meaningless or invalid in columnar display mode.
If Use Tabs is On, typing the Tab key inserts a tab character (ASCII 9), as
it normally would, but it is displayed as a "box" (depending on the font)
that is only 1 column wide.

Columnar data operations are possible when there are tabs in the region, but
if a particular column in the region has a tab in it, every line in the
region should have a tab in that same column, so that the region's
rectangularity is maintained regardless of where it may be inserted or
overlaid.  If tabs are a problem, they should be converted to spaces using
Tabs To Spaces (L-t).

When a columnar region is copied and inserted in the text somewhere, it is
hilited just as the original copied region was; it can be "lifted out" in one
keystroke, because inserted columnar text merely pushes the text beneath it
to the right.  If overlaying rather than inserting is used, however, the
columnar text overlays the text beneath it and the text that is overwritten
cannot be recovered.  Note that inserting columnar text does not push the
lines beneath it downward like pasting in copied text normally does; it
pushes the text rightward instead.

The keypad keys kpDot, kpMinus, and kpEnter work as regular copy, cut, and
paste keys for regular hilite regions, when columnar display mode is Off.
When columnar display mode is On, these keys work instead as columnar copy,
cut, and paste keys.  (See Hilite and Invert Regions, 1.29.)

1.40.1 Columnar Display (SC-)

SC-toggles columnar display mode On/Off.  If columnar display mode is On,
hilite/invert regions are displayed as rectangular in shape, if they
correspond to columnar regions.  If columnar display mode is Off, a colored
region may be visible; yet the region may become uncolored when columnar
display mode is turned On, because the end of the region is not in a higher
column number than the start of the region.

1.40.2 Columnar Cut (SC-1)

SC-1 (or kpMinus) copies and then clears the hilited columnar region.  Text
to the right of the deleted region is pulled to the left.  The copy is stored
in buffer 37.

1.40.3 Columnar Erase (SC-2)

SC-2 erases the hilited columnar region by filling it with spaces.

1.40.4 Columnar Copy (SC-3)

SC-3 (or kpDot) copies the hilited columnar region.  The copy is stored in
buffer 37.

1.40.5 Columnar Insert (SC-4)

SC-4 (or kpEnter) inserts the copied columnar text into curFile at the
cursor.  Text beneath it is pushed to the right.  The inserted columnar
region is hilited and can be lifted out using Columnar Cut (SC-1 or kpMinus).

1.40.6 Columnar Overlay (SC-5)

SC-5 overlays the copied columnar text at the cursor in curFile.  The text
beneath it is overwritten and cannot be restored.  The columnar region is
hilited.

1.40.7 Insert Columnar Hilite at Cursor (SC-6)

SC-6 inserts the hilited columnar region in curFile at the cursor in curFile
without making an intermediate copy of it.  The inserted region is hilited.
This command does not disturb buffer 37, which may be holding an earlier
copied columnar region.

1.40.8 Overlay Columnar Hilite at Cursor (SC-7)

SC-7 overlays a hilited columnar region in curFile at the cursor in curFile
without making an intermediate copy of it.  The overlaid region is hilited.
The text beneath it is overwritten and cannot be recovered.  This command
does not disturb buffer 37, which may be holding an earlier copied columnar
region.

1.41 Paging

Printed page (form) boundaries are determined by formfeeds (ASCII 12) in the
text or by the line-count based on the current pageLines (lines per page)
value.  A formfeed in the text causes Uedit to draw a horizontal line across
the window, marking the page boundaries.  The paging commands described below
insert a formfeed, when they create a page division.

To see the pageLines value that curFile is using, select Show Vals (S-Help).
To set pageLines, select Lines/Page (A-g).  To see the cursor's page-row-
column in curFile, turn On Row/Column (C-2).

In preparing a file for paging, leave out the page-divisions (formfeeds or
blank lines for margins) until the text is satisfactory.  Use only the blank
lines that are needed for separating paragraphs and sections.  When satisfied
with the file, save a copy of it before paging it.

Turn On Row/Column (C-2), which causes the page-row-column of the cursor to
be displayed in the message line.  Page-divisions may be installed in the
following ways:  manually, by putting in blank lines or formfeeds by hand;
manually, by choosing page-break locations and using Divide Page (L-v);
automatically, by using Auto Page Division (L-r).

Inserting page-divisions with the paging commands installs the page number;
it is put in the middle of the line which is 1/2 the bottomMargin distance
above the end of the page, where the end of the page is determined by the
current pageLines setting.  Example:  If pageLines is 66 and bottomMargin is
4, 1/2 of 4 is 2, so the page number is put in the middle of line 64,
followed immediately by a formfeed.  (See PageLines, TopMargin, and
BottomMargin in Local Values, 1.30.)

Programmer note:  Programmers often need to go to a line number, rather than
going to page & line.  To disable paging so that only line number is used,
set pageLines to 1 using Lines/Page (A-g).  To go to a line number, use Goto
Line N (C-n).

1.41.1 Go To Page # (A-3)

A-3 asks for the printed page (form) number to go to.  Input the page number
and press ESC.  The cursor is moved to the beginning of the specified page.

1.41.2 Top of Page (L-h, C-kp8)

L-h and C-kp8 move the cursor to top of form (printed page).  If already at
top of form, the cursor moves to the top of the preceding form.

1.41.3 Bottom of Page (L-b, C-kp2)

L-b and C-kp2 move the cursor to bottom of form.  If already at bottom of
form, the cursor moves to the bottom of the next form.

1.41.4 Insert FormFeed (L-f)

L-f inserts a formfeed (ASCII 12) at the cursor.  A formfeed may also be
inserted using Input Control Character (C-c) followed by "l".

1.41.5 Divide Page (L-v)

L-v inserts a page division at the cursor line.  A page division is a
formfeed (FF) preceded by and followed by blank lines according to the
current bottomMargin and topMargin values.  BottomMargin determines how many
blank lines are put before the page number and FF.  TopMargin determines how
many blank lines are put after the FF.

1.41.6 Delete Page Division (L-d)

L-d deletes the next page division.  L-d removes the blank lines before and
after the page-division's formfeed; it does not know whether blank lines
should be left to separate two paragraphs or whether the page division was
splitting a paragraph; watch out for cases where blank lines need to be typed
back in after using L-d.

Page divisions are easy to delete using Delete Word-Right (kp9) also.  Put
the cursor in a blank line at the bottom of the page and press kp9; this
deletes the page number and all lines up to it, leaving the formfeed and top
margin after it.  Delete the desired number of blank lines using Del,
Backspace, or Delete Line (C-d).

1.41.7 Auto Page Division (L-r)

L-r inserts page divisions from the cursor page forward.  To page an entire
file, put the cursor in the first page and use L-r.  It first scans forward,
displaying a "Scanning" message while it looks for formfeeds.  If it finds a
formfeed, it stops and tells you to delete the existing page divisions.  Use
Bottom Page (L-b) to find the old page divisions, and delete them using one
of the methods discussed earlier.

Once the old page divisions have been removed, put the cursor in the page
that you want auto-page-division to start from and press L-r again.  This
time it inserts page divisions and page numbers.  It uses bottomMargin and
topMargin as described earlier.  L-r looks for a non-blank line to page-break
on, because page-breaking on a blank line may cause the top margin of the
next page to have extra blank lines in it.

1.41.8 Delete Page Number (L-y)

L-y finds and deletes the page number at the next page division.  It does not
delete the blank lines in the top and bottom margins.

1.42 Split Windows

There may be up to 8 split windows in use at the same time.  The minimum
split window size is 2 lines, and the maximum is whatever will fit into
Uedit's window, leaving at least 2 lines for the main window.  The split
window that is currently active has "Uedit" in its title bar.  To activate a
split window, click the mouse in it or select Next Split (L-9).  The buffer
displayed in the active split window is by definition curFile.  Split windows
use the colors of the buffers displayed in them, so each split window may use
a different 4-color combination.  Split windows are discarded, when you
switch to or from interlace screen (S-esc) or change to a different font size.

Technical note:  If a buffer is displayed in two split windows, each uses its
own cursor and page locations.  locSC is the second window's cursor and locSP
is its start of page.  When you switch between the buffer's two windows,
atCursor is swapped with locSC and sPage is swapped with locSP.  This is the
only time locSC and locPC are changed by Uedit internally; locA through locJ
are never changed internally.

1.42.1 Mouse Size (L-=)

L-= can resize the lower split windows, but not the main window.  Activate
the split window you wish to resize by clicking the mouse in it.  Then select
Mouse Size (L-=).  Hold down the mouse button and move the mouse up or down
to resize the split window.  Release the button, when the size is
satisfactory.

1.42.2 Next Split (L-9)

L-9 activates the next split window and the buffer in it becomes curFile.  A
split window may also be activated by clicking the mouse in it.

1.42.3 Drop Split (L-0)

L-0 removes the active split window, relinquishing its window-space to the
main window.

1.42.4 Current File (L-c)

L-c opens a split window which also has curFile in it.

1.42.5 Undo Buffer (L-1)

L-1 opens a split window with the Undo buffer in it (buffer 45).

1.42.6 Search Buffer (L-2)

L-2 opens a split window with the search buffer in it (buffer 49).

1.42.7 Replace Buffer (L-3)

L-3 opens a split window with the replace buffer in it (buffer 48).

1.42.8 Hilite Buffer (L-4)

L-4 opens a split window with the copied hilite buffer in it (buffer 47).

1.42.9 Invert Buffer (L-5)

L-5 opens a split window with the copied invert buffer in it (buffer 46).

1.42.10 Columnar Buffer (L-6)

L-6 opens a split window with the copied columnar buffer in it (buffer 37).

1.42.11 Directory Names (L-7)

L-7 opens a split window with the directory buffer in it (buffer 38).

1.42.12 Split Window Size (L-8)

L-8 asks for the number of lines for newly created split windows to use.
Input the number of lines and press ESC.  The minimum number of lines allowed
is 2, and the maximum is as many lines as will fit into the window, leaving
at least 2 lines for the main window.  To resize existing split windows, use
Mouse Size (L-=).

1.43 Printing

If there is enough memory to copy the text to be printed, printing files or
regions in Uedit is spooled out and handled in the background, so that you
can go on working.  Up to 12 print jobs may be spooled.  If memory is low,
printing is done in foreground and you must wait until it has finished.
Printing in foreground may be aborted with Amiga-ESC.  Amiga-ESC does not
abort spooled printing, however, so it is safe to use Amiga-ESC while editing
during spooled prints.  Spooled printing may be aborted using Abort Print (L-
a) or Stop All Prts (R-a).  If printTabs is False (see Config! defaults),
tabs are converted to spaces for the printer.  If printTabs is True, they are
not converted.

If Map Illegals (SA-m) is turned On, mapped illegal characters in the text
being printed are converted back to their former illegal values (ASCII 0-3)
before they are sent to the printer.  (See Map Illegals, 1.31.9.)

1.43.1 Print Select

The Print Select value (0 to 3) determines where printed text is sent.
Spooled prints are handled according to the value of Print Select at the time
they were queued up; thus, you may queue up prints for both serial and
parallel printers at the same time.  (The CL variable prefPrint is the same
as Print Select.)

If a print job is too big to spool on account of insufficient memory, one of
two things happens:  If no prints are queued up, the text is printed in the
foreground ("busy" mode) and you must wait for it to finish, unless you abort
it with Amiga-ESC.  If other print jobs are in the queue, Uedit will hang and
keep printing in order to free up some memory; this hang-up may be aborted
with Amiga-ESC.

In tiny window, spooled prints and file-saves continue to be processed.  When
you quit Uedit, spooled prints and file-saves are finished before Uedit
closes out.  If during that time you give any input, the quit is abandoned
and you are returned to normal edit mode.  (See Quit, 1.18.)

Uedit's printer control codes may be embedded by commands in the Printing
menu.  These codes are of the form ESCxESC, where "x" is 1 to 3 characters
based on the printer control code and its arguments, if any.  When Print
Select 2 or 3 is used, Uedit strips off the second ESC and converts the "x"
to an Amiga printer code before sending it to the print device that you
selected with Preferences.  (See ROM Kernal Manual & table below.  Also see
the CL function printerCode() in 3.4.)

The Print Select (prefPrint) value determines which of 4 methods of printing
is used:  0 = raw straight out the parallel port.  1 = raw straight out the
serial port.  These go through the Amiga print device selected with
Preferences:  2 = Uedit converts its ESCxESC codes; print device touches all
text.  3 = Uedit converts its ESCxESC codes; print device touches only those
codes.

The advantage of Print Select 0 & 1 is that everything is sent out the
parallel or serial port in raw form.  Anything you put into the file is sent
"as is" and the printer selected with Preferences is ignored.  Do NOT use
Uedit's ESCxESC codes, in this case, because those are intended to be
processed by the Amiga print device, not by a printer directly.  That is, do
NOT embed printer control codes using the Printing menu when you are going to
print using Print Select 0 or 1.

The advantage of Print Select 3 is that Uedit translates its own ESCxESC
codes for the Amiga print device, but all other text, including your own ESC-
sequences to control your personal printer, is sent raw to the printer.

The advantage of Print Select 2 is that you may embed generic Amiga printer
control codes (listed in the Amiga ROM Kernal Manual) in the text or may
embed Uedit's ESCxESC codes using the Printing menu.  When the text is
printed, Uedit identifies its own ESCxESC sequences and converts them to
Amiga printer control codes, but it sends all other text, including the
control codes you embedded yourself, to the Amiga print device "as is".

The following summarizes the meanings of the Print Select values:

                                   What the Amiga does with
Print Select (to)    Uedit's ESCxESC codes           your ESC-sequences
-----------------    -----------------------------   ------------------
0 (parallel port)    don't use                       sent in raw form
1 (serial port)      don't use                       sent in raw form
2 (print device)     converted & used                used or discarded by print device
3 (print device)     converted & used                sent in raw form

1.43.2 Printer Control Table

The Amiga print device recognizes 76 printer control codes, which it
translates into commands for your printer.  (See Amiga ROM Kernal Manual,
page 3-198.)  When using Embed Code in the Printing menu (or when writing
Uedit commands using the printerCode() function), use the following control
code values.  The printer codes which are marked with asterisks require 1 or
2 numerical arguments, such as for color number or form length:

0    reset                              45   proportional on
1    initialize                         46   proportional off
2    lf                                 47   proportional clear
3    rtn, lf
4    rev lf                             48   * set proportional offset
5    norm char set                      49   auto left justify
6    italics on                         50   auto right justify
7    italics off                        51   auto full justify
8    underline on                       52   auto justify off
9    underline off                      53   letter space (justify)
10   boldface on
11   boldface off                       54   word fill (auto center)
12   * fgnd  color n
       (n = 30-39. See colors below.)   55   1/8" line spacing
13   * bkgnd color n                    56   1/6" line spacing
       (n = 40-49. See colors below.)   57   * set form length n
14   normal pitch                       58   * perf skip n
15   elite on                           59   perf skip off
16   elite off
17   condensed fine on                  60   left margin set
18   condensed off                      61   right margin set
19   enlarged on                        62   top margin set
20   enlarged off                       63   bottom margin set
21   shadow print on                    64   ** T&B margins
22   shadow print off                   65   ** L&R margins
23   double strike on                   66   clear margins
24   double strike off
25   NLQ on                             67   set horiz tab
26   NLQ off                            68   set vert tabs
                                        69   clear horiz tab
27   superscript on                     70   clear all h tabs
28   superscript off                    71   clear vert tabs
29   subscript on                       72   clear all v tabs
30   subscript off                      73   clear all h & v tabs
31   normalize the line                 74   set default tabs
32   partial line up                    75   * extended commands
33   partial line down
34   US character set
35   French char set
36   German char set            * one number argument is required.
37   UK character set          ** two number arguments are required.
38   Danish I char set
39   Swedish char set
40   Italian char set
41   Spanish char set
42   Japanese char set
43   Norwegian char set
44   Danish II char set

Printer color codes:
Imagewriter II         0=black,   1=red,  2=green,  3=yellow, 4=blue
no background colors   5=purple,  6=blue, 7=yellow, 8=yellow, 9=black
Canon Inkjet           0=black,   1=red,  2=green,  3=yellow, 4=blue
foreground/background  5=magenta, 6=cyan  7=white

1.43.3 Print Select (A-p)

A-p asks for the new Print Select value.  Input a number, 0 to 3.  (Print
Select is the same as the CL variable prefPrint.)

1.43.4 Print Hilite (C-p)

C-p prints the hilite region in curFile, if it exists, using the current
Print Select value.

1.43.5 Print File (AC-p)

AC-p prints all of curFile, using the current Print Select value.

1.43.6 Abort Print (L-a)

L-a aborts the current spooled print, if a spooled print is in process.  The
print is removed from the print queue.

1.43.7 Stop All Prints (R-a)

R-a aborts all spooled prints.  The prints are removed from the print queue.

1.43.8 Restart Print (L-s)

L-s restarts the currently active spooled print.  Use this to start over
after a paper jam has occurred.

1.43.9 Code Help (SAC-p)

SAC-p displays help for the Bracket Hilite (L-p) command.  See Bracket Hilite
below.

1.43.10 Bracket Hilite (L-p)

L-p asks you to type in one of the following letters corresponding to a
printer control:  i=italics, u=underline, b=boldface, c=condensed, e=elite,
l=enlarged, s=shadow, d=double strike, n=NLQ, x=superscript, y=subscript, 8=8
lines/inch, h=help.

The hilite region in curFile is bracketed with the corresponding ESCxESC
printer codes that are required.  The control code at the start-of-hilite
turns On the printer feature, such as boldface.  The control code at the end-
of-hilite turns Off the feature.  You must print using Print Select 2 or 3 in
order for these special codes to be detected and converted by Uedit to the
correct generic Amiga printer control codes.  The Amiga print device, in
turn, converts the generic codes to the correct Esc-sequences for the printer
that was selected with Preferences; do not print using Print Select 0 or 1,
because Uedit will send the text raw and your printer will not recognize the
generic printer control codes.  (See the earlier discussion of Print Select,
1.43.3.)

1.43.11 Find Code (R-g)

R-g searches starting at the cursor in curFile to find the next ESCxESC code
in the text.  If one is found, it is inverse-displayed and may be deleted
using Delete Invert (C-i).

1.43.12 Embed Code (L-g)

L-g asks you to input a printer control code number (0 to 75).  Input the
control code number and press ESC.  The corresponding ESCxESC printer code is
embedded at the cursor.  Note that unlike the Bracket Hilite (L-p) command,
L-g lets you embed the code for any printer command, 0 to 75.  Also, L-g does
not bracket a region.  You must print using Print Select 2 or 3, if ESCxESC
codes are embedded.  (See the Printer Control Table, 1.43.2.  See earlier
discussion of Print Select, 1.43.3.  See printerCode() in 3.4.)

1.44 Building an Index

The first command below accumulates words and phrases for an index.  The
second command builds an index using the accumulated list.

1.44.1 Store Index Words (SA-buttonDown)

SA-buttonDown and SA-buttonUp work together to store words and phrases for an
index.  Press Shift and Alt, put the mouse on the word or phrase you wish to
include, then either click the mouse if it is a word or hold down the button
and drag the mouse across the words if it is a phrase.  The text is inverted,
and the word/phrase is copied into buffer 41.  You need only include each
word/phrase one time, but duplicates are removed in the second step if any
are present.  To monitor and edit the accumulating list periodically, use
Swap Buffer (C-w).

1.44.2 Build Index (SA-i)

Having accumulated a word/phrase list for the index in buffer 41, while
looking at the file to be indexed press SA-i to build the actual index.  SA-i
asks for the lines-per-page value.  Input the pageLines value and press ESC.
If a pageLines value is not input, the current pageLines value is used.
Regardless of the pageLines value, formfeeds in the text are taken as page
boundaries in computing the page numbers for index words and phrases.  SA-i
scans buffer 41, removing duplicate entries from the list.  Then it goes
through the list of index words/phrases, searching curFile for occurrences of
each, and storing the page number of each occurrence after the word/phrase
entry in the index.  Each word or phrase is displayed in the message line as
it is being processed.  When finished, it displays the message "Press Ctl-w
to see Index".  The Index is in buffer 41 and can be saved to disk.  Some
cleanup work on the index is required.  The entries are in first-character
alphabetical order only, and must be shuffled slightly.  Entries with extra
many page numbers, creating lines that are too long, must be broken into
multiple lines.

1.45 NoName

Uedit insists that at least one file buffer be open at all times.  When Uedit
is started up, if you do not specify one or more files to load in, it opens a
NoName file buffer; if a NoName file exists in the current directory, it is
loaded automatically when no files are specified at startup.

Uedit opens a NoName file buffer, if you close the last file buffer.  Again,
if a NoName file is in the current directory, it is loaded in automatically.
This stubborn behavior means that if a NoName file exists, you cannot quit
Uedit using the CloseBox, because it will keep loading in the NoName file.
To make it possible to quit using the CloseBox, it is necessary to delete or
rename the NoName file in the current directory.  However, you may find it
convenient to keep a list of notes and directory/file names in a NoName file
in each work directory.  It is loaded by default and resides in the "home"
buffer slot (buffer 0).  If there is low memory when Uedit tries to load in
the NoName file, it opens an Empty buffer instead.  (See Buffers, 1.20.  See
Close File (CloseBox), 1.17.1.)

1.45.1 NoName.info Icon

The NoName.info icon should be in your working directory or in S:, if Make
Icons (AC-i) is turned On.  If Make Icons is On, when a file is saved to
disk, Uedit copies NoName.info into MyFile.info, where MyFile is the file
being saved.  Uedit can use any icon that is named NoName.info and which is
in the current directory or in S:.

1.46 Spelling

The programs associated with spell-checking are:
    Ue          Uedit uses spell-checking CL functions.
    UdBuild     Program to build working dictionary and table.
    Uspell      Program to spell-check files.
    Ufind       Program to find words in dictionary using wildcards.

The files associated with spell-checking are:
    dict.A-dict.Z       Readable, editable dictionary files.
    Udict               Working dictionary, compressed.
    Udtable             Table for working dictionary.

UdBuild reads the dict.A-dict.Z files and builds a working dictionary and
table.  The default working dictionary name is Udict and the default table
name is Udtable.  UdBuild looks for dict.A-dict.Z in the current directory,
unless a directory for them is specified.  UdBuild runs faster when the
dictionary and table are built in RAM.  If 200k or more of memory is
available, type:
        UdBuild MySpellDir -tRAM:Udtable -dRAM:Udict
where MySpellDir is the directory containing dict.A-dict.Z.  Typing "UdBuild"
by itself would read dict.A-dict.Z from the current directory and build Udict
and Udtable in the current directory.

The Ufind program finds words in the working dictionary Udict based on
wildcards.  Using Ufind, you could build Dict.A-dict.Z from a working
dictionary and table by typing the following in CLI:
        Ufind A* -oRAM:dict.A
        Ufind B* -oRAM:dict.B
        ...
        Ufind Z* -oRAM:dict.Z

In "word" handling, such as in cursor word-left and word-right movements,
Uedit considers the following characters to be "word" characters:  A-Z, a-z,
0-9, the apostrophe "'", and characters in the range ASCII 128-255.

But spell-checking considers only the following to be "word" characters and
only these may be used in dict.A-dict.Z and are looked at during spell-
checking:  A-Z, a-z, and the apostrophe "'".

1.46.1  Load Speller (R-u)

R-u brings up the speller.  It loads the dictionary table, Udtable (about
12k), into memory.  It tries to load the working dictionary, Udict (about
150k), into Uedit's memory also.  Spell-checking is much faster, if the
working dictionary is resident in Uedit's memory.  If unable to load Udict,
it accesses Udict on disk during spell-checking.  The Load Speller (R-u)
command may be customized in Config!S so that Uedit does not try to load
Udict into memory, by changing the flag in StartSpeller() from 1 to 0.  Also
it may be customized to use different working dictionaries and tables or to
look in different directories for them or to ask for their names at runtime.
Note that, as currently configured, R-u looks for Udict and Udtable in the
current directory.  (See the StartSpeller() CL function in 3.4.)

If Uedit cannot find about 12k to hold Udtable, a "No memory" message is
displayed.  When short of memory or finished using spell-checking, select
Free Speller (R-f) to free up the speller's memory, especially if Udict is
residing in Uedit's memory.

1.46.2 Spell-Check (R-c)

R-c spell-checks curFile from the cursor forward and stops on the first word
not found in the dictionary.  Optional spellings are presented in the message
line, if the spelling dictionary is resident in memory.  Click the desired
word in the message line and it replaces the bad word and spell checking
resumes.  Click anywhere else and the word is left as is and spell checking
continues.  Spell checking stops at end-of-file or when aborted with Amiga-
ESC.  Buffer 41 may contain a supplemental dictionary; spell-checking looks
in the supplement, if the current word is not found in the main dictionary.
(See Swap Buffer (C-w).  See Check & Collect (R-l), which loads in a
supplemental dictionary, UdSupplement, and adds words to it.  See Sort Lines
(SA-s); it can sort an existing list of words alphabetically.)

1.46.3 Spell-Check and Mark Words (R-m)

R-m spell-checks curFile from the cursor forward and puts an "@" character
after each word not found in the dictionary.  Spell-checking continues until
end-of-file or abort with Amiga-ESC.

1.46.4 Spell-Check and Collect Bad Words (R-l)

R-l asks what dictionary supplement to use.  If none is specified, it opens a
"UdSupplement" file.  R-l loads an existing supplement file, if one exists.
For every word not found in the dictionary during spell-checking, R-l adds
the word to the supplement if it is not already there.  The words are added
in alphabetical order as a stacked list, with one word on each line.  Spell-
checking continues until end-of-file or abort with Amiga-ESC.

UdSupplement may be used as a supplemental dictionary and can be merged with
dict.A-dict.Z.  Supplemental dictionaries are not compressed; they are
readable files that can be edited.  This makes them slower to use in spell-
checking and less space efficient to store, but easier to modify, and
different supplements may be maintained for different purposes.  (See R-c,
Spell Check.)

1.46.5 Merge Supplement with Dictionary (R-d)

R-d merges a stacked list of words (dictionary supplement) in curFile with
the dictionary files dict.A-dict.Z.  Dict.A-dict.Z must be in the current
directory.  The words should be in a stacked list with one word on each line.
The list should be in at least first-letter alphabetical order, for best
speed.  (Use Check & Collect (R-l) to create the list, and it is created in
alphabetical order.)

Words already in dict.A-dict.Z are not added by R-d.  Before using R-d, make
a backup copy of dict.A-dict.Z for safety.  Also before using R-d, edit the
list of words, removing any that should not be merged with the dictionary.
But if words are added by R-d which need to be removed later on, use Del From
Dict (R-e).  After dict.A-dict.Z have been updated, run UdBuild to rebuild
the working dictionary.

1.46.6 Delete from Dictionary (R-e)

R-e deletes a stacked list of words in curFile from the dictionary files
dict.A-dict.Z.  Dict.A-dict.Z must be in the current directory.  For best
speed, the words should be in first-letter alphabetical order.  Use R-e to
remove words mistakenly added using R-d.

1.46.7 Free Speller (R-f)

R-f removes the table and working dictionary from Uedit's memory.  If Udict
was being accessed on disk, it closes the Udict file.

1.46.8 Dict.A-Dict.Z

Dict.A through dict.Z are readable, editable dictionary files.  They have
over 40,000 words in them.  UdBuild reads dict.A-dict.Z and builds a working
dictionary and dictionary table.

In dict.A through dict.Z, words beginning with A must be in dict.A; words
beginning with B in dict.B, and so on.  Words must be in strict alphabetical
order.  They must be 32 characters or less in length.  Only the letters A-Z
and the apostrophe (') are allowed in words.  Upper and lower do not matter;
case is ignored.  Words beginning with apostrophe (') must be put at the
front of dict.A in alphabetical order.  Hyphenated words must be entered as
separate words.

1.46.9 Udict and Udtable

Udict and Udtable are the default working dictionary and table names.  The
speller programs (Uspell, Ufind, and UdBuild) can accept different working
dictionary and table names, if the -d and -t flags are used.  Uedit can use
different names for these also; but the Load Speller (R-u) command would have
to be customized in order to accept different dictionary and table names.
(See the Config!S file.)

A given working dictionary and table go together.  Uedit, Uspell and Ufind
may not work correctly, if a table from one UdBuild session is used with a
working dictionary from another.

When new words are added to dict.A-dict.Z and the working dictionary is
rebuilt with UdBuild, the size of Udtable may not increase much or at all due
to the new words, because Udtable contains a table of 3-letter prefixes and
only so many of these are used in words.  Udict does grow when words are
added, however, and the maximum size for a working dictionary is over a
billion bytes or several hundred million words.

1.46.10 UdBuild

UdBuild reads dict.A-dict.Z and creates a dictionary table and working
dictionary.  To run UdBuild, in CLI type:  UdBuild

If dict.A and dict.Z are not in the current directory, you may specify the
directory they are in by typing:  UdBuild MySpellDir

To create a working dictionary and table using different names, type:
    UdBuild MySpellDir -dMyUdict -tMyUdtable

Building a dictionary takes several minutes.  Messages indicate which file
(dict.A-dict.Z) is being processed.  UdBuild errors that may be reported are:

* Word too long.  Words must be 32 characters or less.  If an over-long word
    is found, it is discarded and processing continues.
* Words not in alphabetical order.  In this event, words are skipped until
    one is found that restores alphabetical ordering.
* Illegal character in dict.A-Z.  Bad characters are skipped over.
* No more room to write the dictionary or table.

Processing continues, despite errors, so that all error messages are
reported.  If errors are found, edit the faulty dict.A-dict.Z files and run
UdBuild again.

1.46.11 Uspell

Uspell reads a text file and spell-checks the words in it.  It outputs the
words that are not in the dictionary.  If -oOutputFile is used, it outputs
the bad words to OutputFile, searching it first to see if the word has
already been added; thus, Uspell can create and update a dictionary
supplement.  (Note:  The words are not added in alphabetical order.  The list
may be alphabetized by using Sort Lines (SA-s) on it in Uedit.)

Uspell looks for Udict and Udtable in the current directory.  Using the -t
and -d flags, a different table, working dictionary, and directory may be
specified.  Using all options, running Uspell looks like this:
    Uspell MyDocument -oRAM:OutputFile  -dRAM:MyDictionary -tDF1:MyTable

For Uspell to work quickly, Udict should be copied to RAM:, because Uspell
accesses it randomly.  Uspell reads Udtable only once at startup, so Udtable
may be on disk.

Bad words are stored in the output file only once.  The output file must be
searched before each new word is added.  This makes performance slow, if the
output file is on disk and has a number of words in it.  The output file
should be copied to or created in RAM: to get better speed, if an output file
is used.

1.46.12 Ufind

Ufind finds words in the working dictionary using wildcards.  It looks for
Udict and Udtable in the current directory.  The wildcards are "*" and "?"
for multiple and single characters, respectively.  Example:  To find words
ending with "ment" or "mint" type:
        Ufind *m?nt

A different working dictionary and table may be specified by using the -d and
-t flags.  An output file may be specified by using the -o flag.  Using all
options, using Ufind would look like this:
        Ufind *mask* -tMyTable -dMyDictionary -oMyOutput

If Udict is in RAM:, lookups with Ufind are a little faster, but not that
much because Ufind reads the dictionary serially; it works fairly well even
with Udict on disk.  Ufind reads Udtable only once at startup, so Udtable may
also be on disk.

1.47 Hyper Text

A Uedit hyper text facility consists of a binary lookup table and a text file
that is organized to be used as a hyper text file.  The lookup table is built
with the UHC (Uedit Hyper Create) program.  As you will see, it is quite easy
to create a custom hyper text facility.

A sample hyper text facility is provided on the Uedit disk.  To use it,
HyperSample and HyperSample.tbl must be in S: or the current directory.  You
must open hyper text using Open HT (R-gadget3).  Then use Click Hyper Word
(R-buttonDown) or Input Hyper Word (R-gadget1) to select hyper word and bring
up the the hyper text window.  When completely finished using hyper text,
close it with Close HT (R-gadget4).

While in the hyper text window, use the following commands:
    ESC:            close hyper text window
    buttonDown:     scroll or place cursor
    arrow keys:     move cursor and scroll
    R-buttonDown:   look up word that is clicked
    Return          look up the cursor word
    f1:             go to beginning of lookup table
    f2:             go to parent of current hyper word
    f3:             go to child of current hyper word
    f4:             go to next sibling of current hyper word
    f5:             go to previous sibling of current hyper word
    f6:             step back through last 20 hyper words looked up
    f7:             get hyper word input and look it up
    f8:             go forward to next hyper word in lookup table
    f9:             go backward to previous hyper word in lookup table

1.47.1 Open HT (R-gadget3)

R-gadget3 loads in the sample hyper text file, HyperSample, and its lookup
table, HyperSample.tbl.  (These must be in the current directory, unless you
customize this command to make it look elsewhere for them.)

1.47.2 Click Hyper Word (R-buttonDown)

R-buttonDown opens the hyper text window and looks up the word that was
clicked.  If it happens to be a hyper word, its text, if any, is displayed.
A hyper phrase (2 or more words) can be click-selected, if it is enclosed in
angle brackets <>.  Use ESC to close the hyper text window.

1.47.3 Input Hyper Word (R-gadget1)

R-gadget1 asks for a hyper word input.  Type in a word or phrase and press
ESC.  The hyper text window opens and displays the hyper text, if any, for
that word.  To close the hyper text window, press ESC.

1.47.4 Close HT (R-gadget4)

R-gadget4 closes the hyper text facility, freeing its memory.

1.47.5 Hyper Words

A hyper word is any word (or phrase) for which you would like to be able to
look up help information.  The first 17 characters of a hyper word (or
phrase) are stored in a lookup table along with the byte offset into the
hyper text file where the word is defined.  Single words in any buffer can be
click-selected and looked up instantly.  Hyper phrases (2 or more words) can
be click-selected, if they are enclosed in angle brackets <>.  (See Click
Hyper Word (R-buttonDown) and Input Hyper Word (R-gadget1).)

1.47.6 Hyper Text Files

A sample hyper text file and lookup table are provided on the Uedit disk.
The text file is HyperSample and its lookup table is HyperSample.tbl.
HyperSample contains help for the standard Uedit commands and hyper text.
Load HyperSample into Uedit and look it over, as you read these sections
about hyper text.

A hyper text file is a text file consisting of sections defining hyper words.
Up to 65535 hyper words may be defined in a hyper text file.  A section
begins with a formfeed (ASCII 12).  Next is the Parent Line containing the
<parent hyper word> in angle brackets.  (The parent hyper word must be
defined before its children are.)  Next is the Word Line with the new <hyper
word> being defined; the new <hyper word> must be at the start of its line in
angle brackets.  Other <related hyper words> or text may follow on the Word
Line.  Below the Word Line is any amount of text, which may contain hyper
words with or without angle brackets.  A formfeed (ASCII 12) beginning the
next section (or end of file) marks the end of the current section.  Sections
should be brief, 10 or 20 lines, but no size limit is imposed.

Section outline:
FORMFEED                                                ((start of section))
<parent hyper word>                                     ((Parent Line))
<new hyper word>  <related word> <related word> ...     ((Word Line))
text.....................................
text.....................................
text.....................................
FORMFEED                                                ((next section))

The very first section in a hyper text file has an empty Parent Line, because
it has no parent.  All other sections must have a <parent hyper word> in
their Parent Line.  Hyper phrases (2 or more words) that are included in the
text area should be enclosed in angle brackets <>, if they are to be
selectable.  Single hyper words do not need brackets in order to be
selectable.  Formfeeds must not be used in the text area, because a formfeed
marks the start of a new section.

1.47.7 Parent, Child, Sibling

Each hyper word has a parent.  Only the very first hyper word has no parent,
because it is the parent, grandparent, etc, of all other hyper words.  Each
hyper word (except the very first) may have siblings who share the same
parent.  Each hyper word may have children.  A parent must exist before its
children are defined, or else UHC cannot build the lookup table.  The
organization of a hyper text file is very much like that of a manual or text
book:  First you define the children of the most recent hyper word before
going on to define its siblings, just as in a reference manual you cover the
subsections of the current section before starting on the next main section.
(See UHC, 1.47.10.)

1.47.8 Uniqueness

Upper/lower case is ignored in hyper words.  But spaces in hyper phrases do
matter; use just one space between words in a hyper phrase.  A hyper word
cannot use the same spelling as its parent, child, or sibling.  Other than
that, hyper words do not have to be unique.

Technical info:  Associated with each hyper word is its index in the lookup
table.  When calling the hyper() CL function to do a lookup, you may include
both a hyper word and an index argument.  If the hyper word is not unique,
the index helps in locating the right incarnation of the word.  Example:
Suppose Help has children Cursor and Scroll.  Cursor and Scroll each have a
child Commands.  The child (Commands) of Cursor can be found if you call
hyper(), passing it the hyper word "Commands" and the table index of Cursor
along with a flag value of 2.  Flag=2 causes a lookup algorithm to be used.
Flag=1 would probably also find the right Commands (the one that is a child
of Cursor).

1.47.9 Lookup Table

After a hyper text file has been written using Uedit, a binary lookup table
is built for it using the UHC program (Uedit Hyper Create).  Each time you
modify a hyper text file, you must rebuild its lookup table, because the
table stores byte offsets to sections in the text file.

Technical info:  UHC gets the following information for each hyper word and
stores it in the binary lookup table:  the first 17 characters of the hyper
word (or phrase); byte offset to its section in the hyper text file; parent's
index; child's index (if any); next sibling's index (if any); previous
sibling's index (if any); level or generation.  The index is simply the entry
number in the binary lookup table.  There may be up to 65535 hyper word
entries.  The first hyper word has level 0; its children have level 1; their
children have level 2; and so on.  (See hyper() in 3.4 concerning the various
lookup methods and related info.)

1.47.10 UHC (Uedit Hyper Create)

The UHC program creates a binary lookup table for a hyper text file.  The
hyper text file must consist of sections as described earlier.  For example,
to use UHC to rebuild the lookup table for HyperSample, type the following in
CLI:
    UHC HyperSample HyperSample.tbl

After you have created a custom hyper text file, run UHC to create its lookup
table.  Each time you modify the hyper text file, you must again run UHC to
rebuild its lookup table.

UHC reports any error that it finds.  A common error is failing to define the
parent hyper word before defining its child, or misspelling the parent hyper
word.  UHC reports the hyper text file line number of the error.

1.47.11 Creating a Custom Hyper Text Facility

Only 3 simple steps are involved in creating a custom hyper text facility:
(1) Create your custom hyper text file using Uedit.  Load HyperSample into
Uedit and use it as an example.  (2) Save your hyper text file to disk and
run UHC to create a lookup table for it.  Correct the errors UHC reports
until you succeed in building the lookup table.  (3) Load Config!H into Uedit
and customize the R-gadget3 (Open HT) command.  Make it load your hyper text
file and lookup table instead of HyperSample and HyperSample.tbl.  Put the
cursor above the command and press f6 to compile it.  Select Save Data (A-f6)
to save the modified configuration for permanent use.

That's all there is to it.  Now you can use your custom hyper text facility.
Open hyper text using R-gadget3.  You can use the other hyper text commands
just as they are to access your new hyper text facility.

1.48 Grep

With grep you can search for patterns in the text and optionally clear or
replace or rearrange parts or all of the matched area.  Being slower and not
as simple, grep should only be used when the search string is too complex for
the faster search method which uses simple wildcards (? and *) or when the
replace operation you need cannot be done using the simple Search and Replace
commands (f9 and f10).

Uedit's grep uses a superset of the standard symbols for pattern matching.
Also other greps usually require using symbols like \f, \r, and \n for
formfeed, return, and newline, but with Uedit's grep you can simply type
control characters into the search and replace strings.  Grep searching may
be aborted with Amiga-ESC.

1.48.1 Set Grep (L-f7)

In a grep string, the first character is taken as the delimiter.  It delimits
the replace string, if any, from the search string.  A trailing delimiter is
optional.  In the following example, the search string is "abc", the replace
string is "def", and slash (/) is the delimiter:  /abc/def/

L-f7 displays the existing grep search and replace strings separated by
delimiters.  The cursor is automatically placed at the beginning of the
search string.  Type in the desired search and replace strings and terminate
the input with pmESC.  When you terminate the input a search forward is done.

Grep search and replace strings may be up to 63 characters in length, not
counting the delimiters.  To embed a delimiter in a search or replace string,
put a backslash (\) before it.  For example, the following grep string
searches for "abc/":  /abc\//

You can use the delimiter to define or cancel search and replace strings:
    /       cancel existing search and replace strings
    ///     keep existing search string; cancel existing replace string
    /abc/   input search string abc; keep existing replace string
    /abc//  input search string abc; cancel existing replace string
    //def/  keep existing search string; input replace string def

The search and replace strings may use bracketed Regular Expressions (RE)
\(..\) and special symbols for pattern matching.  These will be discussed
later on.  (See Regular Expressions, Symbols, and Examples, 1.48.6.)

Case sensitivity:  If case sensitivity is Off, upper and lower case are
treated equally in grep searches just as they are in ordinary searches.  If
case sensitivity is turned On, upper and lower case are not the same.  (See
Case Sensitivity (C-8).)

1.48.2 Grep Fwd (L-f9)

L-f9 does a grep search forward.  If the search fails, "Search failed" is
reported.  If the search is successful, the matched area is colored as an
invert region and the cursor rests at the start of the matched area.

1.48.3 Grep Bkwd (R-f9)

R-f9 does a grep search backward.  If the search fails, "Search failed" is
reported.  If the search is successful, the matched area is colored as an
invert region and the cursor rests at the end of the matched area.

1.48.4 Grep Search & Replace Fwd (L-f10)

L-f10 does a grep search forward.  If successful, it replaces the matched
area with the replace text.  If no replace string is defined, the matched
area is cleared.

1.48.5 Grep Search & Replace Bkwd (R-f10)

L-f10 does a grep search backward.  If successful, it replaces the matched
area with the replace text.  If no replace string is defined, the matched
area is cleared.

1.48.6 Regular Expressions, Symbols, and Examples

A regular expression (RE) defines a set of one or more strings of characters.
A regular expression is said to match any string it defines.  A grep search
string is a regular expression and may contain embedded bracketed REs \(...\)
as well.  The following standard symbols are special when used within regular
expressions:
        Special symbol   Function
        --------------   --------
        .                (period) match any single character except eol or formfeed
        [abc] or [a-c]   define a character class that matches a b or c
        [a-x]            define a character class that matches a to x
        [^abc] or [^a-c] define a class matching anything but a b or c
        *                (asterisk) match 0 or more occurrences of a match of the
                            preceding character or RE
        ^                (carat) force a match to start of line
        \                to quote special characters
        \(abc\)          match what abc matches (a bracketed RE)
        \1 to \9         represents the 1st (to 9th) matched bracketed RE
                            in the search string

To include a special symbol or delimiter literally in a search string,
precede it with a backslash (\).  In Uedit, control characters such as
formfeed, newline, tab, and carriage return may be typed into buffers, so it
isn't necessary to use special symbols for them in search strings.  For
instance, to force a match to end of line, just type an eol (ASCII 10) into
the search string; similarly, for tab, formfeed, carriage return, and most
other control characters, just type them into the search string.  (\r may be
used for carriage return and \n for newline, if you wish.)

Uedit uses an enhanced set of special symbols, and the following additional
symbols are special when used within regular expressions:
        Special symbol   Function
        --------------   --------
        \n or ASCII 10   force a match to end of line
        \r or ASCII 13   match to a carriage return
        :c               match to any control character
        :@               match to any control character except LF or  FF
        :w               match to whitespace (space or tab)
        :b               match to a backspace (ASCII 8)
        :!               match to ASCII 0-31 or 128-255 except LF or FF
        :?               match to any character, including LF and FF
        :l               match to any lower case alpha
        :u               match to any upper case alpha
        :A               match to any alpha (upper/lower case) or apostrophe
        :a               match to any alpha (upper/lower case)
        :N               match any alpha (upper/lower) or digit or apostrophe
        :n               match any alpha (upper/lower) or digit
        :d or :#         match any digit
        :o               match any octal digit (0-7)
        :x or :h         match any hex digit (0-9 A-F or a-f)
        |                OR, divides 2 or more alternative search strings
                            (when used inside an RE it divides that RE only)
        :s               force a match to start of file
        :e               force a match end of file
        \<               force a match to start of word
        \>               force a match to end of word
        :<               previous character
        :>               next character

The :< and :> symbols let you test the previous or next character to see
whether it satisfies a given condition such as belonging to a set [].  If :<
is used at the start of a search string, the character is not selected but
you can test it.  If :> is used at the end of a search string, the character
again is not selected but you can test it.  If used in the middle of a search
string, :< enables you to back up and perform another test on the previous
character.  Examples:
    /:<[a-z]xyz/            Selects xyz only if the char before it is a-z.
    /abc[a-z]:<[^tx]def/    Selects abc?def; ? is any of a-z but not t or x.
    /abc:>[a-z]/            Selects abc only if the character after it is a-z.

In replace strings, the following symbols are special:
        Special symbol   Function
        --------------   --------
        &                stands for the entire matched text from the search
        \1 to \9         represents the 1st (to 9th) matched RE from the search

The OR (|) symbol and RE numbering:  Ordinarily \1...\9 represent the matched
area of the 1st through 9th REs, numbering the REs in the search string from
left to right.  If referenced in the replace string, \1...\9 have the same
meaning.  Example:
        /\(abc\)def\(ghi\)\1/\2\1/
This matches abcdefghiabc and replaces it with ghiabc.  Another example:
        /\(now\) is the time/&, \1/
This matches "now is the time" and replaces it with "now is the time, now".
Note that the ampersand (&) in the replace string refers to the entire
matched area.

But when the OR (|) is used in a search string, it may change how REs are
numbered.  For instance, if there is one RE on each side of an OR (|), both
REs are assigned the same RE number because only one of them is ever matched.
An OR (|) divides only the RE it is in; if in the outer search string, it
divides the outer search string; if inside a bracketed RE, it divides only
that RE.  Multiple ORs may be used within the same RE.

In the following example, you can see how RE numbers (1-9) are assigned when
the OR (|) is used.  For clarity, RE brackets \( and \) have been shortened
to ( and ), and no text was used in the search string.  The numbers on the
second line are the RE number of the RE that is beginning '(', or ending ')',
or current '|'; RE #0 refers to the outer search string:
             / ( ( ) | ( ) ( ( ) ( ) | ( ) ) ( ) | ( ) ) ( ) | ( ) /
               1 2 2 1 2 2 3 4 4 5 5 3 4 4 3 6 6 1 2 2 1 7 7 0 1 1

In the above skeletal example, notice how RE numbers are reused following an
OR.  Study the example carefully to understand how numbers are assigned to
REs.  The way in which REs are numbered is important, if you use the \1...\9
symbols in a search or replace string.  The numbering may be tricky if ORs
are used, but it is monotonically increasing when OR is not used.

When OR is used, a particular match may result in a certain RE's not being
matched.  If an unmatched RE number appears in a replace string, it is
ignored when the replace is done.  Example:
    /\(abc\)x|y\(def\)z\(ghi\)/\2\1/
    If abcx is matched:  \1 is abc, \2 is undefined.  The replace text is abc.
    If ydefzghi is matched:  \1 is def, \2 is ghi.  The replace text is ghidef.

The backslash (\):  If a backslash precedes a character, the character is
taken literally, provided the backslash and character do not make up a
special symbol such as \(, \), or \1...\9.  Two backslashes \\ embed a single
backslash in a search or replace string.  Backslash followed by a delimiter
character embeds the character literally.

Grep string examples:  (Note that when the asterisk (*) is used, forward
searching selects the longest match, but backward searching selects the
shortest match.)

    String              Match
    ------              -----
    /.alk/              talk, walk, balk
    /abc\/def/          abc/def
    /[bB]ill/           bill or Bill
    /t[aeiou].k/        talk, took, teak, tank
    /number [03-5]/     number 0, number 3, number 4, number 5
    /[^a-zA-Z]/         any character not in a-z or A-Z
    /ab*c/              ac, abc, abbc, abbbc
    /ab.*c/             longest string beginning with ab and ending with c
                        abc, abxc, ab495c, ab 700 x c
    /t.*ing/            ting, thing, thought of going
    /[a-z A-Z]*/        longest string consisting of letters & spaces
    /(.*)/              longest string bounded by ( and ):
                        (this) and (that)
    /([^)]*)/           shortest string bounded by ( and ):
                        (this), (this and that)
    /^This/             line beginning with This
    /stop\./            stop.
    /^[0-9][0-9]*\./    any 1 or more digit number at the beginning of a line
                        and followed by a period
    /\\/                \
    /\*/                *
    /\[0\]/             [0]
    /and\/or/           and/or
    /Th.*is/            longest string beginning with "Th"
                        and ending with "is"
    /\(abc\)/           what /abc/ would match
    /a\(b*\)c/          what /ab*c/ or /a\(b\)*c/ would match
    /:d:d*/             any 1 or more digit number
    /[0-9][0-9]*/       any 1 or more digit number
    /0[xX]:x:x*/        any hexadecimal number
    /this|that/         this or that
    /\<con/             words beginning with con
    /ion\>/             words ending with ion
    /hero\(es\)*/       hero or heroes
    /Help!*/            Help, Help!, Help!!
    /Help!!*/           Help!, Help!!, Help!!!
    /abc\(def|ghi\)/    abcdef or abcghi


Advanced examples:
    /^\(.*\n\)\1/\1/    finds pairs of identical lines and deletes one of them
    /find me/& first/   changes "find me" to "find me first"
    /[0-9][0-9]*/nnn&nnn/   brackets any 1 or more digit number with nnn


1.49  Folds

To fold a file means to "hide detail", creating a sort of outline consisting
only of the desired text lines, such as headings (in documents) or function
names (in program modules).  When curFile is folded, the resulting text is
put into a new file buffer using curFile's name with a ".fold" extension.

Folding is line-oriented, for the most part.  The folding process consists of
examining each line of text in curFile, and applying one or more tests in
order to see whether to skip (fold) the line or keep it, putting it into the
curFile.fold buffer.

1.49.1  Set Fold (L-\)

L-\ displays the current testing steps and lets you modify them.  Up to 16
testing steps can be applied in the folding process.

Each testing step has associated with it the following:
    Step number (1 to 16).
    Description of the testing option F used in the step.  (See the table below.)
    X value; X is a number, if indentation or line-length is used by test F,
        and X is a text string for the other tests.
    SKA value; 0=Skip, 1=Keep, 2=And.

The testing options F are the following:
1   line is blank                       (X ignored)
2   indentation = X
3   indentation < X
4   indentation > X
5   line-length = X
6   line-length < X
7   line-length > X
8   1-4 character string X (eg, "x" or "abcd") is in the line
9   1-4 character string X is at start-of-line
10  1-4 character string X is at end-of-line
11  character in range X (eg, "AZ" or "09") is in the line
12  character in range X is at start-of-line
13  character in range X is at end-of-line
14  rgn bounded by quotes or brackets in X (eg, "\"\"" or "[]") is in line
15  rgn bounded by quotes or brackets in X may be in multi-lines

L-\ displays the currently existing testing steps and the testing options F
that testing steps may use.  The testing steps are numbered 1 to 16.  Step
numbers may be skipped; that is, you may define steps 2 and 4, leaving steps
1 and 3 undefined and available for future changes.

Each testing step that exists uses a testing option F (1 to 15), from the
table above.  To remove testing step T, specify the step number T and specify
-1 for the testing option.  Alternatively, you can define step T again and
the new definition supercedes the old one.

Each testing step also uses an X value (text string or indentation or line-
length, depending on the testing option F) and an SKA value.  (See the table
above.)

SKA is used ONLY if the test succeeds:  That is, the line is a blank line (if
F=1) or the line's indentation is > X (if F=4), and so on.  The line is
simply skipped by default (does not end up in curFile.fold), if none of the
testing steps succeeds.

SKA means SKIP/KEEP/AND.  Assuming that a testing step succeeds, SKIP means
to skip the line; KEEP means to keep it - that is, to put it into the
curFile.fold buffer; AND means to AND the current testing step with the next
one.  Both AND and OR behavior may be used in conjunction with the testing
steps:

OR:  The testing steps (which exist) are performed on each line of text in
curFile, starting with step 1.  The serial order is like ORing the sequence
of tests.  If the current test succeeds and SKA=SKIP or KEEP, the line is
skipped or kept (put into curFile.fold) accordingly.  No other tests are
tried on that line of text.  If the current test fails, the next testing step
is tried.  This is OR behavior.

AND:  If SKA=AND, the current testing step is ANDed with the next testing
step.  If the current test fails, the next step and all subsequent ones that
were ANDed with it are bypassed.  If the current test succeeds, the next test
is tried; and if it also succeeds, then its SKA dictates the action to be
taken (SKIP or KEEP the line, or AND with the next step).

Order of tests:  The order in which the tests are performed is critical.
Also whether SKA is SKIP or KEEP makes a big difference, obviously.  If no
testing step uses SKA=KEEP, no lines are kept and curFile.fold is empty.
When curFile.fold does not look as you had hoped, press L-\ and look at the
current testing steps.  Try these questions:
    1) Should test A come AFTER test B instead of before it?
    2) Is test A SKIPping lines before test B has a chance to KEEP them?
    3) Should a test be redefined to KEEP instead of SKIP or vice versa?
    4) Does at least one test use KEEP?  (If not, no lines are kept!)
    5) Does the last test use SKIP or AND?  (If so, it achieves nothing.)

Folding can look for single or multi-line regions enclosed in single-
character brackets such as quotes or parens.  It does not look for multi-line
regions enclosed in 2-character brackets, such as the comment brackets of the
C (/* and */) and Pascal programming languages.  However, using slashes as
brackets "//" will work in C program modules, if "/" is not used anywhere
except in comment brackets.  (See tests F=14 and F=15 in the F table above.)

Blank lines:  If F=1 (line is blank) and SKA=KEEP in a testing step, this
specifies that blank lines be kept.  This is recommended for readability,
because if several blank lines are in series, only one blank line is kept.

Default testing steps:  If no testing steps have been defined, by default
Uedit defines two steps:  1) keep blank lines, and 2) keep lines with no
indentation.  Folding a program source module using the default tests may
yield a fair outline of the module.  However, the default tests aren't useful
for folding most documents, because they keep all the unindented detail and
skip all the indented section headers.

1.49.2  Fold curFile (R-\)

R-\ folds curFile using the testing steps that are currently in use.  The
folded text is put into a new file buffer named curFile.fold.  Note that
multiple (or nested) folding is possible, by folding curFile.fold, then
curFile.fold.fold, and so on, using different sets of folding tests.  R-\
asks if you want to include line numbers.  If you select line numbers, you
can use the Goto Source (A-\) command below.  (See Set Fold (L-\).)

1.49.3  Goto Source (A-\)

A-\ works as follows:  First, you must have used the line numbers option when
folding the source file.  Put the cursor in any line.  (They are all
numbered.)  A-\ will then take you to that line in the source file.


Part2 & Part22:::

Part 2.  Getting More out of Uedit

2.1  CLI Command Line

A number of command-line flags may be used, when starting Uedit in CLI.  The
flags may be upper or lower case.  Here is an example using all of the flag
options:

run UE -A0xffff0000 -B11 -LmyLearn -K13 -CmyConfig -DmyData -SmyState files....

-A flag: set userGlobalA to value 0xffff0000.
-B flag: set userGlobalB to value 11.
-S flag: load state file "myState" (default is "uestate")
-L flag: run the learned sequence ("myLearn"), if the file exists.
-K flag: run key command (macroNum) 13, if the command exists.
-C flag: load and compile config file "myConfig" and its A-Z segments, if it exists.
-D flag: load data file "myData"; or, if -C is used, name the data "myData" in Uedit.

The -C and -D flags are acted upon first.  -CmyConfig causes myConfig and its
A-Z segments, if any, to be loaded and compiled.  If -C has no file name
following it, the standard config file, Config!, is loaded and compiled.
When -DmyData is used with -C, myData becomes the data file name that will be
used when you save the data during the edit session.  If -DmyData is used
without the -C flag, myData is loaded in instead of the standard data file,
Data!.

The A, B, L, S, & K flags are acted upon after -C and -D have been processed.
-A and -B set the values of userGlobalA and userGlobalB, respectively, which
are CL integer variables.

The sequence of events at startup is as follows:
        Read the flags and set the data file name, if -D is used.
        Load and compile the config, if -C is used; if it is not, load the data file.

    After the config has been compiled or the data file loaded in:
        If -A or -B was used, set the UserGlobal to the specified value.
        Load in the files specified for editing, if any.
        Load the state file specified, if any.
        Run the learned sequence, if -L was used.
        Run the key command, if -K was used.

Note that the files are loaded in before -LlearnedSeq and -KkeyCmd are
processed.  Thus, you can cause files to be loaded in and action taken upon
them, using a learned sequence or key command or both.  The UserGlobalA/B
values are set before -Llearnseq is run or -Kkeycommand is run, so the user
globals can affect the learned sequence or key command, if desired.

The above flags must come before any file names in the CLI command line.  The
learned sequence and key command that are named should exist, although no
harm is done if they do not.  Example:  95 is the MacroNum of the Help key.
"Run Ue -k95" runs the Help key automatically just after Uedit comes up.
(See Keys and MacroNums, 2.31.)

Common example:  Run Ue -c -dS:Data! file1 file2 ...

This loads and compiles the standard configuration, Config! and its A-Z
segments; Uedit looks for Config! first in the current directory and, if not
there, in S:.  After it compiles Config! and its A-Z segments, it asks if you
want to save the new data.  The -d flag tells it that the data file is
S:Data!.  Selecting Yes on the "Save new data?"  question causes Uedit to
save the newly compiled configuration as the file S:Data!.  (Without the "-
dS:Data!", Uedit saves Data! in the current directory by default, when you
select Yes on the "Save new data?" question.)

2.2 More About Primitive Mode

Primitive Mode is what Uedit is, when you take away its commands and are left
with the bare bones of typing, single-character deletes, and cursor
movements.  Normal editing commands, such as Delete Line (C-d) or placing the
cursor with the left mouse button, do not work in Primitive Mode.  PM
originated because a way was needed for the user to "bootstrap" Uedit into
existence, if no config file happened to be available.

Primitive Mode is invoked by either of two CL functions, inputString() or
inputNum().  It is not necessary to use PM for text and number inputs.
Custom input routines could be written in the CL that let you use all of the
editing commands during string and number inputs.  EditBuf() could be used in
place of inputString() or inputNum() in such a routine, but a certain amount
of coding would be required because editBuf() "falls through" to the next
function, whereas inputString() and inputNum() keep accepting inputs until
pmEsc is input.  Another approach would be to use the single-input function
getKeyVal() and a split window; in the input routine, characters that you
input would be typed in using typeChar() and keys that you input would be run
using runKey().  When only a single character or key input is required,
getKeyVal(), getChar(), and getKey() are more user friendly than either
Primitive Mode or editBuf(), because Primitive Mode has to be terminated by
inputting pmEsc or a mouse click and a routine using editBuf() would require
some method of terminating input as well.

Primitive Mode is convenient to use for string and number inputs, however,
for a number of reasons:  InputString() and inputNum() "hang up" until the
user is finished inputting, whereas editBuf() does not.  PM allows direct
typing of control characters, handles the display by itself, and only
consumes as many lines in the window as are typed in.  Nonetheless, if you so
desire, the use of PM could be eliminated by replacing all occurrences of
inputString() and inputNum() in the standard config with a different method
of collecting string and number inputs.  (See the CL input functions in 3.4.)

2.3 Config, Data, and Customizing

A config is a readable, editable source file that is the source of the
default values and command definitions that Uedit is to use.  A config has a
root file (segment), such as MyConfig, and may use up to 26 extension files
(segments), MyConfigA through MyConfigZ.  (See Config Segments, 2.5.)

Uedit can compile a whole configuration at startup or during an edit session
you can compile individual commands or the config defaults.  When Uedit is
compiling, it compiles only the parts that are enclosed in angle brackets
"<...>".  Anything outside the angle brackets is ignored.  When compiling a
config at startup, Uedit pulls in and compiles each of the config's segments,
if any exist, automatically.

The first thing in the root segment of a configuration must be a list of
defaults, which are flags and numerical settings enclosed in angle brackets.
Following the defaults in the root segment, any number of command definitions
may appear, in any order.  There may be up to 26 additional config segments,
ending with the letters A-Z.  Command definitions are written in CL and are
enclosed in angle brackets.  The smallest possible config would contain, as a
minimum, a list of default values like those at the beginning of Config!.
(See Config Defaults, 2.4.)

The standard configuration provided with Uedit is Config!, and it uses the
following segments:  Config!H (hyper text, grep, bookmarks), Config!M
(miscellaneous), Config!P (printing, paging), Config!R (Rexx), Config!S
(spelling, split windows), and Config!Z (new or modified commands, if it
exists).

A data file is the compiled, binary image of a config.  When a config is
compiled by Uedit, first it reads the default values and then it reads the
command definitions, compiling them into binary pcode.  It is in this binary
form that Uedit's "data" is stored on disk as a data file, such as MyData or
Data!.  Data files contain the version number of the Uedit program that
created them and they cannot be used with other versions of Uedit.

Uedit's "data" at any given time consists of all commands and values it is
currently using.  The numerical and flag values, such as lineLength,
wordWrap, margins, and colors, defined originally in the config's defaults,
are part of Uedit's "data".  If you make changes to the "data" during an edit
session, such as by compiling a new command or swapping keys or changing
colors or lineLength, you can save the data to disk by using Save Data (A-
f6), and your custom modifications are preserved for future use.

The standard data file is Data!.  Data! can be recreated anytime by compiling
Config!.  Uedit loads Data! automatically at startup, unless told to do
otherwise by the command-line flags or unless it cannot find Data!.  If it
cannot find the data file, it loads in Config! automatically and compiles it.
(See CLI Command Line, 2.1.)

By writing a custom config or by modifying the standard config, you can
customize Uedit completely, creating a special work environment or emulating
a favorite editor or wordprocessor.  To make Uedit compile the new config at
startup, in CLI type:
        Run UE -cMyConfig -dMyData

When Uedit finishes compiling MyConfig and asks whether to save the data,
answering Yes saves the data as MyData.  Afterward, to start Uedit up using
MyData, type:
        Run UE -dMyData

Any amount of customizing is possible during edit sessions, without needing
to close the files you are editing.  The changes can be saved by using Save
Data (A-f6).  But if at some future time you recompile MyConfig, you regain
the old defaults and commands that are in MyConfig, and these do not include
the changes that were saved in MyData during edit sessions.  It is better to
customize Uedit by editing MyConfig, putting in the desired default values
and commands, recompiling it, and saving the data as MyData.  Then MyData can
be reproduced correctly anytime by recompiling MyConfig.

When Uedit is doing a startup-compile, it can be interrupted using Amiga-ESC.
Or if the compiler finds an error, it stops at the error point.  In either
case, make the necessary corrections, put the cursor on or before the left
angle bracket "<" of the command you want to resume compiling with, and press
ESC to resume compiling.  If instead you press Amiga-ESC a second time, Uedit
asks if you want to quit.  If the current config segment has been modified,
it asks if you want to save the changes before it quits.  (See Compile
Errors, 2.27.  See Config Segments, 2.5.  See Building Key-Help for Teach
Keys, 2.11.)

It is a good idea to define a cursor-movement and scrolling command, such as
the mouse button (normal-buttonDown) command, first thing in your config,
right after the config's defaults.  This way, if an error is found during a
startup-compile, you are not stuck using the less convenient cursor movement
abilities of Primitive Mode.  (See Config!.  See Primitive Mode, 1.7.)

2.4 Config Defaults

The first thing in the root segment of a config must be a list of default
values and flag settings.  In editing the defaults, the order in which the
defaults appear must not be changed.  The angle brackets "<>" must be
preserved.  Do not use angle brackets anywhere in configs, except to enclose
defaults or commands.  You may keep two versions of any default or command
and "comment out" one of them by putting two dots "..<" in front of its left
angle bracket.

If you edit a config's defaults and want Uedit to pick up on the changes,
select Cfg Defalts (AC-f6); Uedit compiles the defaults and closes and
reopens its window using the new defaults.  If a bad default is found, the
screen flashes and the cursor stops on the error.

The following are the defaults which are in Config!.  Unless told otherwise,
0 means "No" and 1 means "Yes".  If an integer value is required, it may be a
positive, zero, or negative 4-byte integer in either decimal or hexadecimal:

<1>     Make Key-Help file during this compile.  (For "TEACH KEYS" in menu.)
<S:Key-Help>  Name of Key-Help file to create or look for.  19 chars max.
<1>     Show cursor during compile of this configuration.  Slower, if show.
<RAM:uejunk>  Name for temporary file when one is needed.  19 chars max.
<clean> Font name (19 chars max).
<8>     Font pixel height ( >= 8).
<27>    Primitive Mode (pmESC) terminator character.

<0>     User global flag A.  Any integer value.
<0>     User global flag B.  Any integer value.
<0>     Columnar display mode
<0>     Cram display mode
<0>     Show page-row-column

<0>     Mark gadgets
<0>     Interlace/bitplanes. 0-3.
<1>     Show invisibles
<1>     Show busies
<0>     Teach keys mode

<35>    Maximum files to edit.  1-100.
<0>     Make icons
<0>     Search/grep case-sensitivity flag
<?>     Search single wildcard.      Printable character.
<$>     Search either-or delimiter.  Printable character.

<*>     Search multi wildcard.       Printable character.
<~>     Search all-but delimiter.     Printable character.
<0>     White allowed under single wildcard: 0=no, 1=space/tab, 2=any white.
<0>     White allowed under multi wildcard: 0=no, 1=space/tab, 2=any white.
<75>    Percent offset for submenus.  0-100 percent.

<0>     RESERVED  (l)
<0>     RESERVED  (m)
<0>     Speak requester alerts
<0>     Speak messages
<0>     Print tabs (if 0, tabs are converted to spaces during print)

<1>     Smart tabs (don't convert tabs if inside quotes)
<1>     Screen type, 0=Workbench type, 1= Custom type
<0>     Use printable keys for typing, disabling any commands on them.
<0>     Printer selection.  0=par:, 1=ser:, 2=prt:, 3=prt: (raw).
<100>    Idle-time (tenths of seconds) after which time idle cmd is run. 1-32767

<0>     Hide display.
<1>     Scroll type: 0 = show colors, 1 = faster
<0>     Trap menus to use menu mouse button as a key
<640>   Screen width in pixels (640-1064)
<200>   Screen height in pixels (gets auto-doubled for LACE) (200-1064)

<0>     Task priority when in tiny window (-128 to 127)
<0>     Reserved    (capsLock)
<0>     Reserved    (clickTime)
<0>     User global flag C.  Any integer value.
<1>     User global flag D.  Any integer value.

<0>     Put in tabs, not spaces, when tab key pressed.
<1>     Autoindent mode
<0>     Overstrike mode
<0>     Autobackup mode
<0>     RESERVED  (r)

<1>     Wordwrap mode
<0>     Rightjustify mode
<1>     Map illegal chars (ASCII 0-3) to table values.  (See table below.)
<0>     RESERVED  (c)
<0>     User local flag A

<0>     User local flag B
<4>     Tab ruler to use.    0-4.  (See ruler tables below.)
<77>    Line-length.  1-9999.
<5>     Split window size in lines.  2-100, up to max lines in window.
<0>     Left margin.    0-255.

<0>     top margin.     0-255.
<1>     bottom margin.  0-255.
<66>    lines/page.     1-255.
<10>    End-of-line char.  10 = Newline, 13 = Carriage Return.

These are the 5 TAB rulers.  There can be up to 32 column-entries in each tab
ruler.  The highest column is 255.  The lowest is 2.  In Uedit, to change
tab rulers, select "Tab ruler".  To see the settings, select "See ruler".
To adjust the tabs, select "Set ruler".
<7 13 19 25 31>     Tab ruler 0.
<9 17 25 33 41 49>  Tab ruler 1.
<11 21 31 41 51 61
71 81>              Tab ruler 2.
<>                  Tab ruler 3.
<5 9 13 17 21 25 29
33 37 41 45 49 53 57
61 65 69 73 77 81 > Tab ruler 4.

Uedit uses ASCII characters 0-3 internally for markers.  Files cannot
legally contain these characters.  If the above "Map illegal chars" flag
is not set, any illegal characters (ASCII 0-3) are replaced by "@" upon
loading the file.  If "Map illegal chars" is set, illegal chars are mapped
to the "safe" chars given below upon loading the file.  Upon saving the
file, the chars are remapped back into their old ASCII 0-3 values:
<128>    map ASCII 0  Values must be 128-255.
<129>    map ASCII 1
<130>    map ASCII 2
<131>    map ASCII 3

Printable key arrays:  DON'T TOUCH, unless you know what you are doing!
These are 4 translation tables which convert raw keystrokes into printable
characters.  (See Rom Kernal Manual, Volume 1, page 3-81.)  There must be 64
characters in each row of these tables.  Use OVERSTRIKE typing mode when
modifying these 4 tables, in order to avoid trouble:
Normal and SHIFT keys:
Unused -->     U             U    EUROPE--> EE   U          U
<`1234567890-=\ 0qwertyuiop[] 123asdfghjkl;'  456 zxcvbnm,./ .789>
<~!@#$%^&*()_+| 0QWERTYUIOP{} 123ASDFGHJKL:"  456 ZXCVBNM<>? .789> .."
ALT and SHIFT+ALT keys:  (Put foreign letters in these 2 arrays.)
Keypad keys --> K           KKKKKK              KKK             KKKK     "
<`¹²³¢¼½¾·«»-=\  å°©®þ¤µ¡ø¶      æßð     £;'      ±×窺­¸,./     > ..
<~!@#$%^&*()_+|  Å°©®Þ¥µ¦Ø¶      ƧР    £;'      ¬×Ǫº¯¸,./     > .."

Colors:  (values must be 0-3, corresponding to RGB color register numbers)
                                fg        bg
    ((local colors for buffers))
    0  normal text              <1>      <0>
    1  cursor                    <1>      <2>
    2  hilite                    <1>      <3>
    3  cursor+hilite            <3>      <1>
    4  inverse                  <0>      <1>
    5  cursor+inverse            <0>      <2>
    6  hilite+inverse            <3>      <1>
    7  cursor+hilite+inverse    <0>      <3>
    ((screen colors))
    8  title bar                <1>      <3>
    9  msg line                 <2>      <0>
    10 menus                    <1>      <3>
    11 tab ruler                <1>      <2>
    12 requester                <1>      <2>
    13 formfeed                 <1>      <2>
    14 spare1                    <0>      <1>
    15 spare2                    <0>      <2>

RGB colors:  (Range is 0-15.)
Red     Green    Blue
<0>     <5>     <10>    Register 0
<15>    <15>    <15>    Register 1
<15>    <9>     <0>     Register 2
<0>     <9>     <15>    Register 3

Gadget Names in the message line.  19 chars max:
<Next File/MARK>        Name for gadget 1
<Prev File/MARK>        Name for gadget 2
<Down/SET MARK>         Name for gadget 3
<Up/INIT MARKS>         Name for gadget 4

2.5  Config Segments

When Uedit compiles a config at startup, after it has compiled the root
segment (such as Config! or MyConfig), it loads and compiles its segments.
Config segments must be in the same directory as the root segment.  Example:
            MyConfig
            MyConfigA .. if it exists
            MyConfigB .. if it exists
            ...
            MyConfigZ .. if it exists

When an error is found during a startup-compile, the cursor stops on the
error in the current segment; for example, MyConfigD.  Correct the error, put
the cursor on or before the beginning angle bracket "<" of the command that
had the error, and press ESC to resume the compiling.

Note:  Suppose an error is found in MyConfigD or you interrupt the startup-
compile using Amiga-ESC; if you load in MyConfigC and resume compiling by
pressing ESC, Uedit does not load in MyConfigD again when it has finished
compiling MyConfigC.  It instead looks for MyConfigE, because it loaded
MyConfigD earlier.

You may selectively compile various config segments using either of two
approaches:  (1) Rename or remove those segments that you do not want Uedit
to find; or (2) press Amiga-ESC while Uedit is loading the segment you want
to skip; this aborts the loading and causes Uedit to load the next segment.

2.6 Partial Data Files

A data file contains all of the current commands and default settings and
values for a particular configuration of Uedit.  A partial data file merely
stores one or more commands.  The advantage of partial data files is that
blocks of commands may be kept off-line and pulled in as needed.  When key
commands are read in from a partial data file, they replace the old commands
on the same keys.  Keys may be read in individually or in blocks.  (See
saveKeys() and loadKeys() in 3.4.)

Blank, unused keys may be stored in partial data files also.  When blank keys
are loaded in, they wipe out their existing counterparts.  Thus a partial
data file, when loaded in, can cleanly replace an existing set of commands or
bring on-line a new block of commands.  Partial data files have the Uedit
version number in them, just as data files do, so they may only be used with
the version of Uedit that created them.

Compile the following examples, to learn how to use partial data files.  To
create different partial data files, change the "pData" file name.  (See
PreKey, 2.32.)

This PreKey command saves to the pData file every key that is pressed, until
you press SAC-ESC, which kills the PreKey command:

<PreKey: if (eqNum(MacroNum,shftAltCtl-esc)) killKey(PreKey) .. escape hatch
         putMsg("Saving every key pressed - press ShftAltCtl-ESC to quit")
         saveKeys("pData",MacroNum,0)
         equateNum(MacroNum,0)
         equateNum(InputChar,0) >

This PreKey command loads in every key that is pressed, if it is in the pData
file, until you press SAC-ESC, which kills the preKey command:

<PreKey: if (eqNum(MacroNum,shftAltCtl-esc)) killKey(PreKey) .. escape hatch
         putMsg("Loading every key pressed - press ShftAltCtl-ESC to quit")
         loadKeys("pData",MacroNum,0)
         equateNum(MacroNum,0)
         equateNum(InputChar,0) >

The same key may be stored repeatedly, although this is not recommended.
Each key command is added to the end of the file.  When keys are read in, the
last copy of each key is used.  No harm is done by storing the same key
repeatedly, but it makes the file bigger.  Once you are straight on which
keys you want to store, create a fresh partial data file from scratch that
does not have duplicates in it.

Saving keys one at a time is efficient.  Loading is more efficient if all
keys are loaded in together.  You can load them all in by using
loadKeys("pData",1,1199), where 1 is the lowest allowed MacroNum and 1199 is
the highest MacroNum.  Loading the keys in this way does not erase any keys
in memory that are not represented in the partial data file.  (See Keys and
MacroNums, 2.31.)

To save every key command in Uedit, including all of the (many) blank, unused
keys, use saveKeys("pData",1,1199).  To save just the keys that actually have
commands, you could use:  do (n54,1,1199) if (inUse(n54))
saveKeys("pData",n54,0).  But this would take forever to run, because each
time the saveKeys() function is called, the pData file is opened, appended
to, and closed; it would be better to save contiguous blocks of keys.

2.7 Editing Tricks

It wouldn't be possible to list every editing trick you will think of once
you are an experienced user of Uedit.  However, it is hoped that this section
will get you started looking for the easy way out of drudge work and on the
road to getting the most out of this program.

If you are not yet ready to bother with the command language, even though the
CL examples here are quite brief and simple, just skip over any examples that
use the CL.  Pay particular attention to the Learn Mode examples.  Learn Mode
is simple to use, requires no familiarity with the CL, and offers such power
and convenience that it rivals the command language in the potential benefits
it affords the user:

*** Saving learned sequences can be useful.  The Learn menu selection Load &
Run (C-7) loads and runs a learned sequence stored on disk.

Example:  Select Start Learn (C-s).  Press C-downArrow, which scrolls to end
of curFile.  Click the mouse button low in the window, placing the cursor at
the end of curFile.  Press Return 2 or 3 times and type a letter ending with
your name, address, and phone number.  Select Run Learn (C-r) to end Learn
Mode.  Select Save Learn (C-5) and type in "nameaddr" and ESC.

Put the cursor anywhere in any file and press C-r to run the learned
sequence.  Your letter ending is inserted at the end of curFile.  When the
learned sequence is not the current one stored in Uedit's memory, use Load &
Run (C-7) to load it in and run it.

*** To make the previous example more automatic, type in the following
command, put the cursor above it, and press f6 to compile it.  Press SA-1 to
try it out:
     <shftAlt-1: if (loadLearn("nameaddr")) runLearn >

*** Normally to input a search string, you would select Set Search (f7),
which uses Primitive Mode.  But Primitive Mode is primitive and does not let
you paste in a search string like you can in normal edit mode.

In such cases, select Edit Buffer (SA-f6), type in 49 and ESC.  Buffer 49 is
used for Search string input, in the standard config.  Delete whatever is in
buffer 49 and paste in the search string.  This does not tell Uedit what the
new search string is, however.  Press S-f7 and ESC.  The S-f7 command does
not erase buffer 49 like f7 does, but like f7 it calls the setSearch(buf49)
CL function, which informs Uedit of the search text.  Now you can search
using the search string that you pasted into buffer 49.

*** Referring to the previous example, you may have a frequent need to paste
in search strings.  Select Search Buf (L-2) in the Split Windows menu.  This
opens a split window with buffer 49 in it.  When you need to edit-in a new
search string, activate the split window by clicking the mouse in it, and put
in the search string.  Press S-f7, when you are ready to inform Uedit of this
new search string.

*** Suppose you need to search for occurrences of the ESC character.  ESC is
the pmEsc (Primitive Mode terminator) character, so you cannot type an ESC
into a search string using Set Search (f7), because f7 uses primitive mode
and ESC would terminate it.

But you can temporarily change pmEsc to the Return key.  Press ESC, and it
asks for the new pmEsc character; press Return.  Now select Set Search (f7)
and type in the desired search string, including an ESC character, as needed.
Press Return to terminate Primitive Mode.  Press ESC twice and it restores
pmEsc to the ESC character.

*** To input control characters when in normal edit mode, you must use the
Input Control Character (C-c) command.  Press C-c and the next letter you
type is inserted as a control character at the cursor.  But in Primitive Mode
you can type in control characters directly.  If you need to search for
carriage returns (ASCII 13), select Set Search (f7) and press Ctrl-m and ESC.
If you need to search for formfeeds (ASCII 12), use Ctrl-l.

*** Uedit opens a NoName buffer when you close the last file buffer.  If a
NoName file exists, it loads the NoName file.  If you start Uedit without
naming any files to load in, it loads in a NoName file by default, if one
exists.  Otherwise it just opens a NoName file buffer.

It may be convenient to keep a list of "things to do" and a window full of
directory and file names in a NoName file in each work directory.  Then you
can click-load files as needed, and you can change the click-loading
directory name anytime by Ctrl-clicking directory names, such as "df0:" and
"dh0:myDirectory/", in the Noname file.

Buffer 38 is named S:Directories and it contains a list of directories.  To
see the Directory List in buffer 38, Ctrl-click the mouse in whitespace in
curFile.  This opens a split window showing buffer 38.  The current click-
loading directory is hilited in buffer 38.  To select a new click-loading
directory in buffer 38, Ctrl-click the directory name.  To make Uedit's
current directory (the one you started Uedit in) the default click-loading
directory, Ctrl-click in whitespace in buffer 38 or in curFile.  To make the
split window disappear, click the mouse normally.

When you Ctrl-click a directory name in any buffer, if it is not already
stored in buffer 38, it is added to the list and it becomes the new click-
loading directory.  Note that you can save buffer 38 to disk, as the file
S:Directories, by using F3 when the Directories split window is open; after
that when running Uedit, S:Directories is loaded from disk automatically the
first time a directory name is called for.

*** Suppose that you need to edit 10 or even 1000 files, doing the same
search, replace, and editing operations on each file.  You could get a
directory listing and click-load them one by one and run a learned sequence
on each one.  But you'd have to sit there and do it.  Uedit can do the whole
operation automatically.  Get a directory list or make a list with the file
names in it, stacked vertically, as follows:

File1
File2
File3
....

The list may have hundreds or even thousands of file names in it.  If the
file name list is not in buffer 0, it is a good idea to select Swap Buf #0
(A-w), which makes it the "home" buffer.  Click-load the first file, File1.
Select Start Learn (C-s).  Do the desired search and replace and other
editing steps.  Select Auto Close (S-f3), which saves the file, if it has
been modified, and closes it.  Uedit returns to the "home" buffer with the
file list in it.  Press downArrow to scroll the display up one line.  Click-
load File2; click the file name near the left border, so that any short names
in the list won't be missed when their turn comes.  Select Run Learn (C-r) to
end Learn Mode.

Press C-r (Run Learn) to see how it works.  If it works as planned, select
Command Multiplier (C-m) and set the command multiplier to the number of
remaining files in the stacked list.  Press C-r.  The files will be processed
automatically.

*** The getStackSize() CL function gets the number of entries in the buffer
stack, the number stack, and the file-saving stack.  The delay() CL function
causes a delay of a specified amount of time.  During delay(), Uedit
processes spooled prints and file-saves.  Thus, getStackSize() and delay()
may be used together in order to polish off the spooled file-saves.  The
following command could be included in a learned sequence, in order to clean
up the spooled file-saves during each running of the sequence:

    <normal-esc:
        while (getStackSize(n54,n54,n53) & !eqNum(n53,0)) delay(5) >

As an example of where this command might be useful, suppose that you want to
create a learned sequence that saves a hilite region as a "Junk" file and
uses AmigaDOS to print the Junk file using some kind of filter program.
(Such a need arose in preparing this manual.)  If Junk is saved to disk, the
AmigaDOS program gets executed while Junk is still "in use" in the file-save
queue or the save has not begun yet, so the filter program cannot process the
most recently saved Junk file.  However, the above command would force the
file-save to complete first, and the latest Junk file would be available for
the filter program to process.

*** The cycle counter (SA-c) can be very useful.  To find out how many words
are in curFile, put the cursor at the start of curFile.  Press SA-c and press
kp6 (Cursor Word Right).  The cycle counter runs kp6, moving the cursor word-
right, until it reaches end of file.  It then reports the number of successes
in the message line, which is the number of words in the file.  (It is a
rough word count, because it relies on what Uedit considers to be a "word"
character.  These characters are a-z, A-Z, 0-9, the apostrophe "'", and any
character whose ASCII value is 128-255.)

To count the number of lines from the cursor line to end-of-file, use kp2
instead of kp6.  The cycle counter is also useful with Search (f9) or Search
and Replace (f10).  It reports the number of successful searches.

*** The cycle counter (SA-c) can be used in place of Command Multiplier (C-m)
when running learned sequences (C-r), provided the last step in the learned
sequence "fails" at some point.  The "failed" (False) return is what stops
the cycle counter command.  For example, if the last step in the learned
sequence is cursor-word-right, it will fail at eof.  But in many learned
sequences, the last step may not give a False return.  Or, conversely, it may
always give a False return and therefore cannot be used with the cycle
counter.  If the cycle counter does not quit due to a "fail" as expected,
abort it with Amiga-ESC.  If it runs only once and quits, the learned
sequence must be returning a False in all cases, so you must use Command
Multiplier (C-m) instead of the cycle counter.

*** To run an Amiga utility or other program while working in Uedit, select
AmigaDOS (C-y) and type "run MyProg", where MyProg is the utility you wish to
run.  Since Uedit sleeps inbetween inputs, the utility runs about as fast as
if Uedit were not running.  If a utility is needed frequently, use Learn Mode
to store the above procedure and invoke it at will using Run Learn (C-r).  Or
create a special command to run the utility, as follows:
    <shftAlt-2:  execute(" ","Run MyProg") >

*** Suppose that you need to bracket section titles in a file with control
codes that make it print in boldface.  Put the cursor in a line that you want
printed in boldface.  Select Start Learn (C-s).  Press A-kp4, moving the
cursor to start-of-line.  Press kp1, marking it as start-of-hilite.  Press A-
kp6, moving the cursor to end-of-line.  Press kp3, marking it as end-of-
hilite.  Select Bracket Hilite (L-p) and type "b" for boldface.  Select Run
Learn (C-r) to end Learn Mode.

Now select Swap MouseUp (A-m) and press C-r; this swaps the Run Learn key
with the mouse's buttonUp command.  Scroll through the file, using the arrow
keys, looking for section titles, or search for them using Search.  To
boldface each section title, click the mouse in it.

When finished, select Swap MouseUp and press C-r again, unswapping the Run
Learn key, so that you can once again use the mouse for scrolling.

*** Suppose that you need to collect scattered words into a list.  Put the
cursor in the middle of a word.  Press C-s to start Learn Mode.  Press kp6
(Word Right), kp7 (Delete Word Left), and kp0 (Undo Scratch Deletes).  Press
C-w (swapping to buffer 41), press kp0 to insert the copied word, and press
Return.  Press C-w, to swap back to the original file.  Press C-r to
terminate Learn Mode.

Select Swap MouseUp (A-m) and press C-r.  This swaps the Run Learn key with
the mouse's buttonUp command.  Now you can go through various files clicking
words and they are added to the list in buffer 41.

When finished, select Swap MouseUp and press C-r again, to reverse the swap.

*** When using the arithmetic commands (C-0, C--, C-= and C-\) with columns
of numbers, you can teach Learn Mode to skip the cursor over any adjacent
columns of numbers, adding just a single column.  This can be done using the
keypad's cursor-movement keys, but it is probably better to position the
cursor with the mouse, in this instance.

To add numbers in a column that is between other columns of numbers, do the
following:  Press C-s to start Learn Mode.  Use the mouse to place the cursor
in the top number.  Press C-= to add in the number.  Press downArrow to
scroll up one line.  Press C-r to end Learn Mode.

Now each time you press C-r, it adds another number in the column.  When
finished, put the cursor where the total should go and press C-\ to insert
the total.

*** Suppose that you are building a table of contents.  On the right should
be the page numbers, and on the left would be the chapter or section titles.
A-5 will right-justify everything from the cursor to end-of-line.  You can
use Learn Mode to right-justify the page numbers as follows:

Put the cursor at the end of the line above the table of contents.  Press C-s
to start Learn Mode.  Press A-kp6, which moves the cursor to end-of-line,
putting it at the end of the first line in the table of contents to the right
of a page number.  Press kp4, moving it word-left so that it is on the page
number.  Press A-5 to right-justify the page number.  Press A-kp6, moving the
cursor to the end of the current line.  Press C-r to end Learn Mode.

Press C-r again to try out the sequence.  To cause the right-justification to
be at any particular column, press C-Return and reset the lineLength
temporarily.

*** The Alt-number-row keys are useful for beautifying lines of text.  They
can right-justify, center, left-justify, match indentations, and so on.  For
example, you can click-center lines of text as follows:  Select Swap MouseUp
(A-m) and press A-2, which centers lines of text.  Now any line that you
click is centered in the window, based on the current lineLength setting.  To
change the centering, press C-Return and adjust the lineLength.

*** Paragraph Reformat (C-3) uses the current typing settings.  If leftMargin
is 0, and if autoIndent is On, it uses autoIndent.  If autoIndent is Off, it
does not indent the reformatted paragraph.  If leftMargin is non-zero, it
reformats using leftMargin as the indentation.  If you wish to reformat a
paragraph at a particular indentation, set leftMargin to the desired column,
and then reformat using C-3.  If you wish to reformat an indented paragraph
so that it has no indentation, set leftMargin to 1.

*** The Join Lines (C-j) key is useful when you need to reformat a badly
scattered or corrupted paragraph which may even have some blank lines in it.
Put the cursor in the first line of the paragraph and press C-j as many times
as needed, in order to get the paragraph onto one long line.  Then press C-3
to reformat it.

*** Partial data files may contain a block of commands that you do not want
to have on-line, unless the need arises.  Suppose that the block of commands
consists of the Rexx commands.  These are in the Rexx submenu and the command
definitions are in Config!R.

First, save all of the Rexx commands to a partial data file called RexxData.
(See the examples in Partial Data Files, 2.6.)

The menu definitions in the startup command in a config work as follows:  The
menu item that serves as a submenu header has to be assigned to an existing
key, even though you cannot "select" that item because it is a submenu
header.  This can be useful.  Suppose that the "Rexx" menu item (submenu
header) were assigned to the following command:
        <shftAlt-3:  loadKeys("RexxData",1,2000) runKey(startup) >

The Rexx menu item should be defined like this:  menu("Rexx",4,shftAlt-3)

Now, if the Rexx commands are not on-line when the menus are built (such as
at startup or if you toggle the colors), the submenu items cannot appear; but
the Rexx menu item above does appear, because the SA-3 command exists.
Selecting Rexx (SA-3) causes the Rexx commands to be loaded in.  It runs the
Startup command, causing the menus to be rebuilt.  The Rexx submenu items now
appear.  And the Rexx item (SA-3) cannot be selected any longer, because it
is now the submenu's header.  (See Customizing the Menus, 2.17.)

*** The previous example can be refined a step further:  The SA-3 command
above could use the inUse() CL function to test whether a particular Rexx
command, such as AC-1, exists or not.  If it does not exist, SA-3 would load
in the Rexx commands, creating the Rexx submenu as described above.  If AC-1
does exist, SA-3 would kill all of the Rexx commands using killKey() and
would call runKey(Startup), rebuilding the menus minus the Rexx submenu once
again.  In this way, SA-3 toggles the Rexx submenu, and all of its commands,
into and out of existence.  Note that while you cannot select Rexx (SA-3)
when the submenu exists, you can still press SA-3 in order to remove the
submenu.

Note that other submenus lend themselves to this kind of arrangement as well:
Obvious candidates are the Spelling, Printing, and Split Windows submenus.

*** You can cut and paste using 1) scratch deletes and Undo, 2) the hilite
region, 3) the invert region, and 4) a columnar region, all at the same time.
Each of these uses a separate buffer to store the copy in.

If these are not enough buckets, select New File (C-f1) and use a file buffer
as a holding place, or select Swap Buf #41 (C-w) and use buffer 41 as a
scratch pad.

If those are not enough, select Edit Buffer (SA-f6) and use any buffer # up
to 99.  If you need still more buffers, select Push Buffer (L-w) and push
some buffers onto the buffer stack.  This frees up their buffer-number slot
so that it can be reused.  When you need the buffers on the stack, select Pop
Buffer (R-w) to pop them off.  Use Roll Stack (SA-w) as needed, to rotate the
stack so that you can pop off the desired buffer.

*** Suppose that you need to put a box of asterisks around a rectangle of
text without disturbing the text.  First, make a copy of the columnar region
of text that is to go inside the box:  Select Col Display, turning on
columnar display mode.  Press Shift and click the mouse in the upper left
corner of the text's rectangular region.  Press Alt and click the mouse in
the lower right corner of the text-rectangle.  This should hilite a columnar
region.  Select Col Copy (SC-3 or kpDot) to copy this rectangle.

Create the box of asterisks somewhere in curFile and make it a hilited
columnar region using the mouse as described above, but do not copy it.  Put
the cursor outside the rectangle of text you just copied which the box of
asterisks is to surround; the cursor should be at the upper left corner of
the text rectangle, but not inside it.

Select Ovl Hil->Csr (SC-7).  This overlays the box of asterisks onto the
cursor.  It overwrites the text you copied earlier.  Now put the cursor
inside the box, in the upper left corner, and select Col Overlay (SC-5).
This overlays the copied rectangle of text inside the box of asterisks.

*** Sometimes a serial printer loses data because the serial-line handshaking
protocol is not agreed upon by the computer and printer.  You may be able to
prevent the loss of data by using delays in the sending process.  Suppose
that your serial daisy wheel printer can print 20 chars/second, and you need
to send a file to the printer at 300 baud (30 chars/second).  A delay of
about 1 second per line might prevent lost data due to printer buffer
overflows.

Press SA-d, and type in 10 and ESC; this sets the delay variable to 1.0
seconds.  Put the cursor at the start of the first line to be printed.  Press
C-s to start Learn Mode.  Press kp1, marking the start-of-hilite.  Press kp2,
moving the cursor down one line.  Press kp3, marking the end-of-hilite.
Select Print Hilite (C-p).  Press A-d, causing a delay of 1.0 seconds.  Press
C-r to end Learn Mode.

Press C-m to set the command multiplier to the number of lines you wish to
print and press C-r to run the learned sequence.

If the serial printer still loses characters, crank up the delay to 1.5 or
2.0 seconds.  If it still loses characters, it must mean that the serial
printer has no input buffering.  So instead of printing a line at a time,
print a word or a character at a time, using a small delay, like 0.1 second.

*** When working with many files and one file is needed oftener than the
rest, it is convenient to use Swap Buf #41 (C-w) to switch back and forth
between the other files and the main one.  A good example is when you have a
file-name list from which you are occasionally click-loading new files or in
which you are collecting section titles or a list of notes.  By keeping the
list in buffer 41, you can see it instantly by pressing C-w, no matter which
buffer is in the window at the time.  And pressing C-w again switches back to
the original file.  To make this even more convenient, swap C-w to the ESC
key using Swap Keys (f5).

*** There may be a tendency to think that after copying the hilite region you
should not then hilite another region and clear it with Clear (C-h).  This is
not so; it is safe to create another hilite region and even to clear it.  As
long as you do not Cut or Copy a new hilite region or select Free Buffers (A-
f3), you will not destroy the copy that you made earlier.

*** When you click the title bar, Uedit switches to tiny window.  You can
position the tiny window wherever you want.  If you switch to tiny window
again later on, it is where you last put it.  If you select Save Data (A-f6),
tiny window's x-y position is saved to disk.  Next time you run Uedit, you
will not have to reposition the tiny window.

*** When you need to compare two files, to look for any difference between
them, use Learn Mode.  Load in the two "identical" files.  Press C-s to start
Learn Mode.  Press A-downArrow to scroll down a page.  Press F1 to switch
files.  Press A-downArrow again.  Now press F1 four times.  Press C-r to stop
learning.

Now start pressing C-r.  Any difference between the two files, even an extra
comma or space, will jump out at you.  Using this technique, which
astronomers call a "blink comparator", you can actually compare files at
nearly the same speed as file-comparison programs do.

*** It is possible, and quite straightforward, to do a mail merge using Learn
Mode.  Without describing each step, it goes roughly as follows:

Load the customer list and a form letter into Uedit.  Press C-s to start
learn mode.  Delete a name from the customer list using a scratch delete key
such as Delete Line (C-d) or A-kp9 (Delete to End-of-Line) and insert it back
using Undo (kp0), press f1 to switch to the form letter, insert the customer
name using Undo (kp0), select Print File (AC-p) to print the form letter,
delete the customer name from the form letter, press f1 to go back to the
customer list, and move the cursor downward to the next customer in the list.
Press C-r to end Learn Mode.  Set the command multiplier (C-m) or use the
cycle counter (SA-c) along with C-r to run the learned sequence as many times
as needed.  (Technical note:  Hundreds or thousands of deletes in a learned
sequence like this would fragment the customer list badly and could use up
all memory.  However, if you select File Size (C-1) in the learned sequence,
it forces the list to be packed and prevents fragmentation.)

*** Sometimes it is desirable to use both carriage return (ASCII 13) and
linefeed (ASCII 10) as the line terminator.  This may be handled in several
ways:

Method 1:  Select Start Learn (C-s).  Press C-c (Input Control Character) and
the letter "m".  This inputs a carriage return.  Press C-c and "j", which
inserts a linefeed.  Press C-r to end Learn Mode.  Select Swap Keys (f5) and
press C-r and the Return key.  This swaps the Run Learn key with the Return
key, so that now when you press Return it types in both a CR and a linefeed.

Method 2:  Compile the following command for the Return key:
            <normal-Return: typeChar(13) typeChar(10) >

Method 3:  Use Search & Replace, searching on linefeed (Return key) and
replacing with Ctrl-m and linefeed.

*** In the CL, there is a local flag Favorite which is not used in the
current standard config, although in earlier versions of Uedit it was used.
The Favorite flag may be put to use for any purpose where a buffer-local flag
is needed.  However, Favorite is meant to be used in conjunction with the
toggle() function as follows:  To turn On/Off the Favorite flag for curFile,
use flipFlag(curFile,favorite).  Assuming that a number of files have been
tagged as "favorite", you can toggle to the next favorite file by using
toggle(favorite).

*** Rather than setting MaxFiles to a high number, which requires customizing
the config files to change buffer numbers in its commands, you can store
files on the buffer stack and access them just as though they were in file
buffers.

Load each file and use the cmd below to push the file onto the buffer stack
(L-w).  You can load as many as memory will hold, and it doesn't use up file
buffer slots.

Swap current buffer with stack & roll stack
<normal-esc:
    equateNum(n51,99)
    getStackSize(n51,n52,n53)
    if (eqNum(n51,0)) {
        putmsg("buffer stack is empty")
        returnFalse
    }
    equateNum(n54,curfile)
    ..if (getFlag(curfile,changed)
    ..    & askYesNo("Save this changed buffer?")
    ..    ) saveFile(curfile)
    push(buf99,curfile)
    rollstack(curfile,1)
    pop(buf99,buf[n54])
>

*** The number stack and the CL can be used in implementing a fake learn
mode.  Note, however, that due to stack and CL usage, the fake learned
sequences would not run as fast as real learned sequences.  Regular learn
mode only stores 200 steps, and the memory cost per key is 14 bytes.  A fake
learn mode could store an arbitrary number of steps at a cost of only 8 bytes
per key, up to the limit of memory.  Regular learned sequences cannot be
edited or reordered.  Fake learned sequences using the stack could be
reordered or edited, using rollStack(), pop() and push().  PreKey would be
used for the learning process.  InputChar and macroNum would be stored in 16
bits each in a number that is pushed onto the stack.  This fake learn mode
would not store mouseXY, but you could test for macroNums corresponding to
buttonDown and buttonUp and store mouseXY in a separate entry on the stack.
Or, since inputChar is never higher than 255, it only needs 8 bits and
macroNum, whose max is 1199, only needs 11 bits, and that leaves 13 bits in
which to store the mouse's x-y position.  When running the fake learned
sequence, values should be popped off, parsed out, pushed back onto the
stack, and the stack rotated.  For one-shot running of the sequence, just pop
the numbers off and parse them.  The learned sequence could be stored on disk
by converting the stack values into ASCII in a buffer and saving the buffer
to disk.  The following should be used, after parsing inputChar and macroNum
from a stored value:
        if (gtNum(inputChar,0)) typeChar(inputChar)
        else runKey(macroNum)

Note that the stack is LIFO (last in, first out), so it is necessary to roll
the stack by minus one before each value is popped off, unless the preKey
command that loads the stack loads it in reverse order by using rollStack()
after each push().

Technical note:  The reason that normal Learn Mode requires 14 bytes per step
is that it stores Amiga input messages, which include various fields such as
the mouseXY position.  Learned sequences must run as though they were being
freshly typed in.

*** The best source of CL examples is Config!, Config!H, Config!M, Config!P,
Config!R, Config!S, and Config!Z (if it exists), which contain about 300
examples that you may use.  When you need to create a custom command, think
of one in the standard config that works about like the one you need to
create, and use it as an example.

*** The Rexx interface in Uedit offers countless possibilities.  For example,
you can make Uedit load MyFile by sending it the Rexx message "Rx u
f:MyFile", if Rexx auto-traffic mode is active.  Further messages could cause
Uedit to edit, save, and close MyFile.  A command using the CL function
toggle(toTiny) makes Uedit switch to tiny window during its next pause.  When
in tiny window, Rexx traffic makes Uedit go to its big window.  Thus, Rexx
messages could make Uedit go to its big window, process a file, and return to
tiny window.  (See Rexx Interface (2.8) and its examples.)

*** You may control your printer either by using generic printer codes that
go to the Amiga print device that you selected with Preferences or by
embedding raw escape-sequences that your printer recognizes.  (See Printing,
1.43.)  If you embed raw escape-sequences for your printer, set Print Select
(A-p) to 3.  This makes Uedit send the Amiga's codes to the Amiga and all
other text, including your escape-sequences, straight to the printer.  Here
are some examples of both methods of controlling your printer:

To embed a control code to set your printer's left and right margins at
columns 10 and 70, use a command like the following:
    <normal-esc: printerCode(curFile,65,10,70) >

The following embeds the escape-sequence ESCx at the cursor, where ESCx is
some escape-sequence that your printer needs:
    <normal-esc: insertChar(curFile,27) insertChar(curFile,"x") >

The above escape-sequence can be embedded with Learn Mode also:  Press C-s to
start Learn Mode.  Press C-c (Input Control Character) and ESC, which puts an
ESC in the text.  Type in the other keys in the sequence; if they are control
characters, use C-c to input them.  Press C-r to end Learn Mode.

2.8 ARexx Interface

ARexx is the Amiga implementation of the REXX language.  To use Uedit's ARexx
interface, you must have ARexx and know how to use it.  (ARexx was written by
William Hawes and is included with new versions of AmigaDOS.)

If ARexx is up and running, Uedit detects it and messages and replies can be
sent or received.  When in tiny window, Uedit returns to its big window, if
it receives something from ARexx.

Normally, nothing is sent to ARexx by Uedit, unless you initiate it with a
command.  (Aborting with Amiga-ESC and quitting Uedit are exceptions
discussed later on.)  If a message or reply is sent to Uedit by an ARexx
host, Uedit picks up the message or reply in the background.  Then it is up
to you whether to fetch and use it or not; if you are using autoTraffic mode,
messages and replies are processed automatically, however.

The commands supplied with the Uedit-Rexx interface enable you to send and
receive messages in a variety of ways.  For example, you can send a hilite
region to ARexx or send a full buffer.  You can receive messages from ARexx
into a buffer or receive them into curFile at the cursor location.  (At the
command language level, even greater flexibility is afforded.  See rexxIn()
and rexxOut() in Part 3.)

autoTraffic mode fetches and replies to Rexx messages automatically.  When
autoTraffic mode is turned On, an external program can control Uedit using
Rexx messages and a command protocol.  Rexx commands from Uedit can control
external programs as well.  When in tiny window, Uedit returns to the big
window, if a Rexx message arrives; and if autoTraffic mode is On, Uedit
immediately acts upon the Rexx message.  It loads in a file or does whatever
the message tells it to.  (See Rexx autoTraffic Mode, 2.8.11.)

Port Name:  To send messages to Uedit from ARexx hosts, you will need Uedit's
ARexx Port Name, which is:  URexx

File Extension:  Rexx programs can be run from inside Uedit.  Rexx allows for
a default file-extension that is related to the host program (such as Uedit).
Uedit's File Extension is the same as its Port Name:  URexx

You can create a Rexx program for Uedit to use and call it MyProg.URexx.
Then you can run it from inside Uedit by calling it "MyProg", omitting the
extension.  Rexx appends Uedit's extension automatically.

2.8.1 Using the ARexx Interface

The original ARexx Command Language interface provided with the standard
config (in the Config!R file) used raw macroNums and inputChars, which,
though flexible, were cryptic and unfriendly.  The Rexx CL interface that is
now provided with the standard config (in Config!R) was written originally by
Kerry Zimmerman, a Uedit user, and it uses sensible words for desired
operations.  It is easy to add new words to the word-list.  The currently
defined words are in the REXXCOMM file:
    /* REXXCOMM */
    ask            1063+105 |
    text        1077+0 |
    shilite        29+0 |
    ehilite        31+0 |
    loadfile    1078+0 |
    gotoline    1094+110 |
    up            62+56 |
    down        30+0 |
    left        149+0 |
    right        151+0 |
    searchfor    1064+111 |
    einvert        447+51 |
    sinvert        231+105 445+49 |
    cut            490+31 |
    message        1065+112 |

By editing REXXCOMM, you can easily add new command-words to use in Rexx
messages to Uedit.  (See Add Command Words to REXXCOMM (AC-0), 2.8.10.)  For
convenience, a demo.urexx Rexx message to Uedit is also provided.  (See the
REXXCOMM, demo.urexx, and Config!R files.)  These will be discussed further
later on.

When you send an Outgoing Message to Rexx from Uedit, you cannot send another
until a Reply to your Message has arrived and you have fetched the Reply
using one of the Rexx fetching commands such as Cursor<-Rexx (AC-6).  When
you fetch a Reply, Uedit releases the original Message resource, allowing
another Outgoing Message to be sent.

When an Incoming Message arrives, Uedit holds onto it until you send a Reply
to it.  You may fetch the Message over and over, but Uedit does not release
the Message resource until a Reply to it has been sent.

If you press Amiga-ESC to abort, Uedit sends a Failed reply to any
outstanding Rexx message.  If a number of Rexx messages are waiting to be
picked up, pressing Amiga-ESC repeatedly gives a Failed reply to them one by
one.

Most Rexx messages do require a reply.  If no reply is received, the sending
program may hang up waiting on a reply.  (Non-return messages do not require
a reply.  See the RXFF_NONRET flag in Rexx Features Supported, 2.8.18.)  Not
replying to messages that require a reply wastes memory and may cause
programs to hang expecting a reply.

When you quit Uedit, it can let go of most Rexx traffic gracefully.  If it
cannot, it will not let you quit.  When you try to quit:  1) Uedit sends a
"Something's wrong" Failed reply to each Rexx message it receives.  This lets
the sender release the message resource.  2) Uedit releases the resource of
an incoming reply, if one arrives or is on hand that has not been fetched.
3) If you have sent an outgoing message and its reply has not arrived yet,
you cannot quit until the reply arrives.  You do not have to fetch and use
the reply, but it must arrive so that Uedit can free the resource.  If you
try to quit and a reply is outstanding, a requester will say "Wait for Rexx
reply".

2.8.2 Edit Rexx Output Buffer (AC-1)

AC-1 switches you to buffer 62, which is used for Rexx output, so that you
can type an outgoing Rexx message.  To send the message, use Buf62->Rexx (AC-
3).

2.8.3 Edit Rexx Input Buffer (AC-2)

AC-2 switches you to buffer 61, which is used for Rexx input, so that you can
examine or copy incoming Rexx messages.  To fetch an incoming message into
buffer 61, use Buf61<-Rexx (AC-4).

2.8.4 Send Output Buffer To Rexx (AC-3)

AC-3 sends to Rexx the contents of buffer 62, the Rexx output buffer.  Once a
message has been sent, Uedit will not let you send another until a reply to
the last message has been received and you have fetched the reply.

2.8.5 Fetch Rexx Input Into Buffer (AC-4)

AC-4 fetches a Rexx message or reply that has arrived, putting it into buffer
61, the Rexx input buffer.

2.8.6 Send Hilite Region To Rexx (AC-5)

AC-5 sends the hilite region in curFile as a message to Rexx.

2.8.7 Fetch Rexx Input At Cursor (AC-6)

AC-6 fetches a Rexx message or reply that has been received and inserts the
text at the cursor in curFile.

2.8.8 Send OK Reply To Rexx (AC-7)

AC-7 sends an OK reply to the current message from Rexx that has not been
replied to yet.  If no message is on hand, nothing is sent.

2.8.9 Send OK Reply and Hilited Text to Rexx (AC-8)

AC-8 sends an OK reply to the current message that has not been replied to
yet.  If the message used the RXFF_RESULT modifier, indicating that it wants
a text reply, the hilite region in curFile is sent in the reply.  Most
messages do not use RXFF_RESULT, however, so text is seldom sent in a reply.

2.8.10 Add Command Words to REXXCOMM (AC-0)

How to send command key and text inputs to Uedit can be understood by looking
at the demo.urexx file that is provided.  It uses the message command-words
defined in REXXCOMM.  (See the demo.urexx and REXXCOMM files.)  When
autoTraffic mode is On, commands can be sent to Uedit with Rexx using the
command words in REXXCOMM.

Add Command Words (AC-0) lets you define new command words to be stored in
REXXCOMM.  First it asks for the command word, followed by ESC.  Then it asks
you to type the function keys and text that are to be executed in Uedit when
the command word is used in a Rexx message.  When you are finished typing in
the command keys and text, press ESC to end the current command-word's
definition.  When finished defining new command words, press ESC a second
time.  AC-0 then asks whether you want to save the modified REXXCOMM file.
If you select Yes, it is saved; if you select No, you can save the modified
REXXCOMM later on if you wish.  The copy of REXXCOMM in buffer 36 is erased
by AC-0; this means that autoTraffic mode must reload REXXCOMM next time it
is needed; thus, if you want the new version of REXXCOMM to be used, you must
save it to disk.

In CLI or a shell or in another Rexx host program, the REXXCOMM command words
can be used in messages to Uedit; the messages contain commands and text for
Uedit to process in autoTraffic mode.  The commands and text are stored in
REXXCOMM as pairs of decimal numbers which are macro numbers and ASCII
character values:  MacroNum+InputChar.  (See InputChar and MacroNum, 2.30.)

See demo.urexx for an understanding of how to use REXXCOMM's command words in
messages to Uedit.  The rexxKey command, which handles Rexx traffic in Uedit
when autoTraffic mode is On, interprets the command words that are in
incoming messages using the definitions in REXXCOMM and acts upon them.  The
rexxKey command actually is attached to the virtual-t key when autoTraffic
mode is Off, and it is swapped to rexxKey when autoTraffic mode is turned On.

Rexx messages to Uedit may invoke Primitive Mode or a Requester or the Tab
Ruler.  If any of these is invoked by commands included in a Rexx message, do
not include their inputs in the command or in a command-word's definition in
REXXCOMM.  That is, you must type in the inputs they require at runtime when
Uedit receives and acts upon the Rexx message.

Mouse inputs are represented as MacroNum+InputChar number pairs like keyboard
inputs are, but the mouse X-Y position is not stored when a command word is
defined in REXXCOMM.  Any mouse clicks you store will use the old X and Y
positions which were last input in Uedit using the mouse.  (The treatment of
mouse X-Y positions can be handled differently by customizing the commands in
Config!R, however.)

2.8.11 Rexx autoTraffic Mode (AC-9)

Normally, if you send a Rexx message to Uedit, it is received in the
background, and you must fetch it using one of the Rexx commands, such as
Cursor<--Rexx which inserts the message's text at the cursor in curFile.  And
you must reply to each message, before Uedit can receive another Rexx input.

When you turn On autoTraffic mode (using AC-9), the following happens:  1)
The CL userGlobalB flag is set to a non-zero value, indicating autoTraffic is
On.  2) The autoTraffic (virtual-t) command (see Config!R) is swapped with
the rexxKey.  3) During idle periods rexxKey runs automatically, when Rexx
traffic arrives, and processes it.

When autoTraffic mode is turned Off, the reverse happens:  1) The userGlobalB
flag is zeroed.  2) rexxKey is again swapped with virtual-t, so that a
rexxKey command no longer exists.  3) Rexx messages are no longer processed
automatically.

If Uedit is in tiny window, arriving Rexx traffic causes it to spring back to
its big window; if autoTraffic mode is On, Uedit automatically processes the
traffic; if autoTraffic mode is Off, it is up to you to respond to the Rexx
traffic using the Rexx commands described earlier.  By using autoTraffic mode
and keeping Uedit in tiny window, you can make it act like a quick in-and-out
editor by sending it a Rexx message whenever you want it to load in a file
for editing.  A Rexx message can even cause it to return to tiny window or
move its screen to the back.

2.8.12 Rexx Features Supported

The Uedit-Rexx interface supports common Rexx action codes.  It does not
support tokenization of arguments, however.  Uedit does not process the extra
15 message arguments that Rexx allows.  But you should not need them, because
of the flexibility of Rexx and Uedit.  (See the ARexx User Reference Manual.
See the CL functions rexxIn() and rexxOut() in Part 3.)

MESSAGE SIZE:  Rexx messages can be up to 65535 bytes in size.  When you try
to send a too-big message or reply, an error is reported.  If it is a too-big
message, the message is not sent.  If it is a too-big reply, a reply is sent,
but a Result value of 10 is sent (reporting "Something's wrong") rather than
the Okay (0) Result that would normally have been sent.  (See Uedit-Rexx
Result and Error Codes, 2.8.13.)

ACTION CODES AND MODIFIER FLAG BITS:  In the rexxOut() CL function, the
ActionResult field may use defaults for the most common Rexx action code,
RXCOMM, and most common modifiers, RXFF_RESULT and RXFF_NONRET.  (See the
action code and modifier tables below.  Also see rexxOut() and rexxIn() in
3.4.)  You may also set ActionResult to other Rexx action codes and modifiers
in the tables below.  No assurance is given that any action codes and
modifier flag bits will work, however, except the common ones discussed here.

RXFF_NONRET MODIFIER:  If you send a message with (RXCOMM | RXFF_NONRET) in
ActionResult, Uedit sends the message but does not expect a reply from it.
You can send a stream of RXFF_NONRET messages, because no replies are
expected.  If you receive a message that uses the RXFF_NONRET modifier, you
must still reply to the message at some point, because while Uedit does not
really send a reply it needs to know it can release the resource and accept
another input.

ARGUMENT STRINGS:  Rexx messages provide for up to 16 arguments (Args[0] to
Args[15]) which may contain text (argument strings) or integer arguments.
Most Rexx messages only use Args[0].  Uedit supports only Args[0].  If an
incoming message uses Args[1-15], Uedit ignores those arguments.  Only
Args[0] should be needed, because any number of text and integer arguments
may be passed in Args[0] and parsed out at the other end.

QUOTATION MARKS:  In Rexx messages, quotation marks are sometimes needed.
Uedit does not insert any quotation marks automatically, though it could be
customized do so.  If quotes are needed, you must supply them.  (See the
rexxIn() and rexxOut() CL functions in Part 3.)

In the table below are the command (action) codes used by ARexx.  On outgoing
messages, an action code or a Uedit default must be put into the ActionResult
argument of rexxOut().  On incoming messages, rexxIn() reports the incoming
message's action code in the ActionResult argument.

On outgoing and incoming replies, the ActionResult field of rexxOut() and
rexxIn() contains a Result code.  (See Uedit-Rexx Result and Error Codes,
2.8.13.)

REXX COMMAND (ACTION) CODES
name      hex       decimal
----      ---       -------
                    0                 Uedit defaults to RXCOMM
                    1                 Uedit defaults to RXCOMM | RXFF_RESULT
                    2                 Uedit defaults to RXCOMM | RXFF_NONRET
RXCOMM    0X1000000 16777216          a command-level invocation
RXFUNC    0X2000000 33554432          a function call
RXCLOSE   0X3000000 50331648          close the port
RXQUERY   0X4000000 67108864          query for information
RXADDFH   0X7000000 117440512         add a function host
RXADDLIB  0X8000000 134217728         add a function library
RXREMLIB  0X9000000 150994944         remove a function library
RXADDCON  0XA000000 167772160         add/update a ClipList string
RXREMCON  0XB000000 184549376         remove a ClipList string
RXTCOPN   0XC000000 201326592         open the trace console
RXTCCLS   0XD000000 218103808         close the trace console


Here are the modifier flag bits which may be logical-ORed with a Rexx command
(action) code:

REXX MODIFIER FLAG BITS
name         flag bit
----         -----------
RXFF_NOIO    (1L << 16L)             suppress I/O inheritance?
RXFF_RESULT  (1L << 17L)             result string expected?
RXFF_STRING  (1L << 18L)             program is a "string file"?
RXFF_TOKEN   (1L << 19L)             tokenize the command line?
RXFF_NONRET  (1L << 20L)             a "no-return" message?

Uedit does not validate the action codes that you put into ActionResult when
using rexxOut().  Normally your action code in messages will be RXCOMM,
possibly with the RXFF_RESULT or RXFF_NONRET modifier.  You may use the Uedit
defaults shown in the Action Code table for these.

Do not use the modifiers in the above table, if you use one of Uedit's
default action codes (0, 1, or 2) in the ActionResult field of rexxOut().
The modifiers should only be used when you use one of Rexx's own action
codes.  Also recall that Uedit does not support RXFF_TOKEN.

2.8.13 Uedit-Rexx Result and Error Codes

If CL function rexxIn() or rexxOut() returns FALSE, the returncode argument
contains one of the following Uedit error values and the error message is
displayed in the message line:  (See CL functions rexxIn() and rexxOut() in
3.4.  See the Rexx commands in Config!R.)

UEDIT-REXX ERROR RETURN CODES
        -1 ARexx not up.
        -2 Not enough memory or outBuf-outRgn was empty.
        -3 Message or reply > 65535 bytes in size.
        -4 Nothing to fetch or reply to.
        -5 Must fetch reply to last msg before sending this one.

Rexx Result Codes:  Rexx reply Result codes are normally 0 (the OKAY result).
A non-zero Result code means a problem occurred.  When rexxIn() fetches a
reply, the Rexx Result code is reported in the ActionResult argument.  When
you send a reply, one of the following Result values must be put into the
ActionResult argument of rexxOut():

REXX ERROR RESULT CODES
        name      value
        ----      -----
        RC_FAIL   -1              something's wrong
        RC_OK     0               success
        RC_WARN   5               warning only
        RC_ERROR  10              something's wrong
        RC_FATAL  20              complete or severe failure

When you try to fetch a message with rexxIn() and it cannot load in the
message due to low memory, rexxIn() sends an RC_ERROR "Something's wrong"
reply to the Rexx sender automatically.

When you try to send a reply with rexxOut() and your reply text (if any) is
too big or there's not enough memory, Uedit sends an RC_ERROR reply instead
of sending an RC_OK reply.

When you press Amiga-ESC to abort, Uedit sends an RC_ERROR reply to any
outstanding Rexx message.  When you quit Uedit and it is cleaning up the Rexx
traffic, Uedit replies with RC_ERROR to any incoming messages that are queued
up.

2.8.14 Rexx-Interface Buffer and Number Variable Conventions

The buffer variable conventions used with Uedit-Rexx commands are:
buf36    =  REXXCOMM word list
buf61    =  Rexx Message/Reply IN
buf62    =  Rexx Message/Reply OUT

The integer variable conventions used with Uedit-Rexx commands are:
n26      =  used for flagging purposes
n27      =  ActionResult: action in Messages; result in Replies.
n28      =  flag for rexxIn()/rexxOut() indicating Message(0) or Reply(1)
n29      =  returncode from rexxIn()/rexxOut(), if FALSE is returned.
MacroNum =  used in capturing macro numbers in virtual-t/rexxKey command.
InputChar=  used in capturing input characters in virtual-t/rexxKey command.

2.9 Swapping Keys Permanently

Using Swap Keys (f5), you can safely swap, on a permanent basis, keys that
are not run by other keys or by menu selections.  Selecting Save Data (A-f6)
preserves the swapped arrangement in the Data! file.  (See Keys, 1.38.)

But if, later on, you recompile the config files, you will get back the old
key layout and will have to do the swaps again.  To swap keys permanently,
edit the config files.  This way you can even swap keys that are run by other
keys and by menus.  And the new key arrangement is preserved, even when the
config is recompiled.

To rearrange the keys in Config! and its segment files (Config!M, etc), use
Search (f9) and Replace (f10).  Change every occurrence of the key that is
being swapped, in each of the config segments.  Key arguments may appear in
the following places:  In menu() functions, at the beginning of commands
after the left angle bracket "<", in runKey() functions, and in integer and
key functions.  After rearranging the keys, load in and edit the Help! file,
bringing it up to date.

2.10 Mapping the Keyboard Keys

The "a" key on the keyboard can be mapped to the letter "b" by compiling the
command <normal-a: typeChar("b")>.  The disadvantage of mapping in this way
is that each mapped key runs a command and consumes a few bytes of memory.
Also it does not map the extra keys that are on European Amiga keyboards, and
it is slower running than direct mapping would be.

The Config! defaults have two 64-character arrays corresponding to the
printable, lower and upper case keys on the Amiga keyboard.  Rearranging the
characters in these arrays remaps the Amiga keyboard (for Uedit).  This
method is 100% efficient, because it defines the internal key array that
Uedit uses.  The arrays have blanks corresponding to extra keys on European
Amiga keyboards.  Those extra keys can be mapped so that Uedit will use them.

If you decide to modify the 64-character arrays in Config!, note the
following:  There must be exactly 64 characters in each array.  It is better
to use OverStrike typing mode, when modifying the arrays.  If you edit the
arrays and leave out the letter "a", and then select Cfg Defalts (AC-f6) to
recompile the config defaults, there is no way to type in the letter "a".
Therefore do not select Save Data (A-f6) to save a modified keyboard mapping,
until it has been thoroughly checked out.  If problems arise during the
remapping of the keyboard, select Load Data (C-f6) and recover the original
keyboard mapping.  When finished rearranging the characters in the printable
character arrays, select Cfg Defalts (AC-f6) to recompile the defaults and
select Save Data (A-f6) to save the new arrangement permanently.

2.11 Building Key-Help for Teach Keys

When Teach Keys (C-Help) is used, it puts Uedit into Teach Keys mode.  In
Teach Keys mode, instead of working as function keys, inputs are looked up in
the key-help file and their help messages are displayed.

The first flag in the default values at the front of Config! is the build-
key-help flag.  If this flag is <1>, when Config! is compiled at startup, a
key-help file is automatically built.  The second default <S:Key-Help>
defines the directory/file name that the key-help file is to use.  It is
suggested that the S: directory be used for the key-help file, because then
Teach Keys may be used in any directory.

The key-help file consists of a one-line message for each key that has a
command in your config.  In your config, the help message is the line that
appears just above each command's left angle bracket "<".  To keep the key-
help file smaller, the help messages should be brief as possible.  Help
messages that exceed 80 characters are truncated to 80 characters in the key-
help file.

Building a key-help file slows down the startup-compile considerably, and the
key-help flag should be left at <0> until the configuration is finished and
satisfactory.  Then set the key-help flag to <1> and compile your config one
last time, building a new key-help file for it.

2.12 Locations and Regions

(See the Function Argument Lists in 3.1.)

The following 20 memory addresses (locations or pointers) in each Uedit
buffer are tracked and maintained when the buffer is modified:  atCursor
mouseLoc sPage ePage sHilite eHilite sInvert eInvert locA-thru-locJ locSC
locSP.

A hilite region exists, only if sHilite<eHilite.  When sHilite>=eHilite, no
hilite region exists.  The same logic applies to invert and loc regions.  The
following 8 regions may exist in each buffer, using the buffer's location
pointers:  hilite invert loc locCD locEF locGH locIJ locPC

The following are modifiers, not locations.  They instruct CL functions to
modify existing locations (such as atCursor in moveCursor(curFile,eWord)):
        sFile eFile eForm sForm sLine eLine sWord eWord sTab eTab sChar eChar
        upLine downLine

Do not confuse locations, such as atCursor and sHilite, with modifiers, such
as sForm, eLine, and sChar.  Modifiers merely tell functions like
moveCursor() and equateLoc() how to modify existing locations.

The following regions are calculated relative to atCursor when referenced in
a function:  line word char

"Line" is everything from the cursor to eol, but not including eol.  "Word"
is everything from cursor to end-of-word.  "Char" is the character under the
cursor.  The region "all" is calculated when needed, using start-of-buffer
and the end-of-file marker.

A region is bounded by two locations.  For example, hilite is bounded by
sHilite and eHilite.  sHilite points to the first character inside the hilite
region.  But eHilite points to the first character just outside the region.
Thus, the start-location is included in regions, but the end-location is not
included in regions.

When a region is cleared, locations inside the region are bumped upward to
point to the first character after the cleared region.  Example:  If you
delete the cursor line, after the delete the cursor is at the beginning of
the next line.  If text is inserted on top of a location, the location does
not move; it still points to the same character after the insertion that it
pointed to before the insertion.  Example:  Typing in text at the cursor does
not alter the cursor's location.  The cursor still points to the same
character, which is moved forward as the text is typed in.

sPage and ePage refer to a window "page", not a printed page.  "sForm" and
"eForm" refer to a printed page; printed pages are determined by line-count
and formfeeds in the text.  When the window is refreshed, the displaying
begins at sPage.  sPage points to the first character in the first line
visible in the window.  To control what is displayed, such as when about to
call editBuf() to display and edit a different buffer, set sPage in the
buffer to the desired location before calling editBuf().

ePage is the first character in the line below the last line in the window.
If eof is in the window, ePage is at eof.  ePage is updated only when the
last line in the window is refreshed, and Uedit tries to get by with
refreshing just the cursor line as much as possible.  ePage is only used when
referenced as a CL function argument or in carrying out the internal onscreen
test to see whether it is necessary to scroll to display the cursor or not.
ePage is often out of date, and this causes inaccuracy in the internal
onscreen test and the onScreen() CL function.

The sPage and atCursor memory locations are used internally very frequently,
as one would expect.  ePage is used in the internal onscreen test.  mouseLoc
is borrowed as a scratch loc during paragraph reformatting. (mouseLoc is
updated when the mouse is clicked, so it seemed like a good buffer loc
variable to borrow, though perhaps it would have been better to borrow ePage
as the window is refreshed after reformatting anyway.)  locSC and locSP are
used internally to store the second atCursor and sPage locations, if you
happen to be displaying the same buffer in two split windows; locSC is
swapped with atCursor and locSP with sPage, when you switch between the two
split windows.  Other than that, except for atCursor and sPage which are used
constantly, the only time buffer locations are changed internally is when
they are tracked during text inserts and deletes or are modified in response
to CL function calls.

Locations are local to each buffer.  There is no cross-linkage of locations
between or among buffers.  That is, atCursor of buf10 is unrelated to
atCursor of buf20.  The only way to relate locations from one buffer to
another is to use byte-indexing into the text in the buffers.  (See
locToIndex(), indexToLoc(), locToLine(), and lineToLoc() in 3.4.)

2.13 Scratch Location Variables

locA through locJ, locSC, and locSP are provided to use as scratch locs.  As
noted earlier, locSC and locSP are used internally for storing atCursor and
sPage if a buffer is displayed in two split windows; they aren't used in the
standard config, however, and could be used for scratch locs if you don't
need them for a second split window.  locC through locJ are used as
bookmarks, if bookmark commands (S-gadget1, S-gadget2, and S-gadget3) are
used; if not using bookmarks, they are available as scratch locs.

LocB is used in the standard config by the scratch-delete commands (C-d, kp7,
and kp9).  When a scratch delete is done, atCursor is stored in locB.  If
another scratch delete is done, locB is compared to atCursor; if they are not
equal, the Undo buffer (buf45) is deleted, starting a fresh collection of
scratch deletes.  As long as locB equals atCursor, scratch deletes are
accumulated in the Undo buffer.

locA is used for scratch purposes in commands in the standard config, but not
as a durable location variable like locB is.  In non-curFile buffers, both
locA and locB are available to use as scratch locs.  (Note that this
discussion applies only to the standard config.  You may use locA and locB as
you wish in custom configs or in customizing the standard config.)

ePage may be used as a curFile scratch loc, when the window is sure to get
refreshed later on; ePage is updated by the display routine when the window
is refreshed.  It may be used freely as a scratch loc in non-curFile buffers,
because even if they become curFile later on they are sure to be displayed,
which will update ePage.

mouseLoc is a good scratch loc to use in curFile.  The mouse button commands
which use mouseLoc run only after the mouse button is clicked, which updates
mouseLoc.  In non-curFile buffers, mouseLoc may be used as a durable or
scratch location variable.

In non-curFile buffers, all buffer locations may be used as durable location
variables, as long as atCursor and sPage are set to their desired locations
before letting the buffer be displayed as curFile, if it becomes curFile.

2.14 Display and ThisKey

Uedit tries to refresh the display only as needed and only during pauses.  It
tries not to update the display, when it would hurt performance.  Various CL
functions may set bits in the internal displayFlag variable, which tells the
display routine to refresh just the cursor line, from cursor to end-of-page,
the whole page, or any of the split windows, during the next pause.  At any
point in a command, displayFlag may have bits set for one or more of these
display actions.  During the next pause, the display refreshes whatever the
bits instruct it to.  As a backup measure, the active window is fully
refreshed after a 4-second pause.

The updateDisplay CL function causes Uedit to act on displayFlag's bits
immediately.  refreshDisplay causes curFile's window and title bar to be
fully refreshed immediately.  Commands should not call refreshDisplay or
updateDisplay unconditionally, if they may be used in learned sequences or
repetitively hundreds or thousands of times.

The thisKey CL function was provided in order to eliminate display overhead
in cases where commands are run by other commands.  thisKey returns True,
when the key it is in is the primary key.  It returns False, when the key it
is in is being run by another key.  For example, "if (thisKey)
refreshDisplay" causes a window-refresh, only if the command it is in is
running as the primary command.  When a command is run in a learned sequence,
it never is the primary key, and so thisKey could be used to suppress a
refreshDisplay.  When you need to force the display to be refreshed in
learned sequences, select Refresh (SC-Help) when creating the learned
sequence using Learn Mode.

Always run custom commands first without a display function in them, because
in many cases Uedit handles refreshing correctly.  If a display refresh turns
out to be necessary, try using updateDisplay before resorting to
refreshDisplay.  updateDisplay is not foolproof, because it relies on the
accuracy of displayFlag's bits at any given time.  If updateDisplay does not
refresh as needed, sometimes switching around the functions that come before
it (functions such as moveCursor() and vscroll()) may help.  If all else
fails or performance is not a concern, use refreshDisplay.

2.15 Space and Speed

Because every command in Uedit is customizable, it is necessary for it to
have an engine that parses and follows the instructions of command-pcode in
processing user inputs.  The engine is not needed for typing inputs, but any
key that has a command compiled for it is processed by the engine.  There is
engine-overhead associated with each call to a function in a command, in
addition to the overhead of the function itself.  The more you can make Uedit
do while inside functions, the faster your commands will run.

A good example is the End-of-Line (C-e) command, which changes the eols in
curFile.  If moveCursor(curFile,eChar) were used instead of using
moveCursor(curFile,eLine) to find the eols in curFile, the C-e command would
take years to run, because the function-calling overhead would occur for each
character in curFile instead of only once per line.  By using eLine, control
stays inside moveCursor() until it finds an eol.  Similarly, a command that
manipulates words is faster, if its functions use eWord and sWord instead of
using eChar and sChar.

Space efficiency:  Using insertRgn() or insertChar() in a repetitive process
or loop may consume memory like crazy, because Uedit may split memory-blocks
each time through the loop.  This is the result of a space/speed tradeoff.
Uedit recovers the memory during the next pause when it does housekeeping.
Inserting text at eFile (end-of-buffer) is efficient, however, because space
is allocated only when the last block becomes full.  This effectively keeps
the buffer packed at all times.  When possible, text should be inserted at
eFile.

It is more efficient to use insertRgn() and clearRgn() to insert and clear
blocks of text than to do it a character at a time using functions like
insertChar() and clearChar().  But when only one character need be inserted,
cleared, or swapped, the character functions are better.  In particular,
swapChar() is efficient, because it does no block-splitting.  insertChar()
may split a block, unless it is used when atCursor is at eFile.  Once a block
has been split, inserts can continue at that location until the block becomes
full; but in search & replace operations each insert takes place at a new
location, and it results in rampant block-splitting.  (Technical note:
Commands can force Uedit to pack a buffer by calling the fileSize() CL
function.  It packs the buffer before calculating its size.)

Is it better to store text, such as headers and footers, in commands or in
buffers?  There is less space overhead in commands, because buffers carry
pointers and flags.  But commands may not exceed 10k bytes in size.  And
buffer space overhead really is not so bad; it is under 5% on moderate to
large files.  And it is not desirable to fatten up the Data! file with
commands filled with verbose text.  But the least efficient way to store text
is in learned sequences; each character input costs 14 bytes in a learned
sequence, so there is a factor of 14 in overhead.

2.16 StartUp Key and Menus

Startup is a special key, like Idle and PreKey, that uses no shift-modifiers.
That is, the shft, alt, ctl, etc key-prefixes may not be used with the
Startup key-name.  The main use of the Startup command is to define Uedit's
menus and buffer names.  It may serve other purposes too, such as auto-
loading files, setting parameters, or displaying a message or requester when
Uedit is first started.  (See the Startup command in Config!.)

Configs may include a Startup command, but one is not strictly required.
Typically the Startup command is the largest in any config, because of the
dozens of menu definitions in it.  (See Customizing the Menus, 2.17.)

The Startup command is run at the following times:  (1) When Uedit is first
started.  (2) After Startup has been recompiled or swapped or a new Startup
command read in from a partial data file.  (3) When you load in a new data
file.  (4) When you run it using runKey(Startup).

In all cases, even when using runKey(Startup), Startup is not actually run at
the time.  Instead, all that happens is that the menus are deleted, which
causes Startup to be run the next time the menus are checked during a pause.
It takes a second or two to run a large Startup command with plenty of menus
and for the Amiga to set up the menus afterward.  Putting this off until a
pause gives friendlier performance.

When Uedit is first started and Startup is run, every function in it is
called.  But after that, when Startup is run every function in it is executed
except runKey().  Thus, if you want something to happen only when Uedit is
started up, such as displaying an About... message, use runKey() to run the
command containing it.

There are two ways you can selectively cause a particular command to be run
automatically when Uedit is first started up:  You can use the CLI command-
line flags -K or -L; or you can include a runKey(myKey) in the Startup
command.  If myKey exists, it is run when Uedit first comes up and only then.
If myKey does not exist, the runKey() does nothing.  (See CLI Command Line,
2.1.)

2.17 Customizing the Menus

Uedit's menus are completely defined by calls to menu functions in the
Startup command.  Menu functions may be used only in Startup and nowhere
else.  NameBuffer() functions in the Startup command define the buffer names
to be shown in the title bar when buffers, such as the copied hilite buffer,
are displayed in split windows.  (See the menu() and nameBuffer() CL
functions in 3.4.)

It is easy to customize the menu and buffer-name definitions in the Startup
command in Config!.  The menu CL functions used are:

            menu("description",menu#,key-arg)
     checkedMenu("description",menu#,key-arg,flag-var)
         subMenu("description",menu#,key-arg)
  checkedSubMenu("description",menu#,key-arg,flag-var)


The name-buffer function is:  nameBuffer(buf#,"buffer-name")

The rules governing menu definitions are these:

1.  Menu "description" may be up to 17 characters in length.

2.  All key-args in menu functions must correspond to existing key commands,
or else the menu definition is ignored and does not appear.

3.  There may be up to 7 main menus, using menu# = 1 to 7.  A main menu
consists of a collection of menu functions, each using the same menu#.

4.  The first menu function using a new menu# serves as the menu header for
that menu#.  Its "description" is displayed in the window's title bar when
you press the right mouse button.

5.  Each main menu header may have up to 20 menu items following it, each
using the same menu#.  These use the menu() and checkedMenu() functions.

6.  Each menu item may serve as a real menu item or a header for a submenu.
If submenu functions follow an item, it serves as a submenu header.  If no
submenu functions follow it, it serves as a real menu item.  Each menu item
may have up to 12 submenu items following it.  The submenu items use the same
menu# as the parent menu.  Submenu items use the subMenu() and
checkedSubMenu() functions.

7.  Checkmarked menu and submenu items use a fourth argument, which is a
flag-var such as WordWrap or RightJustify.  The flag-var's value at any time
determines whether the item or subitem appears checkmarked or not.  If the
flag-var is non-zero, a checkmark appears.  Checked menu and submenu items
use inverted colors so that they are easily noticed.  Selecting a checked
item or subitem toggles On/Off the value of the flag-var.

The following is an example, taken from Config!:
<Startup:
  menu("Files",1,normal-f1) .. first occurrence of menu#1, so it's the header
     menu("Next file      f1",1,normal-f1).. first actual item
     menu("Prev file    S-f1",1,shft-f1).. second item
     menu("Open             ",1,alt-f1).. third item is used as submenu header
  SUBmenu("Open         A-f1",1,alt-f1).. first submenu item
  SUBmenu("File request L-f1",1,lAmiga-f1)..second submenu item..
  SUBmenu("New file     C-f1",1,ctl-f1)
  SUBmenu("Insert file SA-f1",1,shftAlt-f1)
  SUBmenu("Restore     SC-f1",1,shftCtl-f1)
  SUBmenu("Rename        A-n",1,alt-n).. last submenu item
     menu("Save             ",1,normal-f2).. 4th menu item is also submenu header
  SUBmenu("Save           f2",1,normal-f2)
  SUBmenu("Save as...   S-f2",1,shft-f2)
  SUBmenu("Save changes A-f2",1,alt-f2)
  SUBmenu("Abort save  SA-f2",1,shftAlt-f2)......

After customizing the Startup command, put the cursor above the "<Startup:"
that begins the command and press F6 (Compile) to recompile the command.
Select Save Data (A-f6) to save the changed menus permanently in the data
file.

After Startup has been recompiled, the menus are rebuilt, which takes a
second or two.  If you swap Startup to some other key, the menus are removed.
If Startup is swapped back into place, the menus reappear a short time later.

If a key referenced in a menu definition does not exist when Startup is run,
the menu item for that key does not appear.  If a key used in a menu item is
killed, the item stays visible in the menu until Startup is run again at some
point.  Startup may be run anytime to rebuild the menus by selecting Do Menus
(SAC-Help).  If a key used in a menu is swapped with another key, selecting
that menu item runs the other key.  If a menu key is swapped with a key that
has no command, the menu item does nothing when it is selected, and the menu
item will not reappear if the Startup command is run later on.

2.18 Idle Key and IdleTime

The Idle key, like Startup and PreKey, does not use shift-modifiers.  The
Idle command, if it exists, runs automatically when there is a pause of
IdleTime tenths of a second.  IdleTime may be 0 to 32767 tenths of a second.
In the defaults in Config!, IdleTime is set to 10 seconds.  IdleTime may be
changed by selecting Idle Timer (SAC-i).

The Idle command in the Config!M file implements the Save On Idle feature.
If Save On Idle (C-f2) is checkmarked in the Local Modes menu, changes in
curFile are auto-saved when you pause for 10 seconds.  (Selecting Save On
Idle turns On the UserLocalA flag for curFile.  Idle looks at all file
buffers to see whether their UserLocalA flag is On; if On, it saves the
buffer, if the buffer's Changed flag is also On.)  Pauses are not measured
very accurately by Uedit, because it does some work during pauses, packing
buffers, updating menus and display, and processing spooled prints and file-
saves.

The following Idle example saves curFile automatically, if it has been
modified, after you have paused for IdleTime tenths of a second.
        <Idle: if (getFlag(curFile,changed)) saveFile(curFile) >

When you turn on Rexx autoTraffic mode, a special Idle command is used in
place of the normal (Save On Idle) command and handles Rexx traffic.  Rexx
autoTraffic mode sets IdleTime to zero, so that traffic is handled
expeditiously.

When IdleTime is 0, there is an interval of about 1 tenth of a second between
executions of Idle.  Increasing IdleTime to 1 tenth of a second would cause
Uedit to sleep more, which would give more resource to other tasks on the
Amiga.  If no Idle command exists, Uedit sleeps most of the time, once its
housekeeping has been caught up.  When using the Save On Idle feature,
IdleTime should be 10 seconds or more for best results.

Upon returning from tiny window, if IdleTime is 0, Idle runs before the menus
are reenabled.  This gives faster response during Rexx autoTraffic mode.
For instance, if Uedit is in tiny window and a Rexx message tells it to load
myFile, it immediately returns to its big window and loads myFile.  While it
is doing that, if you press the right mouse button there should not be any
menus yet.  The menus are reenabled after Idle has processed any outstanding
Rexx traffic, if IdleTime is 0.

2.18.1 rexxKey

rexxKey is a key-name, which like startup and preKey, does not use shift
modifiers.  The rexxKey command, if it exists, runs automatically in idle
periods ONLY if there is an incoming Rexx message or reply waiting to be
processed.  The purpose of rexxKey is to reduce overhead.  (When the idle
command used to be used in order to process rexx traffic with idleTime=0,
there was undue overhead because it ran constantly in idle periods.)  rexxKey
runs (during idle periods) only if there is incoming traffic to process and
won't run again until there is new incoming traffic.  In the standard config,
rexxKey runs only if autoTraffic mode is On.  (See 2.8 ARexx Interface.)

Note: In order to keep rexxKey from running repeatedly in idle periods, you
must process the incoming traffic by calling rexxIn() in your rexxKey
command.  (See rexxIn() and rexxOut() in Part 3.)  The standard config takes
care of this automatically, when autoTraffic is On.  In Config!R, the rexxKey
command is actually assigned to virtual-t and when autoTraffic mode is turned
On, virtual-t is swapped with rexxKey, bringing the rexxKey command on-line.
(See Config!R and see 2.8 ARexx Interface.)

2.18.2 onAbort

onAbort is a key-name, which, like startup and preKey, does not use shift
modifiers.  When an abort occurs, either after you press Amiga-ESC or due to
another cause such as running out of memory or loading a data file, the
normal abort cleanup-work is done by Uedit and then, if an onAbort command
exists, it is executed.  An onAbort cmd may free scratch buffers, reset
buffer flags, and so on.  Example:
    <onAbort:    do (n54,50,59) freeBuf(buf[n54])  .. free scratch buffers
                downFlag(curFile,overStrike)  .. turn off overstrike mode
    >

Warning:  As with preKey, it is possible to hang up Uedit with an ill-
conceived onAbort command.  That is, if something in the onAbort command
itself causes an abort, the command will run until you reboot the machine.
For this reason, in writing an onAbort command, it is a good idea not to do
anything that may cause memory to be allocated or that could conceivably
bring about an abort.  For instance, loading in a data file causes an
internal abort; an abort is forced because whatever command is running ceases
to exist in Uedit when a new data file is loaded in.

In order to get the most flexibility and utility out of onAbort, it may be
useful to create a number of commands for onAbort, assigning them to "unused"
macroNums.  The normal state might be to have no onAbort command; but inside
each key that requires onAbort, copy or swap one of the abort commands into
onAbort using copyKey() or swapKey(); then as the last step in the command
kill the onAbort command using killKey() or use swapKey() a second time.
(See copyKey(), swapKey(), and killKey() in Part 3.  See Keys and MacroNums,
2.31.)

2.18.3 onTitle

onTitle is a key-name, which, like startup and preKey, does not use shift
modifiers.  Normally, clicking the title bar causes Uedit to switch to tiny
window.  But if an onTitle command exists, it is executed instead when you
click the title bar.  An onTitle command might do some cleanup work for you,
such as freeing scratch buffers, and it can even switch you to tiny window
before or after doing its other work.  Example:
    <onTitle:  toggle(toTiny)     .. can still goto tiny window as always
               freeBuf(buf54)     .. free scratch buffer
               .. do other stuff, like save file changes
    >

Rather than compiling onTitle each time you need it, it is convenient simply
to swap it to some unused key slot such as macroNum 1199.  (See swapKey() in
Part 3.)  Example:  <normal-esc: swapKey(onTitle,1199) >

If the macroNum 1199 command does not exist, pressing ESC would restore the
normal click-for-tiny-window action.  Pressing ESC again would reinstate the
onTitle cmd.

2.19 Overview of Commands

All of Uedit's commands originated as command language (CL) and may be
customized or reinvented or done away with by the user.  Uedit's CL is self-
descriptive and should be intuitive for programmers to learn to use.
Commands are enclosed in angle brackets "<>" and begin with a valid key
argument followed by a colon ":".  The remainder of the command consists of
function calls and optional control structures.  When a CL function uses no
arguments, no parentheses are required or allowed; when it uses arguments,
they are required.  (See Valid Key Arguments, 2.29.  See Control Structures,
2.20.)

Uedit's compiler ignores extra whitespace and does not care about upper/lower
case.  The following two commands are identical and valid:

<shftAlt-w:    if (getFlag(curFile,wordWrap)) putMsg("Wordwrap is ON")
               else {
                    putMsg("Wordwrap is Off")
                    flipFlag(curFile,wordWrap)
                    alertUser("Now wordwrap is On!")
                } >

<SHFTALT-W:IF(GETFLAG(CURFILE,WORDWRAP))PUTMSG("Wordwrap is On")ELSE{PUTMSG(
"Wordwrap is OFF")FLIPFLAG(CURFILE,WORDWRAP)ALERTUSER("Now wordwrap is On!")}>

A command is brought on-line by typing it into any buffer, putting the cursor
in front or on top of the left angle bracket "<", and pressing F6 to compile
it.  Selecting Save Data (A-f6) saves the current data to disk, with the new
command now included.

Compiling a command creates a binary pcode representation which is more
compact than the original command written in CL.  The maximum pcode size
allowed for a compiled command is 10k bytes.  Compiling shrinks the size
considerably, so a 10k compiled command would be quite large in its source
command language.

All functions and most arguments in the CL require only 1 byte in pcode.
Literals (in "quotes") are stored verbatim, so they may add greatly to the
size of a compiled command.  The Startup command in Config! sets up the menus
and has dozens of literal arguments, which are menu names.  Startup is
typically the largest command in any config.  However, except for literals
which are stored verbatim, Uedit's pcode takes much less memory than the same
functionality would take if written in machine code.  Of course, there is a
penalty for the flexibility and compactness afforded by the CL; the pcode has
to be interpreted by Uedit's engine at runtime.

When compiling a command, the compiler moves the cursor forward until it
finds a left angle bracket "<".  It then compiles until it finds an error or
reaches the command's right angle bracket ">".  If an error is found, the
screen flashes and the cursor stops at the error point.  If the compile is
successful, the pcode size is reported in the message line.  If it is a new
command, the word "Size" is used in reporting the pcode size; if it is
replacing an existing command, the word "Replace" is used.

Commands may run other commands using runKey() to a maximum nesting of 10
levels.  When you press a key, its command runs at level 1.  If it runs
another key, the second one runs at level 2, and so on.  If nested commands
try to exceed level 10, Uedit aborts and the screen flashes.

It is good practice to write small modular commands, rather than writing big
ones that are hard to read and follow.  For memory efficiency, it is better
to use functional modules, because commands can share the same modules or
routines.  A "virtual" key-prefix was provided to enable you to write
routines that cannot be run directly by giving an input but may be run by key
commands using runKey() or by menus.  Additionally, there are many "unused"
MacroNum slots that may be used for such routines.  (See Keys and MacroNums,
2.31.)

An example of sharing and modularity is the Search and Replace commands.  F9
is the Search Fwd key.  F10 is the Replace key.  After a successful "find"
with F9, you can press F10 to do a replace.  After doing the replace, F10
runs F9 again to continue the search forward.  A-F10 (Replace All Fwd) runs
F10 and F9 in a loop, searching and replacing, until the search in F9 fails.

In addition to running other commands with runKey(), commands may compile
commands (using Compile), swap them (swapKey()), copy them (copyKey()), erase
them (killKey()), save them to disk (saveConfig() or saveKeys()), and load
them in from disk (loadConfig() or loadKeys()).  Thus the degree of power and
flexibility afforded by the command language is almost unlimited.  Add to
that the power and flexibility of Learn Mode and the ARexx interface, the
number of buffer and number variables that are available, the buffer and
number stacks, and the range of possibilities is hard to imagine.

2.20 Control Structures

A Command may contain any number of functions, as long as it stays within the
maximum pcode size of 10K bytes.  Commands return the True or False of the
last function called in them.  For example, runKey() gives the return value
of the last function called in the command it runs.

Control Structures used in the CL include the if()...else, do(), while(),
goto-label(), switch()-case(), gosub-label(), and define().  Curly brackets
("{...}") may nest a series of functions inside an if()'s or while()'s or
do()'s domain.  Control structures may be nested within control structures to
any depth that memory and maximum command size (10k) will allow.

As in C and other programming languages, multiple arguments may be used
inside the if() and while() parentheses.  The following symbols are used:
    NOT = ! or not
    AND = &
    OR  = |

The control structures are:

2.20.1  do (Index,From,To)
Index:    list 13 (see the variable lists in Part 3.)
From,To:  list 10 (numbers)

Examples:
    do(n54,20,n88) putMsg("this is a test")

    do (n50,n51,n52) if (not fct(args)) {
        .... structures and functions ....
    }

    equateNum(n53,0)
    do (cmdMultiplier, "A", 128) add(n53,n53,cmdMultiplier)

Do() works in the forward direction.  Index is incremented at the bottom of
the loop and the loop continues until Index is greater than To.  Do() always
runs at least once, even if From is greater than To.

2.20.2 while (Function)
Function:  One or more Functions or Not Functions with/without parentheses.

Examples:
    while (fct1(args) & !(fct4(args) | fct5)) if (fct2(args)) fct3(args)
    while (!fct4(args)) {
        .... structures and functions ....
    }

2.20.3  if (Function) ... else ....
Function:  One or more Functions or Not Functions with/without parentheses.

Examples:
    if (fct1(args) | !fct5) fct2(args)
    else fct3(args)
    if (!fct4(args)) {
        .... structures and functions ....
    } else {
        .... structures and functions ....
    }

2.20.4  goto & label(Number)
Number:  0 to 99

There may be at most 100 labels in a given command.  Labels may be defined
only once, but there may be up to 255 goto's.  Monotonic ordering of labels
is not required.

Examples:
label(31)
      fct1(args)
      if (fct2(args)) goto label(29)
      while (not fct3(arg)) {
         fct4
         if (fct5(args)) goto label(31)
         else if (not fct6(args)) return
      }
label(29)
      fct7(args) ....

2.20.5  switch(N) & case(N)
N:  list 10   (See Argument Lists used in the Command Language, 3.1.)

The switch()/case() control structure is similar to that used in the C
programming language, but it is more flexible; both the switch() and case()
arguments may be variables or constants.  Curly brackets are required.  The
default case is optional.

Example:
      switch(n54) {               .. can use a literal or constant here also
          case(10)                .. fall thru to next case
          case(-1)   { ... }
          case("abcd") { ... }
          case(n55) { ... }       .. can use a variable like n54
          default   { ... }       .. default is optional
      }

2.20.6  gosub label(Number)
Number: 0 to 99

gosub acts like a goto label(nn), except gosub label(nn) returns control to
the next statement after the calling point when a return or the end of the
command is run into.  Subroutines are normally at the end of the command, so
that the command's ending bracket ">" can cause a return.  Multiple gosubs
may exist, however, and normally there would be a return, returnTrue, or
returnFalse terminating the routine under some condition or other.  gosub
label(nn) may be used inside an if() or while(), and the subroutine should
return a meaningful True or False accordingly.  Subroutines are recommended
anytime the routine need not be callable by other commands; in the latter
event, runKey() should be used so that other commands can also call the
routine.

Example:
<normal-esc:
    define(label(50),MY_ROUTINE)
    if (gosub MY_ROUTINE) putMsg("TRUE")
    else putMsg("false")
    return  .. need a return here unless you want control to fall into
            .. the code below.

MY_ROUTINE  .. subroutine, just a demo
    alertUser("SUBROUTINE")
    return  .. don't need this, return happens anyway at end of command
    >

2.20.7 define() and the defines command:

define(Object,Name) lets you use aliases for CL Objects, making your commands
more readable.  When used in a command, the define() statements must all be
at the start of the command; they are illegal following any CL function.
(See the previous example for gosub label().)  The define()s inside commands
no longer exist after the command is compiled.

Arguments in define(Name, Object):
    Name must be a contiguous "word" which may contain upper or lower case
    alpha characters or the "_" underscore character.

    Object has no restrictions.  Object continues after the comma "," until
    the closing ")" right paren is encountered.  Matching and nested parens
    are allowed inside Object, however, as are quotes, spaces, linefeeds,
    comments, CL functions and variables, and so on.

To create global defines, a defines key-name is provided.  Example:
<defines:
    define(S_Buf,buf54)
    define(Color,7)
    define(Message,"End of file")
>

Only one set of global defines can exist at any one time, and when a new
defines command is compiled, the global definitions in it replace the earlier
global ones.  The global definitions currently in memory apply when any
command is compiled.  To erase the global definitions from memory, after you
are finished compiling commands, simply compile an empty defines command:
<defines: >

NOTES:
1.  The global defines are not stored in data files.  The the <defines:  ...>
command once compiled simply stores the definitions in memory and it stays
there until you quit Uedit or compile an empty <defines:> command.

2.  Local defines are kept only while the command that contains them is being
compiled, then they are wiped from memory.

3.  Define(), whether used or not, has no effect on the size or content of
compiled commands.

4.  You can redefine a CL word like "char" and the compiler won't complain.
But it will not use the illegal redefinition.

2.21 Buffer Variables

Uedit has 100 buffer variables, buf0 through buf99.  The lowest buffer
numbers, starting with buf0, are used for editing files and are called "file
buffers".  You may select Max Files (AC-f1) and set this number from 1 to
100.  If MaxFiles is 20, buf0 to buf19 are file buffers and loadFile() only
lets you load in 20 files.  By pushing buffers onto the buffer stack, any
number of buffers is possible, up to the limit of memory, but buffers on the
stack cannot be accessed until they are popped back into a buffer-number slot
in the range buf0 to buf99.  (See Buffer Stack, 1.20.7.)

Buffers may be referenced in the CL in several ways.  Examples:
    function(buf33)
    function(buf[n22]) .. n22 must be in the range, 0 to 99.
    function(curFile)  .. current buffer in the window.


When indexing into the buffer array is used, the command is aborted if the
index is out of bounds.  For example, buf[n22] causes an abort when n22 is
not in the range 0 to 99.

If MaxFiles is 20, buf20 to buf99 are "work buffers".  Work buffers are used
for storing cut/paste/copy text or for any other purpose.  Functions that
insert text, such as insertRgn(), create work buffers automatically if they
do not already exist.  Functions that do not insert text, such as getFlag(),
return False when the buffer referenced in them does not exist.  Work buffers
that are created continue to exist until you quit Uedit or free them in some
command that uses freeBuf(), such as Free Buffers (A-f3).

2.22 Integer Variables N0 to N99

There are 100 general purpose integer variables, n0 thru n99, available for
commands.  Integers may be referenced directly (n54) or by indexing into the
integer array (n[n20]).  Also there are named integer variables, such as
lineLength and cmdMultiplier, which are listed in Part 3 in the function
argument lists.  Using the number stack, any number of integers may be
stored, up to the limit of memory.  (See Buffer Stack, 1.20.7.  Also see the
CL functions push(), pop(), rollStack(), and getStackSize() in 3.4.)

When indexing into the number array is used, the command is aborted if the
index is out of bounds.  For example, n[n22] causes an abort when n22 is not
in the range 0 to 99.

Integer variables may have any 4-byte positive, zero, or negative value.  No
checking for overflow takes place in the arithmetic functions, such as mul()
and add().  Throughout Uedit, whether in using the CLI command-line flags, in
inputting numbers, or in the CL, numbers may be expressed in either decimal
or hexadecimal, with or without a minus sign.

Examples:
    add(n53,0xff490,n49[n54])
    sub(n40,n39,4)
    pop(cmdMultiplier)
    push(-400)

Commas ",", dollar signs "$", and decimal points "." are not recognized by
Uedit in numbers.  Commands which operate upon numbers in the text must look
for these special characters and handle them.  (See the arithmetic commands
in Config!M.)

2.23 Local and Global Integer and Flag Variables

Buffers each have the following local integer variables:  LineLength
PageLines LeftMargin TopMargin BottomMargin TabTable.  Each of these has a
global counterpart with the same name:  LineLength PageLines etc.

When a new buffer is opened, it picks up the current global values of both
integers and flags.  (Flags are discussed below.)  A buffer's local integer
values may be changed only by a command that uses setLocal().  Global integer
variables are changed using functions such as equateNum() and add(); they are
not changed as a by-product of setting local values.  (As discussed below,
global flags are changed by setting local flags, however.)

Examples of setting local and global integer values:
    equateNum(lineLength,100)               .. set global lineLength to 100
    setLocal(curFile,lineLength,lineLength) .. set local to global value
    setLocal(curFile,lineLength, 90)        .. set local lineLength to 90

There are global integer variables which have no local counterpart.  These
are:  allBut cmdMultiplier eitherOr idleTime inputChar macroNum menuOffset
multiWhite multiWild pmEsc prefPrint singleWhite splitSize userGlobalA
userGlobalB wildCard.

Certain of the global integer variables have a specified range of values
which should be adhered to, but in the CL it is possible to set them out of
range.  (See Config Defaults and their CL Arguments, 2.25.)

Flags are variables which have only two values, True or False.  Each buffer
has the following local flags:  autoBackup autoIndent changed favorite
mapChars overstrike readOnly rightJustify trueTabs userLocalA userLocalB
wordWrap.

A buffer's local flags may be changed by using flipFlag() and may be checked
using getFlag().  Local flags have a global counterpart of the same name,
except for the following which are local only:  changed favorite readOnly
userLocalA userLocalB.

Local and global integers and flags are treated as follows:  (1) The global
integers and flags are set initially in the config defaults, when the config
defaults are compiled.  (2) When a data file is loaded in at startup or
during an edit session, the global integers and flags in the data file are
loaded in.  (3) When buffers are created, they inherit the current global
integers and flags.  (4) Changing a buffer flag with flipFlag() changes both
the local and global flag.  Changing a buffer's global integer values, such
as lineLength, using setLocal() does not change the global integer variable.

Examples using flags:
    flipFlag(curFile,wordWrap)   .. affects local and global flags
    flipFlag(curFile,favorite)   .. affects local flag; there is no global flag
    getFlag(curFile,readOnly)    .. tests local flag; there is no global flag
    toggle(favorite)             .. switch to next file marked "favorite"

The following flags are global only and have no local counterpart:  busies
columnar cram hideDisplay icons lace learnMode markGadgets printTabs rowCol
scrollType searchCaps smartTabs speakAlerts speakMsgs spooks teachKeys
trapMenus useKeys userGlobalA userGlobalB.

Global flag variables serve both as flag variables which may be used in
flipFlag() and as integer variables which may be used in arithmetic functions
such as equateNum() and mul().  (See list 10 in Argument Lists used in the
Command Language, 3.1.)

2.24 UserGlobal Variables

userGlobalA and userGlobalB may be used as flags or integers.  They may be
used with arithmetic functions, such as equateNum(), and with the flag
functions, flipFlag() and getFlag().  The userGlobals are initialized in the
config defaults and may be preset to a value at runtime using the CLI
command-line flags, -A and -B.  UserGlobals have another advantage over the
n# variables, in terms of using them as flags or to store integer values, in
that they are stored on disk in the data file.  (See CLI Command Line, 2.1.)

When used with flipFlag(), if the userGlobal is non-zero, flipflag() sets it
to 0; if it is 0, flipFlag() sets it to 1.  Thus, if the userGlobal is being
used elsewhere as a bit-mask, flipFlag() destroys the upper bit settings
because it uses only the first bit.  GetFlag() returns True, if the
userGlobal is non-zero, or False, if it is 0.  When flipFlag() or getFlag()
is used with a global flag variable, the buffer argument in these functions
is just a dummy that is ignored.

32 bit-flags in each userGlobal may be maintained, using the and() and or()
arithmetic functions.  The following example illustrates the use of flag-bits
in userGlobalA:

    if (not and(n54,userGlobalA,128)) alertUser("128-bit not set")
    or(userGlobalA,userGlobalA,128)                        .. set the 128-bit
    if (and(n54,userGlobalA,128)) alertUser("now 128-bit set")

All flag bits are set by using <-1> or <0XFFFFFFFF> in the config defaults or
using equateNum(userGlobalA,-1).  As mentioned above, userGlobals are saved
to disk when the data is saved and are loaded in when a data file is loaded
in; thus, in a custom config up to 64 global bit-flags are available, or
ranges of bits may be masked in order to store a number of numerical values.
The following routines treat userGlobalA as a bit-mask:

This routine checks the bit(s) indicated by n54.  The ANDed result is put
into n53, but the True/False return of runKey(virtual-b) also tells whether
the bit is set or not:
    <virtual-b:  and(n53,userGlobalA,n54) >

Example:
    equateNum(n54,16)
    if (runKey(virtual-b)) putMsg("16-bit of userGlobalA is ON")

This routine turns on the bit(s) indicated by n54.  It returns False, only if
both n54 and userGlobalA are 0:
    <virtual-1:  or(userGlobalA,userGlobalA,n54) >

This routine turns off the bit indicated by n54.  It returns False, if it
leaves no bits set in userGlobalA:
    <virtual-0:  sub(n53,-1,n54)    .. get bit-mask without the bit in n54
        and(userGlobalA,userGlobalA,n53) >    .. preserve all but the n54 bit

This routine toggles the bit indicated by n54:
    <virtual-t:  if (runKey(virtual-b)) runKey(virtual-0)    .. on, turn it off
        else runKey(virtual-1) >    .. off, turn it on

2.25 Config Defaults and their CL Arguments

The defaults in the root segment of a config preset the values of global
integer and flag variables.  (See the Config! file.)  The globals, in turn,
pass on their values to their local counterparts in buffers, when buffers are
created, such as when a files are loaded in.  For example, in the defaults of
Config! is a setting for the global lineLength; when a file is loaded in or a
buffer is created, it will pick up this value for lineLength unless the
global lineLength has been changed during an edit session.

Below is a list of the config defaults and their corresponding global or
local variables.  Most of the defaults are global.  A few are local and
global.  Three of the defaults, MaxFiles, Color, and Eol, exist internally
only; that is, they cannot be used as arguments in arithmetic or flag
functions such as equateNum() or flipFlag().  Their values may be changed in
the CL using setMaxFiles() for MaxFiles, setLocal() or setColors() for Color,
and setEol() for Eol.

The defaults marked "G:" are global only.  Those marked "L:" are local but
most have global counterparts.  In the following, unless a range of allowed
settings is given, <0>=Off and <1>=On is used:

 (CL variable)   value    Description and values allowed
--------------   -------  --------------------------------
G:(internal only) <topaz> Font name.
G:(internal only) <8>     Font size.
G:(pmEsc)         <27>    Primitive Mode terminator.  ASCII value, 4-31.
G:(userGlobalA)   <0>     User global flag A.  Any integer value.
G:(userGlobalB)   <0>     User global flag B.  Any integer value.
G:(columnar)      <0>     Columnar display mode.
G:(cram)          <0>     Cram display mode.
G:(rowCol)        <1>     Show page-row-column.
G:(markGadgets)   <1>     Mark gadgets.
G:(lace)          <0>     Screen type.
G:(spooks)        <1>     Show invisibles.
G:(busies)        <0>     Show busies.
G:(teachKeys)     <0>     Teach keys mode.
G:(internal only) <35>    Maximum files to edit.  1-100.
G:(icons)         <0>     Make icons.
G:(searchCaps)    <0>     Search (or grep) case-sensitivity flag.
G:(wildcard)      <?>     Search single wildcard.      Printable character.
G:(eitherOr)      <$>     Search either-or delimiter.  Printable character.
G:(multiWild)     <*>     Search multi-wildcard.       Printable character.
G:(allBut)        <~>     Search all-but delimiter.    Printable character.
G:(singleWhite)   <0>     White at single wildcard: 0=no, 1=space/tab, 2=any white.
G:(multiWhite)    <0>     White at multi wildcard: 0=no, 1=space/tab, 2=any white.
G:(menuOffset)    <75>    Percent offset for submenus.  0-100 percent.
G:(learnMode)     <0>     RESERVED  (l)
G:(cmdMultiplier) <0>     RESERVED  (m)
G:(speakAlerts)   <0>     Speak requester alerts.
G:(speakMsgs)     <0>     Speak messages.
G:(printTabs)     <0>     If 0, convert tabs to spaces when printing.
G:(smartTabs)     <1>     If 1, don't convert tabs to spaces inside quotes.
G:(customScreen)  <0>     0=Workbench screen, 1=Custom screen.
G:(useKeys)       <0>     Use printable keys for typing, disabling commands on them.
G:(prefPrint)     <2>     Printer selection.  0=par:, 1=ser:, 2=prt:, 3=prt: (raw).
G:(idleTime)      <100>   Idle-time (tenths of seconds).  1-32767.
G:(hideDisplay)   <0>     Suppress display updates when working.
G:(scrollType)    <1>     Scroll type: 0 = show colors, 1 = faster
G:(trapMenus)     <0>     Trap menus to use menu mouse button as a key
G:(sWidth)        <640>   Screen width (640-1064)
G:(sHeight)       <200>   Screen height (200-1064) (auto-doubled for lace)
G:(tinyPriority)  <0>     Task priority when in tiny window (-128 to 127)
G:(capsLock)      <0>     RESERVED
G:(clickTime)     <0>     RESERVED
G:(userGlobalC)   <0>     User global flag C.  Any integer value.
G:(userGlobalD)   <0>     User global flag D.  Any integer value.
L:(trueTabs)      <1>     Put in tabs, not spaces, when tab key pressed.
L:(autoIndent)    <1>     Autoindent mode.
L:(overstrike)    <0>     Overstrike mode.
L:(autoBackup)    <0>     Autobackup mode.
L:(readOnly)      <0>     RESERVED  (r)
L:(wordWrap)      <1>     Wordwrap mode.
L:(rightJustify)  <0>     Rightjustify mode.
L:(mapChars)      <1>     Map illegal chars (ASCII 0-3) to table values.
L:(changed)       <0>     RESERVED  (c)
L:(userLocalA)    <0>     User local flag A.  (0-1)
L:(userLocalB)    <0>     User local flag B.  (0-1)
L:(tabTable)      <4>     Tab ruler to use.   0-4.
L:(lineLength)    <77>    Line-length.  1-9999.
G:(splitSize)     <2>     Split window size.  2 to max lines in window.
L:(leftMargin)    <0>     Left margin.    0-255.
L:(topMargin)     <5>     top margin.     0-255.
L:(bottomMargin)  <5>     bottom margin.  0-255.
L:(pageLines)     <66>    lines/page.     1-255.
G:(internal only) <10>    Eol character.  10 = Newline, 13 = Carriage Return.
L:(internal only) <3><2><0><1>  4-color combination when using 2 bitplanes.


2.26  Comments and Literals in Commands

Comments may be put into commands by prefacing the comment with two dots
"..".  Anything on the same line after the two dots is taken as part of the
comment.  Example:
    putMsg("This is a test") .. this is a comment
    updateDisplay ..refreshDisplay .. is commented out

Putting 2 dots in front of the left angle bracket of a command or config
default value causes it to be invisible to the compiler.  Example:
    ..<normal-esc:  putMsg("The compiler won't see this command")
          alertUser("even though there are more lines like this in it") >

Quotes can be embedded inside quotes by using backslashes.  Example:
    putMsg("testing \"z\"")   .. displays as:  testing "z"

Inside quotes, a double-backslash puts in a backslash.  Example:
    putMsg("testing \\ ")     .. displays as:  testing \

Functions that accept integer variables also accept a literal argument
instead.  If the literal is longer than 4 bytes, only the last 4 bytes are
used in arriving at the 4-byte integer equivalent of the literal.  Examples:
    equateNum(n54,"A") .. n54 = ASCII value of "A" (65)
    mul(n54,100,"abcdef") ..n54 = 100 * (4-byte integer equal to "cdef")

2.27 Compile Errors

When compiling a command, if an error is found Uedit does not tell you in so
many words what the error is normally.  The only error it reports verbally is
"Bad goto", which is discussed below.

The kinds of compile-errors that may occur are the following; in each case,
the compiler stops, the screen flashes, and the cursor is on the error spot
or just after it, depending on the type of error:

    Not enough memory to compile a command.
        The "Memory..." message appears.  The cursor is still at its starting
        point, because the compiler cannot find 10k of memory for the command
        buffer.  Or if it finds 10k for the buffer but cannot allocate the
        memory to copy the new command into, the cursor stops on the ending
        angle bracket ">".

    Command too big (more than 20k bytes) when compiled.
        It is unlikely that you will encounter this error, except as a by-
        product of a mistake in the command.  If the cursor ran beyond the
        end of the right angle bracket ">", down lower into some text after
        the command, you forgot to close a set of quotation marks.  The
        compiler thought it was reading a giant quoted argument and ran over
        the 10k size limit trying to find the close-quote mark.

        If the cursor stops inside the command, chances are still good that
        you have not exceeded the size limit.  But if you suspect that you
        may have, put a left angle bracket before the error spot, truncating
        the command.  If it compiles successfully, the size is reported and
        you will know whether size is a problem.  If size is not the problem,
        see the errors below.

    No label for goto.
        Example:  goto label(10) .. but there is no label(10) in the command.
        The message "Bad goto" is displayed.  The cursor stops at the end of
        the command on top of the ending angle bracket ">".  Search on
        "label" and find out which label() referenced in a goto has not been
        defined.

    Misspelled function or argument name.
        The cursor stops right after the last letter in the misspelled word.

    Invalid function argument.
        The cursor stops right after the invalid argument.

        Example:  moveCursor(curFile,hilite) .. should be sHilite or eHilite

    Too many function arguments
        The cursor is on the comma after the last legal argument.  The
        compiler expects to find a closing parenthesis but finds a comma, so
        it stops on the comma.

        Example:  moveCursor(curFile,eLine,sHilite) .. only 2 args required.

    Not enough function arguments
        The cursor stops on the right parenthesis, if the function has
        parentheses.  If it has no parentheses, the cursor stops on the first
        non-white character after the function name, because the compiler is
        looking for a left parenthesis and space between a function name and
        the beginning parenthesis is allowed.

        Example:  moveCursor(curFile) .. 2 arguments are required.

    Unbalanced parentheses or curly brackets
        Example:  if (eqNum(n54,n53) goto label(10)

        Leaving off the 2nd closing parenthesis in if()s and while()s is a
        very common mistake.  It is easy not to spot this, because extra
        whitespace is allowed.  The compiler flags this error by putting the
        cursor where the right parenthesis should be.  Instead of stopping
        just after the last word, as if it were misspelled, it stops on the
        first non-white character, which is the letter "g" in the above
        example.

        A missing closing curly bracket "}" is not detected by the compiler
        until it reaches the end of the command, because structures may be
        nested to arbitrary depth.  A missing-curly-bracket error may seem
        really puzzling until you learn to look out for such errors.  If the
        screen flashes, leaving the cursor on the ">" closing angle bracket
        of the command, look for unbalanced curly brackets.

An experienced user can debug commands rapidly, even though the compiler does
not state what the error is.  The speed of Uedit's compiler aids the learning
process and thinking logically is definitely helpful; for instance,
whitespace is allowed everywhere, and whether the cursor stops on whitespace
or on the next black character tells you whether the last word is bad or the
next character after it should be a comma or parenthesis and is not.  You can
make changes and get feedback in just a few seconds, due to the speed of the
compiler; small commands compile in less than 1 second.

2.28 Runtime Errors

Once a command has been compiled successfully, it can be tried out.  Runtime
bugs are usually easy to figure out and fix.  But in complex commands they
may be hard to track down, until you put diagnostics into the command.
Diagnostics are messages that tell you what the command is doing as it is
running.  After typing in the diagnostics, you must recompile the command.
When finished using the diagnostics, erase them or comment them out and
compile the command one last time.

Diagnostics should be easy to put in, move around, and get rid of.  It may be
convenient to write a small diagnostic routine that you can call with
runKey() anywhere in the command you're debugging.  The diagnostic may use
inputString(), alertUser(), or putMsg() to display its messages.  putMsg()
may flash by too quickly to read, unless you put a delay() after it.  On the
other hand, inputString() and alertUser() both require an input before
allowing the command to continue, so no delay() is needed.

There are two classes of runtime bugs for which diagnostics are helpful:

1.  If there are many goto's and nested curly brackets and you aren't sure
where the action is, plant messages at key locations to find out which
section is currently running and to discover which parts are never accessed.
The diagnostic needs to tell you its location and it should require a
response so that it does not flash by too quickly to see. Example:
alertUser("label(10)") or alertUser(10)

2.  If a command is mishandling a buffer's contents, you can use
inputString() at key spots to monitor the buffer's contents.  It waits until
you click the mouse button or press ESC.  It even lets you modify the buffer.
Example:  inputString(buf54)

You can monitor a suspected number variable in the same way that you would a
buffer variable.  Example: alertUser(n49) or putMsg(n49)

Runtime bugs seem obvious once you figure out what the problem is.  But
large, complex commands may be hard to debug, unless you trace through them
using diagnostics.  Form the habit of using diagnostics, when large commands
are not doing right and you cannot immediately see why.  The answer is always
simple and obvious ... once you find it.

But, better yet, form the habit of not writing huge, spaghetti-code commands.
If a command is hard to debug, break it into small, clear modules.  If it is
too confusing even to break up cleanly, rewrite it from scratch using crisp
modular routines.  For routines that should not be run directly by giving an
input, but rather should only be run by commands using them, use the "unused"
slots in the table of MacroNums or use the virtual key-prefix.

2.29 Valid Key Arguments

Commands in Uedit are assigned to "keys".  A "key" is an input with the
keyboard or mouse.  Menu selections run existing keys, so they are not
considered to be keys themselves.  The window CloseBox and message-line
gadgets are "keys".  Pressing the left mouse button is a "key"; releasing it
is a "key".  Actually any number from 1 to 1199 may be used as a "key" in the
CL.  Some of the numbers in this range do not correspond to keyboard or mouse
button inputs and cannot be expressed using a key-name such as shftAlt-f1 or
ctl-CloseBox; these are "unused" slots in the table of MacroNums; but
commands may still be assigned to them and may be run as routines by using
runKey() even though they cannot be run directly by giving an input.  (See
Keys and MacroNums, 2.31.)

The only "dedicated" key in Uedit in normal operation is (left or right)
Amiga-ESC, the general-purpose Abort key.  But even those may be assigned
commands.  The commands cannot be run by inputting left or right Amiga-ESC,
but they may be run as routines by other commands or by menus.

A "key argument" is a key used in the command language.  In the function
argument lists in Part 3, wherever "keyArg" appears in a list, a key argument
may be used.  Key arguments are integer constants and cannot be modified by a
command.  Example:
    <lAmiga-h: equateNum(n54,ctl-x) putMsg(ctl-x)>

In the above example, lAmiga-h is the key for which the command is defined.
The value of key argument ctl-x is stored in the integer variable n54 by
equateNum() and is also displayed by putMsg().

The compiler converts key arguments into their MacroNums, integers which
identify commands in Uedit.  At runtime, equateNum(n54,ctl-x) stores the
MacroNum of ctl-x in variable n54.  (You may compile a command with
equateNum(ctl-x,99) in it, but nothing useful happens at runtime.  Similarly,
you may compile equateNum(3,99), but again nothing useful happens as a
result.)

All key arguments, except Startup, Idle, and PreKey, require a modifier or
prefix, such as "normal-" or "shftAlt-".  The "virtual-" prefix means that
the key cannot be input with the keyboard or mouse.  Virtual commands are
useful as routines run by menus or by other key commands using runKey().  By
using the "virtual-" prefix on all keys that may be run by other keys in your
custom config, or by always using "unused" MacroNum-slots for them, you are
making it possible to swap any key in your custom config using Swap Keys
without running the risk of swapping away a key that is run by some other
key.  Also virtual routines offer a degree of safety in that they cannot be
run directly by giving an input.

The prefixes (modifiers) used in key arguments are:
normal-     shft-       alt-        ctl-       shftAlt-    shftCtl-    altCtl-
shftAltCtl- lAmiga-     rAmiga-     virtual-

In key arguments, the prefix or modifier is followed by a printable key, such
as "z" and "." or by a non-printable key such as a "f1" or "esc".

The non-printable keys are:
         esc tab f1 f2 f3 f4 f5 f6 f7 f8 f9 f10
         del bs (for backspace) help return space
         upArrow downArrow leftArrow rightArrow
         kpMinus kpEnter kpDot                  ("kp" is for "keypad")
         kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 kp0
         kpLParen kpRParen kpSlash kpStar kpPlus  (Amiga 2000/3000)
         buttonDown buttonUp                    (Left mouse button.)
         menuDown menuUp                        (Right mouse button.  Can only
                                                be input if trapMenus is True.)
         closeBox                               (Close-box in Title Bar.)
         gadget1 gadget2 gadget3 gadget4        (Gadgets in the message line.)

Examples of valid key arguments are:
         shftAlt-f1:
         altCtl-upArrow:
         ctl-/:
         alt-kpDot:         ("kp" refers to keypad.)
         normal-buttonDown: (Left mouse button.)
         shft-closeBox:     (Close-box in Title Bar.)
         ctl-gadget3:       (Each "gadget" is 1/4 of the message line.)
         shft-7:            (The "7" is not the one on the keypad.  That one
                             would be "shft-kp7".)
         startup:           (Startup is not allowed a prefix.)
         idle:              (Idle is not allowed a prefix.)
         altCtl-esc:
         normal-del:
         lAmiga-p:
         0X400:            (a raw MacroNum in the range 1 to 1199 is valid)
         800:
         normal-z:         ("z" is a printable key, but that's ok.)

Examples of invalid key arguments are:
         normal-$:     (Use UNSHIFTED.  It should be shft-4:.)
         shft-preKey:  (PreKey cannot use a prefix.)

Certain Amiga-key combinations are not sent to Uedit properly or at all by
the Amiga.  For safety, some of them are internally mapped to Amiga-ESC, the
abort key.  These keys cannot be run from the keyboard, but they may be
assigned to commands that are used as routines.  Do not use the following
keys for commands to be run from the keyboard:
    lAmiga- & rAmiga- with ESC upArrow downArrow leftArrow rightArrow
    lAmiga-           with n m ESC
    rAmiga-           with ' ; , / tab bs = 6 7 9 ESC kp2 kp6 kp9

You may still create commands for the keys, kpLParen, kpRParen, kpSlash,
kpStar, and kpPlus, and use them as routines, even if your Amiga keyboard
does not have those keys.  Their commands can be used as routines which are
run by other commands or can be invoked directly from the menus.

The compiler converts each key argument into a MacroNum between 1 and 1199.
Anywhere in the CL that a key argument is allowed, a raw number from 1 to
1199 may be used instead.  (See Keys and MacroNums, 2.31.)

2.30 InputChar and MacroNum

InputChar and MacroNum are integer variables which have the most recent input
in them.  InputChar contains the most recent character picked up by the input
stage.  MacroNum has the most recent macro number from the input stage.  Any
input that you give, whether by keyboard or mouse, assigns values to both
InputChar and MacroNum.  (See Keys and MacroNums, 2.31.)

If the input is not a printable ASCII character, InputChar is 0.  MacroNum is
never 0.  When a command exists for MacroNum, InputChar is set to 0 by the
input stage (except in Primitive Mode).  Uedit's work-loop calls the typing
routine, if InputChar is non-zero.  If InputChar is 0, it calls the engine
that runs commands, if a command exists for MacroNum.  Thus, whether or not
inputChar is 0 determines whether the command for MacroNum gets run or not,
assuming that MacroNum has a command.

In a PreKey command, you can capture InputChar and MacroNum before Uedit's
work-loop sees them.  Thus, you can control the work-loop using PreKey.  In
all other commands except PreKey, it doesn't matter what you do with
InputChar and MacroNum; by the time any other command sees them, the work-
loop has acted upon them.  Changing their value anywhere except in PreKey has
no effect on the work-loop.  (See PreKey, 2.32.)

Commands can tell what input was given by looking at InputChar & MacroNum.  A
routine called by a command can tell who the caller is, because the caller's
macro number is in MacroNum.  A caller can influence or instruct the routines
it calls by manipulating the value of MacroNum and InputChar.

InputChar and MacroNum, along with PreKey, give a lot of front-end control
and flexibility.  You can emulate a 2-key editor by creating a PreKey command
that requests a second input based on the first input.  You can emulate
Insert and Command modes of operation like some editors use, by zeroing
InputChar selectively in a PreKey command.

In Primitive Mode, MacroNum is always set to zero by the input stage and if a
preKey command exists, it is not run during Primitive Mode.  Only inputChar
is processed in Primitive Mode.  (See Primitive Mode, 1.7.)

When Use Keys (A-u) in the menu is checkmarked, printable keys with commands
become typable letters again.  The input stage no longer zeroes inputChar
when they are typed, which causes the work-loop to act on inputChar rather
than acting on their MacroNum.  (See Global Modes, 1.19.)

The following PreKey command reports the values of InputChar and MacroNum
when you give any input.  Typing SAC-ESC kills this PreKey, causing an abort.
This preKey sets InputChar and MacroNum to 0, so that the input is ignored by
the work-loop:

<PreKey:  if (eqNum(MacroNum,shftAltCtl-ESC)) killKey(preKey) .. escape hatch!
          freeBuf(buf54)
          insertRgn(buf54,eFile,"MacroNum = ",all)
          toWord(buf54,MacroNum)
          insertRgn(buf54,eFile,",  InputChar = ",all)
          toWord(buf54,InputChar)
          if (inUse(MacroNum)) insertRgn(buf54,eFile,"  CMD KEY",all)
          putMsg(buf54)
          equateNum(InputChar,0)
          equateNum(MacroNum,0) >

When you experiment with the above command, note that InputChar is always 0
when the input has got a command.  And MacroNum is never zero.  The work-loop
looks first at InputChar; if non-zero, it types in the character.  If
InputChar is zero, it looks at MacroNum; if it has a command, the command is
run.

To see how the global useKeys flag works, compile a command for a printable
key such as the following:
    <shft-a:  putMsg("Shift-a command") >.

Then compile the PreKey command above.  Notice that when you type shft-a,
InputChar is 0, because now shft-a has a command.  Now kill PreKey by
pressing SAC-ESC.  Select Use Keys (A-u) to turn On the useKeys flag.
Compile PreKey again and try shft-a.  This time InputChar is 65 (not 0),
because useKeys is causing the input stage not to zero inputChar; as a
result, Uedit's work-loop would process inputChar instead of MacroNum for all
printable keys, bypassing their commands.

To make Uedit do nothing with an input, set InputChar and MacroNum to 0 in
PreKey.  To make it run the command for MacroNum instead of typing the
character in InputChar, set InputChar to 0.  To force all printable
characters to show up in InputChar, turn On Use Keys; then your PreKey can
decide what to do.  You can use inUse(MacroNum) in a PreKey command, to
determine whether MacroNum has a command or not.

To detect CAPSLOCK, do the following in a preKey command:  When a capital
letter A-Z is in InputChar (ASCII 65-90), examine MacroNum.  If MacroNum is
less than 104, this is an unshifted macro number, so the Shift key was not
used; therefore CAPSLOCK must be On.  (See Keys and MacroNums, 2.31.)  The
following example reports when CAPSLOCK is On, if you type a letter from A to
Z:

    if (geNum(InputChar,"A")
           & geNum("Z",InputChar)
             & geNum(104,MacroNum)) putMsg("CAPSLOCK is turned ON")

CL functions that collect an input change the value of InputChar and
MacroNum, so that the old values are no longer available.  These functions
are:
        getKeyVal(), getKey(), and getChar().
        inputKey(), if it finds an input waiting, returning TRUE.
        askYesNo() and alertUser(), requesters.
        setRuler().
        inputString() and inputNum(), the Primitive Mode functions.

If you need InputChar and MacroNum preserved when using any of the above
functions, store them in number variables beforehand or push them onto the
number stack.  The fact that these functions change the value of InputChar
and MacroNum may be useful; the most recent input given to the above
functions is in InputChar and MacroNum, and commands may look at these and
learn something about what happened earlier.

The getKeyVal(), getKey(), and getChar() CL functions report the true ASCII
character value and/or macro number of an input, regardless of whether the
macro number has a command or not.  With these functions, the input character
is always non-zero when it is a printable character, even if MacroNum has a
command and regardless of the status of useKeys.  (See these CL functions in
3.4.)

2.31 Keys and MacroNums

Each key argument maps into a unique positive MacroNum in the range 1 to
1199.  When a command is compiled, the compiler converts key arguments to
their MacroNums.  Anywhere in a command that a key argument may be used, a
decimal or hexadecimal number from 1 to 1199 may be used instead.

There are 104 unmodified MacroNum values, corresponding to all unshifted
inputs as well as a number of "unused" slots which are discussed below.
These include all keys on the keyboard, the mouse buttons, CloseBox, and
message-line gadget inputs.  There are 11 shift-modifier combinations for
each key, including the "virtual-" modifier which cannot be input directly.

If a shift-modifier is used, a multiple of 104 is added to the basic MacroNum
to get the shift-modified MacroNum.  Using all shift-modifiers, there are
1144 MacroNum values.  The special MacroNums, which do not use shift
modifiers, are:
        rexxMacro     1145
        idleMacro     1146
        preKeyMacro  1147
        startupMacro 1148
        onAbort      1149
        onTitle      1150

The macroNums 1151-1199 are "unused" and available for any purpose.

If a MacroNum has an unmodified value (less than 104), you can get its "shft-
" value by adding 104.  If it has a shift-modified value, you can get its
unshifted value by using mod(MacroNum,MacroNum,104).

MacroNums are calculated using the tables below, by adding the basic MacroNum
to the appropriate shift-constant.  The formula is:
    MacroNum  = basic MacroNum (Table 2) + shift-constant (Table 1)

    Example:  shftAlt-z = z (Table 2 value=49) + shftAlt (Table 1 value=312) = 361

Table 1.  ADDITIVE CONSTANTS FOR SHIFT-MODIFIERS
         Shift-keys  Multiply 104 by  ==>  Add this to get shifted MacroNum
         ----------  --------------        --------------------------------
         Normal          0                 0
         Shft            1                 104
         Alt             2                 208
         ShftAlt         3                 312
         Ctl             4                 416
         ShftCtl         5                 520
         AltCtl          6                 624
         ShftAltCtl      7                 728
         lAmiga          8                 832
         rAmiga          9                 936
         Virtual         10                1040

Table 2.  UNSHIFTED (BASIC) MACRONUMS
      Key     MacroNum    Key       MacroNum    Key      MacroNum
      ---     --------    ---       --------    ---      --------
      1           1        f           35       ESC         69
      2           2        g           36       DEL         70
      3           3        h           37       menuDown    71
      4           4        j           38       menuUp      72
      5           5        k           39       middleDown  73
      6           6        l           40       KpMinus     74
      7           7        ;           41       middleUp    75
      8           8        '           42       upArrow     76
      9           9        unused      43       downArrow   77
      0           10       unused      44       rightArrow  78
      -           11       Kp4         45       leftArrow   79
      =           12       Kp5         46       f1          80
      \           13       Kp6         47       f2          81
      unused      14       unused      48       f3          82
      kp0         15       z           49       f4          83
      q           16       x           50       f5          84
      w           17       c           51       f6          85
      e           18       v           52       f7          86
      r           19       b           53       f8          87
      t           20       n           54       f9          88
      y           21       m           55       f10         89
      u           22       ,           56       KpLParen    90
      i           23       .           57       KpRParen    91
      o           24       /           58       KpSlash     92
      p           25       unused      59       KpStar      93
      [           26       KpDot       60       KpPlus      94
      ]           27       Kp7         61       HELP        95
      unused      28       Kp8         62       buttonDown  96
      Kp1         29       Kp9         63       buttonUp    97
      Kp2         30       SPACE       64       gadget1     98
      Kp3         31       BS          65       gadget2     99
      a           32       TAB         66       gadget3     100
      s           33       KpEnter     67       gadget4     101
      d           34       RETURN      68       closeBox    102

Some of the "unused" MacroNums in the table above correspond to keys on
European keyboards.  128 of the lower and upper case keys can be remapped
using the printable key mapping arrays in the config defaults.  For example,
they can be mapped to European umlaut characters.  Mapping for Dvorak is also
possible, and a Dvorak mapping is available.  (See Mapping the Keyboard Keys,
2.10.)

Commands can be created for unused MacroNums, even though they have no key
name.  The MacroNum is used in place of the key name.  The following example
uses "unused" MacroNums:
        <43:  putMsg("this is a test") runKey(44) swapKey(148,14) >

Unused MacroNums are useful for routines that should not be run from the
keyboard but may be run as a routine by commands or menus.  To use a shift-
modified "unused" MacroNum, add a multiple of 104 to it.  Example:
        swapKey(normal-esc,148)   .. where 148 = 104 + 44

2.32 PreKey

PreKey, like Startup and Idle, cannot use shift-modifiers.  A PreKey command,
if one exists, is run after any input that you give, but before the input is
seen and processed by Uedit's work-loop.  PreKey is well suited for use in a
config that emulates a 2-key editor or one that uses Insert and Command modes
of operation.  PreKey is also useful in such applications as a spell-as-you-
type feature.

Here is an example of a PreKey command:
<PreKey:
    if (eqNum(MacroNum,shftAltCtl-esc)) killKey(PreKey)     .. Escape Hatch!
    freeBuf(buf54)
    insertRgn(buf54,efile,"InputChar = ",all)
    toWord(buf54,InputChar)
    insertRgn(buf54,efile," MacroNum = ",all)
    toWord(buf54,MacroNum)
    putMsg(buf54)      .. show the InputChar and MacroNum of the key typed.
        .. The following changes any printable InputChar to "a".
        .. Use shftAltCtl-ESC to kill PreKey and get out of this trap!
    if (gtNum(InputChar,0)) equateNum(InputChar,"a")
       .. This changes any MacroNum to F1, trapping you again!
    equateNum(MacroNum,normal-f1)
>

Because you can change InputChar & MacroNum in PreKey before the work-loop
sees them, you can lock up Uedit so that nothing short of rebooting can get
you out of it.  Aborting with Amiga-ESC does no good, because it does not
erase the PreKey command, and long as PreKey exists, it will run when any
input is given.  Always include an Escape Hatch line as in the above example.
Pressing SAC-Esc kills PreKey, unlocking Uedit.  Do not remove the escape
hatch until the PreKey command is thoroughly debugged and safe.

After PreKey runs, the work-loop validates InputChar and MacroNum.  A valid
InputChar has ASCII value 0 to 255.  If out of range, it is set to 0.  If
InputChar is 1 to 3 after PreKey, either it is mapped to a legal value, if
Map Illegals (SA-m) is turned On, or else nothing is typed in.  MacroNum must
have a value in the range 1 to 1199.  If out of range, it is set to 0 and
nothing is done.  (See Map Illegals, 1.31.9.  See Keys and MacroNums, 2.31.)

In using PreKey, there are two negatives to consider:  A PreKey command adds
extremely high overhead in running learned sequences.  Also there is the
possibility that a poorly designed PreKey may lock up Uedit, forcing you to
reboot and lose edits that have not been saved to disk.

When you set the Command Multiplier (C-m) and press a key such as Cursor Word
Left (kp4), PreKey (if it exists) is run only once, just before the multiple
executions of Cursor Word Left.  But when running learned sequences, PreKey
is run before each learned input is processed; this is because learned
sequences must behave as if the inputs were being freshly typed in.  There is
extreme overhead in running learned sequences when a PreKey exists.  To
minimize overhead, PreKey should be designed so that it returns as quickly as
possible.  It should be swapped to an unused key, when it is not needed.

2.33 Spell-Checking with PreKey

A spell-as-you-type feature can be implemented using PreKey.  The following
command swaps any existing PreKey command with virtual-c:

        <shftAltCtl-c: swapKey(virtual-c,PreKey) >

The following virtual-c command, when swapped to PreKey by pressing SAC-c,
checks spelling as you type:

<virtual-c:
        if (eqNum(InputChar,0)) return      .. don't mess up scrolling etc
        if (not spellerUp) return
        equateLoc(curFile,locA,atCursor)    .. save cursor loc
        moveCursor(curFile,sChar)           .. look at last char typed
        if (!is(curFile,alpha)              .. if not alpha, check preceding word
            & !is(curFile,"'")) {           .. apostrophe is alpha here
            clearRgn(buf54,all)             .. erase last word from buffer
            moveCursor(curFile,sWord)       .. move cursor to start of word to chk
            insertRgn(buf54,sFile,curfile,word) .. store just that 1 word
            moveCursor(buf54,sFile)         .. so speller sees the word
            if (not spell(" ",buf54)) { beepDisplay  putMsg(buf54) } .. bad
        }
        equateLoc(curFile,atCursor,locA)     .. put cursor back where it was
>

This PreKey alerts you when the word preceding the cursor is not in the
dictionary.  With the full working dictionary in memory, spell-checking keeps
up with fairly fast typing.  You can swap in and out the above PreKey as
needed by pressing SAC-c.  When swapped back out, it restores the original
PreKey command, if there was one.

The above PreKey could have been written to look at InputChar instead of
moving the cursor backward to look at the last character typed.  Perhaps this
would have been a better choice.  It would spell-check the previous word,
only if InputChar were not an alpha character or apostrophe.

2.34 Detaching Buffers

The CL functions getBufAddr(), detachBuf(), and attachBuf() make it possible
to pass Uedit buffers to or receive Uedit buffers from other programs.  These
functions are "dangerous" and should only be used by experienced programmers.
The following is the essentials needed in order to write programs that use
Uedit buffers:

Flag bits used in buffer CB header flags field:
#define  TRUETABS      0x0001
#define  AUTOINDENT    0x0002
#define  OVERSTRIKE    0x0004
#define  AUTOBACKUP    0x0008
#define  READONLY      0x0010
#define  WORDWRAP      0x0020
#define  RIGHTJUSTIFY  0x0040
#define  MAPCHARS      0x0080  /* for mapping of illegal characters */
#define  CHANGED       0x0100  /* when buffer has been modified */
#define  USERLOCALA    0x0200
#define  USERLOCALB    0x0400
#define  FAVORITE      0x0800
#define  BACKEDUP      0x1000  /* when autobackup, after backup created */
#define  NEEDPACK      0x2000  /* when buffer is fragmented */
#define  LOCKED        0x4000  /* when in file-save queue */
#define  DELETEIT      0x8000  /* when in file-save queue & freeBuf() called */

Markers used in buffer blocks:
#define  EOFILE   0x03  /* only ONE eof marker in each buffer */
#define  EOB      0x02  /* used only in the endOfBlock field of DB struct */
#define  TRACE    0x01  /* used temporarily when moving data */

Used in tests, when text is manipulated:
#define  ISMARKER(a)   (a<=EOFILE && a>0)
#define  ISWEIRD(a)    (a<=EOFILE)
#define  ISGOOD(a)     (a>EOFILE)
#define  ISPRINT(a)    (a>=' ')

Used in comparing locations, where a = blockptr and b = byteptr:
#define  loc(a,b)    (((ULONG)(a)->BlockNum << 16L) + (ULONG)b - (ULONG)a )

Data block structure used in block chains:
#define  BLOCKSIZE   256
#define  DATASIZE    (BLOCKSIZE - 12)
struct DB   {                   /* a buffer text block */
   UCHAR        Data[DATASIZE];
   UCHAR        endOfBlock;     /* EOB marker is always stored here */
   UCHAR        eols;           /* set to 255 when eols not counted */
   USHORT       BlockNum;
   struct DB    *LastBlock;
   struct DB    *NextBlock;
};

Buffer header structure:
struct CB {
   struct DB  *Block;    /* cursor block ptr */
   struct DB  *SHBlock;  /* sHilite block ptr */
   struct DB  *EHBlock;  /* eHilite block ptr */
   struct DB  *SIBlock;  /* sInvert block ptr */
   struct DB  *EIBlock;  /* eInvert block ptr */
   struct DB  *PBlock;   /* sPage block ptr */
   struct DB  *EBlock;   /* ePage block ptr */
   struct DB  *LABlock;  /* locA block ptr */
   struct DB  *LBBlock;  /* locB block ptr */
   struct DB  *LBBlock;  /* locB block ptr */
   struct DB  *LCBlock;  /* locC block ptr */
   struct DB  *LDBlock;  /* locD block ptr */
   struct DB  *LEBlock;  /* locE block ptr */
   struct DB  *LFBlock;  /* locF block ptr */
   struct DB  *LGBlock;  /* locG block ptr */
   struct DB  *LHBlock;  /* locH block ptr */
   struct DB  *LIBlock;  /* locI block ptr */
   struct DB  *LJBlock;  /* locJ block ptr */
   struct DB  *LSPBlock;  /* locSP block ptr */
   struct DB  *LSCBlock;  /* locSC block ptr */
   struct DB  *MBlock;   /* mouseLoc block ptr */
   UCHAR *Ptr;           /* cursor byte pointer */
   UCHAR *SHPtr;         /* sHilite byte pointer */
   UCHAR *EHPtr;         /* eHilite byte pointer */
   UCHAR *SIPtr;         /* sInvert byte pointer */
   UCHAR *EIPtr;         /* eInvert byte pointer */
   UCHAR *PPtr;          /* sPage byte pointer */
   UCHAR *EPtr;          /* ePage byte pointer */
   UCHAR *LAPtr;         /* locA byte pointer */
   UCHAR *LBPtr;         /* locB byte pointer */
   UCHAR *LCPtr;         /* locC byte pointer */
   UCHAR *LDPtr;         /* locD byte pointer */
   UCHAR *LEPtr;         /* locE byte pointer */
   UCHAR *LFPtr;         /* locF byte pointer */
   UCHAR *LGPtr;         /* locG byte pointer */
   UCHAR *LHPtr;         /* locH byte pointer */
   UCHAR *LIPtr;         /* locI byte pointer */
   UCHAR *LJPtr;         /* locJ byte pointer */
   UCHAR *LSPPtr;        /* locSP byte pointer */
   UCHAR *LSCPtr;        /* locSC byte pointer */
   UCHAR *MPtr;          /* mouseLoc byte pointer */
   struct DB *NextBlock; /* points to First Block in DB chain */
   short  PageCol;       /* col where window display begins, usually 0 */
   short  BufNum;        /* buffer number, 0 to 99 */
   ULONG  Flags;         /* buffer flags, see flags above */
   USHORT LineLength;    /* line length being used */
   USHORT PageLines;     /* lines per page being used */
   short  tabTable;      /* must be 0 to 4 */
   short  LeftMargin;    /* must be 0 to 255 */
   short  TopMargin;     /* must be 0 to 255 */
   short  BottomMargin;  /* must be 0 to 255 */
   ULONG  colors;        /* 32 bit color mask, 2 bits per color */
   long   reserved1;
   long   reserved2;
   UCHAR  FileName[83];
};

DetachBuf() must NEVER be called, UNLESS you have first called getBufAddr()
and stored the buffer's address in an integer variable!  Having detached a
buffer, you can pass its address to another program.  Do NOT pass the address
of buffers, unless you have detached them from Uedit beforehand.  Here are
some guidelines to follow in using Uedit buffers in other programs:

(1) All block pointers in the CB header structure must point to blocks in the
buffer's block chain.  None may be null, and none may point beyond the block
that has the EOFILE marker in it.

(2) All byte pointers in CB buffer header structs must point to valid, non-
null text in the SAME block that their corresponding block pointer points to.
They must never point to a null byte.  They must never point outside the
Data[] array in buffer blocks.  They must never point to the EOB (endOfBlock)
field of the block.  They may point only to valid ASCII characters 4-255 or
to the EOFILE marker inside block Data[] arrays.

(3) In DB Data[] arrays, the only characters allowed are nulls (0) to replace
cleared text, valid ASCII characters 4-255, and one EOFILE marker.

(4) When packing or splitting buffer blocks, it is faster if TRACE characters
are embedded at the address of each CB byte-pointer, temporarily replacing
the text bytes stored there.  Then data can be moved quickly and the CB
pointers need only be adjusted when a TRACE is tripped over.  When the
operation is over, swap back in the characters that were replaced by TRACEs
earlier.

(5) The last block in a buffer chain must have a NULL NextBlock pointer.

(6) The first block in a buffer chain must point to the CB buffer header
structure.  The CB NextBlock field must point to the first block in the
chain.  Buffers must always have at least one data block, even if it only
contains the EOFILE marker in Data[0].  (In this case, ALL CB block and byte
pointers must be pointing to EOFILE at Data[0].)

(7) Each block's endOfBlock field must have an EOB character in it.  Testing
for EOB is easier than indexing into the Data[] array.

(8) The eols field in each block must be set to 255, if you modify the block
and are not counting the eols in it.  If the block contains a formfeed (ASCII
12), the eols field must be set to 255.

(9) After the EOFILE marker, there must be nothing but null bytes in the
Data[] arrays.  Preferably there should be no blocks beyond EOFILE's block.
If there are any empty blocks beyond EOFILE's block, the NEEDPACK bit in the
buffer's flag must be set.

(10) If a data block is modified, the CB structure flag field MUST have the
NEEDPACK bit set.  Also you may set the CHANGED bit.  Do NOT set the LOCKED
or DELETEIT flag bits.

Unless serious need exists and you are an experienced programmer, it is
strongly recommended that the functions discussed here not be used.  The
author accepts no liability for damage done by programs manipulating Uedit
buffers or by Uedit when you pass buffers to it that have been touched by
other programs.

Part 3. :::

Part 3.  Command Language Documentation

3.1  Argument Lists used in the Command Language

Uedit's CL functions use the following 15 argument lists:

LIST 0:   buf# curFile literal

LIST 1:   literal

LIST 2:   buf# curFile

LIST 3:   bottomMargin color lace leftMargin lineLength pageLines tabTable
          topMargin

LIST 4:   downLine eChar eFile eForm eHilite eInvert eLine ePage eTab eWord
          locA locB locC locD locE locF locG locH locI locJ locSC locSP
          mouseLoc sChar sFile sForm sHilite sInvert sLine sPage sTab sWord
          upLine

LIST 5:   atCursor downLine eFile eForm eHilite eInvert ePage locA locB locC
          locD locE locF locG locH locI locJ locSC locSP n# number sFile sForm
          sHilite sInvert sPage upLine

LIST 6:   atCursor eFile eHilite eInvert ePage locA locB locC locD locE locF
          locG locH locI locJ locSC locSP mouseLoc sFile sHilite sInvert sPage

LIST 7:   atCursor eHilite eInvert locA locB locC locD locE locF locG locH locI
          locJ locSC locSP mouseLoc sHilite sInvert sPage

LIST 8:   eHilite eInvert locA locB locC locD locE locF locG locH locI locJ
          locSC locSP sHilite sInvert

LIST 9:   allBut eitherOr eLine inputChar literal multiWhite multiWild n#
          number pmEsc singleWhite wildCard

LIST 10:  allBut autoBackup autoIndent bottomMargin buf# busies capsLock
          clickTime cmdMultiplier curFile customScreen eitherOr hideDisplay
          icons idleTime inputChar keyArg leftMargin lineLength literal
          macroNum mapChars menuOffset multiWhite multiWild n# number
          overStrike pageLines pmEsc prefPrint printTabs rightJustify
          scrollType searchCaps sHeight singleWhite smartTabs speakAlerts
          speakMsgs splitSize spooks sWidth tabTable tinyPriority topMargin
          trapMenus trueTabs useKeys userGlobalA userGlobalB userGlobalC
          userGlobalD wildCard wordWrap

LIST 11:  alpha blankLine ctlChar decimalNum digit eFile eForm eLine ePage
          eWord formFeed hexNum lineTooLong literal lowerCase n# number sFile
          sForm sLine space sPage sWord tabColumn upperCase whiteSpace

LIST 12:  all char hilite invert line loc locCD locEF locGH locIJ locPC word

LIST 13:  allBut autoBackup autoIndent bottomMargin busies capsLock clickTime
          cmdMultiplier customScreen eitherOr hideDisplay icons idleTime
          inputChar leftMargin lineLength macroNum mapChars menuOffset
          multiWhite multiWild n# overStrike pageLines pmEsc prefPrint
          printTabs rightJustify scrollType searchCaps sHeight singleWhite
          smartTabs speakAlerts speakMsgs splitSize spooks sWidth tabTable
          tinyPriority topMargin trapMenus trueTabs useKeys userGlobalA
          userGlobalB userGlobalC userGlobalD userLocalA userLocalB wildCard
          wordWrap

LIST 14:  autoBackup autoIndent busies changed columnar cram favorite
          hideDisplay icons lace learnMode mapChars markGadgets overStrike
          printTabs readOnly rightJustify rowCol scrollType searchCaps
          smartTabs speakAlerts speakMsgs spooks teachKeys trapMenus trueTabs
          useKeys userGlobalA userGlobalB userGlobalC userGlobalD userLocalA
          userLocalB wordWrap

Certain arguments in the above lists are abbreviated, and the correct CL to use is:

       In List    Correct Command Language
       -------    ------------------------
       n#         n0 to n99 or n[n0] to n[n99]
       buf#       buf0 to buf99 or buf[n0] to buf[n99]
       literal    "anything in quotes"
       number     123456 (decimal or hexadecimal integer)
       keyArg     valid key argument, such as normal-t or shftAlt-f10


ADD: setTaskPri(P list 10)
ADD: setFont(F list 0, H list 10)
FIX: spell(B1 list 0, B2 list 2, B3 list 0)
ADD: draw(X,Y,C,M,F) all are list 10
ADD: sortLines(B list 2, C list 10)
ADD: inTiny
ADD: screenToBack
ADD: screenToFront
FIX: spacesToTabs(B list 2)
FIX: tabsToSpaces(B list 2)
ADD: getFont(F list 2, X list 10, Y list 10)
ADD: fullRefresh
ADD: compareBuf(B1 list 2, B2 list 2)
ADD: clearBuf(B list 2)
ADD: loadState(B list 10)
ADD: saveState(B list 10)
ADD: stackBuf(B list 10, F list 10)
ADD: getRGB(R0,R1,R2,R3) list 10
ADD: setColors(B list 2, C & FG & BG list 10)
ADD: getColors(B list 2, C & FG & BG list 10)
ADD: xor(A,B,C) list 10
ADD: setFold(T,F,X,SKA) liset 10
ADD: getFold(T,F,X,B,SKA) B=list 2, rest are list 10
ADD: fold(T list 0, F list 2, R list 12)



3.2  Functions and their Arguments, Alphabetically

Function        Arg Lists   Function      Arg Lists   Function       Arg Lists
--------        ---------   --------      ---------   --------       ---------
abort                       getStackSize  10 10 10    reformat
abortPrint                  getTabs       2 10        refreshDisplay
abortSave                                             restartPrint
add             10 10 10    gotoPage      2 10        return
alertUser       10          gotoSplit     2           returnFalse
and             10 10 10    grep          2 12 10     returnTrue
askYesNo        10          gtLoc         2 6 6       rexxIn        0 6 10 10 10
attachBuf       2 10        gtNum         10 10       rexxOut       0 12 10 10 10
beepDisplay                 hexDecimal    2           rollStack     10 10
case            10          hScroll       10          runKey        10
changeDir       10          hyper         2 0 10 10   runLearn
checkedMenu    1 1 10 10 14 hyperClose                saveConfig    10
checkedSubMenu 1 1 10 10 14 hyperOpen     0 0 10      saveFile      2
clearChar       2           hyperUp                   saveKeys      10 10 10
clearColData    2 12 10     incLoc        2 7         saveLearn     10
clearRgn        2 12        incNum        10          search        2 8 8 10
colToLoc        2 7 10      indextoLoc    2 7 10      seeRuler
compile         2           inputKey      10          setEol        10
compileDefaults 2           inputNum      10          setFileName   2 10
copyChar        2 10        inputString   2           setGrep       10
copyColData     2 6 2 12 10 inputWaiting              setLocal      2 3 10
copyKey         10 10       insertChar    2 9         setMaxFiles   10
decLoc          2 7         insertFile    2 6 10      setRGB        10 10 10 10
decNum          10          insertRgn     2 6 0 12    setRuler
default                     inUse         10          setSearch     10
delay           10          is            2 11        spacesToTabs
detachBuf       2           isEmpty       2           speak         10
div             10 10 10    killKey       10          spell         0 2 0
downFlag        2 14                                  spellerUp
editBuf         2           lineToLoc     2 7 10      splitWindow   2 10
eqLoc           2 6 6       loadConfig    10          startSpell    10 10 10
eqNum           10 10       loadFile      10          stopspell
equateLoc       2 7 6       loadKeys      10 10 10    stringComp    10 10 10 10
equateNum       10 10       loadLearn     10          sub           10 10 10
execute         0 10        locToCol      2 10 6      subMenu       1 1 10 10
fileRequest     2 0 10      locToIndex    2 10 6      swapBuf       2 2
fileSize        2 10        locToLine     2 10 6      swapChar      2 9
flipFlag        2 14        menu          1 1 10 10   swapKey       10 10
freeBuf         2           mod           10 10 10    swapLoc       2 7 7
gadgetName      10 0        mouseDown                 switch        10
geLoc           2 6 6       mouseXY       10 10       tabsToSpaces
geNum           10 10       moveCursor    2 4         teachOne      10
getAddress      10 10       mul           10 10 10    text         10 10 10 10 10
getBufAddr      10 2        nameBuffer    10 1        thisKey
getChar         10          newFile                   toggle        14
getFileName     2 2         nothing                   toLower       2
getFlag         2 14        onScreen      6           toNumber      10 2
getGrep         2           or            10 10 10    toUpper       2
getKey          10          peek          10 10 10    toWord        2 10
getKeyVal       10 10       poke          10 10 10    trackMouse
getLocal        2 10 3      pop           10 10       typeChar      9
getMaxFiles     10          print         0 12        updateDisplay
getPageRowCol   10 10 10    printerCode   2 10 10 10  upFlag        2 14
getSearch       2           push          10 10       vScroll       5
getSerialNum    10          putMsg        10
getSplitLines   10 10       quit          10


3.3  Functions and their Arguments, by Category

   -ABORT/QUIT/RETURN-    toNumber        10 2         getFlag         2 14
abort                     toUpper         2            toggle          14
abortPrint                toWord          2 10         upFlag          2 14
abortSave                       -CURSOR/MOUSE-                  -KEY-
quit            10        mouseDown                    copyKey         10 10
return                    mouseXY         10 10        getKey          10
returnFalse               moveCursor      2 4          getKeyVal       10 10
returnTrue                trackMouse                   inputKey        10
        -AMIGADOS-                                     killKey         10
changeDir       10                                     loadKeys        10 10 10
execute         0 10        -DISPLAY/PAGE/ROW/COL-     runKey          10
fileRequest     2 0 10    beepDisplay                  saveKeys        10 10 10
     -BUFFER ADDRESS-     getPageRowCol   10 10 10     swapKey         10 10
attachBuf       2 10                                            -INPUT-
detachBuf       2         gotoPage        2 10         alertUser       10
getBufAddr      10 2      hScroll         10           askYesNo        10
  -BUFFER/NUMBER STACK-                                getChar         10
getStackSize    10 10 10  refreshDisplay               getKey          10
pop             10 10     setRGB          10 10 10 10  getKeyVal       10 10
push            10 10     text         10 10 10 10 10  inputKey        10
rollStack       10 10     updateDisplay                inputNum        10
       -CHARACTER-        vScroll         5            inputString     2
clearChar       2            -FILE/BUFFER/LOCAL-       inputWaiting
copyChar        2 10      abortSave                             -LEARN-
getChar         10        editBuf         2            loadLearn       10
insertChar      2 9       fileRequest     2 10         runLearn
swapChar        2 9       fileSize        2 10         saveLearn       10
typeChar        9         freeBuf         2                    -LOCATION-
toLower         2         getFileName     2 2          decLoc          2 7
toUpper         2         getLocal        2 10 3       eqLoc           2 6 6
      -COMPILE/DATA-      getMaxFiles     10           equateLoc       2 7 6
compile         2         insertFile      2 6 10       geLoc           2 6 6
compileDefaults 2         loadFile        10           gtLoc           2 6 6
loadConfig      10        nameBuffer      10 1         incLoc          2 7
loadKeys        10 10 10  newFile                      moveCursor      2 4
saveConfig      10        saveFile        2            swapLoc         2 7 7
saveKeys        10 10 10  setFileName     2 10                -LOC TO NUM-
     -CONVERT/FORMAT-     setLocal        2 3 10       colToLoc        2 7 10
hexDecimal      2         setMaxFiles     10           indexToLoc      2 7 10
reformat                  swapBuf         2 2          lineToLoc       2 7 10
spacesToTabs                    -FLAG/TOGGLE-          locToCol        2 10 6
tabsToSpaces              downFlag        2 14         locToIndex      2 10 6
toLower         2         flipFlag        2 14         locToLine       2 10 6


          -MENU-                    -SAVE/LOAD-
checkedMenu     1 1 10 10 14 loadConfig      10
checkedSubMenu  1 1 10 10 14 loadFile        10
menu            1 1 10 10    loadKeys        10 10 10
subMenu         1 1 10 10    loadLearn       10
     -MISCELLANEOUS-         saveConfig      10
delay           10           saveFile        2
getSerialNum    10           saveKeys        10 10 10
hyper           2 0 10 10    saveLearn       10
hyperClose                            -SEARCH-
hyperOpen       0 0 10       getGrep         2
hyperUp                      getSearch       2
nothing                      grep            2 12 10
setEol          10           search          2 8 8 10
speak           10           setGrep         10
teachOne        10           setSearch       10
       -MSG/ALERT-                   -SPELLING-
alertUser       10           spell           0 2 0
askYesNo        10           spellerUp
putMsg          10           startSpell      10 10 10
          -NAME-             stopSpell
gadgetName      10 0               -SPLIT WINDOW-
getFileName     2 2          getSplitLines   10 10
nameBuffer      10 1         gotoSplit       2
setFileName     2 10         splitWindow     2 10
   -NUMBERS/ARITHMETIC-      toggle          14
add             10 10 10               -TABS-
and             10 10 10     getTabs         2 10
decNum          10           seeRuler
div             10 10 10     setRuler
eqNum           10 10        spacesToTabs
equateNum       10 10        tabsToSpaces
geNum           10 10                  -TEST-
gtNum           10 10        getFlag         2 14
incNum          10           inputWaiting
inputNum        10           inUse           10
mod             10 10 10     is              2 11
mul             10 10 10     isEmpty         2
or              10 10 10     onScreen        6
sub             10 10 10     stringComp      10 10 10 10
         -PRINT-             thisKey
abortPrint
print           0 12
printerCode     2 10 10 10
restartPrint
    -REGION/COLUMNAR-
clearColData    2 12 10
clearRgn        2 12
copyColData     2 6 2 12 10
insertRgn       2 6 0 12
         -REXX-
rexxIn          0 6 10 10 10
rexxOut         0 12 10 10 10


3.4  Command Language Functions

CL functions use parentheses only if the function uses arguments.  Most
functions return a True or a False based on their success.  Some, such as
refreshDisplay, always return True.  Most will return False, if they fail for
some reason, such as when a buffer does not exist, when told to modify a
read-only buffer, when told to move the cursor beyond end-of-file, and so on.
Tests such as getFlag() and gtNum() return True or False based on the outcome
of the test they perform.  incNum() and decNum() return False, when their
integer argument passes through zero, but they increment or decrement the
argument anyway.  And() and or() return False, when their numerical result is
zero.

Commands return the True or False result of the last function called in them.
Four functions - Return, ReturnTrue, ReturnFalse, and Abort - cause a command
to return immediately.  Except in the case of Abort, they return gracefully
to the command that called them, if called by some other command; otherwise
they return control to the work-loop which processes inputs.

The Return function causes the command to return immediately with the True or
False of the last function that was called.  ReturnTrue and ReturnFalse cause
the command to return with a forced True or False.  Abort causes Uedit to
abort all activity and throw away any unprocessed inputs.

Certain things automatically cause an abort.  When an abort occurs, such as
when you press Amiga-ESC or when a memory shortage occurs, the screen flashes
and Uedit aborts whatever it is doing.  If a memory shortage occurs, a
"Memory..." message appears and remains visible until Uedit has done memory
housekeeping.

Loading in a new data file with loadConfig() causes an abort after the data
is loaded in.  This is necessary because the command running is replaced by
whatever its counterpart may be in the new data file.  Killing a command that
is currently running also causes an abort.  A key that is running can be
killed by itself using killKey(), by some command it is running with
runKey(), by a call to loadKeys() or loadConfig(), or by being recompiled.
In each case, Uedit's engine sees that it is not looking at the key it
thought it was, so it aborts.

CL functions with both input and output arguments work from right to left;
input arguments are on the right and output arguments are on the left inside
function parentheses.

Valid function arguments often include variables that don't make sense.  For
example, swapKeys(topMargin,bottomMargin) is valid.  Most arguments may be
used for general purposes and these margin variables could be used for
storing macro numbers temporarily.

In the function descriptions, a file buffer is a buffer in the range 0 to
MaxFiles-1.  For example, if MaxFiles is 20, buf0 to buf19 are file buffers.
When a new file is loaded in, it is loaded into the lowest file-buffer slot
available.  The "home" buffer is the lowest numbered file buffer that exists;
it is buf0, when buf0 exists.  A work buffer, is a buffer in the upper
number-range; if MaxFiles is 20, buf20 to buf99 are work buffers.  Buffers do
not exist until a CL function inserts or loads something into them.  Buffers
are not deleted unless the freeBuf() function is called for them.

Functions that use LIST 10 (integer, buffer, and literal arguments) may use
the arguments for either text or integer purposes, depending on the type of
function.  A text function, such as putMsg() or alertUser() converts integer
arguments to text.  For

example, putMsg(n54) would convert the value in n54 to text and display it as
a message.

Number-functions such as add() and equateNum(), when given a buffer input
argument, use the buffer's number, not its contents.  For example,
equateNum(n54,curFile) stores the buffer number of curFile in n54.

If a literal argument is used as an integer, the characters in the string are
byte-shifted into a 4-byte integer; if the string is longer than 4 bytes, the
last 4 bytes are used.  For example, add(n54,n54,"abcdef") adds the 4-byte
integer equivalent of "cdef" to n54.

If a buffer or literal is used as an output argument in a number-function
such as add(), the buffer or literal is unaffected.  For example, in
equateNum(curFile,n54) the result ends up in an internal scratch variable
that is thrown away, so nothing happens that you can detect.  If a number is
used as an output argument, as in add(3333,a,b), the result is also thrown
away.

In the function descriptions, when "(text)" or "(buffer)" is beside LIST 10,
it means that the argument is treated as text and that numbers are converted
into ASCII.  If "(integer)" is beside LIST 10, it means that the argument is
treated as an integer.

All functions return True, except under the conditions noted in the function
descriptions.  Functions may set bits in the internal displayFlag variable to
tell Uedit's display routine how to refresh during the next pause.  The bits
in displayFlag instruct the display routine to refresh one of the split
windows, refresh the cursor line, refresh from the cursor to the end of the
active window, or fully refresh the active window.  The refreshing is done
when there is a pause, if any bits in displayFlag are set.  Also as a backup
measure, Uedit refreshes curFile's window when there is 4 second pause in
activity.

If no display action is noted in a function's description, the function does
not update the display in realtime and does not set bits in displayFlag.  If
a display action is noted, usually it means that the function sets bits in
displayFlag.  Certain functions, however, cause a realtime refresh to occur;
among them are editBuf(), refreshDisplay, seeRuler, and setRuler.  Also
updateDisplay causes a realtime refresh, according to the bits in displayFlag
at the time, if any bits are set.


                                CL Functions

abort

Immediately stops all activity in Uedit.  It cleans out the input queue and
any pending processing.  Abort does not stop spooled prints and saves.  To
stop those, use AbortPrint and AbortSave.

Example:  if (not saveFile(curFile)) abort

abortPrint

Discards the current spooled print being processed in background.  If there
is no queued print, it returns False.  It does not stop foreground ("busy")
printing.  To stop foreground prints, use Amiga-ESC.  To abort all background
prints, keep calling abortPrint until it returns False.

Example:  while (abortPrint) nothing  .. cancel all prints.

abortSave

Aborts the current file-save in process.  It returns False, if there are no
file-saves queued up.  AbortSave closes and deletes the file on disk that it
was saving.  Warning:  AbortSave deletes the partially saved copy of the file
on disk.

Example:  while (abortSave) nothing   .. cancel all file-saves.

add(A,B,C)
A,B,C:  list 10 (integer)

A = B + C.  (See sub(), mul(), div(), mod(), or(), and and().)

alertUser(M)
M:  list 10 (text)

Displays an Okay/Cancel requester box containing the message M.  If the
message is empty, alertUser() does not display a requester box and returns
False.  alertUser() returns True if Okay is selected, and it executes an
Abort if Cancel is selected.  Message length may be up to 75 characters.  If
speakAlerts is True, alerts are also spoken.  (See flipFlag(), getFlag(),
upFlag() and downFlag().)

Example:  alertUser("File not found")

and(A,B,C)
A,B,C:  list 10  (integer)

A = B & C.  and() does a bit-wise AND, returning False only if the result is 0.

Example:  and(n54,96,0X20)   ..n54 = 96 & 32 = 32, so it returns True.

askYesNo(M)
M:  list 10 (text)

Displays the message M in a Yes/No/Cancel requester box.  M may be up to 75
characters long.  askYesNo() returns True, if Yes is selected.  It returns
False, if No is selected.  It executes an Abort, if Cancel is selected.  It
returns False without displaying the requester, if the message is empty.  If
speakAlerts is True, the message is also spoken.  (See flipFlag(), getFlag(),
upFlag() and downFlag().)

Example:  if (askYesNo("Stop prints?")) while (abortPrint) nothing

attachBuf(B,N)
B:  list 2 (buffer)
N:  list 10 (integer)

N is the memory address of a Uedit-type buffer to be attached to buffer B.
If buffer B already exists, attachBuf() returns False.  attachBuf() performs
a simple test to see whether the "buffer" at address N is really a Uedit-type
buffer; this test is not foolproof, but the odds favor it.  attachBuf() makes
no check to see whether buffer address N is already one of Uedit's buffers.
Warning:  If you attach a buffer whose pointers and flags have been managed
improperly or a buffer that already exists in Uedit, this will probably cause
a crash.  (See detachBuf() and getBufAddr().)

Example:  attachBuf(buf19,n0)   .. n0 has address of a Ue buffer.

beepDisplay
Flashes the screen.

Example:  if (not compileDefaults) beepDisplay

changeDir(S)
S:  list 10 (text)

Changes Uedit's current directory to the directory in S.  If unable to change
to the directory in S, it returns False.  changeDir() may not work in
Workbench.  (Also see execute().)

Example:  if (not changeDir("dh0:myWorkDir")) returnFalse

checkedMenu(D,A,N,C,F)
D,A:  literal
N,C:  list 10 (integer)
F:  list 14 (flag)

Creates a menu selection that displays a checkmark based on the realtime
value of the flag F.  The description D and alternate text A must be a
literal in quotes up to 17 characters in length.  It is a good idea to
use two spaces at the beginning of the text in D, leaving room for the
checkmark; otherwise the checkmark will lie on top of the first two letters
in D.  N is the menu number, 1 to 7.  C is the command-key, which must be a
valid key argument or a macro number, 1 to 1148.  It returns False, if N or C
is out of range, if no memory is available, if there are already 20 menu
items for menu N, or if the command for C does not exist.  checkedMenu() may
only be used in the Startup command.  (See menu() and subMenu().  See Config!
for examples.)

checkedSubMenu(D,A,N,C,F)
D,A:  literal
N,C:  list 10 (integer)
F:  list 14 (flag)

Creates a submenu selection that displays a checkmark based on the realtime
value of the flag F.  The description D and alternate Text A must be a
literal in quotes up to 17 characters in length.  It is a good idea to
use two spaces at the beginning of the text in D, leaving room for the
checkmark; otherwise the checkmark will lie on top of the first two letters
in D.  N is the menu number, 1 to 7, that owns the submenu.  C is the
command-key, which must be a valid key argument or a macro number, 1 to 1148.
It returns False, if the menu for this subitem has not been defined yet, if N
or C is out of range, if no memory is available, if there are already 12
submenu items for the current menu item, or if the command for C does not
exist.  checkedSubMenu() may only be used in the Startup command.  (See
menu() and subMenu().  See Config! for examples.)

clearBuf(B)
B: list 2

Clears buffer B without freeing it.  clearBuf() should be used when memory
fragmentation is not a concern and faster performance is desired, because it
is more efficient than clearRgn(B,all) or freeBuf() followed by reallocating
the buffer.  (See clearRgn() and freebuf().)

clearChar(B)
B:  list 2 (buffer)

Deletes the character under the cursor in buffer B.  It returns False, if
buffer B is read-only or cursor is at eof.  (See copyChar(), insertChar(),
swapChar(), and typeChar().)

Display Action:  Refreshes B's window, if any and not curFile.  If B=curFile,
refreshes cursor; if cursor offscreen, centers cursor.

Cursor Action:  Cursor rests on the next character, after clearing the old
one.

Example:  while (moveCursor(curFile,eWord)) clearChar(curFile)

clearColData(B,R,F)
B:  list 2 (buffer)
R:  list 12 (region)
F:  list 10 (integer)

Clears columnar region R in buffer B.  If flag F is 0, it clears the region.
If F is non-zero, it space-fills the region.  It returns False, if no region
exists or B is read-only.

Cursor Action:  If R cleared and cursor in R, cursor advances to the first
character to the right of the cleared region.

Display Action:  Refreshes B's window, if any.

Example:  if (getFlag(curFile,columnar)) clearColData(curFile,hilite,0)

clearRgn(B,R)
B:  list 2 (buffer)
R:  list 12 (region)

Clears region R in buffer B.  It returns False, if B is read-only or no
region exists.

Cursor Action:  If cursor in R, it advances to first character after the
cleared region.

Display Action:  Refreshes B's window, if any and not curFile.  If B=curFile,
refreshes cursor; if cursor offscreen, centers cursor.

Example:  if (not getFlag(curFile,columnar)) clearRgn(curFile,hilite)

colToLoc(B,L,C)
B:  list 2 (buffer)
L:  list 7 (location)
C:  list 10 (integer)

Computes location L based on column C.  The line used is the line containing
location L, which is the cursor line if L=atCursor.  Location L is moved to
column C.  It returns False, if C<=0 or if C is greater than the line's
length.

Cursor Action:  Moves cursor to column C, if L=atCursor.

Display Action:  Refreshes B's window, if any and not curFile.  If B=curFile
and L=atCursor, refreshes cursor; if cursor offscreen, centers cursor.

Example:  colToLoc(curFile,atCursor,20) ..move cursor to column 20.

compareBuf(B1,B2)
B1,B2: list 2

Compares the contents of buffer B1 with the contents of buffer B2 starting
from the cursor forward in each buffer.  It stops and leaves the cursor at
the first spot where the buffer contents disagree.  It sets start-of-page
(sPage) at the start of the cursor line in each buffer.  compareBuf() returns
False when disagreement is found.  It returns True when end-of-file is
reached in both buffers simultaneously.

Cursor action:  As noted above.

Display action:  As noted above.

compile(B)
B: list 2

Compiles the command at or following the cursor in buffer B.  If successful,
the cursor stops at the ">" ending bracket of the command and it returns
True; the message line displays "Size", if it is a new command, or "Replace",
if it is replacing an existing command, followed by the pcode size of the
compiled command.  If an error is found in the command, the cursor stops just
past the offending part of the command, and the return is False.  It returns
False also if there is not enough memory.  (See Compile Errors, 2.27.)

Cursor Action:  Advances cursor as noted above.

Display Action:  Refreshes cursor; centers cursor, if offscreen.

Example:  if (not compile) beepDisplay ..warn, if unsuccessful.

compileDefaults(B)
B: list 2

Compiles the config default values at or following the cursor in buffer B.
If successful, it returns True, closes and reopens the window using the new
defaults, rebuilds the menus, and the cursor is after the last default.  If
it finds an error, the cursor stops just past the bad default or at eof, if
it cannot find enough defaults, and it returns False.  Note that it replaces
the acceptable defaults it finds, so even if it finds an error, some of the
defaults may have been changed.

Cursor Action:  Cursor advances as noted above.

Display Action:  Refreshes cursor, if it finds an error; centers it, if
offscreen.

Example:  moveCursor(curFile,sFile) ..move cursor to front of defaults.
      if (not compileDefaults) beepDisplay ..compile defaults, flash on error.

copyChar(B,N)
B:  list 2 (buffer)
N:  list 10 (integer)

Copies cursor character in buffer B into integer variable N.  It returns
False, if B does not exist or cursor is at eof.  (See clearChar(),
insertChar(), swapChar(), and typeChar().)

Example:  copyChar(curFile,n54) if (eqNum(n54,"?")) return

copyColData(B1,L,B2,R,F)
B1,B2:  list 2 (buffer)
L:  list 6 (location)
R:  list 12 (region)
F:  list 10 (integer)

Copies columnar text region R from buffer B2 into buffer B1 at location L.
If flag F is 0, it overlays (overwrites) any existing text at L.  If F is
non-zero, it inserts the text at L, pushing existing text to the right.  If R
is a hilite region, it hilites the region inserted/overlaid in B1.  If R is
not a hilite region, it inverse-displays the inserted/overlaid text.  It
returns False, if B2 does not exist, if columnar region R does not exist, if
B1 is read-only, or if there is not enough memory.

Display Action:  Refreshes B's window, if any.

Example:
    if (getFlag(buf99,columnar)) copyColData(buf99,atCursor,buf37,hilite,1)

copyKey(K1,K2)
K1,K2:  list 10 (integer)

Copies the command of key K2 into key K1.  K1 and K2 must be valid key
arguments or macro numbers in the range 1 to 1148.  It returns False, if K2
has no command, if there is not enough memory, if K1 or K2 is not a valid key
or macro number, or if K1=K2.  It deletes any existing K1 key.  If K1 is the
Startup key, the menus are removed; the new Startup command is run in the
next pause, rebuilding the menus if it has menu() functions in it.

Example:  copyKey(normal-esc,virtual-esc) ..copy virtual esc to normal.

decLoc(B,L)
B:  list 2 (buffer)
L:  list 7 (location)

Decrements location L in buffer B.  It returns False, if B does not exist or
if L is already at start-of-file.

Cursor Action:  Decrements cursor, if L=atCursor.

Example:  while (decLoc(curFile,atCursor)) swapChar(curFile," ")

decNum(N)
N:  list 10 (integer)

Decrements integer variable N.  It returns False, if N is 0 going in, but it
decrements N regardless.  (Returning False when N=0 going in makes decNum()
useful in while-loops.  See example.  See incNum().)

Example:  equateNum(n0,20) while (decNum(n0)) beepDisplay

delay(N)
N:  list 10 (integer)

Delays for N tenths of a second.  If N<=0, it returns False.  During the
delay, if any file-saves or prints are in the queue, it processes them.  The
accuracy of delay() relies upon the clock-tick accuracy of the computer, plus
any inaccuracies due to background printing or file-saving during the delay.

Example:  delay(10)   .. delay 1 second.

detachBuf(B)
B:  list 2 (buffer)

Detaches buffer B from Uedit.  Warning:  You MUST use getBufAddr() to get the
address first!  Otherwise the buffer cannot be reattached!  It returns False,
if B does not exist.  If B is curFile, the "home" buffer becomes curFile.  If
no file buffer exists after detaching B, a NoName buffer is opened.  (See
attachBuf() and getBufAddr().)

Display Action:  If B=curFile, the new curFile is displayed.

Example:  getBufAddr(n0,curFile) detachBuf(curFile) ..got address FIRST!

div(A,B,C)
A,B,C:  list 10 (integer)

A = B/C.  It returns False, if C=0.

Example:  if (not div(n99,n1,n2)) putMsg("Can't divide by zero!")

downFlag(B,F)
B:  list 2 (buffer)
F:  list 14 (flag)

Sets to False the value of flag F for buffer B.  (See the notes for
flipFlag().)  If flag F is a local (buffer) flag and buffer B does not exist,
it returns False.  If F is a global flag, B is ignored.  If the flag's value
is non-zero, a True is returned.  If the flag is zero, a False is returned.

Example:  if (downFlag(curFile,columnar)) alertUser("Turned off Col display
mode")

draw(X,Y,C,M,F)
X,Y,C,M,F:  list 10 (numbers)

draws a line from the current position to X-Y using color C, drawing mode M,
and flag F.  C = 0-15 specifies a color; C = -1 means use the current (last)
color.  M values are: 0 = JAM1, 1 = JAM2, 2 = XOR, 4 = INVERSE.  F = 0 means
do only a move(X,Y) to set the current drawing position to X-Y; if F = 0,
other arguments are ignored except the color C is stored.  F = 1 means draw a
line to X-Y using color C, mode M, and flag F.  Example:  You can draw (using
XOR) a grating on top of the text in the window & erase it by redrawing it
again with XOR.  You can draw boxes and other figures with the mouse.  draw()
always returns True.  Note:  An internal flag prevents the right (menu) mouse
button from clearing the message line after text() or draw() has been used.
The internal flag is cleared after some other type of displaying action is
called for.

Example 1:  Press shift-mousebutton and move the mouse.
<shft-buttonDown:
    mouseXY(n0,n1)
    gosub label(0)
    if (not mousedown) return
    equateNum(n54,0)
    while (not inputwaiting) {
        trackmouse
        mouseXY(n2,n3)
        if (!eqNum(n2,n0) & !eqNum(n3,n1)) {
            runKey(virtual-esc)
            equateNum(n0,n2)
            equateNum(n1,n3)
            gosub label(0)
        }
    }
    return
label(0)    .. subroutine to draw the box
    draw(n0,n1,   0,2,0)
    add(n54,n0,20)
    draw(n54,n1, -1,2,1)
    add(n53,n1,20)
    draw(n54,n53,-1,2,1)
    draw(n0,n53, -1,2,1)
    draw(n0,n1,  -1,2,1)
>

Example 2:  XOR a grating onto the window.  Erase it on the second execution.
<shft-esc:
    equateNum(n0,0)
    putmsg(n0)
    while (add(n0,n0,8) & genum(sWidth,n0)) {
        draw(n0,16,0,2,0)
        draw(n0,sHeight,0,2,1)
    } >

editBuf(B)
B:  list 2 (buffer)

Makes buffer B become curFile.  It displays B starting at the current sPage
location.  If sPage is at eof, it is moved to start-of-file.  Note that
editBuf() "falls through" to the next function in the command it is in.  If
you want the command to "hang up" until it has collected an input, use
inputString(B) to collect the input.

Display Action:  Displays B as the new curFile.

Example:  equateLoc(buf80,sPage,sFile) editBuf(buf80)

eqLoc(B,L1,L2)
B:  list 2 (buffer)
L1,L2:  list 6 (location)

Returns True, if locations L1 = L2 in buffer B.  If the locations are not
equal or if B does not exist, it returns False.

Example:  if (eqLoc(curFile,atCursor,sFile)) returnTrue

eqNum(N1,N2)
N1,N2:  list 10 (integer)

Returns True, if N1=N2.  Returns False, if they are not equal.

Example:  if (eqNum(0,curFile)) toggle(curFile) ..if buf0, toggle to next.

equateLoc(B,L1,L2)
B:  list 2 (buffer)
L1:  list 7 (location)
L2:  list 6 (location)

Sets location L1 = L2 in buffer B.  It returns False, if B does not exist or
L2 does not exist.

Cursor Action:  If L1=atCursor, the cursor moves to L2.

Example:  equateLoc(curFile,sHilite,eHilite) ..unmark hilite region.

equateNum(N1,N2)
N1,N2:  list 10 (integer)

N1 = N2.

Example:  equateNum(n0,curFile) ..n0 now has curFile's buffer number.

execute(B1,B2)
B1:  list 0  (buffer)
B2:  list 10 (text)

Sends text B2 to AmigaDOS using an Amiga Execute() function call.  DOS
executes the program in B2.  If no text result is desired from DOS, use a
blank literal "" as argument B1.  If a text result is desired, use a buffer
in B1, and the result is inserted at the cursor in B1.  It returns False, if
B2 is empty or does not exist, if B1 is a read-only buffer, or if B1 is a
buffer (thus results are asked for) and no temporary file can be opened for
the result from AmigaDOS.  The temporary file name is specified in the config
defaults.  Execute() returns the return code it gets from the Amiga, which is
normally True even when it shouldn't be.  So True returns may not be
meaningful, but False returns are probably meaningful.

Examples:  execute("","run myprog") ..no result wanted.
execute(buf53,buf54) ..run DOS cmd in buf54; get result in buf53.

fileRequest(B,T,F)
B:  list 2 (buffer)
T:  list 0 (text)
F:  list 10 (number)

Displays a file requester.  B cannot be curFile.  If B contains a directory,
it displays the directory in B.  If B is empty, it displays Uedit's current
directory.  It returns True only if a filename is selected.  If no directory
or file is selected, a "*" is put into B; otherwise, B is cleared and the
directory is put in line 1 in B and the file name is in line 2.  T is hailing
text for the file requester.  F is a flag, which some file requesters can use.
(fileRequest() uses the calling and argument protocol required by the Arp
file requester.  It is common for other file requesters to be compatible with
this protocol.)

Example:  fileRequest(buf54,"Select Directory and/or File",0)

fileSize(B,N)
B:  list 2 (buffer)
N:  list 10 (integer)

Puts buffer B's current size in integer variable N.  Returns False, if buffer
B does not exist.  If buffer B is fragmented, it is packed before the size is
computed.  This is a trade-off; if the size were calculated on a fragmented
buffer, fileSize() would run slower anyway.  Might as well use the time to
good purpose, so buffer B is packed if it needs it.  Use fileSize() when you
want to force a buffer to be packed.  For example, if a command does a large
number of inserts, it may be desirable to force the receiving buffer to be
packed now and then, to avoid an abort due to a memory shortage.

Example:  fileSize(curFile,n0) putMsg(n0) ..display size of curFile.

flipFlag(B,F)
B:  list 2 (buffer)
F:  list 14 (flag)

Flips the On/Off status of flag F in buffer B.  When F is a local flag, such
as WordWrap, if B does not exist, it returns False.  If F is a local flag and
a corresponding global flag exists, the global flag gets the local flag's new
value, On or Off.  When flag F is a global only flag, such as RowCol or Cram,
buffer B is ignored.  CRAM:  The display line spacings are recomputed and the
window is refreshed; if cram mode is turned on, text is crammed vertically by
removing 1 pixel from between lines of text.  LEARNMODE:  If not in learn

mode, it turns On learn mode.  If already in learn mode, learn is cancelled
and wiped.  The title bar is refreshed.  COLUMNAR:  Columnar display mode is
switched on/off and curFile's window is refreshed.  ROWCOL:  Page-row-column
display is turned on/off and the message line is refreshed (cleared).
MARKGADGETS:  MarkGadgets is turned on/off and the message line is refreshed.
TEACHKEYS:  TeachKeys mode is turned on and the title bar is refreshed.
LACE:  The lace variable is rotated to the next value in the range from 0 to
3.  The screen is closed and reopened.  If lace=0, a 4-color non-interlace
screen (2 bitplanes) is used.  If lace=1, a 2-color non-interlace screen (1
bitplane) is used.  If lace=2, an interlace 4-color screen (2 bitplanes) is
used.  If lace=3, an interlace 2-color screen (1 bitplane) is used.  If flag
is OTHER (such as BUSIES):  The flag is flipped but no other action is taken.
(See getFlag(), upFlag(), downFlag(), and setLocal().  See toggle()
concerning scrollType, hideDisplay and trapMenus.)

Display Action:  See discussion above.

Example:  if (getFlag(buf0,changed)) flipFlag(buf0,changed)   .. turn off flag.

fold(T,F,R)
T: list 0 (buffer or literal)
F: list 2 (buffer)
R: list 12 (region)

Folds region R of buffer F into buffer T using the (up to 16) line-folding
tests defined with setFold().  If T already exists, it is erased before being
used.  If T is a literal (such as ""), a new file buffer is created and it
becomes curFile.  F's tab table is used in interpreting TABs in buffer F, and
T inherits the same tab table number.  The lines of text in F's region R
which pass the tests set up with setFold() are skipped or kept (copied into
T) according to the test's SKA value.  If a line's length exceeds 130
columns, only the first 130 columns are copied.  fold() returns FALSE, if no
folding tests have been defined with setFold() or if F or region R doesn't
exist.  (See Folds, 1.49.  Also see setFold() and getFold().)

Example:  Fold current file
<rAmiga-\:
    getFileName(buf54,curFile)
    insertRgn(buf54,eFile,".fold",all)
    if (fold("",curFile,all)) {
        setFileName(curFile,buf54)
        downFlag(curFile,changed)
    }
>

freeBuf(B)
B:  list 2 (buffer)

Frees buffer B.  It returns False, if B does not exist.  If B is curFile, the
"home" buffer becomes curFile.  If no other file buffer exists, it opens a
NoName buffer that becomes curFile; or if memory is too low to load in
NoName, an Empty buffer is opened.

Display Action:  Refreshes B's window, if any and not curFile.  If B=curFile,
displays new curFile.

fullRefresh

Refreshes the entire screen, including all split windows, except it does not
clear the message line.

gadgetName(N,B)
N:  list 10 (integer)
B:  list 0 (text)

The gadget name in buffer or literal B is assigned to gadget N, where N is 1
to 4.  It returns False, if N is out of range or B does not exist.  If B is a
buffer or blank literal "", the gadget name is cleared.  Otherwise, the first
19 characters become the gadget name.  The message line is refreshed
(cleared).

Example:  gadgetName(1,"Next File")

geLoc(B,L1,L2)
B:  list 2 (buffer)
L1,L2:  list 6 (location)

Returns True, if location L1 >= L2 in buffer B.  It returns False, if B does
not exist or if L1 < L2.

Example:  if (geLoc(curFile,sHilite,eHilite)) putMsg("No hilite exists")

geNum(N1,N2)
N1,N2:  list 10 (integer)

Returns True, if N1 >= N2.  It returns False, if N1 < N2.

Example:  if (geNum(n0,1)) putMsg("Number is positive")

getBufAddr(N,B)
N:  list 10 (integer)
B:  list 2 (buffer)

Puts the memory address of buffer B into variable N.  It returns False, if B
does not exist.  (See attachBuf() and detachBuf().)

Example:  getBufAddr(n0,buf54)

getChar(N)
N:  list 10 (integer)

Gets the next character typed and puts it into variable N.  If function keys
are input, they are ignored and getChar() waits until a character is typed.
The character may be a control character.  While waiting, if prints or file-
saves are queued up, they continue to be processed.

Example:  getChar(n99) if (geNum(n99," ")) putMsg("Printable char")

getColors(B,C,Fg,Bg)
B: list 2
C,Fg,Bg: list 10 (numbers)

Gets the global and/or local colors.  C must be in the range 0-15 or else
equal -1.  If C is in the range 0-7, this corresponds to local colors; and if
B exists, the colors C for buffer B are fetched in Fg and Bg; but if B does
not exist or B is a literal "", the colors C that are fetched in Fg and Bg
are taken from the internal local color variable that newly created buffers
inherit.  If C is in the range 8-15, this corresponds to global (screen)
colors and B is ignored; the colors values for C are fetched in Fg and Bg.
In all cases, when C is in the range 0-15, the color values returned in Fg
and Bg will be in the range 0-3, corresponding to an RGB color register
number.

C=-1:  Here Fg and Bg are long word (32-bit) bitmasks containing all of the
local (buffer) and global (screen) colors, respectively.  (Again, if buffer B
doesn't exist or B is a literal, the local colors in Fg are a copy of the
internal color variable that is applied to newly created buffers.):

    The Fg bit masks, which apply to local colors, are as follows:  Each 4
    bits is 2 pairs of 2 bits, each with values 0-3 corresponding to the
    foreground and background colors, respectively.  The sets of 4 bits
    correspond (from left to right) to normal, cursor, hilite, cursor +
    hilite, invert, invert + cursor, hilite + invert, and cursor + hilite +
    invert.

    The Bg bitmasks, which apply to the global (screen) colors, are as
    follows:  Again, each 4 bits is 2 pairs of 2 bits, each with values 0-3
    corresponding to the foreground and background colors, respectively.  The
    sets of 4 bits correspond (from left to right) to title bar, msg line,
    menus, tab ruler, requester, formfeed, spare1, and spare2.

(See setColors(), setLocal(), and getLocal().)

getFileName(B1,B2)
B1,B2:  list 2 (buffer)

Gets the file name of buffer B2 and puts it into buffer B1.  It returns
False, if B2 does not exist or if B1 is curFile.  If B1 exists, it is freed
and reallocated before the file name is stored in it.

Example:  getFileName(buf54,curFile) ..get curFile's file name in buf54.

getFlag(B,F)
B:  list 2 (buffer)
F:  list 14 (flag)

Returns the True/False value of flag F for buffer B.  (See the notes for
flipFlag().)  If flag F is a local (buffer) flag and buffer B does not exist,
it returns False.  If F is a global flag, B is ignored.  If the flag's value
is non-zero, a True is returned.  If the flag is zero, a False is returned.

Example:  if (getFlag(curFile,columnar)) alertUser("Col display mode")

getFont(F,X,Y)
F: list 2
X,Y: list 10 (numbers)

gets the name of the current font and puts it into buffer F, gets the font
character-width and puts it into X, and gets the font-character height and
puts it into Y.  It always returns True.

getFold(T,F,X,B,SKA)
T,F,SKA:  list 10 (integer)
X: list 10 (integer variable or buffer)
B: list 2 (buffer)

Successive calls to getFold(), using testing step T values from 1 to 16,
fetch the testing steps that were set up with setFold() for the use of the
fold() function.  If T=0, the maximum step number in use is returned in T,
and the other arguments are ignored.  If T is between 1 and 16 (or the
maximum step number in use), the values used in step T are put into F, X, B,
and SKA.  The testing option number is put into F.  F is set to 0 and
getFold() returns FALSE, if step T is not in use.  If F<=7, the integer value
associated with test F (an indentation or line length) is put into X, and B
is ignored.  If F>=8, the 1 to 4 character string associated with test F is
put into buffer B; if F>=8, FALSE is returned if B is not a buffer. (See
Folds, 1.49.  Also see setFold() and fold().)

getGrep(B)
B:  list 2 (buffer)

Gets the current grep /search/replace/string and puts it into buffer B.  If B
is curFile, False is returned.  If B exists, it is freed and reallocated.
getGrep() delimits the search and replace strings using the most recently
used delimiter or '/' if none has been used.  (See setGrep() and grep().)

Example:  getGrep(buf54) putMsg(buf54) ..show current grep /search/replace/

getKey(N)
N:  list 10 (integer)

Gets the next input and puts its macro number into variable N.  If any prints
or file-saves are pending, they are processed while waiting for input.

Example:  getKey(n60) if (inUse(n60)) putMsg("This key has a command")

getKeyVal(N1,N2)
N1,N2:  list 10 (integer)

Gets the next input and puts its macro number into N1 and its ASCII character
value into N2.  If any prints or file-saves are pending, they are processed
while waiting for input.  If a non-character is input, such as a function
key, N2 is 0.  N1 receives a value in the range from 1 to 1148.  Control
characters may be input and are reported in N2.

Example:  getKeyVal(n0,n1)
          if (eqNum(n0,normal-a) & eqNum(n1,"A")) putMsg("CAPSLOCK is on")
          (Note:  The capsLock CL variable also indicates the state of the
          capslock key.)

getLocal(B,N,V)
B:  list 2 (buffer)
N:  list 10 (integer)
V:  list 3 (local value)

Gets the local value of V for buffer B and puts it into integer variable N.
It returns False, if B does not exist.  V=COLOR:  The 8 local colors are
stored in 4 bits for each color, which is 2 pairs of 2 bits corresponding to
Fg and Bg, respectively.  (See setLocal() for further information.)  V=LACE:
The global Lace value (display mode, 0 to 3) is reported.  See setLocal() for
more information.  (See toggle() and flipFlag() for a description of the 4
display modes for Lace.)

Examples:
getLocal(buf99,tabTable,tabTable)   .. sets global tabTable to buf99's local value.
getLocal(curFile,n20,lineLength)   .. puts curFile's local lineLength into n20.
getLocal(curFile,n54,lace)   .. get the global lace value

getMaxFiles(N)
N:  list 10 (integer)

Gets the current MaxFiles setting and puts it into integer N.  (See
setMaxFiles().)

Example:  getMaxFiles(n60) putMsg(n60)

getPageRowCol(P,R,C)
P,R,C:  list 10 (integer)

Gets the page-row-column of the cursor location in curFile and reports it in
P, R, and C.  The page referred to is a printed page, not a window page, and
it is based on curFile's local lines-per-page value (pageLines).  Formfeeds
in curFile are considered as page boundaries.

Display Action:  Refreshes cursor line; centers cursor, if cursor offscreen.

Example:  getPageRowCol(n0,n1,n2)

getRGB(R0,R1,R2,R3)
R0,R1,R2,R3: list 10 (numbers)

Gets the current RGB color register contents.  The RGB color values in each
color register argument are in the rightmost 12 bits, 4 bits to each color.
getRGB() always returns True.  Example:  If R0 = 0xf48, it means Red=15
(0xf), Green=4, and Blue=8.

getSearch(B)
B:  list 2 (buffer)

Gets the current search string and stores it in buffer B.  It returns False,
if no search string has been defined or if B is curFile.  If B exists, it is
freed and reallocated before the search string is stored in it.  The search
string reported in B

contains eitherOr and allBut delimiters and wildcards, if they were used in
defining the search string originally.  Note:  If wildCard or multiWild is
changed before calling getSearch(), the search string in B still uses the old
wildcards.  If the eitherOr or allBut delimiter is changed, however, the
search string in B uses the new delimiters.  (See search() and setSearch().)

Example:  getSearch(buf49) putMsg(buf49) ..display current search string.

getSerialNum(N)
N:  list 10 (integer)

Puts the serial number of your copy of Uedit into integer variable N.

Example:  getSerialNum(n54) putMsg(n54) ..display serial number.

getSplitLines(N1,N2)
N1,N2:  list 10 (integer)

Reports the active window split's beginning and ending line numbers in N1 and
N2.  These are window line numbers, unrelated to the text in the window.

Example:  getSplitLines(n0,n1)

getStackSize(B,N,S)
B,N,S:  list 10 (integer)

Reports the current buffer stack size in B, the current number stack size in
N, and the current save-file stack size in S.

Example:  .. get size of buffer stack 22 in n11 & number stack 99 in n12
equateNum(n11,22) equateNum(n12,99) getStackSize(n11,n12,n13)

getTabs(B,N)
B:  list 2 (buffer)
N:  list 10 (integer)

Reports the tab columns of tab ruler N in buffer B in text format.  N must be
0 to 4.  The tab columns are in printable text format, separated by one
space.  Example:  "5 9 13 17".  getTabs() is provided so that you can send
the tab settings to your printer.  getTabs() returns False, if N is out of
range.

Example:  getLocal(curFile,n0,tabTable) ..get curFile's tab ruler number.
getTabs(curFile,n0) ..insert the tab ruler's tabstops at the cursor in
curFile.

gotoPage(B,N)
B:  list 2 (buffer)
N:  list 10 (integer)

Moves the cursor in buffer B to page N.  It returns False, if N <= 0 or if
page N does not exist.  If page N does not exist, cursor is at eof.  Pages
are computed using B's local lines-per-page (pageLines) value; but formfeeds
in buffer B count as page dividers.

Cursor Action:  The cursor is moved to the start of page N.

Display Action:  Refreshes cursor, if B=curFile; centers cursor, if offscreen.

Example:  if (not gotoPage(curFile,n40)) putMsg("Page doesn't exist")

gotoSplit(B)
B:  list 2 (buffer)

Makes the split window with buffer B in it the active window split and B
becomes curFile.  If there are two split windows with B in them, one being
the active window split, the other split is activated.  It returns False, if
there is no split window containing B.

Display Action:  Refreshes the new curFile.

Example:  gotoSplit(buf37) ..activate split with copied columnar in it.

grep(B,R,F)
B:  list 2 (buffer)
R:  list 12 (region)
F:  list 10 (integer)

Does a grep search in buffer B starting at the cursor, using the current
search and replace strings that were set with setGrep().  It returns False if
the search fails.  If a match is found, the cursor is placed at the start of
the matched area and the area is marked using region R's loc variables; for
instance, if R is hilite, the matched area is hilited.  (In backward
searches, the cursor is placed at the end of the matched area.)  If F=0 or 1,
a forward search is done.  If F=-1, a backward search is done.  If F=2, a
forward search and replace are done.  If F=-2, a backward search and replace
are done.  When no replace string exists, if F=2 or F=-2 the matched area is
cleared.  Replace strings may include matched REs \1 to \9 from the search
string, so the size of the actual replace text is unknown until a match is
found; then a 1k block of memory is allocated and the replace text is stacked
into it; it is then inserted into buffer B after the matched area has been
cleared.  If the actual replace text exceeds 1k bytes, no replace is done and
grep() returns False.  grep() uses searchCaps to determine upper/lower case
sensitivity; if searchCaps is False, case is ignored.  Note that grep() is
slower than search() for simple search strings (no wildcards or special
symbols), so grep() should only be used when the requirements call for it.
When a complex search string is required (search() cannot be used) and a
large replace is required but referencing REs in the replace string is not
required, grep() can be used for the search and clearRgn() and insertRgn()
used for the replace; this handles replace text of any amount up to the limit
of available memory.  (See setGrep() and getGrep().  See grep commands in
Config!H.)

Display Action:  Refreshes the cursor line.
Cursor Action:  Puts the cursor at start of matched area.

Example:  grep(curfile,invert,1) ..search forward, don't replace

gtLoc(B,L1,L2)
B:  list 2 (buffer)
L1,L2:  list 6 (location)

Returns True, if location L1 > L2 in buffer B.  Returns False, if B does not
exist or L1 <= L2.

Example:  if (gtLoc(curfile,eInvert,sInvert)) refreshDisplay ..region exists.

gtNum(N1,N2)
N1,N2:  list 10 (integer)

Returns True, if N1 > N2.  Returns False, if N1 <= N2.

Example:  if (gtNum(lineLength,77)) equateNum(lineLength,77) ..set global.

hexDecimal(B)
B:  list 2 (buffer)

Converts the number at the cursor in buffer B from hexadecimal to decimal or
vice versa.  The cursor must be at the start of the number; if it is not, the
number is not converted correctly.  If it is a minus decimal number, the
cursor should be on the "-" minus sign.  If the number is hexadecimal, the
number must begin with "0x" and the cursor must be on the "0".  The
conversion does not move the cursor.  It returns False, if B does not exist,
if B is read-only, if the cursor is not resting on a digit or a minus sign "-
", or if the number is not a valid decimal or hex number.

Display Action:  If B=curFile, refreshes cursor; centers cursor, if offscreen.

Example:  hexDecimal(curFile) ..convert hex/dec at cursor in curFile.

hScroll(D)
D:  list 10 (direction)

Scrolls display horizontally.  If D>0, it scrolls toward end-of-line by
amount D.  If D<0, it scrolls toward start-of-line by amount D.  It returns
False, if trying to scroll past start-of-line or if D=0.  Scrolling toward
end-of-line is limited to 32767 columns.

Display Action:  Refreshes curFile.

Example:  while (hScroll(-1)) nothing ..scroll to start-of-line.

hyper(B,W,I,F)
B:    list 2 (buffer)
W:    list 0 (text)
I,F:  list 10 (integer)

Fetches hyper word W's (or index I's hyper word) descriptive text, doing the
lookup based on flag F.  B cannot be curFile.  W may be empty; if W contains
a (presumed hyper) word or phrase, the first 17 bytes are used for the
lookup; any extra bytes are ignored.  Hyper words have an associated lookup
table index value in the range 0 to N-1, where N is the number of hyper words
defined in the hyper text file.  Thus a hyper word may be referenced by the
word itself or by its table index I.  The first hyper word has index=0 and is
the parent or grandparent etc of all other hyper words.  Hyper words each
have a parent (except the one at index=0) and may have children and any
number of siblings.  The lookup methods available are the following:

    If W is empty:
        if F=0,  look up the hyper word at index I.
        if F=1,  look up the parent of I.
        if F=2,  look up the child of I.
        if F=3,  look up the next sibling of I.
        if F=4,  look up the prev sibling of I.
        if F=5,  step backward thru lookup history.
    If W is not empty:
        if F=0,  find word W by starting at front of lookup table (I=0).
        if F=1,  find word W by scanning the lookup table starting at I.
        if F=2,  find word W using an algorithm starting at I.

The algorithm, given a current table index I, is to search through the:
    A. children of I     (immediate, not grand children etc)
    B. siblings of I     (words with same parent as the I word)
    C. parent of I and parent's siblings
    D. grandparent of I and grandparent's siblings, and so on.

Upper/lower case is ignored in hyper words.  If the hyper() lookup is
successful, True is returned, the hyper word's descriptive text is put into
buffer B, the hyper word is copied into buffer B's name (title) field, and
its lookup table index is put into integer variable I.  hyper() returns
False, if hyper text is not open, if B cannot be allocated, if B is curBuf,
if flag F is invalid, or if the lookup is unsuccessful.

hyperClose

Closes hyper text and returns True, if hyper text is currently open.

hyperOpen(H,T,F)
H,T:  list 0  (text)
F:    list 10 (integer)

Opens hyper text for hyper text file H with lookup table T based on flag F.
In all cases, table T resides in memory.  If F=0, H is also loaded into
memory; if unable to load it, False is returned.  If F=1, an attempt is made
to load H; if no memory, it is accessed on disk.  If F=2, H is not loaded but
is accessed on disk.  False is returned, if unable to find H or T or if there
is insufficient memory.  Warning:  If you edit a hyper text file, you must
rebuild its table using the program UHC (Uedit Hyper Create), because the
table stores byte offsets to hyper words in the hyper text file.

Example:  hyperOpen("HyperSample","HyperSample.tbl",1) .. load into memory if
can

hyperUp

Returns True, if hyper text is currently open.

incLoc(B,L)
B:  list 2 (buffer)
L:  list 7 (location)

Increments location L in buffer B.  It returns False, if B does not exist or
if L is already at eof.

Cursor Action:  Advances cursor, if L=atCursor.

Example:  if (eqLoc(curFile,atCursor,sFile)) incLoc(curFile,atCursor)

incNum(N)
N:  list 10 (integer)

Increments the value of integer variable N.  It returns False, when N going
in is 0, but N is incremented regardless.  (See decNum().)

Example:  equateNum(n0,-10)  while (incNum(n0)) incLoc(curFile,atCursor)

indexToLoc(B,L,I)
B:  list 2 (buffer)
L:  list 7 (location)
I:  list 10 (integer)

Sets location L to byte-index I of buffer B relative to start-of-file.  If
buffer B is fragmented, it is packed.  (See fileSize().)  It returns False,
if B does not exist, if I <= 0, or if I > buffer-size.  If I > buffer-size,
location L is moved to eof.

Cursor Action:  Moves cursor to byte-index I, if L=atCursor.

Display Action:  If B=curFile:  Refreshes window, if L is not atCursor.  If
L=atCursor, refreshes cursor; if offscreen, centers cursor.

Example: indexToLoc(curFile,atCursor,1000) ..move cursor to 1000 bytes into
file.

inputKey(N)
N:  list 10 (integer)

Collects the next input's macro number in variable N, if an input has been
given.  It returns False, if no input is available.  It does not wait for an
input.

Example:  while (inputKey(n0)) push(n0) ..save keys on number stack.

inputNum(N)
N:  list 10 (integer)

Solicits a number input for integer variable N using Primitive Mode.  The
title bar displays the message "Primitive Mode number input (pmEsc=done):".
Primitive Mode is terminated using the current pmEsc character or a mouse
click.  If anything is typed, it returns True.  If nothing is typed, it
returns False.  The number may be typed in using decimal or hexadecimal.
Primitive Mode input may be aborted with Amiga-ESC.

Display Action:  Uses the top line(s) in the window.  Refreshes window
afterward.

Example:  putMsg("Input new line-length:")
    if (inputNum(n54) & gtNum(n54,10)) {
        setLocal(curFile,lineLength,n54)   .. set curFile's line length.
        equateNum(lineLength,n54)   .. set the global value as well.
    }

inputString(B)
B:  list 2 (buffer)

Solicits a string input in buffer B using Primitive Mode.  The title bar
displays the message "Primitive Mode string input (pmEsc=done):".  Primitive
Mode is terminated using the current pmEsc character or a mouse click.  If
anything is typed, it returns True.  If nothing is typed or B is curFile, it
returns False.  inputString() may be aborted with Amiga-ESC.

Display Action:  Uses the top line(s) in the window.  Refreshes window
afterward.

Example:  putMsg("Input new search text:")   .. get new search string.
if (inputString(buf49)) setSearch(buf49)

inputWaiting

Returns True, if an input is waiting to be picked up.  It returns False, if
no inputs have been given.  When inputWaiting is called in a learned
sequence, it always returns True; if it did not, learned sequences would not
run as if they were just being typed in.

Example:  while (not inputWaiting) { vScroll(downLine) updateDisplay }

insertChar(B,N)
B:  list 2 (buffer)
N:  list 9 (character)

Inserts character N into buffer B at the cursor.  It returns False, if B is
read-only, or if N is an illegal character and the MapChars flag is not On
for buffer B.  If N is illegal (ASCII 0-3) and MapChars is On for B, the
character is mapped into a legal character according to the mapping table in
the config defaults.  (See swapChar() and typeChar().)

Display Action:  Refreshes window, if any and not curFile.  If B=curFile,
refreshes cursor; if offscreen, centers cursor.

Example:  insertChar(curFile,"*") insertChar(curFile,13) ..insert "*" and CR.

insertFile(B1,L,B2)
B1:  list 2 (buffer)
L:  list 6 (location)
B2:  list 10 (text)

Inserts the file named in B2 into buffer B1 at location L.  It returns False,
if the file named in B2 does not exist or if buffer B1 is Read-Only.  B1 is
allocated, if it does not exist.  Illegal characters (ASCII 0-3) are mapped
on loading in the file, if MapChars is On for B1.  If B1's MapChars is not On
and there are illegal characters, you will be asked whether they can be wiped
or not.  If you answer Yes, illegals are converted to "@".  If you answer No,
insertFile() quits and returns False.  If memory runs out during
insertFile(), if there are file-saves in the queue, they are finished in
hopes that it will free up enough memory.  If all file-saves have been
finished and there is still not enough memory, it returns False, having only
partially inserted the file.

Display Action:  Refreshes B1's window, if in a window.

Example:  insertFile(curFile,eFile,"MyLetterEnding")

insertRgn(B1,L,B2,R)
B1:  list 2 (buffer)
L:  list 6 (location)
B2:  list 0 (buffer)
R:  list 12 (region)

Inserts region R of buffer B2 into buffer B1 at location L.  It returns
False, if B2 does not exist, if region R is empty, if B1 is read-only, or if
B1=B2.  If B2 is a literal, R is a dummy and ignored.

Display Action:  Refreshes B1's window, if any and not curFile.  If
B1=curFile, refreshes cursor; if offscreen, centers cursor.

Example:  insertRgn(buf54,eFile,curFile,hilite) ..store hilite in buf54.

inTiny

returns TRUE, if Uedit is in tiny window.

inUse(K)
K:  list 10 (integer)

Returns True, if key K has a command attached to it.  K must be a valid key
argument or macro number in the range 1 to 1148.  It returns False, if K has
no command.

Example:  getKey(n0) if (inUse(n0)) putMsg("Key has a command")

is(B,T)
B:  list 2 (buffer)
T:  list 11 (thing)

Tests the character/word/line/location of the cursor in buffer B for some
condition.  (See argument list 11 in 3.1.)  It returns False, if B does not
exist.  Otherwise, it returns True or False, based on test results.  Note
that sForm/eForm refer to start/end of printed page, whereas sPage/ePage
refer to the window boundaries.  is(buf,eLine) returns True, when cursor is
at eof or at end-of-line either one.

Example:
    while (not is(curFile,whiteSpace)) {
        if (is(curFile,".")) return
        moveCursor(curFile,eChar)
    }

isEmpty(B)
B:  list 2 (buffer)

Returns True, if buffer B is empty or does not exist.  Returns False, if B
exists and has content.

Example:  if (not isEmpty(buf54)) setSearch(buf54)

killKey(K)
K:  list 10 (integer)

Kills the command of key K.  K must be a valid key argument or macro number
from 1 to 1148.  If K has a command, the command is deleted and it returns
True.  It returns False, if K is out of range or has no command.  If K is the
Startup key, the menus are deleted.  If K is the current key running, the
engine executes an Abort right after K is deleted.

Example:  getKey(n99)   if (killKey(n99)) putMsg("Command deleted")

lineToLoc(B,L,N)
B:  list 2 (buffer)
L:  list 7 (location)
N:  list 10 (integer)

Moves location L of buffer B to the beginning of line number N in the buffer.
It returns False, if B does not exist, if N <= 0, or if line N is beyond eof.
If N is at or beyond eof, location L is moved to eof.

Cursor Action:  Moves cursor to line N, if L=atCursor.

Display Action:  If B=curFile and L=atCursor, refreshes cursor; centers
cursor, if offscreen.

Example:  lineToLoc(curFile,atCursor,100) ..move cursor to line 100.

loadConfig(B)
B:  list 10 (text)

Loads the data file named in B.  ("loadConfig" is a misnomer; it is not a
config file being loaded in but rather a data file.)  It returns False, if
the file named in B does not exist, or if the data file has the wrong Uedit
version number.  When the data file is loaded in, an Abort is executed,
stopping all activity in Uedit.  This is necessary because the command being
run is deleted before the new data is loaded in.  The window is closed and
reopened using the values in the new data file.

Display Action:  Window is closed and reopened.

Example: loadConfig("S:Data!")  ..load data file.  Aborts if successful.

loadFile(B)
B:  list 10 (text)

Loads the file named in B into the next available file buffer.  The new file
becomes curFile.  It returns False, if B is a buffer and it does not exist or
if all file buffers are in use.  If the file named in B does not exist, an
empty buffer is opened with the name given in B.  If the file already exists
in Uedit, a requester asks if you want to load a ReadOnly copy of it.  The
load may be aborted with Amiga-ESC.  If memory runs out during the load and
there are file-saves in the queue, they are finished in an effort to free up
enough memory.  If no file-saves are pending and memory runs out, the load is
aborted and the partially loaded file is erased from memory.  Note that
insertFile() will load part of a file that is too big for memory, but
loadFile() will not.

Display Action:  Displays new curFile.

Example:  if (inputString(buf54)) loadFile(buf54)   .. get name, load file.

loadKeys(B,K1,K2)
B:  list 10 (text)
K1,K2:  list 10 (integer)

Loads a range of key commands from the partial data file named in B.  It
returns False, if K1<1 or K1>1148, if the partial data file is not found, or
if no key in the range specified is found.  If K2<K1, it sets K2=K1.  If
K2>1148, it sets K2=1148.  If the Startup command is loaded in, the menus are
removed and are rebuilt using the new Startup command during the next pause.
Keys loaded in replace their existing counterparts in memory.  Blank
(unassigned) keys may be stored with saveKeys() and loaded in with loadKeys()
also, and when loaded in they wipe out their existing counterparts in memory.
Keys may be saved multiple times in a partial data file using saveKeys().  If
multiple copies of a key are in the partial data file, only the last version
of the key is picked up by loadKeys().  Keys in memory that fall into the
specified range but which do not exist in the partial data file are not
affected.  To load in every key in the partial data file, specify K1=1 and
K2>=1148.  loadKeys() can load in one key at a time, but it is more efficient
when all keys are loaded at the same time by specifying a range, because it
opens, reads, and closes the partial data file each time it is used.  (See
saveKeys().)

Examples:
    loadKeys("pData",normal-f1,normal-f10)   .. load function keys.
    loadKeys("pData",Startup,0)   .. load in just the Startup command.
    loadKeys("pData",1,2000)   .. load in all keys in pData.

loadLearn(B)
B:  list 10 (text)

Loads the learned sequence named in B.  It looks first in the current
directory, and then, if necessary, in the S: directory.  It returns False, if
Learn Mode is active, if a learned sequence is currently being executed, or
if the named learned sequence is not found or is empty.  (See saveLearn() and
runLearn.)

Example:  if (loadLearn("myHeader")) runLearn ..auto-type letter header.

loadState(B)
B: list 10 (text)

Loads the state file specified in buffer or literal B.  A state is a
"snapshot" of Uedit's current state, which includes all files and buffers
along with their local flags, the cursor locations, colored regions, search
and replace and grep strings, and so on.  Also included are the split window
configuration and color settings.  When you load a state file, the "state" of
Uedit is just as it was when the state file was saved earlier with
saveState().  loadState() can be aborted with Amiga-ESC; if told to abort, it
finishes loading the current file or buffer before aborting.  loadState()
compares the dates-times of each file in the state file with the file copy on
disk, if any; if the copy on disk is newer, loadState() flags the file as
ReadOnly.  Note: The state file does not store commands or learned sequences;
these can be stored separately in disk files.

Cursor action:  As noted.
Display action:  As noted.

locToCol(B,C,L)
B:  list 2 (buffer)
C:  list 10 (integer)
L:  list 6 (location)

Reports the column C of location L in buffer B.  It returns False, if B does
not exist.

Example:  locToCol(curFile,n54,sHilite) putMsg(n54)

locToIndex(B,I,L)
B:  list 2 (buffer)
I:  list 10 (integer)
L:  list 6 (location)

Reports the byte-index I into buffer B of location L.  It returns False, if B
does not exist.  If B is fragmented, it is packed before the index is
calculated.

Example:  locToIndex(curFile,n54,mouseLoc) putMsg(n54)

locToLine(B,N,L)
B:  list 2 (buffer)
N:  list 10 (integer)
L:  list 6 (location)

Reports the line number N in buffer B of location L.  Note that N is the text
line number in B, not the screen or page line number.  It returns False, if B
does not exist.

Example:  locToLine(curFile,n54,atCursor) putMsg(n54) ..report cursor line.

menu(D,A,N,C)
D,A:  literal
N,C:  list 10 (integer)

Creates a menu selection.  Description D and alternate text A must be a
literal in quotes up to 17 characters in length.  N is the menu number, 1 to
7.  C is the command-key, which must be a valid key argument or a macro
number, 1 to 1148.  It returns False, if N or C is out of range, if no memory
is available, if there are already 20 menu items for menu N, or if the
command for C does not exist.  menu() may only be used in the Startup
command.  (See Config! for examples.)

mod(A,B,C)
A,B,C:  list 10 (integer)

A = B mod C.  It returns False, if C=0.

Example:  mod(n54,n53,10) if (eqNum(n54,0)) return

mouseDown

Returns True, if the left mouse button is down.  Returns False, if it is not.
MouseLoc in curFile is updated when the mouse button is pressed or released.
To get continuous updating of mouseLoc, use trackMouse.  If trapMenus is
True, mouseDown also returns True if the right (menu) mouse button is
pressed.  (See mouseXY() and trackMouse.)

Example:  if (not mouseDown) return

mouseXY(X,Y)
X,Y:  list 10 (integer)

Reports the x-y position of the mouse when the left (or right, if trapMenus
is True) mouse button was last pressed or released.  The x-y position is
updated continuously, if trackMouse is used while the button is held down.
(See mouseDown and trackMouse.)

Example:
    while(mouseDown & not inputWaiting) {
        trackMouse
        mouseXY(n50,n51)
        putMsg(n51)   .. report mouse Y position.
    }

moveCursor(B,H)
B:  list 2 (buffer)
H:  list 4 (how)

Moves the cursor in buffer B according to H.  It returns False, if B does not
exist, or if unable to move the cursor due to start or end of file.  Note
that sPage/ePage refer to the window's boundaries, while sForm/eForm refer to
printed page boundaries based on the line-count or formfeeds in the text.

Display Action:  If B=curFile, refreshes cursor; centers cursor, if offscreen.

Example:  if (not is(curFile,sLine)) moveCursor(curFile,sLine)

mul(A,B,C)
A,B,C:  list 10 (integer)

A = B * C.

Example: mul(n54,lineLength,pageLines) putMsg(n54) ..show max chars per page.

nameBuffer(B,N)
B:  list 10 (buffer)
N:  literal

Assigns the name N to buffer B.  It returns False, if name N is empty or
begins with a whitespace character, if buffer B is a file buffer, or if name
N is longer than 63 characters.  Buffer B need not exist at the time.  N must
be a literal.  nameBuffer() is used for naming work buffers (non-file
buffers) so that when they are displayed, such as in split windows, they are
named descriptively.  nameBuffer() may only be used in the Startup command.

Example:  nameBuffer(buf37,"Copied columnar data")

newFile

Opens an empty file buffer named Empty.

nothing

Returns True, doing nothing.  It is useful with while-loops.

Examples:  while (hScroll(-1)) nothing
while (nothing) {
    if (inputKey(n99)) goto label(10)
    vScroll(upLine)
    updateDisplay
}

onScreen(L)
L:  list 6 (location)

Returns True, if location L in curFile is in the window.  onScreen() applies
only to curFile.  It returns False, if L is not in the window.  It is not a
rigorous test, because accuracy was sacrificed for speed, but it is usually
accurate.  The purpose of onScreen() is to avoid unnecessary screen refreshes.

Example:  if (not onScreen(atCursor)) vScroll(atCursor) .. don't scroll
unless must.

or(A,B,C)
A,B,C:  list 10 (integer)

A = B bitwise-or C.  It returns False, if the result A = 0, meaning that
there are no bits set in either B or C.

Example:  or(n99,userGlobalA,userGlobalB)

pop(S,BN)
S,BN:  list 10 (buffer or number)

Pops the next item from stack S into buffer or number variable BN.  Returns
False if stack S is empty.  If S is a buffer variable such as buf10, buffer
stack 10 is used; if S is a number variable such as N22, number stack 22 is
used.  The stack is popped into variable BN.  If a buffer is popped off a
buffer stack the current buffer BN is deleted and the stack is popped into
buffer variable BN.  Note that the stack is LIFO, last-in-first-out.  (See
getStackSize(), push(), and rollStack().)

Display Action:  Displays "home" buffer, if pop into curFile.

Example:  pop(n22, pageLines) .. pop number stack 22 into pageLines variable.
pop(buf99, buf3) .. pop buffer stack 99 into buf3 slot, killing old buf3.

print(B,R)
B:  list 0 (text)
R:  list 12 (region)

Prints region R of buffer B, using the current setting of prefPrint (Print
Select).  If B is a literal, R is a dummy and is ignored.  Up to 12 prints
may be queued up, allowing continued editing while printing is processed in
the background.  If 12 prints are already queued up, print() processes the
printing until a slot in the queue opens up; this waiting may be aborted with
Amiga-ESC.  If the print job is too big to copy into memory and spooled
prints are in the queue, the spooled prints are processed in hopes of finding
enough memory to copy and spool out the new print.  If there are no spooled
prints and there still is not enough memory to spool the new print, it is
printed in foreground ("busy" mode).  Foreground prints may be aborted with
Amiga-ESC.  Spooled prints must be aborted with abortPrint.  If printTabs is
True (see Config! defaults), tabs are sent to the printer; if printTabs is
False (the default), tabs are converted to spaces for the printer.  NOTE:
Print() doesn't count control characters (except eol, ff, and tab) when
counting columns for tab conversion; but ESC sequences may still cause tab
conversion to be inaccurate due to other characters in the ESC sequence.
(See abortPrint and printerCode().  See Printing in Part 1.)

Example:  print(curFile,all)   .. print all of curFile.
equateNum(prefPrint,1) print(curFile,hilite) ..send hilite out serial port.

printerCode(B,X,Y,Z)
B:  list 2 (buffer)
X,Y,Z:  list 10 (integer)

Embeds printer control code X, with arguments Y and Z, at the cursor in
buffer B.  It returns False, if B does not exist, if B is read-only, or if X
or Y or Z is invalid.  X must

be a value from 0 to 75; it is a printer command number from the Amiga ROM
Kernal Manual.  (See Printer Control Table in Part 1.)  Y and Z are arguments
for printer command X and must be in the range 0 to 223.  Unless the printer
code X uses arguments, Y and Z should be 0; most printer commands do not
require arguments.  printerCode() embeds the printer command code in buffer B
at the cursor using the format ESCxyzESC, where x = X + 32, y = Y + 32, z = Z
+ 32.  32 is added to each argument, in order to avoid control characters.
When you print the file, Uedit strips off the ESCs, converts xyz, and sends
the resulting printer code and arguments (if any) to the Amiga print device.
If Y and Z are 0, they are not used; thus, a typical embedded code is of the
form, ESCxESC, where x = X + 32.  prefPrint (Print Select) must be 2 or 3 in
order for these codes to be processed by the Amiga print device; if prefPrint
is 0 or 1, these codes are likely to make the printer print garbage.  (See
Printing in Part 1.  See print() and abortPrint().)

Display Action:  If B=curFile, refreshes cursor; centers cursor, if offscreen.

Example:  printerCode(curFile,6,0,0) ..embed printer code for italics.

push(S,BN)
S,BN:  list 10 (buffer or number)

Pushes item BN, a buffer or number, onto the stack indicated by S.  If S is a
buffer variable such as buf10, it means use buffer stack 10; if it is a
number variable such as n22, it means use number stack 22.  There are 100
buffer and 100 number stacks.  False is returned if 8 bytes is not available
for the stack entry.  If BN is curFile, the "home" buffer becomes the new
curFile; if BN is the last file buffer, a new NoName buffer is opened.  (See
rollStack(), getStackSize(), and pop().)

Display Action:  If curFile pushed, displays new curFile.

Example:  push(buf10, curFile)   .. push curFile onto buffer stack 10.
push(n0,lineLength) .. push lineLength onto number stack 10.

putMsg(X)
X:  list 10 (buffer or literal or integer)

Displays message X in the message line beneath the title bar.  X may be a
buffer, literal, or number.  The message length may be up to 75 characters.
If speakMsgs is True, messages are also spoken.  Use putMsg("") to clear the
message line.

Example:  if (inUse(macroNum)) putMsg("Key is in use")

quit(N)
N:  list 10 (integer)

Quits Uedit, giving return code N to the Amiga.  For a "good quit", use N =
0.  For a bad quit, use an AmigaDOS error return code such as 10.  If prints
or file-saves are in progress, quit() waits until they are completed; if you
give an input during this waiting, Uedit returns to editing mode.  If a Rexx
message has not been sent a reply or messages are waiting to be picked up,
Uedit sends a Failed reply to each of them; but if a Rexx message has been
sent by Uedit and a reply has not been received, a "Wait for Rexx reply"
message is displayed and Uedit returns to edit mode.  If buffers are on the
buffer stack, quit() asks whether it is okay to delete them or not.  If you
answer No or Cancel, you are returned to edit mode.  If you answer Yes, Uedit
frees its memory, closes the window, and quits.  (See discussion of quitting.)

Example:  if (askYesNo("Really quit?")) quit(0)

reformat

Reformats the cursor's paragraph in curFile, starting at the cursor line.  It
returns False, if curFile is read-only, or if cursor is at eof or there is no
text to reformat between cursor and eof.  If the cursor is in a blank line,
the cursor is advanced until a line with text in it is found.  reformat uses
the current local typing settings, such as rightJustify and lineLength.  It
turns on WordWrap and AutoIndent temporarily, if not already on.  The end of
the paragraph is determined by a blank line or a change in indentation.  When
finished, the cursor is at the end of the paragraph.  Note:  reformat uses
mouseLoc as a scratch location; this should be harmless, as mouseLoc is reset
whenever the mouse button is used.  (See discussions of typing, paragraph
reformatting, local modes, and local values in Part 1.)

Cursor Action:  Cursor is moved to the end of the paragraph.

Display Action:  Refreshes cursor; if offscreen, centers cursor.

Example:  reformat moveCursor(curFile, downLine) ..reformat & leave paragraph.

refreshDisplay

Refreshes curFile's window immediately.  It does not refresh any other split
windows.  RefreshDisplay takes time, so do not use it unless it is really
necessary.  Always try new commands without using it, and try using
updateDisplay before resorting to refreshDisplay.  refreshDisplay uses the
current sPage location and does not scroll the display.  (See updateDisplay
and vScroll().)

Display Action:  Redisplays curFile immediately.

Example:  if (thisKey) refreshDisplay ..refresh, if key is primary key.

restartPrint

Restarts the spooled print that is currently in progress.  Use restartPrint
after printer paper jams.

return

Forces the current command to return immediately, using the True/False return
of the most recent function that was called.

Example:  if (not newFile) return ..would always return False here.

returnFalse

Forces the current command to return False immediately.

returnTrue

Forces the current command to return True immediately.

rexxIn(B,L,A,F,C)
B:  list 0 (buffer)
L:  list 6 (location)
A,F,C:  list 10 (integer)  (A=ActionResult, F=Flag, C=ReturnCode)

Fetches a Rexx message/reply into buffer B at location L.  If flag F is 0, a
message was fetched and A is the Rexx command (Action) code of the message.
If flag F is 1, a reply was fetched and A is the Rexx Result code of the
reply.  The Uedit return code C is 0, if rexxIn() returns True.  C contains a
non-zero Uedit error return code, if rexxIn() returns False.  If B is a
blank literal "", the text of the incoming message or reply is discarded.
rexxIn() returns False, if ARexx is not up, if there is no message or reply
to fetch, or if there is no memory to store the incoming text in buffer B.
Fetching an incoming reply with rexxIn() causes the original message's
resource to be released, so replies can only be fetched once.  An incoming
message may be fetched repeatedly, however, and is not released until a reply
to it is sent using rexxOut().  You can dump a stream of incoming messages by
not bothering to call rexxIn(); just call rexxOut() repeatedly until it
returns False.  If a Rexx message arrives when Uedit is in tiny window, it
immediately returns to its big window.  (See rexxOut().  See Rexx Interface
and the examples in Part 2.  See the Rexx commands in Config!R.  See the
ARexx User's Reference Manual.)

rexxOut(B,R,A,F,C)
B:  list 0 (buffer)
R:  list 12 (region)
A,F,C:  list 10 (integer)  (A=ActionResult, F=Flag, C=ReturnCode)

Sends the Rexx message/reply in buffer B, region R, using the Action/Result
code in A.  If F is 0, it sends a message.  If F is non-zero, it sends a
reply.  If rexxOut() returns False, the Uedit error return code is in C.  If
it returns True, C is 0.  If B is a literal, the region argument R is a dummy
and is ignored.  Rexx messages may be up to 65535 bytes in length.  On
outgoing replies (F=1), the A field is the Rexx Result value, which is
normally 0 (for an Okay result).  On outgoing messages (F = 0), the Rexx
command (Action) field A may be one of the Uedit defaults (0, 1, or 2) or an
actual Rexx action code with modifier flag bits.  rexxOut() does NOT validate
the Rexx action code in A, if it is not one of Uedit's default values (0, 1,
or 2).  If you send a message with rexxOut() and do not use the RXFF_NONRET
modifier, a reply is expected and rexxOut() will not let you send another
message until a reply has been received and fetched using rexxIn().  To dump
all incoming messages, keep calling rexxOut() with flag F=1, sending replies,
until rexxOut() returns False.  rexxOut() returns False, if ARexx is not up,
if a previous message sent has not received a reply yet, if there is no
memory for the message or reply, or if you tried to reply to a message when
no message is outstanding.  (See rexxIn().  See Rexx Interface, 2.8.  See
Rexx commands in Config!R.  See the ARexx User's Reference Manual.)

rollStack(X,N)
X:  list 10 (buffer or integer)
N:  list 10 (integer)

rolls the buffer stack X by amount N, if X is a buffer argument such as
buf10; rolls the number stack X by amount N, if X is an integer argument such
as N22.  X indicates which buffer or number stack to roll.  rollStack()
returns False, if the (buffer or number) stack size is less than 2 or if N is
0.  N may be positive or negative, and the stack is rolled forward or
backward based on the sign and amount of N.  The stacks are LIFO, last-in-
first-out.  If N is 1, the first-out stack entry is rolled to the last-out
position, so that second-out becomes first-out.  If N is -1, the last-out
entry is rolled to the first-out slot.  (See push(), pop(), and
getStackSize().)

Example:  rollStack(buf10,1)   .. rolls buffer stack 10 forward by 1.
rollStack(n0,n54)   .. rolls number stack 0 by the amount in n54.

runKey(K)
K:  list 10 (integer)

Runs the command of key K.  K must be a valid key argument or a number or
variable whose value is between 1 and 1148.  runKey() returns False, if K is
out of range or K does not have a command.  If K has a command, it returns
the True/False result of command K.  Commands may run commands to a depth of
10.  The primary command runs at level 1.  If it uses runKey(), the command
it runs is at level 2, and so on.  (See Overview of Commands, 2.19.)

Example:  while (runKey(normal-f9)) runkey(normal-f10) ..while find, replace.

runLearn

Terminates learning with Learn Mode, if Learn Mode is On; runs the current
learned sequence, if Learn Mode is Off.  It returns False, if a learned
sequence is already being executed, or if no learned sequence exists.
runLearn returns the True/False of the last command run in the learned
sequence.  Learned sequences may contain up to 200 steps.  To start Learn
Mode, use flipFlag(curFile, learnMode).  To abort Learn Mode, erasing all
stored steps, use flipFlag(curFile, learnMode) again.  To find out whether
Learn Mode is On, use getFlag(curFile, learnMode).  To terminate Learn Mode
gracefully, use runLearn.  To run the learned steps, use runLearn again, as
many times as desired.  (See Learn Mode, 1.35.  See loadLearn() and
saveLearn().)

Examples:  if (loadLearn("TypeHeader")) runLearn ..type in header.

saveConfig(B)
B:  list 10 (text)

Saves Uedit's data to the file named in B.  If B is blank, it saves the data
using the current data file name.  It returns False, if unable to save the
data for some reason, such as due to an invalid file name.  (See
loadConfig().)

saveFile(B)
B:  list 2 (buffer)

Locks buffer B and puts it into the file-save queue to be saved in
background.  While in the queue, buffer B is locked; but you can still modify
B, if it isn't the buffer currently being saved; if you do so, B is removed
from the file-save queue when its turn comes.  False is returned, if buffer B
is read-only or empty, or if AmigaDOS will not let the file be created for
some reason.  Buffer B is saved under its current buffer name.  During
saving, if mapChars is On for B, mapped characters are remapped back to their
illegal (ASCII 0-3) values.  If freeBuf() is called for B, B is freed
automatically after it has been saved; if a save-error occurs or abortSave is
called, the file-save is aborted and B is not freed.  saveFile() preserves
the file attributes, if the file already exists.  (See abortSave.)

Example:  if (getFlag(curFile,changed)) saveFile(curFile) ..save, if changed.

saveKeys(N,K1,K2)
N:  list 10 (text)
K1,K2:  list 10 (integer)

Saves the range of key commands from K1 to K2 in the partial data file named
in N.  It returns False, if K1<=0 or K1>1148, if file N cannot be created due
to bad file name or path name, or if file N already exists but has the wrong
Uedit version number.  If K2<K1, it sets K2=K1 and saves only that one key.
If K2>1148, it sets K2=1148, the highest allowed macro number.  It appends
each key to the end of the file N.  saveKeys() can save blank, unassigned
keys.  If called repeatedly to save the same key over and over, each copy is
appended to the end of the file; this is wasteful and should be avoided.
(See loadKeys().)

Example: saveKeys("pData",normal-Esc,0)   .. save just Esc key.
saveKeys("pData",normal-f1,normal-f10)   .. save F1 to F10.

saveLearn(N)
N:  list 10 (text)

Saves the current learned sequence to the disk file named in N.  It returns
False, if there is no learned sequence, if Learn Mode is currently On, if
currently executing a learned sequence, or if unable to create file N.
Learned sequences should be saved in the S: directory, if Uedit is to find
them from any directory.  (See loadLearn() and runLearn.)

Example:  saveLearn("TypeHeader")   .. save sequence that types in letter header.

saveState(B)
B: list 10 (text)

Saves Uedit's current state to the disk file named in B.  A state is a
"snapshot" of Uedit's current state, which includes all files and buffers
along with their local flags, the cursor locations, colored regions, search
and replace and grep strings, and so on.  Also included are the split window
configuration and color settings.  When you load the state file back in with
loadState(), the "state" of Uedit is just as it was when the state file was
saved earlier with saveState().  saveState() can be aborted with Amiga-ESC;
if told to abort, it finishes saving the current file or buffer before
aborting.  Note: The state file does not store commands or learned sequences;
these can be stored separately in disk files.

screenToBack

moves Uedit's screen to the back.  screenToBack always returns TRUE, unless
Uedit's screen is not open as when in tiny window.

screenToFront

moves Uedit's screen to the Front.  screenToFront always returns TRUE, unless
Uedit's screen is not open as when in tiny window.

search(B,L1,L2,D)
B:  list 2 (buffer)
L1,L2:  list 8 (location)
D:  list 10 (direction)

Searches buffer B in the fwd/bkwd direction specified by D, looking for a
match to the current search string.  It returns False, if buffer B does not
exist, if no search string exists, or if the search fails.  If D>=0,
searching is forward.  If D<0, searching is backward.  When search() finds a
"hit", the cursor is placed at the beginning of the matched region; the start
and end of the matched region are stored in locations L1 and L2 of B.  There
may be 2 search strings, delimited by the eitherOr character, and there may
be an "all but" string delimited by the allBut character.  Matches to the
"all but" string are skipped over by search().  If there are single or multi
character wildcards in either of the two search strings or in the all-but
string, the inclusion/exclusion of white space in the "matched" region
underneath the wildcards is governed by the values of singleWhite (for
wildCard) and multiWhite (for multiWild):  If these are 0, only black
characters are allowed as a "hit" on wildcards.  If they are 1, spaces and
tabs are also allowed.  If they are 2, any character is allowed as a "hit" on
the wildcard.  If multiWild is used in a search string, up to 32 characters
are allowed to be included by it and searching is declared a "miss" if more
than 32 are required.  Searching is slower when wildcards are used.  (See
getSearch() and setSearch().)

Cursor Action:  If search succeeds, cursor is at the start of the matched
region.

Display Action:  If B=curFile, refreshes cursor; if offscreen, centers cursor.

Example:  search(curFile,sInvert,eInvert,1)   .. search forward.
search(curFile,locA,locB,n54)   .. search fwd/bkwd depending on n54.

seeRuler

Displays curFile's tab ruler.  The ruler is displayed above the cursor line,
if possible.  If not, it is displayed at the top of the window.  Giving any
input causes the ruler to be removed and the display refreshed.  Note that
the input is not discarded; while looking at the tab ruler, you can deposit
the cursor in a desired column in the text using the mouse.  (See setRuler
and getTabs().)

Display Action:  Refreshes window when finished.

setColors(B,C,Fg,Bg)
B: list 2
C,Fg,Bg: list 10 (numbers)

Sets the global and/or local colors.  If B is a buffer which exists, the
local colors of B are set according to the C, Fg, and Bg arguments.  If B is
a literal argument "" or buffer B doesn't exist, the internal local color
variable that is applied to newly created buffers is set according to the C,
Fg, and Bg arguments.  Fg & Bg must be in the range 0-3, corresponding to an
RGB color register number.  C must be in the range 0-15 or equal -1.  If C is
in the 0-15 range, setColors() returns False if Fg=Bg; this prevents you from
setting color combinations which would make text invisible.

C=0 to 7:  The local buffer B Fg & Bg colors corresponding to C are accessed.
(See the color table in the Config! defaults.)

C=8 to 15:  The global Fg/Bg colors corresponding to C are accessed and B is
ignored.  (Only colors 0 to 7 apply to buffers.)  The Fg/Bg color pairs are
as shown in the color table in the Config! defaults.

C=-1:  Fg and Bg are long word (32-bit) bitmasks containing all of the local
(buffer) and global (screen) colors, respectively.  (Again, if buffer B does
not exist or B is a literal "", the Fg color argument applies to the internal
color variable which presets the colors of newly created buffers.):

    The Fg bit masks, which apply to local colors, are as follows:  Each 4
    bits is 2 pairs of 2 bits, each with values 0-3 corresponding to the
    foreground and background colors, respectively.  The sets of 4 bits
    correspond (from left to right) to normal, cursor, hilite, cursor +
    hilite, invert, invert + cursor, hilite + invert, and cursor + hilite +
    invert.

    The Bg bitmasks, which apply to the global (screen) colors, are as
    follows:  Again, each 4 bits is 2 pairs of 2 bits, each with values 0-3
    corresponding to the foreground and background colors, respectively.  The
    sets of 4 bits correspond (from left to right) to title bar, msg line,
    menus, tab ruler, requester, formfeed, spare1, and spare2.

WARNING:  When C=-1, no check is made of the bitmasks in either the Fg or Bg
arguments.  It is possible to send invalid colors which render text invisible.
(See getColors(), setLocal(), and getLocal().)

setEol(N)
N:  list 10 (integer)

Sets the global end-of-line character to the value N.  Normally N would be
ASCII 10 or 13, but N may be any control character from ASCII 5 to 31.
setEol() returns False, if N is not in this range.  setEol() causes all split
windows to be refreshed.  If any buffer is using a different eol, the buffer
is displayed All On One Line and its eols must be converted or else setEol()
must be used again to change eol to the buffer's current eol in order for it
to display correctly.

Display Action:  Refreshes all split windows.

setFileName(B,N)
B:  list 2 (buffer)
N:  list 10 (text)

Sets the file name of buffer B to the name in N.  It returns False, if B does
not exist or is read-only, or if N is empty or begins with whitespace.  File
names may be up to 76 characters in length.  The Changed flag of buffer B is
turned On, when setFileName() is successful.  (See getFileName().)

Display Action:  Window title is refreshed, if B is in a window.

Example:  setFileName(curFile,"MyDocument")

setFont(fontname,fontheight)
fontname:    list 0 (buffer or literal)
fontheight:  list 10 (number)

returns TRUE if fontname exists and uses font size equal to fontheight.  The
font may be in memory or on disk.  If font isn't in memory it is loaded from
disk.  When a new font is selected or when Uedit quits, the current font is
released.

setFont() does not change the font immediately or visibly.  It merely changes
the stored font name and height.  Next time Uedit's screen is reopened - as
when changing screens or returning from tiny window - the new font is used.
If the font cannot be found, topaz 8 is used by default.

The following example command switches Uedit's font.  Notice that it goes to/
from tiny window in order to close/reopen the screen.  And it runs the
startup command so that the menus will use the new font:
    <normal-esc:  setfont("topaz",11) toggle(toTiny) toggle(toTiny)
    runkey(startup) >

setFold(T,F,X,SKA)
T,F,X,SKA:  list 10 (integer or text)

Successive calls to setFold() define the testing steps that will be used in
folding a buffer or region using fold().  T is a step number in the range 1
to 16.  The testing steps T are applied by fold() beginning with T=1.  Gaps
are allowed in the T values; empty T slots are ignored by fold().  Any
existing step T can be overwritten by calling setFold() again, using the same
T.

If setFold() is called with T=0, all testing steps are deleted; and then two
default steps (for T=1 and T=2) are defined, just as if you had called
setFold() as follows:
    setFold(1,1,0,1)    (keep blank lines - it keeps only 1 per series)
    setFold(2,2,0,1)    (keep lines with no indentation)

F specifies the test to apply in step T.  (See the list of F tests below.)
If F=0, step T is deleted.  (To eliminate the above two default steps, call
setFold(1,0,0,0) and setFold(2,0,0,0).)

X and SKA (Skip/Keep/AND) are used with test F.  If F<=7, X must be an
integer (indentation or line length) with a value between 1 and 130.  If F>=8
X must be a text string (of 1, 2, or 4 characters) in a buffer or literal
argument.  If X is to be used as a range of characters (such as "AZ" or "09")
or a set of brackets or quotes (such as "[]" or "\"\"") it must contain at
least 2 characters (only the first 2 are used).  If X is to be used as a text
string (not as a character range or set of brackets), it may contain 1 to 4
characters.  setFold() returns FALSE, if X is invalid.

fold() scans its input buffer line-by-line, applying to each line the tests
that were set up with setFold(), starting with test T=1.  fold() does not
keep a line (put it into the output buffer), unless a test succeeds on that
line of text.

When a test succeeds, SKA specifies the action to be taken:
    If SKA = 0, the line is skipped.
    If SKA = 1, the line is kept (put into the output buffer).
    If SKA = 2, the current test is ANDed with the next one; the SKA of the
    next test dictates what to do after that - assuming that the next test
    also succeeds; if any ANDed test fails, all tests ANDed with it are
    ignored.

NOTE:  Test F=15 may involve multi-lines of text.  If you want to AND a test
15 with other test(s), make sure that test 15 is last in the ANDed series.

Blank lines:  If F=1 and SKA=1, this specifies that blank lines be kept.  If
several blank lines are in series, fold() only keeps the first.

Folding tests (F):

0   erase test F, if it exists  (X and SKA ignored)
1   blank line                  (X ignored)
2   indentation = X
3   indentation < X
4   indentation > X
5   line-length = X
6   line-length < X
7   line-length > X
8   1-4 character string X (eg, "x" or "abcd") is in the line
9   1-4 character string X is at start-of-line
10  1-4 character string X is at end-of-line
11  character in range X (eg, "AZ" or "09") is in the line
12  character in range X is at start-of-line
13  character in range X is at end-of-line
14  rgn bounded by quotes or brackets in X (eg, "\"\"" or "[]") is in line
15  rgn bounded by quotes or brackets in X may be in multi-lines


Example:  Set up folding tests for a C program module
<lAmiga-\:
    setFold(0,0,0,0)    .. clear all testing steps
    setFold(1,1,0,1)    .. include blank lines (it keeps only 1 per series)
    setFold(2,15,"{}",0)  .. skip function code inside {}
    ..setFold(3,15,"//",1) .. keep comments bracketed by //
    ..setFold(4,9,"#",1) .. keep lines beginning with #
    setFold(5,2,0,1) .. keep lines with no indentation
>

setGrep(T)
T:  list 10 (text)

Sets the current grep /search/replace/strings according to the contents of T.
The first character in T is taken as the delimiter character.  If a replace
string is included, it must be delimited using the delimiter.  A trailing
delimiter is optional.  The search and replace strings may be up to 63
characters each.  Search strings may contain up to 9 REs (regular strings) in
brackets \(...\).  Search and replace strings may reference matched REs from
the search by using \1...\9.  The replace string may reference the whole
matched search area by using the ampersand, &.  If the search portion of T is
omitted, the previous search string (if any) is kept and only the replace
string is set.
        Example:  //new replace string/
If the replace portion of T is delimited but empty, the replace string (if
any) is cancelled.
        Example:  /new search string//
If no replace string is delimited, the old replace string (if any) is
preserved.
        Example:  /new search string/
If T is blank except for 2 or 3 delimiters (///) or (//), it preserves the
existing search string but cancels the existing replace string.  If T
contains just 1 delimiter (/) it cancels the existing search and replace
strings.  setGrep() returns False if the search or replace string is invalid.
Note:  setGrep() may not detect every possible invalid or nonsensical string;
in part it relies on grep() to deal with them.  (See the discussion of
Regular Expressions.  See grep() and getGrep().)

Example:  setGrep("/my search \(and this\)/my replace \1/")

setLocal(B,V,N)
B:  list 2 (buffer)
V:  list 3 (value)
N:  list 10 (number)

Sets the local value V of buffer B to the value specified in N.  It returns
False, if B does not exist, if N<=0 or N>32767 when V is lineLength or
pageLines, if N<0 or N>4 when V is tabTable, if N<0 or N>3 when V is Lace, or
if N<0 or N>255 when V is leftMargin, topMargin, bottomMargin.  (Note:  If
N=0 for pageLines, it is set to 1.  When pageLines is 1, there are no pages
or "forms"; this is helpful to programmers who want page-row-column
displaying to display line number, not page & line.)  COLOR:  The 8 local
colors in N must be in 8 bit masks, 4 bits to each mask.  Each 4 bits is 2
pairs of 2 bits, each with values 0-3 corresponding to the Fg and Bg colors,
respectively.  The 4-bit masks correspond (from left to right) to normal
text, cursor, hilite, cursor + hilite, invert, invert + cursor, hilite +
invert, and cursor + hilite + invert.  NOTE:  There is an internal local-
color variable that is used to set the colors of newly created buffers;
setLocal() and getLocal() do not touch this variable.  To access this color
variable, you must use getColors() or setColors() using a literal "" as the
first argument.  (See getLocal(), setColors() and getColors().  See toggle()
and flipFlag().  See the color tables in the Config! defaults.)

Example:  setLocal(curFile,lineLength,200)   .. set local lineLength to 200.
setLocal(curFile,lace,1)   .. use 1 bit-plane, non-interlace screen.

setMaxFiles(N)
N:  list 10 (integer)

Sets the internal variable MaxFiles to N, which determines how many Uedit
buffers are to be used as file buffers.  MaxFiles may be 1 to 100.  It
returns False, if N<0 or N>100.  (See getMaxFiles().)

setRGB(R0,R1,R2,R3)
R0,R1,R2,R3:  list 10

Sets the RGB color register values.  The color values (0-15) are stored in
the lowest 3 nibbles of each R argument.  Use this function for instant
changes of RGB, like when you switch to/from interlace.  The example below
sets the RGB colors to the defaults that are in Config!.  In the example,
0xc60 which is for register 0 sets Red to 12, Green to 6, and Blue to 0.

Example:  setRGB(0xc60,0x0,0xfa0,0xaaa)

setRuler

Displays curFile's tab ruler, based on its tabTable value (0 to 4), and
allows you to set the tab stops using mouse and keys.  Clicking the mouse on
the ruler puts in a tab stop, if none is there; it removes a tab stop, if one
is there.  The Tab key installs new tab stops using the spacing of the first
stop.  The Space bar shifts all stops to the right; the BackSpace key shifts
all stops to the left.  The Del key erases all stops.  The last tab stop in
the ruler is marked with an X.  The highest tab stop allowed is column 255.
There may be up to 32 tab stops.  To scroll the ruler, hold down the left
mouse button and drag the mouse to the right or left.  Typing any
inapplicable key or clicking the mouse 3 or more lines away from the ruler
terminates setRuler and preserves the new tab stops.  Pressing Amiga-ESC
aborts setRuler, restoring the original tab stops.  (See seeRuler and
getTabs().)

Display Action:  Refreshes display, when it terminates.

setSearch(B)
B:  list 10 (text)

Sets the search string using the text in B.  It returns False, if B is empty.
There may be 2 search strings delimited by the eitherOr delimiter and an "all
but" string delimited by the allBut delimiter.  Each string may be up to 64
characters long, but all 3 strings together may not exceed 127 characters.
Search strings and the "all but" string may use the wildcards, wildCard and
multiWild.  The treatment of wildcards in the search is determined by the
values of singleWhite and multiWhite.  (See search() and getSearch().)

Example:  if (inputString(buf49)) setSearch(buf49)

setTaskPri(P)
P:  list 10 (number)

Changes Uedit's task priority to P.  (See the config defaults for task
priority settings for Uedit and for tiny window.  See the tinyPriority CL
variable in the variable lists.  It sets the priority when switching to tiny
window.)

sortLines(B,C)
B: list 2 (buffer)
C: list 10 (number)

sorts the lines in buffer B alphabetically.  If case-sensitivity C is 0, case
sensitivity is not used in the sort.  If C is not 0, case sensitivity is used.

spacesToTabs(B)
B: list 2

Converts spaces in buffer B to tab characters where appropriate.  It returns
False, if buffer B is read-only.  While working, the message "Space->Tab" is
displayed.  If smartTabs is False (see Config! defaults), spaces inside quote
marks are converted to tabs also; if smartTabs is True, spaces inside quote
marks are not converted.  (See tabsToSpaces.)

Display Action:  Centers cursor and refreshes window, if Tabs are put in.

speak(B)
B:  list 10 (text)

Speaks the contents of B.  speak() returns False, if B is empty or if the
SPEAK: device is not mounted.  (Note that using the speakMsgs and speakAlerts
flags, messages and requesters as well as text may be spoken in Uedit.  This
has made Uedit of interest to the blind, while Uedit's reconfigurability has
made it of interest to the physically handicapped.)

Example:  speak("Okay, I am ready now")

spell(B1,B2,B3)
B1,B3:  list 0 (buffer or "")
B2:     list 2 (buffer)

The normal return for spell() is False; this indicates a bad word was found.
It also returns False if B2, the buffer being spell checked, does not exist
or if the speller is not up.  If spell() returns True, it has reached eof.
It checks from the cursor forward in B2, stopping when a bad word is found.
If B1 is a buffer and the spelling dictionary is resident in memory, optional
spellings are put into B1.  If B1 is "", spell() simply returns False when it
finds a bad word.  (See the commands in Config!S.)  When B1 is "" (no
optional spellings), spell() may be aborted with Amiga-ESC.  When B1 is a
buffer (to collect optional spellings), the lookup of spelling options may be
stopped early on by giving an input; the options accumulate in the message
line as they are found, and thus when you see the option you want you can
click it with the mouse and no further options are sought.  If B3 is a
buffer, it is used as a supplemental dictionary; the words in it should be on
separate lines and in alphabetical order.  If B3 is "", no supplement is
used.  (See spellerUp, startSpell() and stopSpell.  See sortLines().)

Cursor Action:  Advances cursor until it finds a bad word or eof.

Display Action:  If B=curFile, refreshes cursor; if offscreen, centers cursor.

Example:
    if (not spellerUp) return
    while (not spell(buf54,curFile,"")) runKey(virtual-z) .. replace bad words

spellerUp

Tests to see whether the spell-checking dictionary table is memory resident,
indicating that Uedit is ready for spell-checking.  It returns False, if it
is not.  (See spell(), startSpell(), and stopSpell.)

Example:  if (not spellerUp) { putMsg("Speller not up") returnFalse }

splitWindow(B,N)
B:  list 2 (buffer)
N:  list 10 (integer)

Creates or removes a split window for buffer B.  If N < 2, it removes B's
split window.  If N >= 2, it creates a split window for B with N lines in it;
the newly created split window becomes the active window and B becomes
curFile.  When creating a split window:  it returns False, if there are
already 8 split windows, or if there are not enough lines to create a window
N lines in size.  When removing a split window:  It returns False, if you try
to remove a split window for B but none exists for B.  When a split window is
created, it is displayed using B's current sPage location.  (Note:  An
integer variable splitSize is provided for convenience, but splitWindow()
does not look at splitSize unless splitSize is used as the N argument.)  (See
getSplitLines() and gotoSplit().  See toggle().)

Display Action:  Displays B as curFile, if a split window is created.
Refreshes all split windows and title bar.

Example:  splitWindow(buf37,5) ..make a 5-line window for buf37.

stackBuf(B,F)
B: list 10 (buffer)

Optionally causes work buffer B to be saved on the buffer B stack instead of
being freed when freeBuf() is called or some other operation would cause
buffer B to be freed.  This option enables you to keep a buffer "history", so
that previously used search strings or copied hilite regions, for instance,
can be recovered.  stackBuf() applies only to work buffers, not to file
buffers.  If F=N, where N>0 and N<=32768, it causes buffer B to be stored on
the buffer B stack.  Up to N buffers can be stored in this way.  Once the
stack is holding N buffers, the oldest (first in) is removed before another
buffer is put onto the stack.  If F=0, buffer B is no longer saved on the
stack automatically when it is freed.  If F=-1, buffer stack B is cleared;
all buffers on stack B are freed.  If F=-2, the current flag status is
returned; if F=0 is returned, it means that buffers aren't being stacked; if
F=N is returned, where N>0, it means that up to N buffers are being stacked.
Note:  Use getStackSize() in order to get the number of buffers currently on
the buffer B stack.  Note:  For any work buffer, buffer-saving may or may not
be in effect.  You can find out its status by using flag=-2.  Suppose you
wish to free buf45 (for real).  You don't know whether buf45 is being saved
on the stack or not.  Use this example procedure:
    equateNum(n54,-2)                   .. use flag=-2 to find out the status
    if (stackBuf(buf45,n54))            .. if buffer-saving is in effect
        stackBuf(buf45,0)               .. turn off buffer-saving temporarily
    freeBuf(buf45)    .. now you can free it FOR REAL, not saving it on stack
    stackBuf(buf45,n54)                       .. restore buffer-saving status

startSpell(T,D,F)
T,D:  list 10 (text)
F:  list 10 (integer)

Loads in the spelling table file T and and either loads in or opens the
working dictionary file D.  If flag F is 0, it accesses working dictionary D
on disk.  If flag F is non-zero, it tries to load working dictionary D into
memory for faster spell-checking; if unable to load D into memory, it uses
the working dictionary D on disk.  It returns False, if the speller is
already up, if T or D is blank, if it cannot find table T or dictionary D, or
if it cannot find enough memory to store table T in memory.  (See spellerUp,
spell(), and stopSpell.)

Example:  startSpell("udtable","udict",1) ..F = 1, try to load udict into
memory.

stopSpell

Frees the speller's memory and closes the working dictionary file, if it is
open.  It returns False, if the speller is not up.

stringComp(N,S1,S2,F)
N:  list 10 (integer)
S1,S2:  list 10 (text)
F:  list 10 (integer)

Compares strings S1 and S2 using flag F and reports the result in N.  If flag
F is non-zero, it ignores upper/lower case in the comparison.  If flag F is
0, upper and lower case are meaningful.  If the strings are equal, result N
is 0.  If N > 0 is reported, string S1 > S2.  If N < 0, string S1 < S2.  The
strings S1 and S2 may be up to 127 characters long; if longer than 127 bytes,
the strings are truncated.  stringComp() returns False, if either the strings
don't match or a string (S1 or S2) is empty or does not exist.

Example:  if (stringComp(n54,buf48,buf49,1)) putMsg("strings are equal")

sub(A,B,C)
A,B,C:  list 10 (integer)

A = B - C.  (See add(), mul(), div(), mod(), and(), and or().)

subMenu(D,A,N,C)
D,A:  literal
N,C:  list 10 (integer)

Creates a submenu item.  Description D and alternate text A must be a literal
in quotes up to 17 characters in length.  N is the menu # (1 to 7) that owns
the submenu.  C is the command-key, which must be a valid key argument or a
macro number, 1 to 1148.  It returns False, if the menu for this subitem has
not been defined yet, if N or C is out of range, if no memory is available,
if there are already 12 submenu items for the current menu item, or if the
command for C does not exist.  subMenu() may only be used in the Startup
command.  (See menu(), checkedMenu(), and checkedSubMenu().  See Config! for
examples.)

swapBuf(B1,B2)
B1,B2:  list 2 (buffer)

Swaps buffers B1 and B2.  It returns False, if B1=B2.  If either buffer is
curFile, the other buffer becomes curFile.  Only the buffer numbers are
swapped; the buffer flags and contents are unaltered.

Display Action:  Refreshes any split window that contains B1 or B2.

Example:  swapBuf(curFile,buf41)

swapChar(B,C)
B:  list 2 (buffer)
C:  list 9 (character or integer)

Replaces the character at the cursor in buffer B with the character C.  It
returns False, if B does not exist, if B is read-only, if the cursor is at
eof, or if C is an illegal character (ASCII 0 to 3) and the mapChars flag is
not On for buffer B.  If C is illegal and mapChars is On, the illegal
character is mapped into the legal character given in the table in the config
defaults.  swapChar() is faster and more efficient than typeChar() or
insertChar(), so it should be used preferentially.  swapChar() does not
advance the cursor.  (See insertChar(), clearChar(), copyChar(), and
typeChar().)

Display Action:  Refreshes B's window, if any and not curFile.  If B=curFile,
refreshes cursor; if offscreen, centers cursor.

swapKey(K1,K2)
K1,K2:  list 10 (integer)

Swaps the commands of keys K1 and K2.  K1 and K2 must be valid key arguments
or macro numbers in the range from 1 to 1148.  swapKey() returns False, if K1
or K2 is out of range, if K1=k2, or if neither key has an existing command.
If either key is the Startup command, the menus are removed so that they will
be rebuilt using the new Startup command during the next pause.  (See
Swapping Keys Permanently, 2.9.  See killKey() and copyKey().)

Example:  swapKey(normal-f1,shft-f1)

swapLoc(B,L1,L2)
B:      list 2
L1,L2:  list 7

Swaps locations L1 and L2 in buffer B.  Returns False if buffer B does not
exist.

Example:  swapLoc(curFile,sHilite,eHilite)

tabsToSpaces(B)
B: list 2

Converts all Tabs in buffer B to the appropriate number of spaces, based on
buffer B's tab ruler.  It returns False, if buffer B is read-only.  During
the conversion, the message "Tab->Space" is displayed.  If smartTabs is True
(see Config! defaults), tabs inside quotes are not converted; if smartTabs is
False, tabs inside quotes are converted.  (See spacesToTabs.)

Display Action:  If any tabs converted and cursor offscreen, it centers
cursor.

teachOne(K)
K:  list 10 (integer)

Displays the Teach Keys message for the key K.  K must be a valid key
argument or a macro number in the range 1 to 1148.  The first time teachOne()
is called (or the first time teachKeys mode is used) the key-help file is
copied to RAM:uejunk.  From then on, teachOne() and teachKeys mode work fast.
The junk file is not deleted from RAM:; getting rid of it is left up to the
user, so that teachKeys and teachOne() will work quickly if used again later
on.  If teachOne() or teachKeys mode cannot find the key-help file, the
message "No key-help file" is displayed.  If the key K has no help message,
the message "No help or unused" is displayed.  flipFlag(curFile,teachKeys)
turns on Teach mode, if a number of keys are to be investigated.  Use Amiga-
ESC to abort Teach mode, when finished using it.  (See flipFlag().  See
Building Key-Help for Teach Keys, 2.11.)

Example:  getKey(n54) teachOne(n54)   .. display the purpose of just one key.
execute("","delete RAM:uejunk")   .. delete the key-help file from RAM.

text(T,R,C,S,F)
T:        list 10 (text)
R,C,S,F:  list 10 (integer)

Displays text T at row R, column C, using color combination S, based on flag
or length F.  It displays text or clears all or part of the screen using the
desired colors without changing the contents of any buffer.  It can display
anywhere in Uedit's screen.  R and C are the text (not pixel) row and column;
if they are -1, text is appended by repeated calls to text().  S is a color
number 0-15.  (See the color tables in the Config! defaults.  Also see
setColors() and getColors().)  F is a flag or length:  If F>0, the text is
displayed and the field cleared to length=F using the specified colors.  If
F=0, the text is displayed only.  When F=-1, the text is displayed and the
display cleared to end of line.  When F=-2, the text is ignored and the
display is cleared to end of screen.  NOTE:  If you do something that updates
the window (other than by using text()), Uedit refreshes the window after a 4
second pause; this limits the lifetime of text displayed with text().  Also
the message line is cleared after a 4 second pause.  To prevent Uedit from
refreshing the window or message line, you may need to include the following
at the end of a command that uses text():
    while (not inputWaiting) delay(5) ..sleep until something is input
Note:  An internal flag prevents the right (menu) mouse button from clearing
the message line after text() or draw() has been used.  The internal flag is
cleared after some other type of displaying action is called for.

Display Action:  As described above.
Examples:  See the About... (SAC-a) and Show Vals (S-help) commands.

thisKey

Returns True, if the command it is in is the primary one - i.e., is running
at level 1.  It returns False, if the command it is in has been called by
some other command.  thisKey is useful in preventing refreshing of the
display when a command is run repeatedly by another command, such as when
running learned sequences or doing automatic searches and replaces.

Example:  if (thisKey) refreshDisplay

toggle(F)
F:  list 14 (flag)

Toggle the thing specified by flag F.  Toggle() always returns True.  TOTINY:
Uedit goes to tiny window during the next pause.  FAVORITE:  It toggles to
the next file buffer whose Favorite flag is turned On, making that buffer
curFile and refreshing the display.  CURFILE:  It toggles to the next file
buffer, making it curFile and refreshing the display.  WINDOWSPLIT:  It
toggles to the next split window, activating it, making it curFile, and
refreshing its display.  LACE:  The lace variable is rotated to the next
value in the range 0 to 3.  The screen is closed and reopened.  If lace=0, a
4 color non-interlace screen (2 bitplanes) is used.  If lace=1, a 2 color
non-interlace screen (1 bitplane) is used.  If lace=2, an interlace 4 color
screen (2 bitplanes) is used.  If lace=3, an interlace 2 color screen (1
bitplane) is used.  TRAPMENUS:  If trapMenus is toggled On, the menu (right)
mouse button becomes the menuDown and menuUp keys.  SCROLLTYPE:  If
scrollType is toggled On, for faster scrolling colored regions aren't colored
during scrolls.  HIDEDISPLAY:  If hideDisplay is toggled On, displaying is
suppressed when running learned sequences or using the command multiplier.
(See setLocal() and flipFlag().)

Display Action:  See discussion above.

Example:  toggle(curFile)   .. switch to next file buffer.

toLower(B)
B:  list 2 (buffer)

Converts the character under the cursor in buffer B to lower case.  It
returns False, if B does not exist, if B is read-only, or if the cursor
character is not an upper-case letter "A" to "Z".  toLower() does not advance
the cursor.

Display Action:  Refreshes B's window, if any and not curFile.  If B=curFile,
refreshes cursor; if offscreen, centers cursor.

Example:  while (toLower(curFile)) moveCursor(curFile,eChar) .. word to lower.

toNumber(N,B)
N:  list 10 (integer)
B:  list 2 (buffer)

Converts the number at the cursor in buffer B into an integer in variable N.
It returns False, if B does not exist or if there is no number under the
cursor.  The cursor must be resting on a left parenthesis "(", a minus sign
"-", or a digit 0 to 9.  Numbers beginning with a left parenthesis or minus
sign are considered to be negative numbers.  The number may be decimal or
hexadecimal.  Hexadecimal numbers must begin with "0x".  toNumber() does not
advance the cursor.

toUpper(B)
B:  list 2 (buffer)

Converts the character under the cursor in buffer B to upper case.  It
returns False, if B does not exist, if B is read-only, or if the cursor
character is not lower-case "a" to "z".  It does not advance the cursor.

Display Action:  Refreshes B's window, if any and not curFile.  If B=curFile,
refreshes cursor; if offscreen, centers cursor.

Example:  while (toUpper(curFile)) moveCursor(curFile,eChar) ..word to upper.

toWord(B,N)
B:  list 2 (buffer)
N:  list 10 (integer)

Types the value of integer N into buffer B at the cursor.  It returns False,
if B is read-only.

Display Action:  Refreshes B's window, if any and not curFile.  If B=curFile,
refreshes cursor; if offscreen, centers cursor.

Example:  toWord(curFile,lineLength) ..type in lineLength at the cursor.

trackMouse

Continuously updates the mouse x-y location as the mouse is moved, as long as
the mouse button (left button, or right button if trapMenus is True) is held
down.  trackMouse is disabled, when running learned sequences or when in
Learn Mode.

Example:
<normal-buttonDown:    .. continuously track cursor as mouse is moved.
    while (not inputWaiting) {   .. this one is fun to watch.
        if (not mouseDown) return
        trackMouse
        moveCursor(curfile,mouseLoc)
        updateDisplay
    } >

typeChar(C)
C:  list 9 (character or integer)

Types character C into curFile at the cursor, just as if it were typed at the
keyboard.  curFile's typing settings for wordWrap, rightJustify, overStrike,
useTabs, autoIndent,

leftMargin, and lineLength are used just as in normal typing.  It returns
False, if curFile is read-only.  If C is an illegal character (ASCII 0 to 3)
and curFile's mapChars flag is On, the character is mapped using the table in
the config defaults.  If mapChars is Off and C is an illegal character,
typeChar() returns False.  (See insertChar() and swapChar().)

Cursor Action:  Cursor behaves just as in typing.

Display Action:  Refreshes cursor.

Example:  typeChar(13) typeChar(10) ..type CR and linefeed.

updateDisplay

Updates the display based on the current bits in the internal displayFlag
variable.  It returns False, if displayFlag is 0.  This is the most efficient
way to update the display.  displayFlag may or may not have bits set.  The
bits depend on what functions were called, what their conditions were, and
the order in which they were called.  Changing the order of the function
calls prior to updateDisplay may improve the results in some cases.

Display Action:  Updates the display based on internal displayFlag.

Example:  while (moveCursor(curFile,eWord)) updateDisplay

upFlag(B,F)
B:  list 2 (buffer)
F:  list 14 (flag)

Sets to True the value of flag F for buffer B.  (See the notes for
flipFlag().)  If flag F is a local (buffer) flag and buffer B does not exist,
it returns False.  If F is a global flag, B is ignored.  If the flag's value
is non-zero, a False is returned.  If the flag is zero, a True is returned.

Example:  if (upFlag(curFile,columnar)) alertUser("Turned on col display
mode")

vScroll(H)
H:  list 5 (How)

Scrolls curFile's display vertically based on H.  The display scrolling
occurs during the next pause based on the displayFlag bits and sPage.  It
returns False, if sPage does not change as a result of vScroll().  upLine and
downLine cause blitter scrolling; other arguments cause curFile's window to
be refreshed using the new sPage.  If scrollType is False, colored regions
are colored during the scroll; if scrollType is True, scrolling is somewhat
faster because regions aren't colored during the scroll.  (See hScroll().)

Example:
while (vScroll(downLine)) updateDisplay .. scroll visibly to end-of-file.

xor(A,B,C)
A,B,C: list 10 (numbers)

Returns the value A = C ^ B.  xor() returns False, if result A is 0;
otherwise it returns True.