/*
** Module   :READ.ME
** Abstract :
**
** Copyright (C) Sergey I. Yevtushenko
** Log: Fri  20/03/1998     Created
**      Mon  30/03/1998     Updated for v0.2.0d
**      Sat  11/04/1998     Updated for v0.2.0i
**      Tue  28/04/1998     Updated for v0.2.0l
**      Sat  09/01/1999     Updated for v0.2.0p
*/
                    Fast Editor Lite v0.2.0r for OS/2

What is FED?
    FED is my small text mode editor. Small but powerful enough to be used
    as my everyday editor. Features of FED includes:
    - Unlimited files open
    - Full UNDO
    - Syntax hiliting for C++/REXX/HTML/ASM/Makefile
    - CUA style blocks
    - Rectangular blocks
    - Goto line/column
    - Indent / unindent
    - Auto indent/smart C++ indent
    - Find/replace
    - Conversion to upper/lower case characters/blocks with NLS support
    - REGEXP find
    - Bracket matching for ()/{}/[]/<> bracket pairs
    - Flexible key assignment
    - Transparent with PM clipboard (only windowed sessions)
    - Block sort of rectangular blocks with NLS collate support
    - Flexible status line format
    - Keyboard macro recorder/player
    - REXX macro support
    - Up to 10 bookmarks per file
    - Saving last cursor position and bookmarks in Extended Attributes
    - Unix/DOS file formats supported
    - Up to 10 user accessible JumpLists supported
    - kbInit/kbDone pseudo keys

Introduction.
    I have started FAST Editor Lite project in April 1997.
    Lack of time does not allows me to do it in more or less regular way.
    So, I'm add feature from time to time (as soon as lack of feature
    becomes annoing), or fix a bug or two (as soon as I found it).

    Primary goal of project was make replacement for QEdit which was
    my main editor for about five years. Of course I have not want to
    do exact copy of QEdit, because I have not use all features of
    QEdit and some features was missing.
    Between missing features two was most important for me: syntax hiliting
    and full undo. And one feature of QEdit I have not want to loose: speed.
    So, first step was writing fast editing engine with syntax hiliting.
    And this took about half of time of development. Rest was much more
    easlier. The goal was reached in January of 1998, and I have started using
    FED as my every day editor. Of course, I have found and fix many
    bugs, but none of them was in design of editor. When I decide
    to make editor available for other peoples, I have add some features which
    useless for me, and which, therefore, may be less tested than editor itself.
    First public beta show needs in few other features which was implemented in
    0.2.0 series.

    Starting from version 0.2.0s so called 'Jump Lists' is supported.
    What is JumpList? This is a list of <file, row, col, comment> elements,
    which can be filled from Rexx script assigned to key and later invoked
    by another (or the same) key. Most useful features of IDE can be
    implemented using JumpList. Sample FED.INI file contain example of
    filling one of the JumpLists with compiler messages and then for
    navigation between locations pointed by that messages.
    JumpList is filled by parsing output of NMAKE (actually output of ICC).


FED Configuration.

    FED is configured through simple ASCII file called FED.INI.
    This file contains all configarable parmeters and key bindings.

    NOTE: Configurable parameters have default values, but key
          bindings are not. This means that FED does not work
          without INI file.

    Sample FED.INI file is included in package.
    You can use it as a base for your own configuration.
    FED.INI should be placed in the same directory as FED.EXE.


  Format of FED.INI

    FED.INI is simple ASCII file which consist from variable assignments,
    comments and empty strings. Comments and empty strings are ignored.
    Comment is a line started with ';','/' or '#' (without quotes).

    Variable assignments is just pairs <variable>=<value>.

    Each configarable parameter have fixed name. Type of value which will
    be assigned to variable depends from variable. Some of them is numeric,
    some - strings.

    Numeric values can be decimal or hexadecimal.
    Hexadecimal values should be prefixed with 0x, exactly as in C/C++.

    String value consist from one or more "segments".
    Each segment consist from quoted string.

    String values should be in single or double quotes.
    Quotes can't be escaped, so if you need to insert single quote, you
    should use it in double quotes quoted string, and if you need double
    quotes, you should use it in single quotes quoted string.
    If you need to continue string on the next line, close quote, add ','
    at the end of line and open quote on the next line.
    This rules is very similar to those in REXX language but
    not completely equal.

    Full list of configarable parameters and
    variable types listed below (short descriptions is below this list):

    color.application.default     - number
    color.application.status      - number
    color.dialog.default          - number
    color.dialog.hilite           - number
    color.static.default          - number
    color.static.hilite           - number
    color.edit.default            - number
    color.edit.selection          - number
    color.edit.eof                - number
    color.edit.comment            - number
    color.edit.ident              - number
    color.edit.const              - number
    color.edit.preproc            - number
    color.edit.number             - number
    color.edit.stdword            - number
    color.edit.semicol            - number
    color.edit.function           - number
    color.edit.xnumber            - number
    color.line.active.default     - number
    color.line.active.selection   - number
    color.line.active.eof         - number
    color.line.active.comment     - number
    color.line.active.ident       - number
    color.line.active.const       - number
    color.line.active.preproc     - number
    color.line.active.number      - number
    color.line.active.stdword     - number
    color.line.active.semicol     - number
    color.line.active.function    - number
    color.line.active.xnumber     - number
    color.line.inactive.default   - number
    color.line.inactive.selection - number
    color.line.inactive.eof       - number
    color.line.inactive.comment   - number
    color.line.inactive.ident     - number
    color.line.inactive.const     - number
    color.line.inactive.preproc   - number
    color.line.inactive.number    - number
    color.line.inactive.stdword   - number
    color.line.inactive.semicol   - number
    color.line.inactive.function  - number
    color.line.inactive.xnumber   - number
    color.list.active.default     - number
    color.list.active.selection   - number
    color.list.active.current     - number
    color.list.active.currsel     - number
    color.list.inactive.default   - number
    color.list.inactive.selection - number
    color.list.inactive.current   - number
    color.list.inactive.currsel   - number
    color.menu.active.default     - number
    color.menu.active.selection   - number
    color.menu.active.current     - number
    color.menu.active.currsel     - number
    editor.tabwidth               - number
    editor.force.pm               - number
    editor.default.format         - number
    editor.hiliting               - string
    editor.untitled               - string
    editor.statusline             - string
    editor.helptext               - string
    cursor.shape.insert           - number
    cursor.shape.overwrite        - number

Short descrption of variables

  Variables "color.*" contains decimal or hexadecimal values of colors of
    different parts of editor. Colors is usual text mode character attributes
    where high nibble (high 4 bits of byte) responsible for background
    color, and lower nibble - for foreground (characters) color.
    Note, that input line in dialog is exactly the same object as full editor
    window, but with hiliting turned off. This causes full list of colors
    for input line appears in list, but really used only part of them
    (.default and .selection).

  Variable "editor.tabwidth" responsible for tab character representation
    in number of space characters.

  Variable "editor.hiliting" contains string which responsible for how editor
    will try to guess hiliting for opened file.
    This string have following format:

        "MODE_NAME_1:*.mask1;*.mask2;...\n",
        "MODE_NAME_2:*.mask3;*.mask4;...\n".

    Note trailing '\n' sequence, it is used for delimiting hiliting mode
    strings.

  Variable "editor.untitled" contains default name for '.Untitled' or newly
    created files.

  Variables "cursor.shape.insert" and "cursor.shape.overwrite" contains
    numbers which responsible for cursor shape. This number means relative
    (in percent) hight of cursor from which shape starts. In other words
    0 - means baseline, 100 - means full character size.

  Variable "editor.statusline" represents format in which editor will
    display status information. This string can contain following format rules:

    %n -  file number 0-9
    %r -+ row
    %c -+ col
    %d -+ current char (decimal)
    %x -  current char (hexadecimal)
    %h -  hiliting mode
    %a -  autoindent flag ('I'|' ')
    %u -  update flag ('*'|' ')
    %f -  filename
    %t -  file type: Unix ('\0x0a' delimited)/DOS ('\x0d\x0a' delimited)

    For formats marked with '+' between % and format can be placed otional
    digit. This digit means minimal length of representation. Unused positions
    will be filled with zeroes. Other characters will be shown in status line
    as is.
    By default this string has following content :
        "L%3r:C%2c %h [%u%f]".

    This means:
        character L,
        followed by 3-digit number of row,
        semicolon,
        character C,
        followed by 2-digit column nuber,
        space,
        hiliting mode name,
        character '[',
        update flag,
        current file name,
        character ']'.
    Example of status line with default format line:
    'L001:C01 REXX [*C:\startup.cmd]'

  Variable "editor.helptext" contains text which will be shown for command
    'HelpScreen' (see below description of this command). Text should be
    formatted on 'per line' basis, and each line should be followed by '\n'
    sequence.

  Variable "editor.force.pm" - Any value greater than 0 forces loading of
    PM clipboard support even for full screen sessions.

  Variable "editor.default.format" - set default format (Unix/DOS) for new
    files. Default (unassigned) value is 0, which means DOS file format.
    Any value other than 0 sets Unix file format.

Key bindings

    Each key binding consist from pair <key> = <action>
    Key name begins with 'kb' followed by zero or more
    special prefixes (Alt, Ctrl, Shift), followed by key name.
    Order of special prefixes: Alt, Ctrl, Shift
    Its means that if you want to bind combination of pressed simulateously
    keys Shift, Ctrl and key F10, you should name this key kbCtrlShiftF10.
    Case of characters used in key name is ignored.

    Full list of key names listed below:

    kb0, kb1, kb2, kb3, kb4, kb5, kb6, kb7, kb8, kb9
    kbA, kbB, kbBackSlash, kbBksp, kbC, kbCenter, kbComma,
    kbD, kbDel, kbDiv, kbDown, kbE, kbEnd, kbEnter, kbEqual,
    kbEsc, kbF, kbF1, kbF10, kbF11, kbF12, kbF2, kbF3, kbF4, kbF5,
    kbF6, kbF7, kbF8, kbF9, kbG, kbGrDiv, kbGrEnter, kbGrMinus,
    kbGrMul, kbGrPlus, kbH, kbHome, kbI, kbIns, kbJ, kbK, kbL,
    kbLbracket, kbLeft, kbM, kbMinus, kbN, kbO, kbP, kbPgDown, kbPgUp,
    kbPoint, kbQ, kbQuote, kbR, kbRbracket, kbRight, kbS, kbSemicolon,
    kbSpace, kbT, kbTab, kbTilde, kbU, kbUp, kbV, kbW, kbX, kbY, kbZ

    Actions is a sequence of quoted blocks of text and function names
    Quoted text can contain escape sequences '\t' (insert TAB character)
    and '\n' (emulates pressing Enter key).
    For quoting can be used either single (') or double (") quotes,
    but each block should be quoted with one type of them.
    Case of key names and actions are ignored

    Actions can be continued on the next line by adding ',' at the end of line.
  NOTE! key actions should not contain comments and continuation character (,)
    should not be inside quotes.

    Full list of available functions with short descriptions

    Abort            - abort editor without saving changes
    Bksp             - delete previous character
    Close            - close current file
    Copy             - copy marked block to clipboard
    Copyright        - invoke copyright message
    Cut              - cut marked block to clipboard
    Del              - delete current char or clear marked block
    DelLine          - delete current line
    DelToEOL         - delete from current position to end of line
    DelWordLeft      - delete word to left from cursor
    DelWordRight     - delete word to right from cursor
    Down             - move cursor down one line
    DownMark         - move cursor down one line and extend marked block
    End              - move cursor to end of line
    EndMark          - move cursor to end of line and extend marked block
    Exit             - exit with acknowledgement for saving files
    FileBegin        - move cursor to begin of file
    FileBeginMark    - move cursor to begin of file and extend marked block
    FileEnd          - move cursor to end of file
    FileEndMark      - move cursor to end of file and extend marked block
    FileList         - invoke list of opened files
    FlipAutoIndent   - switch autoindent on/off
    FlipBlockMode    - switch rectangalar/stream block
    FlipHiliting     - switch hiliting between C++/REXX/MAKE/ASM/HTML/none
    HelpScreen       - invoke dialog with help text
    Home             - move cursor to begin of line
    HomeMark         - move cursor to begin of line and extend marked block
    Indent           - indent block or line by one char right
    Ins              - switch insert/overwrite mode
    InsDate          - insert current date at current cursor position
    InsFileName      - insert current file name at current cursor position
    InsFileNameShort - insert current file name with path name stripped
    JumpCol          - invoke dialog and move cursor to column entered in dialog
    JumpLine         - invoke dialog and move cursor to line entered in dialog
    Left             - move cursor one char left
    LeftMark         - move cursor one char left and extend marked block
    Load             - invoke 'Open File' dialog
    Lower            - convert current char/marked block to lower case
    MatchBracket     - find matching bracket
    MatchBracketMark - find matching bracket and extend marked block
    New              - open new window with '.Untitled' file
    NextFile         - switch to next opened file
    OpenJumpList0-9  - Show jump list 0-9
    Paste            - paste block from clipboard
    PgDn             - move cursor one page down
    PgDnmark         - move cursor one page down and extend marked block
    PgUp             - move cursor one page up
    PgUpMark         - move cursor one page up and extend marked block
    PrevFile         - switch to previous opened file
    Right            - move cursor one char right
    RightMark        - move cursor one char right and extend marked block
    Save             - save current file, invoke 'Save As' dialog for '.Untitled'
    SaveAll          - save all opened files
    SaveAs           - invoke 'Save As' dialog
    Search           - invoke 'Search' dialog
    SearchAgain      - repeat last search operation
    Undo             - undo action
    UnIndent         - indent blockone char left
    Up               - move cursor up one line
    UpMark           - move cursor up one line and extend marked block
    Upper            - convert current char/marked block to upper case
    WordLeft         - move cursor left one word
    WordLeftMark     - move cursor left one word and extend marked block
    WordRight        - move cursor right one word
    WordRightMark    - move cursor right one word and extend marked block
    MacroRecStart    - start recording keyboard macro
    MacroRecEnd      - end recording and invoke 'Assign key' dialog
    MarkSet0-9       - set bookmark 0-9
    MarkGo0-9        - go to position saved as bookmark 0-9

Some notes about REXX API interface.

    FED REXX API is still under construction. There are some known bugs
    (especially with loading REXX code with curly braces inside '{}'),
    but this API becomed more or less useful and short (very short) explanation
    below tries do fill some gaps in information about this interface.

    List of REXX API's exported by FED cosists of two parts. First path
    is just the same functions as key macro functions described above.
    All of these functions does not have parameters.

    fedAbort              fedLeft
    fedBksp               fedLeftmark
    fedClose              fedLoad
    fedCopy               fedLower
    fedCopyright          fedMacrorecend
    fedCut                fedMacrorecstart
    fedDel                fedMatchbracket
    fedDelline            fedMatchbracketmark
    fedDeltoeol           fedNew
    fedDelwordleft        fedNextfile
    fedDelwordright       fedPaste
    fedDown               fedPgdn
    fedDownmark           fedPgdnmark
    fedEnd                fedPgup
    fedEndmark            fedPgupmark
    fedExit               fedPrevfile
    fedFilebegin          fedRight
    fedFilebeginmark      fedRightmark
    fedFileend            fedSave
    fedFileendmark        fedSaveall
    fedFilelist           fedSaveas
    fedFlipautoindent     fedSearch
    fedFlipblockmode      fedSearchAgain
    fedFliphiliting       fedSort
    fedHelpscreen         fedUndo
    fedHome               fedUnindent
    fedHomemark           fedUp
    fedIndent             fedUpmark
    fedIns                fedUpper
    fedInsdate            fedWordleft
    fedInsfilename        fedWordleftmark
    fedInsfilenameshort   fedWordright
    fedJumpcol            fedWordrightmark
    fedJumpline

    Second group is more functional and does not have counterparts in macro
    function list.

    fedFillJumpList       - Fill JumpList with information
    fedMsgBox             - Open simple message box and waits for key press.
    fedOpenJumpList       - Show filled JumpList
    fedOpenFile           - Open file or switch to it if already open
    fedInsChar            - Insert sequence of characters
    fedGetChar            - Get current char/line/substring
    fedSet                - Set FED values
    fedGet                - Get FED values
    fedFind               - Find string in current file


rc = fedFillJumpList(stem, jumplist)

    stem - variable name filled as follows:
            stem.jump_len   	number of items in stem
            stem.XX.jump_header what to show in list box
            stem.XX.jump_file   file name
            stem.XX.jump_row    row to jump (0 - does not change position)
            stem.XX.jump_col    col to jump (0 - does not change position)

            Where XX is number from 0 to stem.jump_len-1.

            NOTE: all variables should be filled, even if not used.
                  For example: if there is no column to jump in list item 5,
                  variable stem.5.jump_col should be set to 0.

    jumplist - number of jump list to use. Range: 0-9

    rc - success, negative value - error.


rc = fedMsgBox(message)

    message - text of message to show.

    rc - success, negative value - error.


rc = fedOpenJumpList(jumplist)

    jumplist - number of jump list to use. Range: 0-9

    rc - success, negative value - error.


rc = fedOpenFile(filename)

    filename - file name to open or switch to.

    rc - success, negative value - error.


rc = fedInsChar(string)

    string - text to insert.
             Text will be inserted from current cursor position.

    rc - success, negative value - error.


rc = fedGetChar(row, [col], [len])

    row - line number in current file to get text
    col - start column for text to get
    len - len of substring to return

    rc - success, negative value - error.

    If len parameter is omitted, rest of string is returned.
    If col is omitted, full line is returned (starting from column 1).

rc = fedSet(selector, [value])

    selector - variable to set
    value    - new variable value

    I - Insert mode  (if value omitted, mode flips between insert/replace)
    H - Hiliting mode (if value omitted, mode is switched through all modes)
    A - Autoindent mode (if value omitted, mode flips between on/off)
    M - Marking state (if value omitted marking mode is switched off)
    R - Go to line
    C - Go to column
    B - switch to buffer with given handle
    N - Rename buffer to given name.

    rc - success, negative value - error.

rc = fedGet(selector)

    selector - variable to return

    rc - success, negative value - error.

    Supported selectors:

    I  - Insert mode
    H  - Hiliting mode
    A  - Autoindent state
    M  - Marking state
    R  - Current absolute Row
    C  - Current absolute Col
    CH - Changed status
    CR - Cursor Row (cursor screen coordinate)
    CC - Cursor Col (cursor screen coordinate)
    B  - Current buffer handle
    ?  - Number of opened buffers
    N  - Current buffer name
    X  - Window rectandle size X (Screen columns)
    Y  - Window rectandle size Y (Screen rows)
    L  - Number of lines in file
    D  - FED startup directory (current directory when FED was invoked)


rc = fedFind(flags, pattern)

    flags - find flags

    pattern - pattern to look for

    rc - success, negative value - error.


    Supported flags:

    B - Find in backward direction
    G - Global find (from beginning to end or vice versa, depending on B flag)
    I - Ignore case
    E - Regexp. Pattern is regular expression


Distribution/warranties.
    NOTE: FED still beta sofware.
          This means that it can contain (potentially) dangerous bugs.

    This software provided for free for any purposes. You can free
    redistribute this package as long as you don't change it's content.
    But there is NO WARRANTIES AT ALL.

If you have comments or suggestions, call me. I'm always ready to improve
editor as long as I have time to do this. Some improvements will never
be implemented. Firs of them - mouse support. Second - alternate to
CUA style block marking behavior. Third - word processing features.
FED is programmers editor, not word processor, and never be.

Regargds,
    Sergey I. Yevtushenko.

Internet:evsi@naverex.kiev.ua
FIDO: 2:463/114.69@fidonet

