START-INFO-DIR-ENTRY
* SET's editor: (editor.inf).           Documentation about the editor.
END-INFO-DIR-ENTRY

This is the documentation for the SET's Editor.

Copyright (C) 1996 Salvador Eduardo Tropea

This documentation may be freely distributed with the editor or the RHIDE
package or any part thereof, provided this copyright notice is left intact on
all copies.

EDITOR
******

   Table of Contents
   *****************
1. Introduction
  1.1 What is SETs Editor?
  1.2 Requirements
  1.3 About the Author
2. Available commands
  2.1 Conventions
  2.2 Cursor movement
  2.3 Insert and Delete
  2.4 Blocks
  2.4.1 Block modes
  2.4.2 Selecting with the mouse or Shift
  2.4.2.1 Using the mouse
  2.4.2.2 Using the Shift key
  2.4.3 Indentation
  2.4.4 Rectangular Blocks
  2.5 Pseudo Macros
  2.5.1 Please enlight me - what is that?
  2.5.2 How can I customize that?
  2.6 Miscellaneous
3. Keyboard
  3.1 How to configure the keyboard
  3.2 A program to find the scancodes
4. Edition Modes
  4.1 Overwrite
  4.2 Autoindent
  4.3 Real Tabs
  4.4 Persistent Blocks
  4.5 Inteligent C indent
  4.5.1 Can you explain me more about the behaviour of this mode?
  4.5.2 Do you have more examples?
  4.6 Column cursor
  4.7 Row cursor
  4.8 Match pair highligth
  4.9 Syntax Highlight
5. How to contact me
  5.1 Bugs
6. Index
7. Index of key commands

1. Introduction
***************

This document describes the use of the SET's editor, this editor was designed
for programmers and to be used alone or inside of the RHIDE.

Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on all
copies.

Permission is granted to copy and distribute modified versions of this manual
under the conditions for verbatim copying, provided that the entire resulting
derived work is distributed under the terms of a permission notice identical
to this one.

  People, who helped me, to develop the editor:

   * ROBERT HHNE <Robert.Hoehne@Mathematik.TU-Chemnitz.DE> (with some base
     routines, a lot of patchs and reports)

   * MOLNAR LASZLO <molnarl@postabank.hu> (with test and a lot of ideas)

   * MAREK HABERSACK <grendel@ananke.amu.edu.pl> (with test and a lot of
     ideas)

  The editor is freeware, but the souce-code of this editor is copyright by
Salvador Eduardo Tropea.    If you want to include the editor in your
application, using the whole code or only a part contact at first me
<salvador@inti.edu.ar>

  This editor is included in the Robert Hhne's RHIDE as replace of the
original TVision's editor class.

1.1 What is SETs Editor?
========================

  SET's editor is an editor designed to be used by programmers, the main target
of the editor is C and C++ code but Pascal and Clipper are supported too.

  The editor was designed to be very similar to the DOS standard editors for C,
specially to the Borland's IDE editor. The editor supports a lot of WordStar
style commands plus some CUA commands, so if you used any editor that uses
this kind of commands you'll find my editor very familiar. On the other hand
if you never used a DOS editor, specially if you use VI on UNIX machines
you'll feel loosed. You can configure the keyboard but this feature is
relative limited See Section 3.1.

1.2 Requirements
================

  As by now I only plan to distribute my editor inside of RHIDE the
requirements are the requirements of RHIDE.

1.3 About the Author
====================

0B
0F
0B

The editor was made by Salvador Eduardo Tropea (SET), with the help of Robert
Hhne.

     E-Mail: Salvador Eduardo Tropea <salvador@inti.edu.ar>
     
     Telephone: (+541) 759-0013
     Postal Address:
     Salvador E. Tropea
     Curapalige 2124
     (1678) Caseros - 3 de Febrero
     Prov: Buenos Aires
     Argentina

0B
0F
0B

2. Available commands
*********************

  In this section I will explain the features of the editor and how is
configured the keyboard by default. If you want to change some assigment of a
key consult See Section 3.1.

  Read the conventions topic first to understand my way of indicate keystrokes.

  In the description of each command I'll include the internal name used by the
editor because this name is needed to configure the keyboard.

2.1 Conventions
===============

  I'll use some conventions when talking about the keystrokes needed to trigger
some command. So here is what I use:

  The key named Ctrl or Control is represented as ^, this key don't have any
effect used alone inside of the editor so the ^ symbol will be used ever in
conjuntion with the name of some key indicating that you must press the two
keys at the same time, for example: ^A is Ctrl and A at the same time.  When
I say "at the same time" that means: press Ctrl, hold it, and press the other
key, that's the reason to put Ctrl after A.

  To indicate a sequence of keystrokes I'll use a - to separate the keys, for
example ^K-B is Ctrl and K at the same time, and then press B, of course
release ^K before.

  To indicate keys pressed at the same time others than ^x I'll use the +, for
example: Shift+^Insert is the three keys at the same time!.

  I don't think that you are an stupid, the editor is writed for programmers,
but I'll want to put that clear to avoid problems ;-).

2.2 Cursor movement
===================

   * Character left
        - Editor command: `cmbCharLeft'
        - Key: <Left arrow>
        - Alternative: <^S>

   * Character right
        - Editor command: `cmbCharRight'
        - Key: <Right arrow>
        - Alternative: <^D>

   * Word left
        - Editor command: `cmbWordLeft'
        - Key: <^Left arrow>
        - Alternative: <^A>

   * Word right
        - Editor command: `cmbWordRight'
        - Key: <^Right arrow>
        - Alternative: <^F>

   * Line up
        - Editor command: `cmbLineUp'
        - Key: <Up arrow>
        - Alternative: <^E>

   * Line down
        - Editor command: `cmbLineDown'
        - Key: <Down arrow>
        - Alternative: <^X>

   * Scroll the screen one line up
        - Editor command: `cmbScrollUp'
        - Key: <^W>

   * Scroll the screen one line down
        - Editor command: `cmbScrollDown'
        - Key: <^Z>

   * Page up
        - Editor command: `cmbPageUp'
        - Key: <PgUp>
        - Alternative: <^R>

   * Page down
        - Editor command: `cmbPageDown'
        - Key: <PgDn>
        - Alternative: <^C>

   * Beginning of line
        - Editor command: `cmbLineStart'
        - Key: <Home>
        - Alternative: <^Q-S>

   * End of line
        - Editor command: `cmbLineEnd'
        - Key: <End>
        - Alternative: <^Q-D>

   * Top of window
        - Editor command: `cmbFirstLineInScreen'
        - Key: <^Q-E>
        - Alternative: <^Home>

   * Bottom of window
        - Editor command: `cmbLastLineInScreen'
        - Key: <^Q-X>
        - Alternative: <^End>

   * Top of file
        - Editor command: `cmbTextStart'
        - Key: <^Q-R>
        - Alternative: <^PgUp>

   * Bottom of file
        - Editor command: `cmbTextEnd'
        - Key: <^Q-C>
        - Alternative: <^PgDn>

2.3 Insert and Delete
=====================

   * Delete the character under cursor
        - Editor command: `cmbDelChar'
        - Key: <Del>
        - Alternative: <^G>

   * Delete character to left
        - Editor command: `cmbBackSpace'
        - Key: <Backspace>
        - Alternative: <^H>

   * Delete line
        - Editor command: `cmbDelLine'
        - Key: <^Y>

   * Delete to end of line
        - Editor command: `cmbDelEnd'
        - Key: <^Q-Y>
        - Alternative: <Shift+^Y>

   * Delete to start of line
        - Editor command: `cmbDelStart'
        - Key: <^Q-H>

   * Delete word at left
        - Editor command: `cmbDelWord'
        - Key: <^T>

   * Delete word at right
        - Editor command: `cmbDelPrevWord'
        - Key: <^Backspace>

   * Insert line
        - Editor command: `cmbNewLine'
        - Key: <Enter>
        - Alternative: <^N>

   * Insert mode on/off
        - Editor command: `cmbInsMode'
        - Key: <Ins>
        - Alternative: <^V>

  When you are in insert mode all the typed characters are inserted in the
text, but when the isert mode is off the typed characters replaces the old
text. The editor starts with insert mode on. You can quickly know the mode by
the cursor shapem when the insert mode is on the cursor is only a line, but
when is off the cursor is a block.

2.4 Blocks
==========

  A block is a selected portion of the text, you can copy, delete, etc blocks
of text. The asociated commands are:

   * Move to beginning of block
        - Editor command: `cmbGoBeginBlock'
        - Key: <^Q-B>

   * Move to end of block
        - Editor command: `cmbGoEndBlock'
        - Key: <^Q-K>

   * Set beginning of block
        - Editor command: `cmbStartSelect'
        - Key: <^K-B>

   * Set end of block
        - Editor command: `cmbEndSelect'
        - Key: <^K-K>

   * Hide/Show block
        - Editor command: `cmbHideSelect'
        - Key: <^K-H>

   * Mark line
        - Editor command: `cmbMarkLine'
        - Key: <^K-L>

   * Mark word
        - Editor command: `cmbMarkWord'
        - Key: <^K-T>

   * Delete block and copy it to the Clipboard
        - Editor command: `cmbCut'
        - Key: <^K-Y>
        - Alternative: <Shift+Del>

   * Copy the selected block
        - Editor command: `cmbCopyBlock'
        - Key: <^K-C>

   * Move block
        - Editor command: `cmbMoveBlock'
        - Key: <^K+V>

   * Copy to Clipboard
        - Editor command: `cmbCopy'
        - Key: <^Ins>

   * Delete block
        - Editor command: `cmbClear'
        - Key: <^Del>

   * Paste from Clipboard
        - Editor command: `cmbPaste'
        - Key: <Shift+Ins>

   * Read block from disk
        - Editor command: `cmbReadBlock'
        - Key: <^K-R>
        - Alternative: <Shift+^R>

   * Write block to disk
        - Editor command: `cmbWriteBlock'
        - Key: <^K-W>
        - Alternative: <Shift+^W>

   * Replace the block by the Clipboard block
        - Editor command: `cmbReplaceSelect'
        - Key: <Shift+^Ins>

   * Convert to Uppercase
        - Editor command: `cmbToUpper'
        - Key: <^K-M>

   * Convert to Lowercase
        - Editor command: `cmbToLower'
        - Key: <^K-O>

   * Report the length of the block
        - Editor command: `cmbSelLength'
        - Key: <^Q-L>

2.4.1 Block modes
-----------------

  There are two block modes, one is the mode that the old editor of RHIDE used
this mode is used in CUA programs, and the other is called Persistent Blocks.

  In the normal mode each time you select a block and then insert any thing on
it (with `cmbPaste' or typing anything) the selected block is deleted and is
replaced by the new text.

  In persistent blocks the selection is not replaced and is not loosed when you
move the cursor, from here comes the name "Persistent", in this mode you can
use `cmbMoveBlock' and `cmbCopyBlock' without using the Clipboard, in adition
you can apply indentations to the block (See Section 2.4.3), search only
inside it, etc, that's makes this mode much more powerful than the former. If
you really like to replace the selected text by the selection of the
Clipboard, that's the default behaviour of the first mode, you can use the
`cmbReplaceSelect' command to achieve the same in the Persistent Blocks mode.

2.4.2 Selecting with the mouse or Shift
---------------------------------------

  The described commands for select a block, `cmbStartSelect' and
`cmbEndSelect', are good but not so quick, there are another ways to make
that.

2.4.2.1 Using the mouse
.......................

  Using the mouse you only need to point the start place, hold the left button
pressed and move the mouse to the end point of your block.

  To select a word with the mouse just double click on it.

2.4.2.2 Using the Shift key
...........................

  Using the shift key you only need to move the cursor to the start point, hold
Shift pressed and move the cursor to the end point with any of the available
See Section 2.2 commands.

2.4.3 Indentation
-----------------

  You can indent or unindent a block of text using various commands, but you
must keep in mind that by now the editor is limited in the following: If you
are using See Section 4.3 to indent your text don't mix the tabs with spaces
and if you are using spaces to indent don't mix it with real tabs.

   * Indent block one position adding an space
        - Editor command: `cmbIndentBlkOne'
        - Key: <^K-I>
        - Alternative: <Shift+^I>

   * Unindent block one character - not an x position
        - Editor command: `cmbUnIndentBlkOne'
        - Key: <^K-U>
        - Alternative: <Shift+^U>

   * Indent block
        - Editor command: `cmbIndentBlk'
        - Key: <^K-Tab>

   * Unindent block
        - Editor command: `cmbUnIndentBlk'
        - Key: <^K-Shift+Tab>

   * Smart Indent block
        - Editor command: `cmbSmartIndent'
        - Key: <^Tab>

   * Smart Unindent block
        - Editor command: `cmbSmartUnIndent'
        - Key: <Shift+^Tab>

`cmbUnIndentBlkOne' unindents deleting one char at the start of the line so
if the line is indented with tabs the line will retroced one tab.

`cmbIndentBlk' acts according to the mode, if you are using See Section 4.3,
the editor will put one tab in each line, if you aren't using tabs the editor
will operate the Tab command on the first line and then will use this amount
of indentation in the rest of the block.

`cmbUnIndentBlk' acts according to the mode too, in See Section 4.3 mode is
just like `cmbUnIndentBlkOne' deleting one tab but if you don't use tabs the
editor uses Backspace on the first used column of the first line of the block
and unindents the resulting amount all the block.

`cmbSmartIndent' and `cmbSmartUnIndent' indents taking as reference the { }
pair where the block is, for example:
       {
     line1
          line2
        line3
       }
After indenting a block that contains line1 to line3 is:
       {
        line1
        line2
        line3
       }
The indentation is made with spaces.

2.4.4 Rectangular Blocks
------------------------

  The editor includes a mode where you can select a rectangular portion of the
text and copy, cut, clear, paste, move, etc this region.    This tool is very
useful for modifications on columns.

  Attention! the selected area is based on the X,Y coordinates, for this reason
if you insert lines before the bottom of the rectangle the area won't be
moved. I don't plan to move the area by now because that takes some CPU and I
think that this selection is made just before using it. So don't report that
like a bug is that the way that works.

   * Set beginning of block
        - Editor command: `cmbSelRectStart'
        - Key: <^K-Shift+B>

   * Set end of block
        - Editor command: `cmbSelRectEnd'
        - Key: <^K-Shift+K>

   * Hide/Show block
        - Editor command: `cmbSelRectHide'
        - Key: <^K-Shift+H>

   * Delete block and copy it to an special Clipboard
        - Editor command: `cmbSelRectCut'
        - Key: <^K-ShiftT>

   * Move block
        - Editor command: `cmbSelRectMove'
        - Key: <^K+Shift+V>

   * Copy to special Clipboard
        - Editor command: `cmbSelRectCopy'
        - Key: <^K-Shift+C>

   * Delete block
        - Editor command: `cmbSelRectDel'
        - Key: <^K-Shift+L>

   * Paste from special Clipboard
        - Editor command: `cmbSelRectPaste'
        - Key: <^K-Shift+P>

2.5 Pseudo Macros
=================

  This feature is very useful to save some keystrokes, with this feature you
can create a lot of shortcuts to make your life easiest.

2.5.1 Please enlight me - what is that?
---------------------------------------

  So now, What's a Pseudo Macro?, It's like a macro but is triggered but two
things: one the text behine the cursor and two the Shift+Space convination.

  And What's the result?, the result is customizable, but by default there are
some predefined behaviours for example, type in a new window the following
two letter: #i and the press Shift+Space ...

  Surprised?, I bet, you got: #include <.h> and the cursor just in the right
place to write the name of the header.

Now write the famous stdio word, press End, then Enter twice and now write
the following two letters: ma and then Shift+Space ...

  I bet that this time you predicted better what will happend so you aren't so
surprised ;-), anyways Surprise!, now type pr and the magic keys and ....
printf(""); appears, to end the happy history now type Hello world!, that's
all you writed the hello world program at a very good speed.

  Now you know what I mean when I say pseudo-macros.

2.5.2 How can I customize that?
-------------------------------

  Is very easy there is a file called `pmacros.txt' in the same directory where
you started the editor, this file contains the definitions for each pseudo
macro, you can define up to 32 pseudo macros (Please tell me if that isn't
enough I can sacrify some time to make it dinamically expandable).

  The pmacros.txt file is a very good example and is self-explained but I'll
include here one example.

Trigger: "i("
Mode: 0,1,0,1,0
 "if (@0)\n"
 "  {@1\n"
   "}\n"
 "\belse\n"
 "  {@2\n"
   "}"

  The Trigger keyword defines the two letter behine the cursor that will
trigger the pseudo macro.

  The Mode keyword indicates the mode that the editor will use when inserting
the text. The modes are:

   * Overwrite See Section 4.1

   * Autoindent See Section 4.2

   * Use Tabs See Section 4.3

   * Persistent blocks See Section 2.4.1

   * Inteligent C indent See Section 4.5

  Each mode can be 0 or 1. The editor will return to the original mode after
expanding the pseudo macro. In this case the macro is expanded in the No
overwrite, autoindent, don't use See Section 4.3, the blocks are persistent
and don't be smart when indenting mode.

  The rest is the code to insert surrounded by ". You can use \b to indicate
backspace, \n for newline and \\ to indicate a simple \. If you want to
insert a @ you have to type it twice @@, because this character has a special
meaning (see below).

  After the insertion the cursor is positioned in the place marked with @0,
don't forget to signal this point or the cursor will positioned at the
beggining of the file, the places marked with @1, @2 and @3 are saved in the
markers 7, 8 and 9.

2.6 Miscellaneous
=================

   * Autoindent mode on/off
        - Editor command: `cmbIndentMode'
        - Key: <^O>

   * Find place marker
        - Editor command: `cmbGotoMarkn'
        - Key: <^Q n*>

   * Set marker
        - Editor command: `cmbPutMarkn'
        - Key: <^K n*>

   * Search the { where the cursor is
        - Editor command: cmbSearchStart
        - Key: <^[>

   * Search the } where the cursor is
        - Editor command: cmbSearchEnd
        - Key: <^]>

   * Search the ( where the cursor is
        - Editor command: `cmbSearchOpPar'
        - Key: <Shift+^9>

   * Search the ) where the cursor is
        - Editor command: `cmbSearchClPar'
        - Key: <Shift+^0>

   * Search the [ where the cursor is
        - Editor command: `cmbSearchOpCor'
        - Key: <Shift+^[>

   * Search the ] where the cursor is
        - Editor command: `cmbSearchClCor'
        - Key: <Shift+^]>

   * Undo
        - Editor command: `cmbUndo'
        - Key: <Alt+Backspace>

   * PMacro's Trigger
        - Editor command: `cmbExpandCode'
        - Key: <Shift+Space>

   * Goto Line
        - Editor command: `cmbGotoEditorLine'
        - Key: <^J>

   * Set the options of the current window (Not in RHIDE)
        - Editor command: `cmbSetLocalOptions'
        - Key: <Alt+L>

   * Set the default options (Not in RHIDE)
        - Editor command: `cmbSetGlobalOptions'
        - Key: <Alt+G>

   * Convert all tabs in spaces
        - Editor command: `cmbExpandAllTabs'
        - Key: <From menu>

   * Compact the text using tabs
        - Editor command: `cmbCompactBuffer'
        - Key: <From menu>

   * Start recording a macro
        - Editor command: `cmbRecordMacro'
        - Key: <Shift+F10>

   * Stop recording a macro
        - Editor command: `cmbStopMacro'
        - Key: <Alt+F10>

   * Play a macro
        - Editor command: `cmbPlayMacro'
        - Key: <^F10>

3. Keyboard
***********

  The editor uses the scancodes of the keys to trigger the different commands,
you can reconfigure wich key triggers some command. In addition some non US
keyboards can mess the commands so you could need to configure the editor for
your keyboard.

3.1 How to configure the keyboard
=================================

  There are three associated files with the keyboard: `keybind.cc', `keybind.h'
and `keybind.txt'.

  The `keybind.h' file contains the scancode number for each key and the number
for each command, this file is included in `keybind.cc'. If your keyboard
have a different assigment you can modify the scancodes in this file, for
example: The german keyboards have the following sequence QWERTZ instead of
the more common QWERTY, so each time you press ^Z you won't get the function
of ^Z, but ^Y instead. Somebody can live with it, but is fixable.  To fix
this problem you must correct the scancode of the Z key in keybind.h, of
course that this affects to ^Y too. That's only an example, the most common
problem is with the symbols like {, }, [, etc.  If you don't know how to find
the scancode of a key take this link See Section 3.2.

  The `keybind.cc' file is a C++ file but you don't need to compile it and link
with the editor, you only need to preprocess it (I used this methode to save
the time needed to make a parser ;-).

  To convert this file into a `keybind.txt' file use:
  cpp keybind.cpp > keybind.txt
  Where cpp is the C++ preprocessor. You can use any of the comment systems
available in C++ inside the file.
I guess that you have cpp, but if not you can use another C++ preprocessor or
even Clipper using the /P switch.

  There are 7 sections in the file, each section is the keyboard translation
under certain situation.
  The sections are:

   * NORMAL    The normal case.

   * SHIFT    Shift plus a key.

   * CONTROL    Control plus a key.

   * SHIFT_CONTROL    Shift plus control plus a key (all at the same time).

   * QUICK    A key after ^Q or wherever you defined as `cmbCtrlQ'.

   * BLOCK    A key after ^K or wherever you defined as `cmbCtrlK'.

   * BLOCK_SHIFT    A key plus shift after ^K or wherever you defined as
     `cmbCtrlK'.

   In each section you must put the keyboards and the command asociated to it.
   Use the following syntax:

   Scan_Code = Command

   Not all the scan codes are available, for example you can't put:

   RSHIFT = xxxxx

   Look the keybind.h to see the scan codes labels and the available commands.

Important Notes:
I)
  The new assignments are mixed with the original assignments, so if you want
to eliminate an old key combination you *must* assign a `cmbNoCommand' to
this key, for example is you wish eliminate the BACKSPACE key and use the ^O
instead you must:
a) put `BACKSPACE = cmbNoCommand' in the NORMAL section.
b) put `O = cmbBackSpace' in the CONTROL section,
  If you only put the b) you'll not eliminate the BACKSPACE key.

II)
  If some thing is wrong in the `KEYBIND.TXT' file the program will inform the
error, the line number is for the `KEYBIND.TXT' and not for `KEYBIND.CPP'
(sorry some day I'll fix this).
  To continue the execution press any key and then enter.

III)
  You can repeat an assignment, the last win:

     BACKSPACE = cmbNoCommand
     BACKSPACE = cmbBackSpace

  The first is ignored

3.2 A program to find the scancodes
===================================

  The author of the following program is Robert Hhne:

#include <stdio.h>
#include <dos.h>

#ifdef __GNUC__
#include <dpmi.h>
#define REGS __dpmi_regs
#define INTR(nr,r) __dpmi_int(nr,&r)
#else
#define REGS union REGS
#define INTR(nr,r) int86(nr,&r,&r)
#endif

unsigned short getshiftstate(void)
{
  REGS r;
  r.h.ah = 0x12;
  INTR(0x16,r);
  return r.x.ax;
}

unsigned short gkey(void)
{
  REGS r;
  r.h.ah = 0x10;
  INTR(0x16,r);
  if (r.h.al == 0xE0 || r.h.al == 0) r.h.al = 0;
  return r.x.ax;
}

main()
{
  unsigned short key;
  do
  {
    key = gkey();
    fprintf(stdout,"%04X, scan code: %d\n",key,key>>8);
  } while (1);
}

4. Edition Modes
****************

  The editor have 9 settings that controls the edition and the aspect of the
editor. Not all can be controlled by RHIDE Beta 6 release 22/10, and I don't
know if all the settings will be supported in the 1.0 release so if you don't
find some setting in RHIDE and you feel that setting is really needed contact
me.

  The settings are:

4.1 Overwrite
=============

  This setting controls if the typed characters are inserted in the buffer or
if the typed characters replaces the original ones, see See Section 2.3 for a
detailed explanation.

4.2 Autoindent
==============

  This setting controls what happend when you press <ENTER>, if this setting is
off the cursor goes to the column 1 of a new inserted line. If the mode is on
the editor will try to keep the indentation of the code inserting spaces.

4.3 Real Tabs
=============

  This setting controls what happend when you press <TAB>, if this setting is
on the editor will insert an ASCII 9 in this place.

  An ASCII 9 is a TAB, that means that the width of this char is enough to move
the cursor to the next tabulator column. In the editor the tabulator columns
are equidistant and the positions are controled by the Tab Size value.

  If this setting is off the editor won't put any ASCII 9 in your text, instead
the editor will insert enough spaces to move the cursor to the next
tabulator, but if the cursor is positioned on the first character of the line
the editor will insert spaces to move this position to the next hole in the
line over the line where you are. Confused?, sorry for my english, an example
will clarify that:

This is a line over the line where you are

That's the line where the cursor is, at column one.

  After pressing TAB you'll get:

This is a line over the line where you are

     That's the line where the cursor is, at column one.

  Now can ask, why this? Is that useful?, the answer is that's very useful to
keep your code indented, experiment using that under a line with if, for, etc.

  Another thing controlled by this setting is the behaviour of the <Backspace>
key, when the setting is on the key is just 'delete the character at the left
of the cursor' but when the setting is off this key is the 'Unindent' key.

  The editor is much more coherent when you choose to use TABs or not use tabs,
if you mess the two things you'll get some unexpected things, specially in
the indentation of the blocks.

  Is better is you ever works in a file without tabs and with this setting of,
then you'll get much from the editor.

  Now you can say: But I really need tabs because I'm editing a make file! or
because I'll send the file using an ultra slow link and I want the compression
granted by the tabs. In these cases you can first expand all tabs, then work
without real tabs and at the final of your work compact all possible spaces
and generate a file with all the tabs that you need see the See Section 2.6
section.

4.4 Persistent Blocks
=====================

  This setting controls the behaviour of the selected area.

  See the chapter See Section 2.4.1 for a detailed explanation.

4.5 Inteligent C indent
=======================

  This mode was designed to be used in joint with the Pseudo Macros (See
Section 2.5) and the Real Tabs mode in off to achieve an easy way to indent
the code making a better work than the Autoindent mode.

  In this mode the spaces inserted after pressing <ENTER> depends on the first
word in the last line, for example, if you have:

     if (a==b)_

  With the cursor in the '_' position and press <ENTER> you'll get:

     if (a==b)
       _

  Now you can do two things, 1) press space and write the code that will be
executed by the if, or 2) if this a multiline code press { and <ENTER>, in
the last case you'll get:

     if (a==b)
       {
        _

  Now type your first line of code, press <ENTER>, write your next line, press
<ENTER> again and then Backspace:

     if (a==b)
       {
        1st line;
        2nd line;
       _

  Now type } and press <ENTER> one more time:

     if (a==b)
       {
        1st line;
        2nd line;
       }
     _

  As you can see the code is perfectly aligned without a significant work from
your part.

  I tried to make this mode as smart as possible, but needs more work, if you
have suggestions contact me.

  Another important thing is that this indentation have a personal style, mine
style ;-), so may be you don't like it. If that's your case you can do the
following things:

   * Use another way of indentation offered by the editor, for example, turn
     on the Real Tabs mode and indent with tabs.

   * Customize the pmacros.txt file (See Section 2.5), actually this file is
     coherent with this mode.

   * The editor isn't configurable like Emacs or Brief using a language, but
     is writed in C++ and chances that you know C++ are over the 90% so
     contact me and I'll help you to write the routines that you need to get
     an indentation in your own style :-).

4.5.1 Can you explain me more about the behaviour of this mode?
---------------------------------------------------------------

  I'll try to describe the behaviour of the mode:

  Each time you press <ENTER> the editor inserts a '\r\n' string in your text,
after that the editor searchs one line located above the new line that have
at least one character inside. This line is taked as reference, the editor
analizes this line searching for:

   * The first non blank character on this line.

   * The first word on this line.

   * The first parethesis.

   * The balance of parenthesis on the line.

   * The last non-blank and non-comment character in the line.

  Now, if the line contains { at the start the editor goes to the first column
after the {.

  If the line contains } at the start the editor will go to the same column of
the } and then will perform a <Backspace>, is the See Section 4.3 mode is off
that's an unindent.

  If the line starts with a C++ comment the effect is the same as in See
Section 4.2.

  If the line starts with a C comment the editor will try to skip the comment
and analize the rest of the line, but if the comment doesn't end on this line
the editor will go to the column where the / is.

  If the line starts with / the editor goes to this column.

  If the line have more ( than ) the editor will go to the column of the first
non-blank after the first (.

  If the line have more ) than ( the editor will search the line where the
number of parenthesis is balanced, then will analize this line, if the whole
line still generating an unbalanced situation the editor will go to the first
used column in the line that was found at first time. But if this line lets
all balanced the editor will take the first word on the line and will use it
as reference.

  At last, and according to the word founded, the editor will use this word as
reference. The editor recognises the following keywords:

   * do: +2, no if ;

   * if: +2, no if ;

   * for: +3, no if ;

   * else: +2

   * case: +5

   * while: +2, no if ;

   * switch: +2

   * break: unindent

   * return: unindent

   * default: +5

  The numbers are how much spaces are added with refernce to the first letter
of the word. When 'no if ;' is specified means that if the line ends with a
semicolon the editor will make the same as See Section 4.2. The unindent is
performed with <Backspace>.

  Seasick? take a look at: See Section 4.5.2.

  Note: Some of these features was added in v0.2.14 of the editor based on a
suggestion of <Bradford L. Spencer,stud73@nortel.ca> about of the behaviour
of the mode on line like this 'printf("Num: %d",' and the rest of the
parameters in the next line.

4.5.2 Do you have more examples?
--------------------------------

  Well here are some examples, I used some strange convention, is like this: if
I say 'type a[ENTER]{' is type the a letter, then press <ENTER> and finally
press the { key.

Example 1: (Is similar to the explained before but is to show the convention)

     Type:
     if (a==1)[ENTER]{[ENTER]a=2;[ENTER]b=3;[ENTER][BACKSPACE]}[ENTER]
     
     You'll get:
     
     if (a==1)
       {
        a=2;
        b=3;
       }
     [<--- cursor here]

Example 2: A switch/case example

     Type:
     switch(a)[ENTER]{[ENTER]case 1:[ENTER]a=2;[ENTER]b=3;[ENTER]break;
     [ENTER]case 2:[ENTER]b=5;[ENTER]break;[ENTER][BACKSPACE]}[ENTER]
     
     You'll get:
     
     switch(a)
       {
        case 1:
             a=2;
             b=3;
             break;
        case 2:
             b=5;
             break;
       }
     [<--- cursor here]

Example 3: A call to a function that takes a lot of parameters

     Type:
     printf([SPACE]"Num: %d",[ENTER]a[SPACE]);[ENTER]
     
     You'll get:
     
     printf( "Num: %d",
             a );
     [<--- cursor here]

Example 4: A lot of parethesis

     Type:
     if[SPACE]([SPACE](a==1)[SPACE]||[ENTER](b==2)[SPACE]||[ENTER]
     c[SPACE])[ENTER]
     
     You'll get:
     
     if ( (a==1) ||
          (b==2) ||
          c )
       [<--- cursor here]

Example 5: Comment trying to interfer part 1

     Type:
     /*-a-*/for[SPACE](x=1;x;--x)[ENTER]
     
     You'll get:
     
     /*-a-*/for (x=1;x;--x)
               [<--- cursor here]

Example 6: Comment trying to interfer part 2

     Type:
     for[SPACE](x=1;x;--x);[SPACE]//-b[ENTER]
     
     You'll get:
     
     for (x=1;x;--x); //-b
     [<--- cursor here]

 Note: Of course you can full the editor but as you can see is relative smart
;-).

4.6 Column cursor
=================

  This setting enables an strange feature of the editor, when this mode is on
the column where the cursor is is highlithed. This feature is very good to
check if some part of your code is aligned.

  If you like this mode but is very uncomfortable to be used all the time
contact me and if I get enough feedback I'll put this thing in a key to be
turned on/off quickly.

4.7 Row cursor
==============

  This setting is similar to the See Section 4.6 but acts on the row where the
cursor is. If you enable the two modes you'll get a cross on the screen
showing where the cursor is.

4.8 Match pair highligth
========================

  This mode acts showing the pairs of (/), [/] and {/} on the fly. Each time
you type one of these symbols the editor will search the matching pair, if
the editor finds it and the match is on the screen both will be highlithed,
if the match is outside the screen the editor will inform the position on the
status line, and if there is no match the editor will inform the situation in
the status line too.

  That's very usefull when you are typing complex parenthesis expressions or a
very nested code. You can use it in joint with the `cmbSearchStart',
`cmbSearchEnd', `cmbSearchOpPar', `cmbSearchClPar', `cmbSearchOpCor' and
`cmbSearchClCor' commands (See Section 2.6).

4.9 Syntax Highlight
====================

  The editor can make highlight the syntax of your code, the available modes
are:

   * No highlight, all the code is with the same color.

   * C/C++ Highlight.

   * Pascal Highlight.

   * Clipper Highlight.

  The kind of highlight is choosed automatically in RHIDE using the extention
of the file.

  The C/C++ highlight was designed for the GNU C compiler.

  The Pascal highlight was designed for the GNU Pascal compiler.

  The Clipper highlight was designed for the CA-Clipper 5 compiler.

5. How to contact me
********************

  If you have any suggestions or bug report contact me in the address showed in
the See Section 1.3 section.

5.1 Bugs
========

  If you find a bug please contact me, the Undo thing is the most complex one
and I know that needs some work on it.

  When reporting a bug please don't say me: Some times some strange thing
happend ..., try to find a pattern of the problem, what situation triggers
the problem, with wich file. Then send me the file and the description.

  When sending to me a file UUEncode it to avoid problems related with the
e-mail.

6. Index
********



* Autoindent: Section 4.2.
* Blocks: Section 2.4.
* Blocks - Rectangular: Section 2.4.4.
* Bugs: Section 5.1.
* Column cursor: Section 4.6.
* How to contact me: Chapter 5.
* Indentation: Section 2.4.3.
* Insert and Delete: Section 2.3.
* Inteligent C indent: Section 4.5.
* keybind.cc: Section 3.1.
* keybind.h: Section 3.1.
* keybind.txt: Section 3.1.
* Match pair highligth: Section 4.8.
* Movement: Section 2.2.
* Overwrite: Section 4.1.
* Persistent Blocks: Section 2.4.1.
* pmacros.txt: Section 2.5.
* Pseudo Macros: Section 2.5.
* Real Tabs: Section 4.3.
* Row cursor: Section 4.7.
* scan codes: Section 3.2.
* TABs: Section 4.3.
* Use Real Tabs: Section 4.3.

7. Index of key commands
************************



* Autoindent mode on/off <^O>: Section 2.6.
* Beginning of line <Home>: Section 2.2.
* Bottom of file <^Q-C>: Section 2.2.
* Bottom of window <^Q-X>: Section 2.2.
* Character left <Left arrow>: Section 2.2.
* Character right <Right arrow>: Section 2.2.
* cmbBackSpace <Backspace>: Section 2.3.
* cmbCharLeft <Left arrow>: Section 2.2.
* cmbCharRight <Right arrow>: Section 2.2.
* cmbClear <^Del>: Section 2.4.
* cmbCompactBuffer <From menu>: Section 2.6.
* cmbCopy <^Ins>: Section 2.4.
* cmbCopyBlock <^K-C>: Section 2.4.
* cmbCut <^K-Y>: Section 2.4.
* cmbDelChar <Del>: Section 2.3.
* cmbDelEnd <^Q-Y>: Section 2.3.
* cmbDelLine <^Y>: Section 2.3.
* cmbDelPrevWord <^Backspace>: Section 2.3.
* cmbDelStart <^Q-H>: Section 2.3.
* cmbDelWord <^T>: Section 2.3.
* cmbEndSelect <^K-K>: Section 2.4.
* cmbExpandAllTabs <From menu>: Section 2.6.
* cmbExpandCode <Shift+Space>: Section 2.6.
* cmbFirstLineInScreen <^Q-E>: Section 2.2.
* cmbGoBeginBlock <^Q-B>: Section 2.4.
* cmbGoEndBlock <^Q-K>: Section 2.4.
* cmbGotoEditorLine <^J>: Section 2.6.
* cmbGotoMarkn <^Q n*>: Section 2.6.
* cmbHideSelect <^K-H>: Section 2.4.
* cmbIndentBlk <^K-Tab>: Section 2.4.3.
* cmbIndentBlkOne <^K-I>: Section 2.4.3.
* cmbIndentMode <^O>: Section 2.6.
* cmbInsMode <Ins>: Section 2.3.
* cmbLastLineInScreen <^Q-X>: Section 2.2.
* cmbLineDown <Down arrow>: Section 2.2.
* cmbLineEnd <End>: Section 2.2.
* cmbLineStart <Home>: Section 2.2.
* cmbLineUp <Up arrow>: Section 2.2.
* cmbMarkLine <^K-L>: Section 2.4.
* cmbMarkWord <^K-T>: Section 2.4.
* cmbMoveBlock <^K+V>: Section 2.4.
* cmbNewLine <Enter>: Section 2.3.
* cmbPageDown <PgDn>: Section 2.2.
* cmbPageUp <PgUp>: Section 2.2.
* cmbPaste <Shift+Ins>: Section 2.4.
* cmbPlayMacro <^F10>: Section 2.6.
* cmbPutMarkn <^K n*>: Section 2.6.
* cmbReadBlock <^K-R>: Section 2.4.
* cmbRecordMacro <Shift+F10>: Section 2.6.
* cmbReplaceSelect <Shift+^Ins>: Section 2.4.
* cmbScrollDown <^Z>: Section 2.2.
* cmbScrollUp <^W>: Section 2.2.
* cmbSearchClCor <Shift+^]>: Section 2.6.
* cmbSearchClPar <Shift+^0>: Section 2.6.
* cmbSearchOpCor <Shift+^[>: Section 2.6.
* cmbSearchOpPar <Shift+^9>: Section 2.6.
* cmbSearchStart <^[>: Section 2.6.
* cmbSearchStart <^]>: Section 2.6.
* cmbSelLength <^Q-L>: Section 2.4.
* cmbSelRectCopy <^K-Shift+C>: Section 2.4.4.
* cmbSelRectCut <^K-ShiftT>: Section 2.4.4.
* cmbSelRectDel <^K-Shift+L>: Section 2.4.4.
* cmbSelRectEnd <^K-Shift+K>: Section 2.4.4.
* cmbSelRectHide <^K-Shift+H>: Section 2.4.4.
* cmbSelRectMove <^K+Shift+V>: Section 2.4.4.
* cmbSelRectPaste <^K-Shift+P>: Section 2.4.4.
* cmbSelRectStart <^K-Shift+B>: Section 2.4.4.
* cmbSetGlobalOptions <Alt+G>: Section 2.6.
* cmbSetLocalOptions <Alt+L>: Section 2.6.
* cmbSmartIndent <^Tab>: Section 2.4.3.
* cmbSmartUnIndent <Shift+^Tab>: Section 2.4.3.
* cmbStartSelect <^K-B>: Section 2.4.
* cmbStopMacro <Alt+F10>: Section 2.6.
* cmbTextEnd <^Q-C>: Section 2.2.
* cmbTextStart <^Q-R>: Section 2.2.
* cmbToLower <^K-O>: Section 2.4.
* cmbToUpper <^K-M>: Section 2.4.
* cmbUndo <Alt+Backspace>: Section 2.6.
* cmbUnIndentBlk <^K-Shift+Tab>: Section 2.4.3.
* cmbUnIndentBlkOne <^K-U>: Section 2.4.3.
* cmbWordLeft <^Left arrow>: Section 2.2.
* cmbWordRight <^Right arrow>: Section 2.2.
* cmbWriteBlock <^K-W>: Section 2.4.
* Compact the text using tabs <From menu>: Section 2.6.
* Convert all tabs in spaces <From menu>: Section 2.6.
* Convert to Lowercase <^K-O>: Section 2.4.
* Convert to Uppercase <^K-M>: Section 2.4.
* Copy the selected block <^K-C>: Section 2.4.
* Copy to Clipboard <^Ins>: Section 2.4.
* Copy to special Clipboard <^K-Shift+C>: Section 2.4.4.
* Delete block <^Del>: Section 2.4.
* Delete block <^K-Shift+L>: Section 2.4.4.
* Delete block and copy it to an special Clipboard <^K-ShiftT>: Section 2.4.4.
* Delete block and copy it to the Clipboard <^K-Y>: Section 2.4.
* Delete character to left <Backspace>: Section 2.3.
* Delete line <^Y>: Section 2.3.
* Delete the character under cursor <Del>: Section 2.3.
* Delete to end of line <^Q-Y>: Section 2.3.
* Delete to start of line <^Q-H>: Section 2.3.
* Delete word at left <^T>: Section 2.3.
* Delete word at right <^Backspace>: Section 2.3.
* End of line <End>: Section 2.2.
* Find place marker <^Q n*>: Section 2.6.
* Goto Line <^J>: Section 2.6.
* Hide/Show block <^K-H>: Section 2.4.
* Hide/Show block <^K-Shift+H>: Section 2.4.4.
* Indent block <^K-Tab>: Section 2.4.3.
* Indent block one position adding an space <^K-I>: Section 2.4.3.
* Insert line <Enter>: Section 2.3.
* Insert mode on/off <Ins>: Section 2.3.
* Line down <Down arrow>: Section 2.2.
* Line up <Up arrow>: Section 2.2.
* Mark line <^K-L>: Section 2.4.
* Mark word <^K-T>: Section 2.4.
* Move block <^K+Shift+V>: Section 2.4.4.
* Move block <^K+V>: Section 2.4.
* Move to beginning of block <^Q-B>: Section 2.4.
* Move to end of block <^Q-K>: Section 2.4.
* Page down <PgDn>: Section 2.2.
* Page up <PgUp>: Section 2.2.
* Paste from Clipboard <Shift+Ins>: Section 2.4.
* Paste from special Clipboard <^K-Shift+P>: Section 2.4.4.
* Play a macro <^F10>: Section 2.6.
* PMacro's Trigger <Shift+Space>: Section 2.6.
* Read block from disk <^K-R>: Section 2.4.
* Replace the block by the Clipboard block <Shift+^Ins>: Section 2.4.
* Report the length of the block <^Q-L>: Section 2.4.
* Scroll the screen one line down <^Z>: Section 2.2.
* Scroll the screen one line up <^W>: Section 2.2.
* Search the ( where the cursor is <Shift+^9>: Section 2.6.
* Search the ) where the cursor is <Shift+^0>: Section 2.6.
* Search the [ where the cursor is <Shift+^[>: Section 2.6.
* Search the ] where the cursor is <Shift+^]>: Section 2.6.
* Search the { where the cursor is <^[>: Section 2.6.
* Search the { where the cursor is <^]>: Section 2.6.
* Set beginning of block <^K-B>: Section 2.4.
* Set beginning of block <^K-Shift+B>: Section 2.4.4.
* Set end of block <^K-K>: Section 2.4.
* Set end of block <^K-Shift+K>: Section 2.4.4.
* Set marker <^K n*>: Section 2.6.
* Set the default options (Not in RHIDE) <Alt+G>: Section 2.6.
* Set the options of the current window (Not in RHIDE) <Alt+L>: Section 2.6.
* Smart Indent block <^Tab>: Section 2.4.3.
* Smart Unindent block <Shift+^Tab>: Section 2.4.3.
* Start recording a macro <Shift+F10>: Section 2.6.
* Stop recording a macro <Alt+F10>: Section 2.6.
* Top of file <^Q-R>: Section 2.2.
* Top of window <^Q-E>: Section 2.2.
* Undo <Alt+Backspace>: Section 2.6.
* Unindent block <^K-Shift+Tab>: Section 2.4.3.
* Unindent block one character - not an x position <^K-U>: Section 2.4.3.
* Word left <^Left arrow>: Section 2.2.
* Word right <^Right arrow>: Section 2.2.
* Write block to disk <^K-W>: Section 2.4.

