Edit
=======

(WRS: this version not finished, 23-Nov-88: no description of task
windows.)

Edit is a text editor program.

Starting Edit
----------------

Edit must be used within the desktop environment, it cannot be used
on its own. To start up if not within the desktop, use:
  *desktop !Edit <filename>

Edit appears in your directory viewer as a note-pad icon with the
title "!Edit". It is in the root directory of the Welcome disc in this
form. Edit can be started up by double-clicking on this icon. This will
cause a copy of the icon to appear on the icon bar. Clicking on this icon
will make an empty text window appear, into which the user can type.

Double-clicking on any text file icon will also start Edit, or will
simply open a new window if Edit is already loaded. Also, a file of any
other type can be edited by dragging its icon from a directory viewer onto
the Edit icon on the icon bar. This is useful for editing command
scripts.

Double-clicking on a file which Edit already has loaded (but which has
not been edited) will merely pop the existing window to the top. The
exception to this is that Edit checks the datestamp of the file, and if
the file has been udpated since it was loaded into Edit (and not updated
within Edit), the existing window is reloaded with the new contents of
the file.

Edit requires 196K when loading, and grabs more from the Wimp as documents
are loaded into it. If documents are discarded, memory is given back to
the Wimp.

Edit requires that the "C shared library" module be loaded when it
starts. This is provided by the !System application, which must be visible
when Edit is started up. This allows the program to share a large amount
of code with other applications written in C. When Edit is unloaded this
shared library remains, to remove it you must go to the command line and
type *RMKill SharedCLibrary.

Edit ennumerates the available fonts when it is started up. In the default
system, this may cause a request to insert the Welcome disc (because the
default Font$Prefix is ADFS::Welcome.Fonts). A "cancel" at this request will
simply result in no anti-aliased fonts being available.

The default options used to display text windows in Edit can be specified
in the environment variable Edit$Options:
  f<number> -> specify Foreground colour
  b<number> -> specify Background colour
  w<number> -> specify font Width
  h<number> -> specify font Height
  m<number> -> specify right margin in pixels
  l<number> -> specify extra line spacing in pixels (may be negative)
  R -> specify wRap at window edge
  N<rest of string> -> specify foNt name
Experiment within Edit in order to find your favourite settings.

Text Windows
------------

Text is displayed in windows on the screen, using either the system font or a
variable-width one. The window title is:

  The file name associated with this window, or <untitled> if none.
  A "*" if the window has been modified since last being saved/loaded.
  A digit if there is more than one window on the same document,
    showing the number of windows currently open on this document.

The caret appears at the type-in point, and a selected range of text is
indicated using inverse video.

Note that a file cannot contain characters of different fonts.

The vertical scrolling bar on a text window is slightly unusual, in that
it displays the fraction of the file visible expressed as a fraction
of the total number of characters in the file, rather than as a fraction
of a visible image. This may result in the indicated size of the visible
part of the document changing as scrolling proceeds.

Screen Modes
------------

Edit works in any screen mode.

Keyboard Commands
-----------------

Typing at the keyboard causes the characters typed to be inserted at
the caret. Control characters in the text are displayed as the hex
value of the character, within square brackets.

In addition to this, the following keys provide speicific editing functions.

Arrow keys:

   Arrowkey,          One character left, right, up, down.

   Shift + Arrow key, One word left, right and one page up, down.

   Control + Arrow key,
                       End of line, start of line, start of file, end of file.

   Shift + Control + up or down,
                       scroll the viewing window without moving the caret.

Function keys:

   F1                  Shell command. A wimp task is created (with memory
                       as specified by the "next" bar in the Switcher display)
                       and a CLI prompt given, at which standard Arthur CLI
                       commands can be typed. Just pressing return returns
                       you to the desktop world.

   F2                  Edit a new file. Load/Create a file in a new window. A 
                       dialog box will prompt for a filename.

   Shift + F2          Insert file. Load and inserts a file at the caret 
                       position. A dialog box will prompt for a filename.
                       If the window is empty before the insertion, the window
                       assumes the filename of the inserted file.

                       A similar effect is gained by dragging the icon for
                       any file from a directory viewer into a text window.

   F3                  Save as. Save file in currently selected input window. A
                       dialog box will display current file name, and an
                       icon which can be dragged to a directory viewer.
                       A dialog box appears showing an icon for the file,
                       and the current filename associated with the window.
                         Possible responses:
                           type -> alter the given name
                           RETURN or click OK -> save with specified name
                           ESCAPE or close -> cancel operation
                           drag icon to Finder viewer ->
                             save with given leaf name, in given directory.

   F4
     Find command. Displays a dialog box and prompts for text
     to be found and replacement string. Possible responses:
       ESCAPE or close -> cancel operation.
       type -> enter string to find
       RETURN -> specify replace string
       up/down arrows -> find/replace entry
       RETURN or F1 click on GO -> perform find
       F2 or click on Previous ->
         install find/replace strings from previous search.
       F3 or click on Count ->
         count occurrences of the find string, starting
         at the caret within the document.
       F4 or click on Case Sensitive ->
         toggle case-sensitivity of searches. This is
         preserved between searches.
       F5 or click on Magic ->
         enable escape sequences in find/replace strings.
         This is preserved between searches.
           Possible escape sequences:
             \* = any string
             \a = any letter or digit
             \d = any digit
             \. = any char
             \n = newline
             \\ = \
             \cX = control-X (for any char X)
             \xXX = character specified in hex
                    (for two hex digits XX)
             \& (in replace string) = found string
             F4 or click on NoCase -> toggle case sensitivity
             F5 or click on Count ->
               search the rest of the file, and count
               occurrences of the search string.
      When a string has been found, the selection is set to the
      found string and a new dialog box appears. Possible responses:
        ESCAPE or RETURN or S click on close -> stop
        C or click on Continue -> look for next occurrence
        R or click on Replace -> replace string and Continue
        L or click on Last Replace -> replace and stop
        E or click on End of file Replace -> replace all (global)
        U or click on Undo -> undo last search/replace step
        D or clikc on reDo -> redo last undone search/replace step
      The dialog boxes make all of these choices and options clear,
      so that there is no need to remember them by heart.

   Shift + F4          Exit editor. Prompts for confirmation.

   Control + F4        Indent text. If a block of text has been selected, a 
                       dialog box prompts for the number of spaces in indent by.

   F5                  Goto command. Displays a dialog box showing present line
                       and character number. Possible responses:
                         ESCAPE or click on close -> do nothing
                         type -> set line to go to
                         RETURN -> go to specified line

   F6                  If there is no selection, set the selection to be the
                       character directly after the caret. If there is a
                       selection, adjust its nearest end to the position
                       of the caret.
   Shift + F6          Clear the selection.

   Control + F6        Format the text from the caret on to about 78 columns,
                       until the next blank line or line starting with a
                       puctuation character. F8 is useful if this is invoked
                       by accident.

   F7                  Copy the selection to the caret.

   Shift + F7          Move the selection to the caret.

   F8                  Undo command. Undoes insertions and deletions
                       of the text, movements of the caret, and setting/
                       clearing of the selection. Multiple operations
                       (including undos) can be undone.

   F9                  Redo command. Redoes the last undone edit.

   Control + F8        Toggle CR and LF.

   Control + Shift + 1 Expand tabs.


Control keys:

   Control + Z         Clear selection.

   Control + X         Delete selection.

   Control + C         Copy selection to caret. May be in a different window.

   Control + V         Move selection to caret. May be in a different window. 

   Control + Copy      Delete line at caret.


Tab:
   Move caret under the start of words on the preceding line.

Delete and backspace keys:
   Delete character at caret position.

Escape:
   Remove menu or dialog box.

Mouse functions
---------------

SELECT:

  Clicked once selects section of text from caret to mouse pointer.
  Clicked twice selects section of text from caret to
    the end of the word covered by pointer.
  Clicked three selects section of text from caret to
    the end of the line covered by pointer.
  Drgged after any of the above, continuously resets the caret or
    selection.

MENU:

  Calls up the main menu (see below)

ADJUST:

  Pressed once moves the text caret (input focus) to 
    mouse pointers position, may be in a different window.
  Pressed twice selects a word at pointers position.
  Pressed three times selects a line at pointers position.
  Held down after any of the above the selection or caret
    follows the mouse pointer.

Main text menu
--------------

Entries in Edit's main menu are as follows. In all cases, a left-click
will select the entry and cancel the menu while a right-click will select
the entry and retain the menu.

Misc: a submenu of miscellaneous functions:
      Info: version information about Edit.
      File: type/pathname/datestamp information about this file.
      New view of same file:
                       Create a new view of the current file. The current
                       window is split vertically into two, to create
                       two different windows on the same text file.
                       Changes in either are reflected immediately in
                       the other.

Save: save the entire file. Same as F3.

Select: a submenu of operations that apply to the selection:
        save: As F3, but only applies to the selection.
        copy: same as control-C.
        move: same as control-V.
        delete: same as control-X.
        clear: same as control-Z.
        save: same as the Save Selection menu entry.
        indent: same as control-F4.

Edit: a submenu of miscellaneous editing commands:
      goto: same as F0.
      find: same as F4.
      undo: same as F8. Right-click to undo several.
      redo: same as F9. Right-click to redo several.
      CR<->LF: swap line feeds and carriage returns in the file.
               The resulting file, if one long line of text, can take
               a substantial time to display.
      expand tabs: expand literal tab characters in the file.
      format text: same as control-F6.
        there is also a width field as a submenu of this, to
        control the formatting operation.

Option: a submenu of display options for this window.
        font: set the display font. A further submenu appears,
              providing "system font" and all fonts detected by the
              font manager (via Font$Path) when the editor was started
              up. Choosing one of these will cause the relevant font to
              be used for displaying the text.
        font size:
              This sets the point size of an anti-aliased font used
              for displaying the text. A small selection of typical
              sizes is provided in a submenu. The final entry of the
              submenu is writable, so any point-size can be typed in.
        font height:
              The height of the font can be set independent of its width.
              This allows extra-tall or thin characters to be used.
        invert:
              Swap the foreground and background colours within the window.
              Some people prefer editing white-on-black text, for instance.
        wrap:
              This toggles the wrap state of the window. The default state
              is to wrap long text lines at the width of the screen.
              The alternative state is to wrap them at the width of the
              window.
        foreground:
              Set the foreground colour in which the system font is displayed.
              A submenu of sixteen possible values is provided.
        background:
              Set the background colour on which the system font is
              displayed. A submenu of sixteen possible values is provided.


The icon menu
-------------
... not finished ...
