home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / fed024.zip / readme.txt < prev   
Text File  |  1999-01-25  |  23KB  |  565 lines
  1. /*
  2. ** Module   :READ.ME
  3. ** Abstract :
  4. **
  5. ** Copyright (C) Sergey I. Yevtushenko
  6. ** Log: Fri  20/03/1998     Created
  7. **      Mon  30/03/1998     Updated for v0.2.0d
  8. **      Sat  11/04/1998     Updated for v0.2.0i
  9. **      Tue  28/04/1998     Updated for v0.2.0l
  10. **      Sat  09/01/1999     Updated for v0.2.0p
  11. */
  12.                     Fast Editor Lite v0.2.0r for OS/2
  13.  
  14. What is FED?
  15.     FED is my small text mode editor. Small but powerful enough to be used
  16.     as my everyday editor. Features of FED includes:
  17.     - Unlimited files open
  18.     - Full UNDO
  19.     - Syntax hiliting for C++/REXX/HTML/ASM/Makefile
  20.     - CUA style blocks
  21.     - Rectangular blocks
  22.     - Goto line/column
  23.     - Indent / unindent
  24.     - Auto indent/smart C++ indent
  25.     - Find/replace
  26.     - Conversion to upper/lower case characters/blocks with NLS support
  27.     - REGEXP find
  28.     - Bracket matching for ()/{}/[]/<> bracket pairs
  29.     - Flexible key assignment
  30.     - Transparent with PM clipboard (only windowed sessions)
  31.     - Block sort of rectangular blocks with NLS collate support
  32.     - Flexible status line format
  33.     - Keyboard macro recorder/player
  34.     - REXX macro support
  35.     - Up to 10 bookmarks per file
  36.     - Saving last cursor position and bookmarks in Extended Attributes
  37.     - Unix/DOS file formats supported
  38.     - Up to 10 user accessible JumpLists supported
  39.     - kbInit/kbDone pseudo keys
  40.  
  41. Introduction.
  42.     I have started FAST Editor Lite project in April 1997.
  43.     Lack of time does not allows me to do it in more or less regular way.
  44.     So, I'm add feature from time to time (as soon as lack of feature
  45.     becomes annoing), or fix a bug or two (as soon as I found it).
  46.  
  47.     Primary goal of project was make replacement for QEdit which was
  48.     my main editor for about five years. Of course I have not want to
  49.     do exact copy of QEdit, because I have not use all features of
  50.     QEdit and some features was missing.
  51.     Between missing features two was most important for me: syntax hiliting
  52.     and full undo. And one feature of QEdit I have not want to loose: speed.
  53.     So, first step was writing fast editing engine with syntax hiliting.
  54.     And this took about half of time of development. Rest was much more
  55.     easlier. The goal was reached in January of 1998, and I have started using
  56.     FED as my every day editor. Of course, I have found and fix many
  57.     bugs, but none of them was in design of editor. When I decide
  58.     to make editor available for other peoples, I have add some features which
  59.     useless for me, and which, therefore, may be less tested than editor itself.
  60.     First public beta show needs in few other features which was implemented in
  61.     0.2.0 series.
  62.  
  63.     Starting from version 0.2.0s so called 'Jump Lists' is supported.
  64.     What is JumpList? This is a list of <file, row, col, comment> elements,
  65.     which can be filled from Rexx script assigned to key and later invoked
  66.     by another (or the same) key. Most useful features of IDE can be
  67.     implemented using JumpList. Sample FED.INI file contain example of
  68.     filling one of the JumpLists with compiler messages and then for
  69.     navigation between locations pointed by that messages.
  70.     JumpList is filled by parsing output of NMAKE (actually output of ICC).
  71.  
  72.  
  73. FED Configuration.
  74.  
  75.     FED is configured through simple ASCII file called FED.INI.
  76.     This file contains all configarable parmeters and key bindings.
  77.  
  78.     NOTE: Configurable parameters have default values, but key
  79.           bindings are not. This means that FED does not work
  80.           without INI file.
  81.  
  82.     Sample FED.INI file is included in package.
  83.     You can use it as a base for your own configuration.
  84.     FED.INI should be placed in the same directory as FED.EXE.
  85.  
  86.  
  87.   Format of FED.INI
  88.  
  89.     FED.INI is simple ASCII file which consist from variable assignments,
  90.     comments and empty strings. Comments and empty strings are ignored.
  91.     Comment is a line started with ';','/' or '#' (without quotes).
  92.  
  93.     Variable assignments is just pairs <variable>=<value>.
  94.  
  95.     Each configarable parameter have fixed name. Type of value which will
  96.     be assigned to variable depends from variable. Some of them is numeric,
  97.     some - strings.
  98.  
  99.     Numeric values can be decimal or hexadecimal.
  100.     Hexadecimal values should be prefixed with 0x, exactly as in C/C++.
  101.  
  102.     String value consist from one or more "segments".
  103.     Each segment consist from quoted string.
  104.  
  105.     String values should be in single or double quotes.
  106.     Quotes can't be escaped, so if you need to insert single quote, you
  107.     should use it in double quotes quoted string, and if you need double
  108.     quotes, you should use it in single quotes quoted string.
  109.     If you need to continue string on the next line, close quote, add ','
  110.     at the end of line and open quote on the next line.
  111.     This rules is very similar to those in REXX language but
  112.     not completely equal.
  113.  
  114.     Full list of configarable parameters and
  115.     variable types listed below (short descriptions is below this list):
  116.  
  117.     color.application.default     - number
  118.     color.application.status      - number
  119.     color.dialog.default          - number
  120.     color.dialog.hilite           - number
  121.     color.static.default          - number
  122.     color.static.hilite           - number
  123.     color.edit.default            - number
  124.     color.edit.selection          - number
  125.     color.edit.eof                - number
  126.     color.edit.comment            - number
  127.     color.edit.ident              - number
  128.     color.edit.const              - number
  129.     color.edit.preproc            - number
  130.     color.edit.number             - number
  131.     color.edit.stdword            - number
  132.     color.edit.semicol            - number
  133.     color.edit.function           - number
  134.     color.edit.xnumber            - number
  135.     color.line.active.default     - number
  136.     color.line.active.selection   - number
  137.     color.line.active.eof         - number
  138.     color.line.active.comment     - number
  139.     color.line.active.ident       - number
  140.     color.line.active.const       - number
  141.     color.line.active.preproc     - number
  142.     color.line.active.number      - number
  143.     color.line.active.stdword     - number
  144.     color.line.active.semicol     - number
  145.     color.line.active.function    - number
  146.     color.line.active.xnumber     - number
  147.     color.line.inactive.default   - number
  148.     color.line.inactive.selection - number
  149.     color.line.inactive.eof       - number
  150.     color.line.inactive.comment   - number
  151.     color.line.inactive.ident     - number
  152.     color.line.inactive.const     - number
  153.     color.line.inactive.preproc   - number
  154.     color.line.inactive.number    - number
  155.     color.line.inactive.stdword   - number
  156.     color.line.inactive.semicol   - number
  157.     color.line.inactive.function  - number
  158.     color.line.inactive.xnumber   - number
  159.     color.list.active.default     - number
  160.     color.list.active.selection   - number
  161.     color.list.active.current     - number
  162.     color.list.active.currsel     - number
  163.     color.list.inactive.default   - number
  164.     color.list.inactive.selection - number
  165.     color.list.inactive.current   - number
  166.     color.list.inactive.currsel   - number
  167.     color.menu.active.default     - number
  168.     color.menu.active.selection   - number
  169.     color.menu.active.current     - number
  170.     color.menu.active.currsel     - number
  171.     editor.tabwidth               - number
  172.     editor.force.pm               - number
  173.     editor.default.format         - number
  174.     editor.hiliting               - string
  175.     editor.untitled               - string
  176.     editor.statusline             - string
  177.     editor.helptext               - string
  178.     cursor.shape.insert           - number
  179.     cursor.shape.overwrite        - number
  180.  
  181. Short descrption of variables
  182.  
  183.   Variables "color.*" contains decimal or hexadecimal values of colors of
  184.     different parts of editor. Colors is usual text mode character attributes
  185.     where high nibble (high 4 bits of byte) responsible for background
  186.     color, and lower nibble - for foreground (characters) color.
  187.     Note, that input line in dialog is exactly the same object as full editor
  188.     window, but with hiliting turned off. This causes full list of colors
  189.     for input line appears in list, but really used only part of them
  190.     (.default and .selection).
  191.  
  192.   Variable "editor.tabwidth" responsible for tab character representation
  193.     in number of space characters.
  194.  
  195.   Variable "editor.hiliting" contains string which responsible for how editor
  196.     will try to guess hiliting for opened file.
  197.     This string have following format:
  198.  
  199.         "MODE_NAME_1:*.mask1;*.mask2;...\n",
  200.         "MODE_NAME_2:*.mask3;*.mask4;...\n".
  201.  
  202.     Note trailing '\n' sequence, it is used for delimiting hiliting mode
  203.     strings.
  204.  
  205.   Variable "editor.untitled" contains default name for '.Untitled' or newly
  206.     created files.
  207.  
  208.   Variables "cursor.shape.insert" and "cursor.shape.overwrite" contains
  209.     numbers which responsible for cursor shape. This number means relative
  210.     (in percent) hight of cursor from which shape starts. In other words
  211.     0 - means baseline, 100 - means full character size.
  212.  
  213.   Variable "editor.statusline" represents format in which editor will
  214.     display status information. This string can contain following format rules:
  215.  
  216.     %n -  file number 0-9
  217.     %r -+ row
  218.     %c -+ col
  219.     %d -+ current char (decimal)
  220.     %x -  current char (hexadecimal)
  221.     %h -  hiliting mode
  222.     %a -  autoindent flag ('I'|' ')
  223.     %u -  update flag ('*'|' ')
  224.     %f -  filename
  225.     %t -  file type: Unix ('\0x0a' delimited)/DOS ('\x0d\x0a' delimited)
  226.  
  227.     For formats marked with '+' between % and format can be placed otional
  228.     digit. This digit means minimal length of representation. Unused positions
  229.     will be filled with zeroes. Other characters will be shown in status line
  230.     as is.
  231.     By default this string has following content :
  232.         "L%3r:C%2c %h [%u%f]".
  233.  
  234.     This means:
  235.         character L,
  236.         followed by 3-digit number of row,
  237.         semicolon,
  238.         character C,
  239.         followed by 2-digit column nuber,
  240.         space,
  241.         hiliting mode name,
  242.         character '[',
  243.         update flag,
  244.         current file name,
  245.         character ']'.
  246.     Example of status line with default format line:
  247.     'L001:C01 REXX [*C:\startup.cmd]'
  248.  
  249.   Variable "editor.helptext" contains text which will be shown for command
  250.     'HelpScreen' (see below description of this command). Text should be
  251.     formatted on 'per line' basis, and each line should be followed by '\n'
  252.     sequence.
  253.  
  254.   Variable "editor.force.pm" - Any value greater than 0 forces loading of
  255.     PM clipboard support even for full screen sessions.
  256.  
  257.   Variable "editor.default.format" - set default format (Unix/DOS) for new
  258.     files. Default (unassigned) value is 0, which means DOS file format.
  259.     Any value other than 0 sets Unix file format.
  260.  
  261. Key bindings
  262.  
  263.     Each key binding consist from pair <key> = <action>
  264.     Key name begins with 'kb' followed by zero or more
  265.     special prefixes (Alt, Ctrl, Shift), followed by key name.
  266.     Order of special prefixes: Alt, Ctrl, Shift
  267.     Its means that if you want to bind combination of pressed simulateously
  268.     keys Shift, Ctrl and key F10, you should name this key kbCtrlShiftF10.
  269.     Case of characters used in key name is ignored.
  270.  
  271.     Full list of key names listed below:
  272.  
  273.     kb0, kb1, kb2, kb3, kb4, kb5, kb6, kb7, kb8, kb9
  274.     kbA, kbB, kbBackSlash, kbBksp, kbC, kbCenter, kbComma,
  275.     kbD, kbDel, kbDiv, kbDown, kbE, kbEnd, kbEnter, kbEqual,
  276.     kbEsc, kbF, kbF1, kbF10, kbF11, kbF12, kbF2, kbF3, kbF4, kbF5,
  277.     kbF6, kbF7, kbF8, kbF9, kbG, kbGrDiv, kbGrEnter, kbGrMinus,
  278.     kbGrMul, kbGrPlus, kbH, kbHome, kbI, kbIns, kbJ, kbK, kbL,
  279.     kbLbracket, kbLeft, kbM, kbMinus, kbN, kbO, kbP, kbPgDown, kbPgUp,
  280.     kbPoint, kbQ, kbQuote, kbR, kbRbracket, kbRight, kbS, kbSemicolon,
  281.     kbSpace, kbT, kbTab, kbTilde, kbU, kbUp, kbV, kbW, kbX, kbY, kbZ
  282.  
  283.     Actions is a sequence of quoted blocks of text and function names
  284.     Quoted text can contain escape sequences '\t' (insert TAB character)
  285.     and '\n' (emulates pressing Enter key).
  286.     For quoting can be used either single (') or double (") quotes,
  287.     but each block should be quoted with one type of them.
  288.     Case of key names and actions are ignored
  289.  
  290.     Actions can be continued on the next line by adding ',' at the end of line.
  291.   NOTE! key actions should not contain comments and continuation character (,)
  292.     should not be inside quotes.
  293.  
  294.     Full list of available functions with short descriptions
  295.  
  296.     Abort            - abort editor without saving changes
  297.     Bksp             - delete previous character
  298.     Close            - close current file
  299.     Copy             - copy marked block to clipboard
  300.     Copyright        - invoke copyright message
  301.     Cut              - cut marked block to clipboard
  302.     Del              - delete current char or clear marked block
  303.     DelLine          - delete current line
  304.     DelToEOL         - delete from current position to end of line
  305.     DelWordLeft      - delete word to left from cursor
  306.     DelWordRight     - delete word to right from cursor
  307.     Down             - move cursor down one line
  308.     DownMark         - move cursor down one line and extend marked block
  309.     End              - move cursor to end of line
  310.     EndMark          - move cursor to end of line and extend marked block
  311.     Exit             - exit with acknowledgement for saving files
  312.     FileBegin        - move cursor to begin of file
  313.     FileBeginMark    - move cursor to begin of file and extend marked block
  314.     FileEnd          - move cursor to end of file
  315.     FileEndMark      - move cursor to end of file and extend marked block
  316.     FileList         - invoke list of opened files
  317.     FlipAutoIndent   - switch autoindent on/off
  318.     FlipBlockMode    - switch rectangalar/stream block
  319.     FlipHiliting     - switch hiliting between C++/REXX/MAKE/ASM/HTML/none
  320.     HelpScreen       - invoke dialog with help text
  321.     Home             - move cursor to begin of line
  322.     HomeMark         - move cursor to begin of line and extend marked block
  323.     Indent           - indent block or line by one char right
  324.     Ins              - switch insert/overwrite mode
  325.     InsDate          - insert current date at current cursor position
  326.     InsFileName      - insert current file name at current cursor position
  327.     InsFileNameShort - insert current file name with path name stripped
  328.     JumpCol          - invoke dialog and move cursor to column entered in dialog
  329.     JumpLine         - invoke dialog and move cursor to line entered in dialog
  330.     Left             - move cursor one char left
  331.     LeftMark         - move cursor one char left and extend marked block
  332.     Load             - invoke 'Open File' dialog
  333.     Lower            - convert current char/marked block to lower case
  334.     MatchBracket     - find matching bracket
  335.     MatchBracketMark - find matching bracket and extend marked block
  336.     New              - open new window with '.Untitled' file
  337.     NextFile         - switch to next opened file
  338.     OpenJumpList0-9  - Show jump list 0-9
  339.     Paste            - paste block from clipboard
  340.     PgDn             - move cursor one page down
  341.     PgDnmark         - move cursor one page down and extend marked block
  342.     PgUp             - move cursor one page up
  343.     PgUpMark         - move cursor one page up and extend marked block
  344.     PrevFile         - switch to previous opened file
  345.     Right            - move cursor one char right
  346.     RightMark        - move cursor one char right and extend marked block
  347.     Save             - save current file, invoke 'Save As' dialog for '.Untitled'
  348.     SaveAll          - save all opened files
  349.     SaveAs           - invoke 'Save As' dialog
  350.     Search           - invoke 'Search' dialog
  351.     SearchAgain      - repeat last search operation
  352.     Undo             - undo action
  353.     UnIndent         - indent blockone char left
  354.     Up               - move cursor up one line
  355.     UpMark           - move cursor up one line and extend marked block
  356.     Upper            - convert current char/marked block to upper case
  357.     WordLeft         - move cursor left one word
  358.     WordLeftMark     - move cursor left one word and extend marked block
  359.     WordRight        - move cursor right one word
  360.     WordRightMark    - move cursor right one word and extend marked block
  361.     MacroRecStart    - start recording keyboard macro
  362.     MacroRecEnd      - end recording and invoke 'Assign key' dialog
  363.     MarkSet0-9       - set bookmark 0-9
  364.     MarkGo0-9        - go to position saved as bookmark 0-9
  365.  
  366. Some notes about REXX API interface.
  367.  
  368.     FED REXX API is still under construction. There are some known bugs
  369.     (especially with loading REXX code with curly braces inside '{}'),
  370.     but this API becomed more or less useful and short (very short) explanation
  371.     below tries do fill some gaps in information about this interface.
  372.  
  373.     List of REXX API's exported by FED cosists of two parts. First path
  374.     is just the same functions as key macro functions described above.
  375.     All of these functions does not have parameters.
  376.  
  377.     fedAbort              fedLeft
  378.     fedBksp               fedLeftmark
  379.     fedClose              fedLoad
  380.     fedCopy               fedLower
  381.     fedCopyright          fedMacrorecend
  382.     fedCut                fedMacrorecstart
  383.     fedDel                fedMatchbracket
  384.     fedDelline            fedMatchbracketmark
  385.     fedDeltoeol           fedNew
  386.     fedDelwordleft        fedNextfile
  387.     fedDelwordright       fedPaste
  388.     fedDown               fedPgdn
  389.     fedDownmark           fedPgdnmark
  390.     fedEnd                fedPgup
  391.     fedEndmark            fedPgupmark
  392.     fedExit               fedPrevfile
  393.     fedFilebegin          fedRight
  394.     fedFilebeginmark      fedRightmark
  395.     fedFileend            fedSave
  396.     fedFileendmark        fedSaveall
  397.     fedFilelist           fedSaveas
  398.     fedFlipautoindent     fedSearch
  399.     fedFlipblockmode      fedSearchAgain
  400.     fedFliphiliting       fedSort
  401.     fedHelpscreen         fedUndo
  402.     fedHome               fedUnindent
  403.     fedHomemark           fedUp
  404.     fedIndent             fedUpmark
  405.     fedIns                fedUpper
  406.     fedInsdate            fedWordleft
  407.     fedInsfilename        fedWordleftmark
  408.     fedInsfilenameshort   fedWordright
  409.     fedJumpcol            fedWordrightmark
  410.     fedJumpline
  411.  
  412.     Second group is more functional and does not have counterparts in macro
  413.     function list.
  414.  
  415.     fedFillJumpList       - Fill JumpList with information
  416.     fedMsgBox             - Open simple message box and waits for key press.
  417.     fedOpenJumpList       - Show filled JumpList
  418.     fedOpenFile           - Open file or switch to it if already open
  419.     fedInsChar            - Insert sequence of characters
  420.     fedGetChar            - Get current char/line/substring
  421.     fedSet                - Set FED values
  422.     fedGet                - Get FED values
  423.     fedFind               - Find string in current file
  424.  
  425.  
  426. rc = fedFillJumpList(stem, jumplist)
  427.  
  428.     stem - variable name filled as follows:
  429.             stem.jump_len       number of items in stem
  430.             stem.XX.jump_header what to show in list box
  431.             stem.XX.jump_file   file name
  432.             stem.XX.jump_row    row to jump (0 - does not change position)
  433.             stem.XX.jump_col    col to jump (0 - does not change position)
  434.  
  435.             Where XX is number from 0 to stem.jump_len-1.
  436.  
  437.             NOTE: all variables should be filled, even if not used.
  438.                   For example: if there is no column to jump in list item 5,
  439.                   variable stem.5.jump_col should be set to 0.
  440.  
  441.     jumplist - number of jump list to use. Range: 0-9
  442.  
  443.     rc - success, negative value - error.
  444.  
  445.  
  446. rc = fedMsgBox(message)
  447.  
  448.     message - text of message to show.
  449.  
  450.     rc - success, negative value - error.
  451.  
  452.  
  453. rc = fedOpenJumpList(jumplist)
  454.  
  455.     jumplist - number of jump list to use. Range: 0-9
  456.  
  457.     rc - success, negative value - error.
  458.  
  459.  
  460. rc = fedOpenFile(filename)
  461.  
  462.     filename - file name to open or switch to.
  463.  
  464.     rc - success, negative value - error.
  465.  
  466.  
  467. rc = fedInsChar(string)
  468.  
  469.     string - text to insert.
  470.              Text will be inserted from current cursor position.
  471.  
  472.     rc - success, negative value - error.
  473.  
  474.  
  475. rc = fedGetChar(row, [col], [len])
  476.  
  477.     row - line number in current file to get text
  478.     col - start column for text to get
  479.     len - len of substring to return
  480.  
  481.     rc - success, negative value - error.
  482.  
  483.     If len parameter is omitted, rest of string is returned.
  484.     If col is omitted, full line is returned (starting from column 1).
  485.  
  486. rc = fedSet(selector, [value])
  487.  
  488.     selector - variable to set
  489.     value    - new variable value
  490.  
  491.     I - Insert mode  (if value omitted, mode flips between insert/replace)
  492.     H - Hiliting mode (if value omitted, mode is switched through all modes)
  493.     A - Autoindent mode (if value omitted, mode flips between on/off)
  494.     M - Marking state (if value omitted marking mode is switched off)
  495.     R - Go to line
  496.     C - Go to column
  497.     B - switch to buffer with given handle
  498.     N - Rename buffer to given name.
  499.  
  500.     rc - success, negative value - error.
  501.  
  502. rc = fedGet(selector)
  503.  
  504.     selector - variable to return
  505.  
  506.     rc - success, negative value - error.
  507.  
  508.     Supported selectors:
  509.  
  510.     I  - Insert mode
  511.     H  - Hiliting mode
  512.     A  - Autoindent state
  513.     M  - Marking state
  514.     R  - Current absolute Row
  515.     C  - Current absolute Col
  516.     CH - Changed status
  517.     CR - Cursor Row (cursor screen coordinate)
  518.     CC - Cursor Col (cursor screen coordinate)
  519.     B  - Current buffer handle
  520.     ?  - Number of opened buffers
  521.     N  - Current buffer name
  522.     X  - Window rectandle size X (Screen columns)
  523.     Y  - Window rectandle size Y (Screen rows)
  524.     L  - Number of lines in file
  525.     D  - FED startup directory (current directory when FED was invoked)
  526.  
  527.  
  528. rc = fedFind(flags, pattern)
  529.  
  530.     flags - find flags
  531.  
  532.     pattern - pattern to look for
  533.  
  534.     rc - success, negative value - error.
  535.  
  536.  
  537.     Supported flags:
  538.  
  539.     B - Find in backward direction
  540.     G - Global find (from beginning to end or vice versa, depending on B flag)
  541.     I - Ignore case
  542.     E - Regexp. Pattern is regular expression
  543.  
  544.  
  545. Distribution/warranties.
  546.     NOTE: FED still beta sofware.
  547.           This means that it can contain (potentially) dangerous bugs.
  548.  
  549.     This software provided for free for any purposes. You can free
  550.     redistribute this package as long as you don't change it's content.
  551.     But there is NO WARRANTIES AT ALL.
  552.  
  553. If you have comments or suggestions, call me. I'm always ready to improve
  554. editor as long as I have time to do this. Some improvements will never
  555. be implemented. Firs of them - mouse support. Second - alternate to
  556. CUA style block marking behavior. Third - word processing features.
  557. FED is programmers editor, not word processor, and never be.
  558.  
  559. Regargds,
  560.     Sergey I. Yevtushenko.
  561.  
  562. Internet:evsi@naverex.kiev.ua
  563. FIDO: 2:463/114.69@fidonet
  564.  
  565.