OS/2 Shareware BBS: 5 Edit/05-Edit.zip/sedit281.zip/editor.doc

Text File | 1996-10-05 | 32KB | 648 lines

Introduction
 The sedit editor is a fully featured professional text and binary editor. The
 editor is modeled after the E PC editor. This editor is however a functional
 superset of E with many useful additional features (except that there is no
 REXX support). The OS/2 EPM editor is another editor with the same ancestors.
 Users of E or EPM will quickly feel at home with this editor since basic
 operation is quite similar.

Documentation
 This file is the ASCII text version of the editor documentation and is the
 most general format but the ugliest looking. A Postscript version of the
 documentation is the file editdoc.ps and the Latex source and DVI files are
 *.tex and *.dvi respectively.

Highlights
 Highlights of this editor are as follows:

 Complete OS/2 PM applications with all editor commands available either from
 drop down menus or by using CTRL and ALT key combinations. Appearance and
 operation of this editor are highly configurable.

 Edits text files of arbitrary size and line length.

 Edits binary files in either hex or in a special alphanumeric coded form that
 allows easy identification of strings in a binary file.

 Unlimited undo of previous changes and corresponding step for step redo. Lines
 can be restored to their previous state even if subsequent edits on other
 lines have been made that are to be kept.

 Column editing features to allow movement of columns of text. This allows easy
 change of indentation for example and is extremely useful for manipulating
 columns of numbers. Columns can be moved, copied, deleted, overlaid and
 filled.

 Bracket matching of all sorts of brackets and C code comment delimiters.

 Single key left justification of moved code blocks with first non-blank line
 above.

 Run programs such as dir, grep or compilers from the command line. These may
 optionally run as a separate thread so you can continue to edit while they run
 or synchronously for predictable behaviour in a macro. Output from programs
 started from the command line is piped into another file in the ring of loaded
 files. Files can be loaded from these read only output files by double
 clicking on any file names with a trailing number, if any, interpreted as a
 line number.

 Programming support. Run compilers from the command line and jump to file and
 line containing the error by double clicking on the file name. Opens on-line
 programming reference information by double clicking on key words.

 There is full folding support with 6 different fold mechanisms. Four of these
 are toggles which displays either only the lines starting in the first column,
 only the changed lines, only lines containing a place mark or only the lines
 containing the last search string. The remaining two are incremental and
 selectively hide or display portions of the text. One of these is indentation
 based and the other requires fold tags embedded in a comment in the file.

 Changed lines optionally appear in a different colour from the unchanged text.

 A whole ring of files can be loaded up at once allowing painless copying of
 text between files. One particularly nice feature is the ability to load up a
 set of files in a ring and rapidly cycle through them using then CTRL N and
 CTRL P key combinations. Text can be copied between these files by using the
 block and line mark commands.

 This editor has very few built in hard coded limits. The number of files
 simultaneously loaded is limited only by available memory. The number of lines
 in a file or the length of a line is also limited only to the size of
 available memory or the size of a 4 byte integer whichever is smaller.

 The editor has very powerful search options which allow searching with any of
 the following modifiers singly or combined. Search up, Search marked block
 only, Ignore case, whole word only, loop through all loaded files or interpret
 as regular expression. For search and replace a dialog allows the following;
 replace, skip, replace all, quit, undo last replace, and redo last skipped.

 There are all also some features to facilitate carrying out complex repetitive
 editing tasks. In particular sequences of key strokes can be saved and
 assigned to a function key for subsequent reuse. Furthermore, any command
 including function key macros can be repeated a number of times automatically
 by entering a command multiplier. Bound macros are saved between editing
 sessions.

 The editor is completely key configurable. A set of keystrokes can be mapped
 to an editor function simply by specifying the sequence in the auxiliary key
 map file. The combination of key mapping and key macros allow the editor to
 imitate the user interface of other editors or allow the construction of a
 custom user interface to the taste of the user.


Control keys
 The editor is extremely easy to use and largely self explanatory. Text is
 input by straight typing anywhere on the screen. Cursor movement is controlled
 by the arrow keys and auxiliary keypad keys as per their standard definitions
 as well as accelerated movement with CTRL combinations. The cursor can also be
 positioned using the mouse by clicking with the left button at the desired
 cursor location. The cursor position control keys are as follows:


Cursor Motion Keys

    left arrow      left one space
    right arrow     right one space
    up arrow        up one line
    down arrow      down one line
    end             end of line
    home            beginning of line
    PgDn            scroll down one screen
    PgUp            scroll up one screen
    Center Key      fast motion toggle
    CTRL left       left one word
    CTRL right      right one word
    CTRL up         scroll up five lines
    CTRL down       scroll down five lines
    CTRL end        end of file
    CTRL PgDn       end of file
    CTRL home       beginning of file
    CTRL PgUp       beginning of file
    ALT home        top of page
    ALT end         bottom of page
    ALT PgUp        scroll up half a page
    ALT PgDn        scroll down half a page




Editor Control Keys

    CTRL A     set place mark
    CTRL B     bracket match {, (, [, <, or /*
    CTRL C     change case of character under cursor
    CTRL D     delete character
    DEL        delete character
    CTRL E     delete to end of line
    CTRL F     find next occurance of search string
    CTRL H     destructive backspace
    CTRL I     tab
    CTRL J     join next line to current line
    CTRL K     cut current line at cursor
    CTRL L     return to previous set place mark
    CTRL M     insert new line (also return key)
    CTRL N     edit next file in ring
    CTRL 0     switch to other window if screen split
    CTRL P     edit previous file in ring
    CTRL Q     quit without saving file
    CTRL R     redo previous undo
    CTRL S     swap current and next character
    CTRL T     toggle insert/replace
    CTRL U     undo changes to last modified line
    CTRL V     view only lines starting in 1st column
    CTRL W     write file to disk
    CTRL X     delete line
    CTRL Y     split edit window horizontally in two
    CTRL BACK    delete line
    CTRL Z     zap word
    CTRL DEL   zap word
    ALT A      alternate binary representation
    ALT E      execute last macro
    ALT H      view only lines with placemark
    ALT I      clear all placemarks
    ALT K      enter next char literally
    ALT P      position curs at previous location
    ALT Q      restore a line from undo record
    ALT R      re-flow paragraph, stops at blank line
    ALT S      view lines containing search string
    ALT T      teach (end) new macro
    ALT V      view only changed lines
    ALT X      enter control character
    ALT Z      zero command multiplier
    ALT 0-9    enter command multiplier



 The following section provides more detailed information for a selection
 of the above commands that are perhaps not inherently obvious.



 The CTRL A command sets a place mark on the current line in the current file.
 Any number of place marks can be set. Hitting CTRL L will return the
 cursor to these place marks in the reverse order that they where set. To
 remove a place mark hit CTRL A again on the line with the place mark and it
 will be removed. ALT I removes all currently set placemarks and ALT H shows
 only lines on which a placemark has been set.


 The bracket match command CTRL B moves the cursor to the bracket matching the
 one under the cursor. If the cursor does not move it means that a
 matching bracket could not be found or that the cursor is not presently
 sitting on a bracket. The matchable characters are <, >, (, ), {, }, [, ]

 and the C style comment delimiter pairs /* and */.

 CTRL C changes the case of the letter under the cursor. If the case of a
 whole region is to be changed. Block mark the region (ALT B) and then use
 the change case option of the block fill command (ALT F).


 CTRL F finds the next occurance of the search string. The first occurance
 must be found be going to the command line with ESC and entering the
 desired search string after a '/' as in "/string". The search string can
 also be set using the search dialog from the menu bar. In the OS/2 version
 shift CTRL F changes direction and then find the previous occurance of the
 search string.


 CTRL J, K, M. Unlike most editors hitting return ( CTRL M ) does not split the
 current line at the cursor. Instead a line is split at the cursor using CTRL
 K. This usage may take some getting use to but it is the same as used by the
 editor E and optionally by the EPM editor. If, however, you prefer more
 conventional return key behaviour this can be set in the configuration menu.
 CTRL J is used to join two lines together. Return or CTRL M inserts a new
 blank line below the current line but the current line is not split.
 Conventional return key behaviour may optionally be selected in the
 configuration menu.


 CTRL N, P. If more than one file is currently in memory then CTRL N
 switches to the next one in the ring while CTRL P switches to the
 previous file. If the switched to file has been modified since it was
 last seen you will be prompted for an optional reload.


 CTRL Q. Quits the current file which will be removed from memory and all
 changes will be lost. If changes have been made and the file has not been
 saved then you will be prompted for confirmation. It is possible to
 configure the editor to prompt for a confirmation of over writing an old
 version of the file.


 CTRL U, R. Undo the change to the last edited line. The number of undo
 levels is set in the configuration dialog and is essentially unlimited.
 By repeatedly hitting CTRL U all the changes made to a file since it was
 loaded can be undone. CTRL R re-does a previous undo. The changes to a
 file can only be undone in the order that they where made except that any
 line for which a line undo record exists can be restored using ALT Q.
 Only simple edits that only operate on a single line generate
 undo records of the type that can be undone using ALT Q. In some instances
 it may be desirable to turn off the undo record generation for example if
 column manipulations are to be done on very long columns since in that
 case the entire file will have to be duplicated may times for the undo
 records which will adversely affect performance. Undo record generation
 may be turned off by setting the undo limit to zero in the config dialog
 of the file menu.


 CTRL V ALT V ALT S ALT H. These commands toggle folding on and off.
 See  section on folding below.


 CTRL W. Saves the current file to disk using the file name displayed on
 the command line. The file name can be changed by moving to the command
 line ESC and using the rename command. The file can also be saved with a
 different name using the "save as" menu item of the file menu.


 CTRL Y splits the editor window horizontally in to two windows separated
 by a second command line. Hitting CTRL Y again un splits the screen. Use
 CTRL O or the left mouse button to change the current window.


 ALT A selects the alternate binary representation. This key is only
 active for files loaded using the binary switch (-b). The default binary
 representation is hex with two hex characters per byte and 32 bytes per
 line. The alternate representation uses the following codes: Printable
 characters appear with a leading underscore and control characters with a
 leading ^. This second representation also has 32 bytes per line
 and is more useful for identifying text in binary files. Individual hex
 numbers may be converted to decimal or the reverse by using the command
 line commands "hex", "dec" and "asc".


 ALT B,C,D,F,L,M,N,O,U,W,Y are used with marked regions see



 ALT E executes the last defined macro see section on macros.


 ALT I removes all previously set (CTRL A) placemarks.


 ALT K interprets the next character as a literal without re-mapping. This
 key may be useful for enter characters that have been mapped onto editor
 commands. This should not be needed with the default configuration since
 only CTRL and ALT keys are used to control the editor.


 The ALT P command is useful if the cursor was accidentally moved away from
 the region of interest with a CTRL Home or search for example. In these
 situations ALT P will restore the cursor to its previous location. This
 action is similar to using place marks except that unlike place marks these
 are automatically set by any command that causes the cursor to jump by more
 than one line. Only one previous location is remembered though.


 The ALT R command reflows a paragraph with the right and left margins
 and the first line indentation set as specified in the config dialog.
 It starts at the current line and stops at the first encountered blank
 line. Optionally if a region is ALTB marked and the cursor is currently
 in the marked region the marked region only will be reformatted with
 the right and left margins set by the marking and no initial indentation.


 ALT T start and end the definition of a new macro see section on macros.


 ALTH, ALTS, ALTV toggles folding on and off. See discussion for folding below.


 ALT X queries the user for the 3 digit hex code of the character to be
 inserted. ALT X can thus be used to enter characters for which there is
 no keyboard key such as the characters above 127 in the ASCII table.


 ALT 0-9, Z. These keys are used to enter a command multiplier to be used
 on the next command. Entering a multiplier has the same effect as
 entering the following keystroke n times. ALT Z resets the multiplier to zero.


In the OS/2 version of the editor there are also a number of additional defined
control keys.

 ALT - and ALT + fold and unfold the current file to the next fold tag.

 CTRL - and CTRL + fold and unfold the current file to the next tab position.

 ALT * and ALT / finds the next or previous word matching the word currently
 under the cursor respectively. This is equivalent to doing a search for the
 curent word with the /w whole word flag turned on so only whole words matching
 the current word are found. The current search string is not updated however.


 ALT F4. The OS/2 system default close application key removes all loaded files
 and terminates the editor. If there are any changed, unsaved files a
 confirmation dialog appears. Other system menu ALT F* keys perform their usual
 task. These keys are intercepted before reaching the editor and thus cannot be
 used for bound macros.


 CTRL SHFT A. Saves all currently loaded files that have been changed.


 CTRL SHFT F. Changes the current search direction and locates the next search
 string. Thus is the current direction is down then a CTRL SHFT F finds
 previous location of the search string having set the direction to up. If it
 is now desired to continue searching in the up direction use CTRL F.


 Other CTRL SHFT combinations. These predifined key sequences open the
 corresponding dialog as if they had been chosen from the menus.


Folding

 Folding refers to the ability of the editor to selectively hide parts of the
 file in order to give a better overview of the whole file. This may be used
 to rapidly find sections in the text. The folding control keys are as follows:

        Folding Keys

    CTRL V     first column lines only
    ALT V      changed lines only
    ALT S      lines containing search string only
    ALT H      lines containing place mark only
    ALT -      Fold to next lower fold tag
    ALT +      Unfold to next greater fold tag
    CTRL -     Fold to next tab position to left
    CTRL +     Unfold to next tab position to right


 The first 4 of these commands are toggles i.e. hitting CTRL V twice returns
 the file to the unfolded state. Only one type of folding may be active at any
 one time. The file may be fully edited while folded. These commands are useful
 for rapidly finding a section of the file.

 CTRL V causes only lines starting in the first column to be displayed. If the
 text is organized so that only section headings or sub-routine headings start
 in the first column then CTRL V can be used to rapidly locate a section in a
 file. To do this hit CTRL V then move cursor to desired sub-routine heading
 and hit CTRL V to expand again. ALT V and ALT S work similarly except they
 show only changed lines and lines containing the last search string
 respectively. For example in a large case statement the start of any branch
 may be found by doing a search for "case" and then selecting ALT S. This will
 show only lines containing the word "case" on the screen. The cursor may then
 be put on the desired line and the file expanded again. ALT H can be used to
 view only lines on which a place mark has been previously set using CTRLA When
 folded the visible lines may still be edited. See also section on

 The ALT - and ALT + pair are complementary keys and unlike the toggles above
 several levels of this type of folding are possible. To use this folding
 mechanism fold tags must be inserted in the text. By default these are of the
 form // Lnnn where nnn is an integer. This is in the form of a C++ comment
 and can thus be put into source code without perturbing the program. The form
 of the tag string may be edited in the config dialog by changing the fold tag
 regular expression. Note that the fold tags must contain an integer counter as
 part of the tag. The first time ALT - is hit the largest value of all the
 found fold tags is found and the lines between tags of this number and tags
 with smaller numbers are hidden. A subsequent ALT - will decrement the folding
 tag number and hide more lines. Thus multiple levels of folding are possible
 with this mechanism. An ALT + will increment the fold tag number and reveal
 the corresponding hidden lines. A sufficient number of ALT + hits will return
 the file to its unfolded state. This folding mechanism differs from the others
 since the file must be modified to contain the fold tags as special comments
 but it has the flexibility to place fold markers anywhere in the file.

 The CTRL - and CTRL + pair is similar in operation to ALT - ALT + but does not
 use fold tags. Instead on the first CTRL - the greatest number of tab
 indentations (depends on the set tab size) on the current page is determined
 and the file folded to hide all the lines indented this far. A further CTRL -
 decrements this number and hides more lines. CTRL + counter acts a CTRL -.
 This type of folding is useful with structured program code that uses a tab
 indentation to delineate a block. Thus for example the start of both branches
 of an if else block may be seen by hiding the bodies.


Block manipulations

 Block mark and line mark are somewhat different. Use line mark for moving,
 copying or deleting one or more whole lines and block mark for moving,
 copying, deleting, filling or overlaying columns of text. Note also that a
 block marked region can also be moved to the left with CTRL ^ and to the right
 with CTRL _ but the behaviour is different than if the ALT arrow keys are
 used. ALT left and ALT right (or CTRL _ and CTRL ^) are meaningless for line
 marked regions. Block marked regions can furthermore be filled with a
 character, a string or incrementing or decrementing numbers. Marked blocks are
 also used to constrain a search, indicate a target region for column math and
 indicate the desired margins for reflowing a paragraph. ALT N marking is the
 industry standard marking useful for text but not of much use for programming.
 Regions can also be marked by dragging the mouse with one of the three buttons
 down. The type of region mark created depends on the settings in the "config"
 notebook accessed from the "file" menu. Lastly, ALTN type marking can be
 achieved by moving the cursor with the shift key held down.




Block Manipulation Keys

    ALT B      mark column block start, end
    ALT C      copy marked block
    ALT D      delete marked block
    ALT F      fill B marked block with char, change case or inc/dec
    ALT J      justify last copied block to match lines above
    ALT L      mark LINE(s) start, end
    ALT M      move marked block
    ALT O      overlay B marked block
    ALT U      un mark block
    ALT W      write block to `editblck.tmp'
    ALT Y      yank back deleted block
    CTRL _      shift B marked block right
    CTRL ^      shift B marked block left



Macros

 There is also a macro capability for repetitive, complex editing tasks. The
 editor is taught a macro by hitting the ALT T combination. After this all
 subsequent keystrokes are stored as the macro definition until ALT T is hit
 again. There is a 128 keystroke limit on the length of a macro. A macro can
 consist of any keystrokes except ALT T and ALT E. At the end of the macro
 definition the macro can be bound to a function key by hitting the desired
 function key. Available function keys are F1 - F12 as well as shift, alt and
 ctrl F1 - F12. In OS/2 some of these are not available as they are used by the
 system to resize windows etc. and are trapped before they even reach the
 editor. As a special case F10 has been partially activated by defining it as
 an accelerator key in the resources. As a consequence a macro defined for F10
 in the editor.cfg can be executed but no macro can be bound to it from within
 the editor using ALT T. A bound macro is subsequently executed by hitting that
 function key. The predefined macro for that key will of course be lost. The
 last learned macro, whether bound or unbound, can be executed by hitting ALT
 E. If the macro involves a search and another item is not found the rest of
 the macro is not executed. If macros have been bound to function keys they
 will be written to the current configuration file editor.cfg which so that the
 macros will be preserved in between editing sessions. The editor.cfg file as
 received contains a number of predefined macros that emulate the E editor
 usage of the function keys. For example F1 is predefined as help, F2 as save
 (CTRL W), F3 is predefined as quit (CTRL Q) and F4 is save and quit (CTRL W
 CTRL Q). These may of course be over written.

 A repeat factor for a keystroke can also be entered by prefixing the command
 with a multiplier which is input using the ALT number keys. The multiplier can
 be reset to zero during input using ALT Z. This feature also facilitates
 repetitive editing as an operation can be repeated several times. This is
 particularly powerful in conjunction with macros.


Command Line

 Lastly, there are a small number of commands which require typed input on the
 command line. The command line is reached by hitting ESC. This places the
 cursor at the beginning of the command line which is on the last row and
 ordinarily displays some status information. After ESC however text can be
 input here for the following functions:



Command Line Operations (requires text input so terminate line with a return)

     ESC             goto or leave command line

             Change current line
    number        goto line number n
    +number       down n lines
    -number       up n lines

           Change current column offset
    @number       start at column n
    @+number      scroll left n columns
    @-number      scroll right n columns

           Search and Replace.
     find string str (/ actually any punct)
    /str[/-bclr] return
     replace str1 with str2
    c/str1/str2[/-bcl] return

           The optional search suffixes are
    /-            search up (down is default)
    /b            search marked block only
    /c            ignore case
    /l            loop through all files
    /r            interpret as regular expression
    /w            match whole words only

           For regular expression the following symbols have special meaning
    ^ start of line
    $ end of line
    . any character
    \ quote next character
    * match zero or more times
    + match one or more times
    [aei0-9]     match a,e,i and 0 through 9
    [^aei0-9]    match anything but a,e,i and 0 through 9
    (  )         sub expression
    a(ab)*b      matches ab aabb aababb aabababb etc.

           Add other files to ring
    e name1,name2,...[-r]
           The optional edit suffixes are
    -r            read only
    -b            binary mode

     display directory and choose one to edit
             e [*.*]
     activate this help file
             ?
     insert named file at current location
             m name  or merge name
     rename current file to name
             r name  or rename name
     show and modify editor configuration
             cfg or configure
     exit without saving changes
             quit
     fill marked block with result of column math
             col num1 [+-*/] num2
     fill marked block with string
             fill string
     sort lines using field number col as key
             sort col
     convert decimal num to hex
             hex num
     convert hex num to decimal
             dec num
     previous command line entered
             up arrow
     next command line entered
             down arrow
     send command to operating system
             os command
     also any unrecognized string



 There is an important difference between OS system calls initiated using the
 "os" prefix on the command line and those initiated without the "os" prefix.
 The later are run as a separate thread which allows editing to continue while
 the called program runs. The system calls initiated with the "os" prefix
 however do not run as a separate thread. This means that the editor will wait
 until the system call is done before allowing any further editing. This
 behaviour is desirable when a system call is part of a macro since then the
 macro can be made to wait for the results of the system call.

 In order to fill a B marked block with a string be sure that the width of the
 block in characters matches the width of the fill string otherwise the fill
 word will wrap around to the next line or repeat. For filling a marked block
 with the result of column math also be sure to define a sufficiently wide box
 otherwise the results will be truncated.


Configuration Files
 The startup file editor.cfg preserves the values selected from the
 configuration menu item between sessions. You can have multiple editor.cfg
 files in different directories since the current directory is searched before
 using the default editor.cfg stored in the same directory as the executable.
 This is useful since a configuration suitable for text (auto wrap on, auto
 indent off) is not ideal for programming (auto wrap off, auto indent on) thus
 text specific editor.cfg files may be kept in text directories and programming
 specific ones in program directories. The editor.cfg file is plain ASCII and
 can thus be edited with a text editor as an alternative means of changing the
 settings or the macro definitions. If changes have been made to the
 configuration the editor will update the editor.cfg in the directory from
 which it was read. Thus in order to create a custom cfg file for use only
 within one directory copy the default editor.cfg to the current directory
 before starting the editor.

 The macros are defined in plain text and thus in order to accommodate control
 and cursor keys as well each macro keystroke is defined by a pair of letters
 using the following scheme. Starting in the first column of a definition must
 appear the key word or function key identifying the macro. This is followed by
 the macro body. Function keys may not appear in macro bodies. Keystroke and
 are encoded as follows with implied sequences in ASCII order.


    Ordinary characters     prepend with _
    Control Keys            prepend with ^         ^M Return, ^[ esc
    Alt Keys                prepend with %
    Cursor keys             prepend with #          #. Del,  #0 Ins - #9 PgUp
    Ctrl Cursor Keys        prepend with #          #N Del,  #P Ins - #Y PgUp
    Alt Cursor Keys         prepend with #          #n Del,  #p Ins - #y PgUp
    Function Keys           prepend with $          $1 -  $<
    Shift Function Keys     prepend with $          $= - $H


 Consult also the keynames.h file which contains text labels for all these two
 character codes as well as for some codes which do not correspond to keyboard
 keys but might be useful in certain cases. There are also a set of codes
 corresponding to the editor dialogs. By mapping these to key strokes
 accelerator keys may be defined for these dialogs.

 This same key naming scheme is used in the key re-mapping file editkey.map.
 The first entry in a line of the editkey.map file is one or more key codes
 describing a key sequence followed by the code for the un-mapped key name that
 the sequence is to replace. For example the line '^Y ^?' maps CTRL Y onto the
 delete line command. The line `^[ %A' maps "ESC A" onto the ALT A function.
 The example unixkey.map file maps all ALT letter combinations to ESC letter
 sequences and ESC to ESC ESC. This is used in the UNIX dumb terminal version
 since these terminal don't have an ALT key. In order to activate key mapping
 the key_map parameter in the editor.cfg file must be set to 1. If the
 exclusive_map value is also set to 1 then the editor will only respond to
 mapped keys. This thus requires that all keys necessary for basic operation be
 mapped. Note that the key mappings will be reflected in the editor help file
 but not unfortunately, in the accelerator tags of the menu items.