SET's Editor documentation for Version 0.5.4

September 2004

This is the documentation for SET's Editor.

Copyright © 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Salvador Eduardo Tropea

This documentation may be freely distributed, provided this copyright notice is left intact on all copies.

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.

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 develop the editor (alphabetically sorted):

• Andris Pavenis (with a lot of patches and reports)
• Bernd Becker (with a lot of corrections to this text)
• Burton Radons (with the new calculator, bug reports and ideas)
• Frank Donahoe (with a lot of corrections to this text)
• Grzegorz Adam Hankiewicz (with tests and a lot of ideas)
• Ivan Baldo (Debian packages, tests and a lot of ideas)
• Marek Habersack (with tests and a lot of ideas)
• Molnar Laszlo (with the old calculator, tests and a lot of ideas)
• Robert Höhne (with some base routines, a lot of patches and reports)

This editor is included in the Robert Höhne's RHIDE as a replacement for the original Turbo Vision's editor class.

The editor is distributed under the GPL license:

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

1.2 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. Currently I'm trying to make it more general so it's useful not only for programming

The editor was designed to be very similar to the DOS standard editors for C, especially to Borland's IDE editor. The editor supports a lot of WordStar style commands plus some CUA commands, so if you have used any editor that uses these kinds of commands you'll find my editor very familiar. On the other hand if you have never used a DOS editor, especially if you use VI on UNIX machines you'll feel lost. In this case you may want to configure the keyboard. How to configure the keyboard .

1.3 About the Author

     E-Mail: Salvador Eduardo Tropea
     
     Telephone: (+5411) 4759-0013
     Postal Address:
     Salvador E. Tropea
     Curapaligüe 2124
     (1678) Caseros - 3 de Febrero
     Prov: Buenos Aires
     Argentina

Here is a list of what can be configured to customize the editor input.

• The keyboard can be configured Keyboard configuration .
• The keyboard can be also configured using sLisp command. sLisp macros .
• The menues be also configured. Menues configuration .
• The shortcuts displayed at the bottom of the screen are called status bar and can be configured in the same way menues are configured. Menues configuration .
• The small menu that pops up when you right click on editor windows is also configurable using the menu configuration. Menues configuration .
• You can define some abbreviations that can then expanded using ^Space. They are language sensitive and they are called pseudo-macros or pmacros. Pseudo Macros .
• You can ask the editor to record a group of operations and then reproduce them. This is what this documentation calls a macro. The operations to record and play macros can be found in the Macro menu ( Macro ). You can also generate the sLisp code for a macro and store it in the macros.slp file to use it from the menues or just bind it to a key.
• If you want to automate more complex operations you can use sLisp macros. They use a very simple language that is quite similar to Lisp or Scheme languages. sLisp macros . sLisp macros can be called using the Macro|Choose... or Macro|Repeat menu options. You can also add menu entries that start certain sLisp macro or bind a sLisp macro to a key. Additionally you can bind a small piece of sLisp code to a key or menu entry.

Here are some things you can change to ajust how the editor looks.

• The colors used for different elements of the editor can be customized using the Tool&Ops | Options | Colors | Customize... menu option. Customize Colors .
• Some predefined color schemes are available in the Tool&Ops | Options | Colors | Theme... menu option. You can contribute your own color scheme sending me you desktop file (desktop files have .dst as extension). Color Theme .
• The color palette can be customized using the Tool&Ops | Options | Colors | Palette... menu. This is available for most OSs and terminals, but not for all. Color Palette .
• The character encodings used by the editor can be also configured. This is in the Tool&Ops | Options | Encodings... menu. Encodings .
• Some terminals supports changing the screen or window size. This is in the Tool&Ops | Options | Screen Options... menu. Screen Options .
• Some terminals supports changing the font and/or the font size. The editor includes various fonts suitable for it. This is in the Tool&Ops | Options | Fonts... menu. Fonts .

The editor highlights different elements in the code using different colors here are things you can do to modify it.

• The colors used for it can be configured. What can be configured to change the look of the editor .
• The syntax highlighting can be configured and/or extended editing the syntaxhl.shl file. Syntax Highlighting File .
• You can define some words as special words. An example of use is to highlight your own data types. They are called user words and you can define them for each supported syntax highlighting. User Words .

When coding you usually need to access to help files describing the language reference or you need to search in your files. This is a list of the most important tools for it.

• If the language and/or library you are using have documentation in the info format (the format used by the GNU project for on-line documentation) you can configure the editor to search the syntax of a command when pressing ^F1. Syntax help .
• You can browse info files using the InfView info browser. The editor also have a man page viewer. Both can be accessed from the Help menu. Help .
• The editor have a search and replace dialog that supports regular expressions and also supports replacement using templates. The Search | Find ( Find ) and Search | Replace ( Replace ) menu entries are used for it.
• You can search for text using regular expressions. The Powered Grep dialog allows searching in project items and directories, also recursivelly. Grep .
• Using tag files the editor can search for definitions, do word completion and browse classes. TAGS files .
• For some languages the editor can parse your code and extract the function definitions. Jump to function .

You can run external programs to compile, apply filters or any other thing. Here are some related options.

• You run a external program using Tool&Ops | Run program menu option ( Run program ). To configure it you can use the Tool&Ops | Options | Run program (which one) menu option ( Run program (which one) ).
• The editor collects the messages from the external program and displays them in the message window. Message Window .
• The editor parses the messages from the external program looking for errors. The parser can be selected using the Tool&Ops | Options | Run program (which one) menu option. You can add your own parsers editing the errors.cle file. Error messages from an external application .
• You can call external programs binding a sLisp macro to a key or menu entry. sLisp macros , Keyboard configuration , Menues configuration .
• You can also call external filters using sLisp macros. Writing macros that use text filters .

Here is a list of the most important configuration files.

• The editor can read configuration files from various directories. Configuration files location .
• syntaxhl.shl configures the syntax highlghting. Syntax Highlighting File .
• pmacros.pmc and other .pmc files are used to configure the pmacros (pseudo-macros). Pseudo Macros .
• errors.cle configures the error parsers. They are used to collect error messages from external programs. Error messages from an external application .
• macros.slp defines the available sLisp macros. sLisp macros .
• userword.txt defines the user reserved words for syntax highlighting. User Words .
• deflopts.txt configures the default edition options for each syntax highlighting style. Default global edition .
• nobkp.txt configures for which files the editor won't create back-ups. Do not create backups for .
• tcedit.dst and other .dst files. They are desktop files and contains information about opened windows and configuration options. They can be local (one per directory) or global (one for all the system). Projects also have its own desktop file. The format is binary.
• .epr files. They are project files. The format is binary.
• keybind.dat contains keyboard binding information. The format is binary.
• setenvir.dat contains some global settings in binary form.

Read the conventions topic first to understand my way of indicating 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.

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 doesn't have any effect used alone inside of the editor so the ^ symbol will be used only in conjunction with the name of a 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 A after Ctrl.

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

To indicate keys pressed at the same time other than ^x I'll use a plus. For example, Shift+^Insert is the three keys at the same time!

I don't think that you are stupid; the editor is written for programmers, but I wanted to make that clear to avoid problems ;-).

3.2 Cursor movement

3.4 Blocks

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

There are two block modes. One is the mode that the old editor of RHIDE used. This mode is used in CUA programs. The other is called Persistent Blocks.

In the normal mode each time you select a block and then insert anything in it (with cmcPaste or by 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 lost when you move the cursor. From this comes the name "Persistent." In this mode you can use cmcMoveBlock and cmcCopyBlock without using the Clipboard. In addition you can apply indentations to the block ( Indentation ), search only inside it, etc. That's what 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 cmcReplaceSelect command to achieve the same in the Persistent Blocks mode.

3.4.2 Selecting with the mouse or Shift

The described commands for selecting a block, cmcStartSelect and cmcEndSelect, are good but not so quick. There are other ways to do this.

Using the mouse you need only point to the start place, and while pressing the left button moving the mouse to the end point of your block.

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

3.4.2.2 Using the Shift key

Using the Shift key you only need to move the cursor to the start point, keep Shift pressed and move the cursor to the end point with any of the available cursor commands. Cursor movement .

3.4.3 Indentation

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

cmcIndentBlk acts according to the mode. If you are using tabs, the editor will put one tab at the beginning of 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 on the entire block. Real Tabs .

cmcUnIndentBlk acts according to the mode too. Real Tabs . Just like cmcUnIndentBlkOne it deletes 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 by the resulting amount the rest of the block.

The following commands aren't applied to the whole block, they apply only to the line where the cursor is positioned.

       {
     line1
          line2
        line3
       }

       {
        line1
        line2
        line3
       }

3.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. That is the way it works!

You can also assing sLisp defined macros to keys or even small portions of sLisp code to keys. In addition you can change the key assignments using sLisp macros.

If you are looking for information about the names used for the keys in the editor consult: Key names .

These options are located under the menu option called Tool&Ops, submenu Options, submenu Keyboard, submenu Key assignment; yes is a little deep in the menu.

After selecting this option you'll get a window with the keyboard assignments. This window shows entries of the type Key sequence -> Command sequence. You can delete an assignment by selecting it and choosing the Delete button.

The list is sorted by a internal criteria. The keys with Shift have an S in front, for Ctrl you'll see a C and for Alt an A. The editor can distinguish the left and right Alt keys; if you enable it the right Alt will be represented by an a. Alt key configuration .

To add a new assignment press the Add button. A window called Sequence of keys will appear. This window is used to choose the sequence of keys that will trigger an action in the editor. The sequence can be as large as you want, so if you want to assign a sequence like this: ^A-Shift+^Insert-Alt+Z you can, but I doubt you really want to use such a complex combination even if the editor is flexible enough to allow it.

To add a new key to the sequence use the Add button, to delete a key use the Delete button. The Add button always adds a key to the end of the list; to insert a key in the sequence use the Insert button, it will insert the key before the selected key. Finally you can choose if you want to assign a sequence of commands or a sLisp macro to this key sequence. sLisp macros .

A window called Commands will appear. The mechanism to add, insert and delete commands is the same as used for a keyboard sequence. This time when you add or insert a new command to the sequence a window with all the available commands will pop-up. The meaning of each command can be found in the indices of this help.

To make a selection with the commands, like when holding Shift, you must use the SelectOn and SelectOff commands. For an example you can take a look at the assignments for the Shift+Left or Shift+Right keys.

4.1.2 Assigning a sLisp macro

A window called Macros will appear. This window shows all the macros defined in the macros.slp file. sLisp macros .

The main advantage of using macros instead of command sequence is that macros can insert text in your code.

4.1.3 Assigning sLisp code

A window called sLisp code will appear. This window shows allows entering a small portion of sLisp code. For long code use define a macro. sLisp macros .

The sLisp code must start with ( and end with ) or you'll get parser errors.

4.2 Alt key configuration

The editor can distinguish the left and right Alt keys. As old versions didn't allowed that and as different users use different Alt keys the editor doesn't make any difference between them anymore by default.

The Setup Alt keys menu option (under Tool&Ops | Options | Keyboard) allows to enable it. Three options are offered:

If you need to restore the original keyboard assignment because you did something very wrong you can use this option for that. The option is located under Tool&Ops | Options | Keyboard.

4.4 Consulting scan codes

If you need to know the scan code of a key for your program you don't need to use a table or another program. The editor has a tool built in that shows scancodes for keypresses under Tool&Ops | Options | Keyboard.

If you need or want to configure the shortcuts activating the menues or menue options look at the menubind.smn file. The format is self explanatory and the editor supports syntax highlighting for these files. Menues configuration .

This menu contains the file operations (save, load, print, etc.) and the program exit functions.

This option brings the file open dialog ( File Open ). From this dialog you can select a file to load and edit.

Choose the Open button or select a file with Enter to open the file. Use Esc to abort.

If the file is read-only a dialog will ask you if you want to make the file writable, in this case the editor will try to change the file attributes. Not always is it possible to change these attributes, as for example, the CDs are read-only and obviously you can't change files on them.

Name of the command: cmeOpen. Assigned key: F3

5.1.2 New

Use this option to create a new and empty editor window. The window's name will be Untitled.

An alternative way to do it is just using the Open option and give a new name instead of selecting an existing file. Open . The advantage of this method is that the new window already has a meaningful name, instead of having to save the file first.

Name of the command: cmeNew.

5.1.3 Open Read-only copy

Use this option to open a copy of the file you are editing in another window.

Be careful, the new copy is loaded from disk so it may be unsychronized. The copy will automatically become read-only so you won't be able to modify it and accidentally overwrite the first copy.

For more information: Editor General .

Name of the command: cmeOpenROCopy.

5.1.4 Save

This option saves the contents of the current window. Only the contents of this window are saved; not anything else. Additionally it only saves if the window was modified.

If the window is named Untitled this command acts like Save as .

Name of the command: cmcSave. Assigned key: F2

5.1.5 Save as

This option allows to save the contents of the current window specifying a new name for the file. For this purpose the file open dialog is used ( File Open ).

If the file already exists a dialog will pop-up asking for confirmation to overwrite the existing file.

The title of the window is changed to reflect the new file name.

Name of the command: cmcSaveAs.

5.1.6 Save as UNIX or DOS

This menu entry says Save as UNIX for DOS or Win32 systems and Save as DOS for UNIX systems.

This option is very similar to the Save as option ( Save as ). The only difference is that the editor will change the end of line character.

Additionally there is an option to save UNIX files as UNIX files without converting it to DOS style. Tool&Ops|Options|Editor General .

Name of the command: cmcSaveAsConvertEOL.

5.1.7 Save as DOS or UNIX

This menu entry says Save as DOS for DOS or Win32 systems and Save as UNIX for UNIX systems.

This option is useful when the editor is configured to save files without converting the end of line character and you want to force a convertion.

Name of the command: cmcSaveAsNoConvertEOL.

5.1.8 Save with same time

This option is very similar to the Save option ( Save ). The only difference is that the editor won't modify the creation time. This option is very useful to modify header files avoiding the recompilation of the whole project. A common case is when you only add constants to a header that is included by various files but only one will use the new constants.

Name of the command: cmcSaveSameTime.

5.1.9 Save all

All modified editing windows will be saved.

Name of the command: cmcSaveAll.

5.1.10 Print

This option prints the current editor window. Don't use this option without configuring the printer module. Print Setup .

This option was designed to print source files, to print plain text files or avoid all the formating features. Select the portion of text to be printed and save the block (^K-W) to a file with the name of the device to which your printer is connected. As an example to print to the DOS LPT 1 device just write the block to the lpt1 file.

The editor will report the number of lines processed and printed in the message window.

To learn more about the message window Message Window .

Name of the command: cmePrintEditor.

5.1.11 Print Setup

This option brings up a dialog to configure the printing module. After configuring it you can print using the Print option. Print . If you want to print a plain text (without formating) consult the Print option too.

The dialog asks for the following parameters:

• Total lines per page: The total number of lines that fits on one page including the footer and header lines.
• Columns w/o margin: The number of colums that fits on the page excluding the desired margin.
• Left margin: The number of columns left blank at the left side of the page.
• Print line numbers: Select this option to get the line numbers printed
• Time format: The time format specified in the C style. Time and date modifiers formats .
• Date format: The date format specified in the C style. Time and date modifiers formats .
• Title: only used in the header.
• Author: only used in the header.
• Output file: Specify the printer device here. For example: the DOS LPT 1 is the lpt1 file.
• Printer initialization: The sequence of character used to initialize the printer. Normally it includes a reset and a font selection. Specify the values separated by commas.
• Before heading: Commands to send before the header.
• After heading: Commands to send after the header.
• Before footer: Commands to send before the footer.
• After footer: Commands to send after the footer.

The Epson button fills the values with the default settings for Epson printers (ESCP2 language). The HP button fills the values with the default settings for Hewlett Packard ink-jet printers.

The printer module was designed by me some years ago when I needed to present a program at my University (Universidad Tecnologica Nacional) and I wanted to add to the source code listing a header, footer, lines number, page number, date/time of the printing, project and author. So that's what the routines does. I know they are limited but they generate a very good listing, much better than just printing the text without any formating.

Name of the command: cmeSetUpPrinter.

5.1.12 Shell

Calls the default command interpreter indicated by the COMSPEC enviroment variable. I guess you know that by typing exit you'll get back to the editor.

Name of the command: cmeDosShell.

5.1.13 Quit

This option exits the editor deleting all the back-up, desktop and project files located in the current directory. That's useful if you want to keep the directory clean.

When you use this option a dialog will appear asking for confirmation, you can avoid this dialog in the future by checking the "don't show again" option.

Name of the command: cmeQuitDelete. Assigned key: Alt+Q

5.1.14 Exit

This option just exits the program. The editor asks for each modified editor window if you want to save the changes. All the settings are stored in the desktop file automatically.

Name of the command: cmeQuit. Assigned key: Alt+X

5.2 Edit

This menu contains all the editing operations that have a menu shortcut.

This option reverts the last edit operation. Upto 32 operations can be reverted.

Name of the command: cmcUndo. Assigned key: Alt+BackSpace

5.2.2 Redo

This option takes back the last Undo. Undo .

Name of the command: cmcRedo.

5.2.3 Cut

The selected text is copied to the clipboard and deleted from the text. Clipboard .

Name of the command: cmcCut. Assigned key: Shift+Del

5.2.4 Copy

The selected text is copied to the clipboard. Clipboard .

Name of the command: cmcCopy. Assigned key: ^Ins

5.2.5 Paste

The text that's currently selected in the clipboard is inserted at the cursor position. Clipboard .

Name of the command: cmcPaste. Assigned key: Shift+Ins

5.2.6 Show clipboard

This option shows the clipboard window. Clipboard .

Name of the command: cmeShowClip.

5.2.7 Clear

Deletes the selected text. It isn't copied to the clipboard.

Name of the command: cmcClear. Assigned key: ^Del

5.2.8 Set Local

This option pops up the local configuration dialog. The values in this dialog are valid only for the current editor window.

The first group of options are related to the editing modes. Editing Modes .

The syntax highlight group of options allows to choose the type of highlight. Syntax Highlighting .

Additionally the window allows to indicate the tab size and the column where the wrap cuts the lines.

Name of the command: cmcSetLocalOptions. Assigned key: Alt+L

5.2.9 Set Global

This option pops up the global configuration dialog. The values in this dialog are used as default values. If you exit the dialog using the Ok button these values aren't applied to any of the editor windows, they just act as default values for newly opened and created files. If you exit the dialog using the To all button these values are applied to all the editor windows. To set the options for just one window Set Local .

The options are related to the editing modes. Editing Modes .

Additionally the window allows to indicate the tab size and the column where the wrap cuts the lines.

Name of the command: cmcSetGlobalOptions. Assigned key: Alt+G

5.2.10 Expand all tabs

This option converts all the tabs to spaces. Real Tabs .

The tabs are expanded to the current tab size, check this value before using this option.

Name of the command: cmcExpandAllTabs.

5.2.11 Compact text

This option converts spaces to tabs where possible. Real Tabs .

Be careful, if the tab size is too small the editor will generate tons of tabs, even in places where you may not want a tab.

Name of the command: cmcCompactBuffer.

5.2.12 Copy to Windows Clipboard

Copies the selected text to Windows' clipboard. Of course you must be running Windows to be able to use this ;-)). Don't expect this feature to work always though, as Windows has bugs in the WinOldAp module; which is used to provide this function.

There is a command called cmcCutClipWin you can use to cut a portion of text copying it to Windows' clipboard.

Name of the command: cmcCopyClipWin.

Name of the command: cmcCutClipWin.

5.2.13 Paste from Windows Clipboard

Pastes the Windows' clipboard content at the cursor's position. Of course you must be running Windows and have some text in the clipboard. Don't expect this feature to work always though, as Windows has bugs in the WinOldAp module; which is used to provide this function.

Name of the command: cmcPasteClipWin.

5.2.14 Copy to file Clipboard

Copies the selected text to a special file used as clipboard. This option is usually available on UNIX as a replacement for the Windows clipboard functions. The file is created in a user specific directory, for this reason the information is only available to one user.

Name of the command: cmcCopyClipFile.

5.2.15 Paste from file Clipboard

Pastes text from a special file used as clipboard. This option is usually available on UNIX as a replacement for the Windows clipboard functions. The file is created in a user specific directory, for this reason the information is only available to one user.

Name of the command: cmcPasteClipFile.

5.2.16 Push cursor position

It stores the cursor position (x,y) in a stack. You can restore it later using Pop cursor position . The stack can hold up to eleven nested positions; if you try to push a 12th value the oldest is discarded.

Name of the command: cmcPushCursorPos.

5.2.17 Pop cursor position

It restores the cursor position (x,y) from a stack. You can store the position using Push cursor position . The stack can hold up to eleven nested positions; if you try to push a 12th value the oldest is discarded.

Name of the command: cmcPopCursorPos.

5.2.18 Case (Menu)

This submenu contains operations to convert blocks or single characters to uppercase or lowercase and similar operations

Converts all the selected characters to uppercase.

Name of the command: cmcToUpper.

5.2.18.2 Block to lower

Converts all the selected characters to lowercase.

Name of the command: cmcToLower.

5.2.18.3 Character toggle

Converts the character under the cursor to lowercase if it was uppercase and vice versa.

Name of the command: cmcToggleCharCase.

5.2.18.4 Block invert

Converts all the selected uppercase characters to lowercase and vice versa.

Name of the command: cmcInvertCase.

5.2.18.5 Block alternate

It will convert the first character to uppercase, the second to lowercase and so on. If you want the reverse you can use the command to invert a block. Block invert .

Name of the command: cmcAltCase.

5.2.19 Insert new line (do not move)

It inserts a new line character at cursor position but without modifying the cursor position. Note it doesn't apply indentation or other special things to the inserted line.

Name of the command: cmcInsertNewLine. Assigned key: Ctrl+N

5.3 Search

This menu contains the search and replace commands of the editor. The search function also includes advanced tools specifically designed for programmers, like the options to jump to a function definition or a symbol.

This command searches a string in the current editor. The dialog contains the following fields:

• Text to find: The text you want to find.
• Case sensitive: Use this option if the case of the text to search is important.
• Whole words only: When this option is set the editor searches for whole words. If not the text to search can be only part of a word.
• Regular expressions: Use this option if the text to search is a regular expression. A description of the syntax used by regular expressions can be found in the libc. Regular Expressions . Three types of regular expression are supported. Regular Expressions Options .
• Only inside comments: Matches will be returned only if the first character is inside a comment. Every type of comment supported by the syntax highlighting is supported. It doesn't have any sense for plain text.
• Only outside comments: Matches will be returned only if the first character is outside a comment. If the previous option is also enabled this option takes precedence.
• Scope - Global: The search will ignore the selected text.
• Scope - Selected text: The search will be done only inside the selected text.
• Origin - From cursor: The search will start from the position of the cursor.
• Origin - Entire scope: The search will start from the beginning of the text.

To repeat the search use the Search again command. Search again .

Name of the command: cmcFind. Assigned key: ^Q-F

This dialog is accessed from the RegEx Ops button in the Find or Replace dialogs. Here you can indicate some important options about the regular expressions:

RegEx style:

• Basic POSIX: old style POSIX regular expressions.
• Extended POSIX: new style POSIX regular expressions.
• Perl Compatible: Perl like regex, using the PCRE library.

• Normal text: the match is replaced by the text in the replace text area.
• Dollar tags: the text to replace is parsed searching for $n tags. These markers are replaced by the correspondent subexpression. If you know Perl that's just like using the $0, $1, etc. after a search. If you never used Perl and don't know what a subexpression is, just play a little and you'll get the idea; use $n where n is the desired subexpression.

• Try to use normal search: if the editor detects that the search string contains plain text will use a simple search even when regular expressions are enabled. That's about ten times faster.
• Ever use RegEx: the editor doesn't try to be smart and always uses what you selected.

This command searches portions of text and replaces it with another text. The options for the search are the same as in the Find command. Find . The additional replace options are:

• New text: The text used to replace the matching text.
• Prompt on replace: When this option is enabled the editor asks for confirmation before doing the replace.
• Replace all: Use it to replace all the possible ocurrences.

Name of the command: cmcReplace. Assigned key: ^Q-A

5.3.3 Search again

This option repeats the last search.

Name of the command: cmcSearchAgain. Assigned key: ^L

5.3.4 Name current function

It shows the name of the function at the position of the cursor in the status line of the window. It has the same limitations of the Jump to function option. Jump to function . Name of the command: cmcWhichFunctionIs. Assigned key:

5.3.5 Jump to function

his option opens a dialog with the list of functions in your source file you can choose to jump to. The functions are searched in the source file so you don't need to compile it. As the parser uses heuristics it may fail. For an option that uses a more reliable but also slower and complicated search see the Jump to symbol option. Jump to symbol .

The Browse button sends the list of functions to the message window so you can browse the list and visit each function. Message Window .

Currently only a few languages are supported, they are:

• C/C++
• Clipper 5.x
• Syntax Highlight Files
• Texinfo sources (chapters, sections, etc.)
• Assembler files (labels)
• PHP

     #ifndef MSI_USE_GETDELIM
        if (readPipe(textMsgPipe, id, buf, maxLen))
        {
           *buflen = strlen(buf);
     #else
        if ((bytes = readPipe(textMsgPipe, id, buf)) > 0)
        {
           *buflen = bytes - 2;
     #endif
         ....
        }

         ....
     #ifndef MSI_USE_GETDELIM
        }
     #else
        }
     #endif

5.3.6 Jump to prototype

This option pops up a dialog with the list of C function prototypes in your source file. You can then choose one to jump to. The prototypes are searched in the source file so you don't need to compile it. As the parser uses an heuristic approach it may fail, especially if your code has an odd number of curly brackets.

Name of the command: cmcJumpToPrototype.

5.3.7 Jump to symbol

This option uses TAGS files to search for symbols. In order to make it work you should read about TAGS files first. The editor will try to help you to generate the TAGS file if you don't have one. TAGS files .

The word to the left of the cursor will be used to start a search in the list of available symbols. You can make incremental searches in the list and pressing Enter the editor will jump to the symbol.

More about tags? TAGS files . Name of the command: cmeSearchTag. Assigned key: Ctrl+F2

5.3.8 Go to line

Allows you to indicate to which line you want to jump to.

Name of the command: cmcGotoEditorLine. Assigned key: ^J

5.3.9 Class browser

This option uses TAGS files to search for symbols. In order to make it work you should read about TAGS files first. The editor will try to help you to generate the TAGS file if you don't have one. TAGS files .^

First the editor will create an index of available classes from the TAGS files and then will do a search using the word to the left of the cursor. If an exact match was found the editor will go directly to browse this class, otherwise you'll get a list of available classes to choose one. You can make incremental searches in this list typing the first letters of the class name.

The main browser dialog contains three buttons offering different information about the selected class. They are:

• This class: shows a list of the members for this class. You can select any of them to jump to the member code or go back to the main dialog.
• This and parents: shows a list of the members for this class and all the parent classes. The members for this class are first, then come the members of the parents, then the members of the grandparents and so on. The information is more compact and you'll only see the name of the class where the member was found and the level (one for the parent, two for grandparents, etc.).
• Sorted: This option is the same as the previous but the list is alphabetically sorted.

More about tags? TAGS files . Name of the command: cmeClassBrowser.

5.3.10 Word completion

This option uses TAGS files to search for symbols. In order to make it work you should read about TAGS files first. The editor will try to help you to generate the TAGS file if you don't have one. TAGS files .

The word to the left of the cursor is used to perform a search in the list of available symbols. If a partial match is found a list of available symbols will pop-up. To select the symbol you want you can use the arrow cursors or continue typing until you reach the desired symbol. When you type Enter, Space or any symbol the select word will be inserted completing the word. Pressing Esc or Tab will abort the process.

More about tags? TAGS files . Name of the command: cmeWordCompletion. Assigned key: Alt+Right

5.3.11 Jump to last cursor position

This command moves the cursor to the position it was before the last movement. You can use it to go back after a search.

Name of the command: cmcJumpLastCursorPos. Assigned key: Ctrl+Q-P

5.3.12 Jump to last undo position

This command moves the cursor to the position it was before the last movement sequence. This is equivalent to undo the last group of movements.

Name of the command: cmcLastPosCur.

5.4 Macro

This submenu has the options to record and replay macros.

Starts recording all the operations you do in the current editor window.

Name of the command: cmcRecordMacro. Assigned key: Shift+F10

5.4.2 Stop (Macro)

Stops the macro recording.

Name of the command: cmcStopMacro. Assigned key: Alt+F10

5.4.3 Play (Macro)

Replays the saved macro. A macro saved in one window can be used in another.

Name of the command: cmcPlayMacro. Assigned key: ^F10

5.4.4 Choose (Macro)

This option lists all the available sLisp macros so you can choose one to execute.

To learn more about these macros: sLisp macros .

Name of the command: cmcChooseMacro.

5.4.5 Repeat (Macro)

It re-runs the last selected macro. Choose (Macro) . That's useful if the macro isn't assigned to a key and you need to use it several times.

To learn more about these macros: sLisp macros .

Name of the command: cmcRepeatMacro. Assigned key: Shift+F3

5.4.6 Generate Code

This option translates the recorded macro into an sLisp macro. The generated code is inserted at the cursor's position.

To learn how to record a macro: Record (Macro) .

To learn more about these macros: sLisp macros .

Name of the command: cmcGenCodeForMacro.

5.4.7 Run selected code

It interpretes the selected text as an sLisp macro.

Name of the command: cmcRunSel_sLisp.

5.4.8 Enter code to run

It asks for a text and interpretes it as an sLisp macro. The maximum length is one kilobyte.

Name of the command: cmcRunEnter_sLisp.

5.4.9 Pseudo Macro (menu)

It shows a list of all the pseudo macros available for the current syntax highlighting mode. The purpose of this option is just to show you what's available; of course you can choose any from the list but that's much slower than using them directly.

The letters enclosed in brackets are the triggers for the pseudo macro. To learn more about pseudo macros: Pseudo Macros .

Name of the command: cmcChoosePMacrosList.

5.5 Rectangle

This menu contains the rectangular block operations. As they are a bit hard to code and these functions are normally ignored by the users, I put them in a very visible menu.

Selects the top-left corner of the rectangular area.

To learn more about rectangular blocks: Rectangular Blocks .

Name of the command: cmcSelRectStart. Assigned key: ^K-Shift+B

5.5.2 End (Rectangle)

Selects the bottom-right corner of the rectangular area.

To learn more about rectangular blocks: Rectangular Blocks .

Name of the command: cmcSelRectEnd. Assigned key: ^K-Shift+K

5.5.3 Hide (Rectangle)

Hides the rectangular selection.

To learn more about rectangular blocks: Rectangular Blocks .

Name of the command: cmcSelRectHide. Assigned key: ^K-Shift+H

5.5.4 Copy (Rectangle)

Copies the rectangular selection into the clipboard. This clipboard isn't the same clipboard used by the normal selections and is overwritten each time you copy to it.

To learn more about rectangular blocks: Rectangular Blocks .

Name of the command: cmcSelRectCopy. Assigned key: ^K-Shift+C

5.5.5 Paste (Rectangle)

Inserts the contents of the rectangular clipboard at the cursor position.

To learn more about rectangular blocks: Rectangular Blocks .

Name of the command: cmcSelRectPaste. Assigned key: ^K-Shift+P

5.5.6 Cut (Rectangle)

Copies the rectangular selection into the clipboard and then deletes the selected text.

To learn more about rectangular blocks: Rectangular Blocks .

Name of the command: cmcSelRectCut. Assigned key: ^K-Shift+T

5.5.7 Clear (Rectangle)

Deletes the selected text.

To learn more about rectangular blocks: Rectangular Blocks .

Name of the command: cmcSelRectDel. Assigned key: ^K-Shift+L

5.5.8 Move (Rectangle)

Moves the selected text to the cursor's position.

To learn more about rectangular blocks: Rectangular Blocks .

Name of the command: cmcSelRectMove. Assigned key: ^K-Shift+M

5.5.9 To upper (Rectangle)

Converts all the characters inside the rectangle to uppercase. This operation basically does a cut of the block, then processes all the characters and finally makes a paste of the modified block. As a side effect of this operation tabs inside or crossing the rectangle boundaries are converted to spaces.

To learn more about rectangular blocks: Rectangular Blocks .

Name of the command: cmcSelRectToUpper.

5.5.10 To lower (Rectangle)

Converts all the characters inside the rectangle to lowercase. This operation basically does a cut of the block, then processes all the characters and finally makes a paste of the modified block. As a side effect of this operation tabs inside or crossing the rectangle boundaries are converted to spaces.

To learn more about rectangular blocks: Rectangular Blocks .

Name of the command: cmcSelRectToLower.

5.6 Windows

This menu contains the options to handle the windows in the editor.

You can resize the windows by dragging the bottom right corner of the window. You can move the windows by dragging the title line of the window.

Additionally this command allows the same operations to be done without the mouse. Once you entered in this mode the border of the window changes it's color and you can move the window using the arrow keys. To resize the window use the arrow keys holding the Shift. Furthermore Home, End, PgUp and PgDown can be used to move the window to one end of the desktop. When you're done you can end this mode by pressing ESC or ENTER.

Name of the command: cmeResize. Assigned key: ^F5

5.6.2 Zoom

Changes the size of the window to be as large as the whole desktop. The second time you use this command the window is resized to it's previous size. It's the equivalent of the maximize and restore options of other editors.

Name of the command: cmeZoom. Assigned key: F5

5.6.3 Tile

Arranges all the windows in a way that you can see all at the same time.

Name of the command: cmeTile.

5.6.4 Cascade

Arranges all the windows in such a way that they overlap.

Name of the command: cmeCascade.

5.6.5 Next (Window)

Selects the next window. The windows are linked in a circular list, this command selects the next window in the list. To change the order of the windows you can directly select a window with the mouse or ALT plus a number. That window will become the current one, and the other will be the previous window.

Use it to select the most recently used windows.

Name of the command: cmeNext. Assigned key: F6

5.6.6 Previous (Window)

Selects the previous window. The windows are linked in a circular list, this command selects the previous window in the list. To change the order of the windows you can directly select a window with the mouse or ALT plus a number. That window will become the current one, and the other will be the previous window.

Use it to select the most recently used windows.

Name of the command: cmePrev. Assigned key: Shift+F6

5.6.7 Close

Closes the current window. If the content wasn't saved the editor will ask if you want to.

Name of the command: cmeClose. Assigned key: Alt+F3

5.6.8 List

Pops up the List of Windows dialog. This dialog contains the list of all the editor windows, the special windows and the closed windows.

The editor windows are numbered starting from two and the list is sorted by number. If a window isn't saved an asterisk is placed between the number and the name.

The special windows are: the message window (the number of lines is indicated), the project window, the clipboard window (the bytes used by it is indicated) and the InfView windows.

The closed windows list is sorted alphabetically and holds the last closed windows. The editor stores important information about these windows so if you close and re-open one of them the size of the window and other values are restored.

You can jump to any of the windows by selecting it with the mouse, with the arrow keys and ENTER, double clicking, or by using the Go button.

A press of Delete or using the Delete button will delete the closed windows or close any open editor window.

Using the ReEnumerate button you can force to compute the window numbers so all become continuous.

Name of the command: cmeListWin. Assigned key: Alt+0

5.6.9 User Screen

Shows the DOS screen. Press any key to go back to the editor.

Name of the command: cmeUserScreen. Assigned key: Alt+F5

5.7 Tool&Ops

This menu contains all the configuration submenues and some useful tools.

This submenu contains the configuration submenues. You can find the local and global edition options in the Edit menu. Edit .

Some of the deeper submenues are explained here because the documentation tools limit how deep subsections can be nested.

This command allows to customize the colors used by the editor. Almost all the colors are configurable.

The first list, called Group, is the list of things used by the editor. Each entry in the group list has one or more colors in the Item list. First select the group you want to customize and then press Tab to move the cursor to the items list. To customize a color just select it in the list of items; the dialog will show a text example in the bottom right corner and the Foreground and Background colors will be indicated. Using the mouse or moving with Tab and using the arrow keys you can select any of the available colors; the sample text area will show the resulting combination.

Exiting the dialog with ENTER or with the Ok button the new colors will be applied. The colors are stored in the desktop file. If you are using one centralized desktop file these colors will be used each time you run the editor, if not the colors will be used only when you run the editor in that very same directory.

To learn more about the scope of the desktop files and how to indicate default values: Desktop Files .

If you want to use other colors not listed in this dialog you must customize the palette. Color Palette .

Name of the command: cmeSetColors.

5.7.1.2 Color Palette

This option allows to configure the palette of colors used by the editor. I think you know about palettes but I wrote a little explanation, just in case. Text mode attributes .

The Color radio buttons are used to select the index you want to customize. The Red, Green and Blue scroll bars can be used to customize the color. To modify one of the components use the mouse or use the R, G and B to increase the values and Shift+R, Shift+G and Shift+B to decrease the values.

Exiting the dialog with ESC restores the values you had before selecting this option. Choosing the Default button the colors are set to the default values of VGA cards.

These settings are stored in the desktop file. Desktop Files .

Name of the command: cmeEditPalette.

5.7.1.3 Color Theme

With this option you can choose from a list of predefined groups of colors.

Currently only a couple of color themes are available, users are encouraged to contribute their own themes.

Name of the command: cmeColorTheme.

5.7.1.4 Editor General

This will open the general configuration dialog containing several options.

The Save options groups control various settings about which and how files are created by the editor.

• Make backups: When enabled the editor keeps a backup of your files using the .bkp extension. It saved me many times.
• UNIX style backups: When enabled the backups are created appending a tilde symbol to the file extension. This is recommended only for systems that support long file names, not pure DOS.
• Hidden backups: The backups are created as hidden files, it can be used to keep backups, but at the same time make them less annoying.
• Remember bkps to delete: When you exit with Quit the editor deletes backup files. To do it the editor deletes files ending with bkp, but if you use UNIX style backups or just edit files in a directory other than the current it's hard to know where these files are located. For this reason the editor keeps a list of created backup files. If you exit normally this list is lost, so the next time you use the editor and exit with Quit only the backups created during this session will be deleted. This behavior can be modified choosing this option, when enabled the editor will store the list in the desktop file and retrieves it the next time you start the editor. By default this option is disabled because users that don't know about this mechanism and use a centralized desktop file could end up with a very long list of backup files, wasting memory and disk space.
• Don't create desktop files: When enabled the editor creates only one desktop file and not one per directory. Desktop Files .
• Save desktop files hidden: Just what the name says. That's useful if you want to create desktop files in each directory but don't want to see them in directory listings.
• Tile windows vertically first: It affects the Windows|Tile option. Normally this option starts splitting the screen by dividing the height of windows. When this option is selected the width is divided first.
• Save UNIX files as UNIX: When enabled the editor saves to disk UNIX files in UNIX format. That means that the conversion is done only internally and the format of the file on disk isn't altered when you save.
• Do not remember cursor position: If you enable it the editor won't remember the last cursor position of each editor window.
• Do not warn about read-only files: It disables the dialog that warns about opening read-only files. Disabling it you won't be asked about reverting the read-only attribute until you try to save the file.
• Open read-only files as R.O. buffers: When enabled the editor won't allow you to edit files with the read-only attribute. Note: it doesn't disable the warning, use the above mentioned option for this.

The Clock group allows to turn on/off the clock and to choose 24 hs or AM/PM style. The clock is displayed in the top right corner of the screen.

The Max. editor copies controls how many copies of the same file can be opened at the same time. By default the value is one, so when you try to open a file twice the editor will just show you the first copy. Specifying a value different than one will allow you to open more copies of the same file. Only the first copy can be modified and the rest are read-only snap-shots of the file. Note it only affects the number of read-only copies automatically created by the editor, you can open as many as you want using the File | Open Read-only copy menu option. For more information: Open Read-only copy .

The Max. closed to remember value specifies how many closed files are remembered in the list of windows. This value can't be less than three and can't be greater than two hundred. If you reduce this value and there are already more files remembered the editor won't reduce the number immediately, instead you must choose which files to remove by hand.

The + Desktop button opens a second dialog containing options about what is stored in the desktop files. Each section selects if the option will be remembered always (ever), only when no files are specified in the command line or never.

• Remember editor windows: it affects the opened files.
• Remember other windows: it affects other windows, like the help windows.
• Remember closed windows: it affects the list of closed files.

The + Others button opens a third dialog containing options to configure the behavior of the message window when the last or first error in the list is reached.

• Just stop: nothing particular is done, the editor just stops.
• Indicate with a message: a message indicating you reached the first or last pops up.
• Wrap (circular list): the list becomes a circular list. So when you reach the last message the editor jumps to the first and vice versa.
• Make a beep: a sound is generated.

• Use the vertical direction: message and project windows are vertically oriented. By default they are positioned at the left side. When this option is selected the project window has only one column.
• Use the right side: use the right side of the screen instead of the left side. That's used only when the direction is vertical.

To control the size of the windows when you open a new file you have two options.

• Use reserved width or 7 (hz dir): In this case the editor will make windows smaller than the desktop by substracting the value entered in reserved width, for vertical direction projects, or a fixed ammount of seven for horizontal direction projects.
• Avoid message and project windows: When selected the editor will try to avoid using the desktop surface used by the message and project windows. The size computed is the size of these windows without zooming. If the resulting size is too small the window will overlap.

These settings are stored in the desktop file. Desktop Files .

Name of the command: cmeEdGralOptions.

5.7.1.5 Check for modified files

When you edit a file the editor uses a copy of this file stored on memory. The copy on disk can be changed by another user or by a program. If it happends you can be working on a different file and you'll destroy those changes when saving. For this reason the editor must check if the modification time of the file changed. The editor does this check when:

1. You run an external program. This program could generate some output file and it could be one of the opened files.
2. You select an editor window. This is done in the idle loop, so this check could be delayed a fraction of a second.
3. Periodically for the focused file.

• Don't check after executing an external program. It disables the checks done after running an external program.
• Don't check while idle. It disables the the checks done periodically and also the checks done when you select a an editor window. That's because both are done when the editor have some free time.

If you choose to load the file from disk the editor will check if the memory copy is also modified. In this case a collision between your changes and the external changes can lose data. For this reason the editor offers four options:

1. Load file from disk (discard changes): This is the default action, use it if you want to get a fresh copy discarding any changes done in memory.
2. Abort operation: The editor does nothing and you must solve the problem manually.
3. Load and show differences: This is like the first option, but the editor will invoke diff and load it's output. You can analize the differences between your changes and the external changes to solve the problem.
4. Don't load and show differences: This is like the second option, but the editor invokes diff like in the third.

Note that when the editor offers a diff output this is loaded from a temporal file that is discarded as soon as loaded. For this reason the editor marks this window as read only. If you want to use this file to as input for patch just use the Save As option.

Name of the command: cmeSetModiCkOps.

5.7.1.6 Screen Saver

This dialog customizes the screen saver. Note the question mark at the end of the term "screen saver" I did it because the plasma screen saver isn't too good to be used as a real saver for your screen. You can enable or disable, choose the time the editor will wait before starting the screen saver and the screen saver style. The Test button can be used to see how the screen saver looks like.

If you leave the mouse pointer in the upper right corner of the screen for a few seconds the screen saver is activated. This time is three seconds by default and can be configured entering the amount of seconds in the second box labeled Time.

Two types of screen savers are supported: internal and external. Internal screen savers are hardcoded in the editor. External screen savers are external programs started by the editor. If you select an external screen saver from the list the Info and Help buttons are enabled. Pressing these buttons you can get more information about the screen saver. You can pass additional parameters to the external screen saver filling the External Saver box.

If you want to write your own screen saver please download the sources of the editor and read the explanations found in the scrnsave directory. An external screen saver is basically a simple program that supports some special command line options and returns some specified return values.

Name of the command: cmeScreenSaverOpts.

5.7.1.7 SDG Options

These options customize the SDG module (SET's Documentation Generator). see Section SDG Documentation in documentation for SDG .

• Format file: Indicates the name of the format file used to generate the documentation.
• Intermediate file: The name of the temporal file used in the process.
• Base output: The base name of the output file. Doesn't include the extension.
• Directory of formats: The place where the editor will search for the format file.
• Keep intermediate: When enabled the temporal file isn't deleted, so you can see possible errors in it.

These settings are stored in the desktop file. Desktop Files .

Name of the command: cmeSDGDialog.

5.7.1.8 Run program (which one)

The editor can run an external program and collect the errors reported by it if you press the shortcut (^F9). A good example is the make program. Here you can select the name of the program. If you need to run more than one command separate it with ;.

The editor will redirect the stderr (standard error output) and stdout (standard output) of the program and then will analize it looking for errors. The dialog includes a list of parsing algorithms to analize the errors from the external program. To learn how to configure the editor for other formats or just fine tune any of them Error messages from an external application .

The other options found in this dialog are a little bit complex. Here I'll try to explain each of these options but I recommend to just try them to see how they work.

Option Use OS screen to run the program: The editor will try to restore the contents of the screen. So it will look like as it was before running the editor. Meaning the program will be executed and the editor will redraw all the contents of the desktop and windows afterwards. This mechanism is useful when the program you want to run is interactive or doesn't use the standard output. Is important to understand that on some platforms and terminals the editor can't restore the contents of the screen and will just clean it to the grey over black color. It's also important to understand that when this option is enabled the program can't be executed in multitasking mode; it means the option Don't try to run in background will be implicitly selected.

Option Don't try to run in background: On some platforms (currently only Linux) the editor can execute the external program as a child process. It means the program will execute in parallel with the editor (in background). When the editor does this you'll see the message window indicate the program is running but won't say when you are back in the editor. Instead the output of the external program will start to fill the message window. You can select any other window and continue working while the external program runs. When the external program ends the editor will also collect the rest of the messages and errors in the background. While the editor is running the external program and/or parsing the remaining messages the status bar will show an option Ctrl+C Stop; clicking on it or pressing the indicated key the editor will stop the background process and will also stop collecting messages. The purpose of this option: When this option is enabled the editor won't try to run the external program in parallel even if the platform supports it. That's faster, but if the external program is slow you'll be forced to wait until it finishes and you won't be able to stop the program from the editor.

Option Always parse in background: If enabled the editor will collect the messages and errors in the background even if the platform doesn't support the execution of the external program in the background. On platforms that don't support the execution of the external program as a thread the editor will block until the external program ends and then will parse the messages and errors in the background. This is useful when the amount of messages and errors is big and the parsing will take a long time. In this way you can continue working while the editor does this job. You must understand that's even slower but you can at least use the time for reading or editing text.

Option Jump to the first error: If enabled the editor jumps to the file and line of the first error reported by the external program.

Option Don't redirect stdout: Complements the Use OS screen to run the program option. When enabled the editor collects errors only from the standard error and not from the standard output. This is useful for interactive applications that sends its output to the standard output.

The Message window scroll group of options are mutually exclusive and give some control over the behavior of the message window. When you start executing the external program the message window will automatically get the focus. As messages and errors are added to this window the window scrolls and shows the last message. When the external program finishes and the editor parses all the messages and errors the message window will get the focus again. Finally, if the editor found errors, the message window will scroll to the first line. This is the default behavior and you'll be able to see each of this steps only if the editor is running the external program in the background and/or parsing the messages and errors in the background. This behavior corresponds to the Ever (always) option. If you select the Never option the editor won't scroll the message window. In this case you can browse the messages even while the editor is collecting them. Finally you can choose Only if not focused. In this case you'll be able to browse the messages when the message window is selected, but if you select an other window the editor will start to scroll the message window. The fastest option is Never but then you won't see if the external program finished executing, unless you have the message window selected all the time.

The Lines per pass option is associated with the speed of parsing. This option takes effect only when the messages and errors are parsed in the background. What this option indicates is how many lines of messages and errors will be parsed before releasing the CPU. A bigger value will make the parsing faster but will make the editor slower and you'll start having problems to select windows and write text. You must experiment with this parameter. On my machine a value of 20 is acceptable.

All of these settings are stored in the desktop file. Desktop Files .

For more information about the behavior of the message window Message Window .

Name of the command: cmeConfRunCommand.

5.7.1.9 Keyboard

This is a submenu but due to limitations in the documentation tools I was forced to put it with the rest of the options listed in the Options submenu.

It contains all the options to customize the keyboard.

5.7.1.10 Key assignment

With this command you can fully customize the keys used by the editor windows. It doesn't include the menues, for that you must edit the menubind.smn file.

To learn how to use this command consult: How to configure the keyboard .

Name of the command: cmeEditKeyBind.

5.7.1.11 Setup Alt keys

It allows you to select how the editor interpretes the left and right alt keys. For more information: Alt key configuration .

Name of the command: cmeSetUpAltKeys.

5.7.1.12 Key pad behavior

[DOS]

Here you can choose how the keypad is interpreted by the editor. Two options are provided. One is the BIOS default, in this mode the NumLock changes between arrows and numbers. In the other mode the behavior is similar, but holding shift and pressing a number will behave like an arrow key shifted, that's very common in DOS applications so that's the default.

Name of the command: cmeKeyPadBehavior.

5.7.1.13 Back to defaults

This option restores the default key assignments of the editor. Use it if you messed up the keyboard configuration and you want to get back the original values.

Name of the command: cmeKbBackDefault.

5.7.1.14 Consult scan codes

Used to consult the keyboard scan codes: Consulting scan codes . This dialog must be closed using the mouse to press the OK button because it displays the scan codes for the keys, even for ESC and ENTER.

Name of the command: cmeSeeScanCodes.

5.7.1.15 Screen Options

This command opens the screen options configuration dialog. Here you can customize the video mode or window size. This dialog is available only when you are running in a terminal that can control the screen size. If you are looking for the screen saver: Screen Saver .

Not all hardware drivers support it and not all the options are usable for all the drivers. With some you can't control the screen size, like in Linux, in other cases you have total control, like when you run the editor in X11, and in others you have limited control, like in DOS.

The first group of options defines how the editor will try to set the video mode. The available options are:

• Don't force: The editor won't try to change the screen size.
• Same as last run: The editor will remember the last size used and will try to restore the closest possible size.
• External program: It currently makes only sense in DOS. It can be used when you have an external program that can set the video mode for you. In this case you must also indicate the command line for it in the External program box.
• Closest to specified size: The editor will try to select a screen size that's as close to the values indicated in Width, Height, Chars width and Chars height boxes as possible. Note that some drivers support only a small set of fixed values and others have silly limitations imposed by the operating system.
• Specified mode number: This is mainly for DOS. Use it if you know about a video mode supported by your video card that isn't known by the editor. In this case you must indicate the video mode number in the Mode number box.

5.7.1.16 Encodings

This dialog is used to select the encodings used by the editor. This is a complex topic and you'll have to play a little bit with these options before you can get all the funtionality. Usually you won't need to use it unless you deal with more than one encoding.

Currently the editor can only use files where one letter corresponds to just one character. It limits the editor to 256 different symbols. This is the common case for most operating systems and environments. Which symbols are represented by these 256 values is called an encoding.

The encodings are also known as code pages. An example of a code page is the DOS code page 437 used by PC VGA boards or the ISO 8859-1 encoding used by most POSIX systems as a default encoding. Currently more than 47 encodings are supported. These encodings cover the latin, cyrillic and greek alphabets. If your alphabet or favorite encoding isn't supported please consider contributing.

In most cases the editor will detect the encoding currently used by the operating system without problems. A special case is the GNU/Linux OS where the concept of code page doesn't really exist and you can find all kinds of errors in the fonts and unicode maps.

This dialog can have two, three or four encodings to select, they are:

• Application: which encoding the application uses, ie. used in your documents.
• Input: how the data from the keyboard is encoded. It is usually the same encoding used by the screen. If the application and input code pages don't match the editor will translate the data from the keyboard to the application encoding.
• Screen: the encoding if the screen. Not all hardware drivers support it because some of them work with a fixed code page and this value is known. Here you indicate how the font used by your hardware or OS is encoded. If this value doesn't match the application code page the editor will translate the data before sending it to the screen.
• Second font: how the secondary font is encoded. This is available only when the driver supports more than one font at the same time.

If you force the screen encoding the selected value must match the OS encoding. The exception is when you select a font in the Fonts dialog. In this case the editor will recode the selected font to match the encoding. Don't forget this interaction with the Fonts dialog. Fonts .

Note that you can easily edit documents encoded in a code page different than the one used by the OS without doing any specific recoding. Example: if you are using X11 and the ISO 8859-1 encoding but you want to edit a DOS file encoded using the 850 code page you just need to select the application encoding as PC 850 and force it. Your keyboard will generate ISO 8859-1 values, they will be translated into 850 encoding and put in your document. At the same time the text encoded using 850 code page will be translated to ISO 8859-1 before displaying it.

Name of the command: cmeEncodings.

5.7.1.17 Fonts

This dialog is used to select the fonts used by the editor. Not all hardware drivers support custom fonts and some only support only one font. The editor can handle up to two fonts at the same time. However, the use of two fonts is complex.

Only the fonts marked with Load font are used, don't forget to enable it before leaving this dialog.

The size of the fonts must be the same, that's why even on systems that supports two fonts only one size can be selected.

The offered fonts are the ones provided by the editor and not the OS. This is because some systems doesn't provide fonts and the systems that provide fonts usually provides only a few fixed width fonts. The font format used is documented in the Turbo Vision library.

The fonts marked with limited don't cover all the encodings supported by the editor. Encodings .

When you load a font the encoding for this font will be the value indicated by the screen encoding option selected in the Encodings dialog. If you change this encoding the editor will automatically change the encoding of the font.

Name of the command: cmeFonts.

5.7.1.18 User Words

This option is used to define reserved words defined by the user. A very common use is to define typedefs you normally use in your programs. The user words are language dependant. They are highlighted with a special color different than the color used for reserved words.

The first dialog is used to select the language, the names are the ones defined in the syntax highlighting file ( Syntax Highlighting ). Selecting one of the names and pressing ENTER pops up the second dialog.

The next dialog is used to add or remove words to the list. Pressing ENTER you confirm the changes and they are saved to disk. If you exit with ESC the old list is preserved.

The user words are stored in a file called userword.txt, in the same directory all other configuration files are stored. Such a file isn't included in the distribution because those words must be defined by the user. You can edit the file by hand if you want, the format is very simple. The start of a list is marked with . followed by the name of the language. The items of the list are marked with +. Any line starting with a different character will be ignored during the parsing.

Note: The menu option is "Tool&Ops|Options|User Words".

Name of the command: cmeEditUserWords.

5.7.1.19 Default global edition

To understand how this menu option works you must know some details about the global options of the editor. Set Global .

The global options are good, but sometimes you want to make some small differences depending on the kind of file you are editing. For example: I want the Intelligent C indent mode enabled for C, but not for most of the files, I also want to wrap lines for Texinfo files and files without syntax highlighting. That's impossible to achieve just using the global options, that's when this option comes into play.

The mechanism is like this: each time you open a new file the editor will copy the default global options to it and select the syntax highlighting according to various things, mainly the extension. Once the editor selects the syntax highlighting the next step is to transfer some options that apply only to the selected syntax highlighting. By default the list of options to apply is empty but you can add some using this menu option.

The list of options indicates which settings will be enabled, or disabled, in addition to the global options. That's something very important to keep in mind, the list does not replace the global options, it modifies them. So the list will say things like "also enable the intelligent C indent", "disable the wrap lines", etc.

The first dialog shows the list of syntax highlighting defined in the syntaxhl.shl and has three buttons. The Edit button is the default button, so pressing ENTER you'll edit the settings for the selected syntax highlighting. The No SHL button is used to edit the options that will be applied for files with no syntax highlighting associated to.

Once you selected a syntax highlighting a dialog with the list of the settings for it will appear. The first time it will be empty because those are defined by the user, and therefore no defaults are provided. In this list the settings that will be enabled in addition to the global options are marked with a + before the name of the option. The options that will be disabled are marked with a -. The options are the same described in the editing modes section. Editing Modes .

The dialog contains an Add and a Delete button like other dialogs. You can also use the Insert and Delete keys. When adding a new setting to the list a dialog containing the list of available settings is displayed. Note that this list contains all the settings that are available, once you add one of them to the previous dialog it is removed from this list.

After selecting one setting to add a new dialog will be displayed. This dialog will ask information related to this setting. Most settings are flags that can be added or removed from the global options, but some of them are just values that will overwrite the global options. Examples of the last type are the tab size and the wrap column; in this case the dialog will ask for the value.

The values are stored in a very simple format in the deflopts.txt file. You can edit this file by hand, but in this case you'll need to know the names of the settings. The format is very simple, a line starting with . starts a section, the full stop is followed by the name of the highlighting affected. Flags that will be added (enabled or ored) are marked with a + as in the dialog, flags that will be substracted (disabled or anded) are marked with a - again like in the dialog, in fact the dialog shows the same string as those in the file. If the setting is numeric it will ever start with + and after the name a = and the asigned value will follow. Just play a little bit and see the resulting file.

Name of the command: cmeEditDeflOpts.

5.7.1.20 File open dialog

This command is used to configure some details of the file open dialog. File Open . Name of the command: cmeFileOpenOptions.

5.7.1.21 Do not create backups for

Sometimes you don't want to create backups for some particular files. In my case I use a tool called cvs. It generates some temporal files and calls the editor so I can write some information. Those files are short and temporal, creating backups for them doesn't make any sense.

This command shows a configuration dialog where you can enter a list of regular expressions. If any of these regular expressions match with the file name of the file you are about to save then the editor won't create a backup file for it. The regular expressions are Perl style because I think they are much more intuitive than POSIX regex.

The list shown in this dialog is stored in a file called nobkp.txt. The exact place of the file depends on your system like other files created by the editor.

Note that files listed here aren't remembered in the list of closed editors. That's because the editor assumes those files are temporal and you won't need to use them again.

Name of the command: cmeEditNoBkp.

5.7.1.22 Search files under cursor in

When you press Ctrl+Enter the editor tries to load the file that's in the text at the cursor position. If the cursor is in an include line the editor will extract the name of the header. In any other case the editor will try to find where the name starts and ends.

If the file isn't located in the current directory the editor will try to find the file in the list of directories indicated by this option.

You can use environment variables for this list. Here is an example that shows how to use the content of the ALLEGRO environment variable:

     $(ALLEGRO)/include

This list is stored in the desktop file.

Name of the command: cmeIncludeList.

5.7.1.23 List of tag files

This dialog controls which tag files are loaded to search for symbols. To learn more about tags please read the corresponding chapter. TAGS files .

When you add a file the editor tries to load it and shows how many symbols it contains.

After selecting a new tag file a dialog will ask if you want to add it using a relative path. This is a very important question. If you are using one centralized desktop file and you have just a few projects you can add a list of tag files in this desktop file, but the list must contain absolute entries. If you are entering a list of tag files for a project or a local desktop file I recommend using relative paths, but it depends on your needs.

Name of the command: cmeTagFiles.

5.7.1.24 Tag files options

To maintain the tag files you should use a makefile. This makefile will update the tag files when any of your sources changes.

To make things easier the editor provides an option to automatically keep the tag files updated. This option can be enabled from this dialog and only works if you are using a project.

When this option is enabled and you perform a search that involves tags the editor will automatically check if any of the files included in your project is newer than the tag files. If newer files were found the editor will invoke ctags to update the tags. If you delete the tag files the editor will create a new one.

This option works with a tags file called tags located in the same directory as the project. This file will be listed in the list of tag files to search but marked with automatic. You won't be able to remove this entry from the list manually.

When new items are added to the project they are marked in a way that their symbols will be added to the tags file, but when you remove items symbols from this file aren't removed. If this is annoying just remove the tags file and let the editor create a new one.

Name of the command: cmeTagsOps.

5.7.1.25 Regenerate central file

The central file is maintained using the incremental features of ctags. Some times ctags fails to remove obsolete entries in the tags file. This bug can become really annoying. In this case you can use this command to regenerate the file from scratch.

Name of the command: cmeTagsAutoRegen.

5.7.1.26 Calendar options

The editor can mark holidays in the calendar using a different color. As holidays depends on the country this feature needs to know:

1. What's your country
2. About the holidays celebrated in your country.

The second is achieved using plug-ins. Currently the editor supports it only for systems that implements the dlopen family of functions. If you can't find a plug-in for your country and you know how to write small C programs consider wrtiting a plug-in for your country. The information about how to do it is contained in the sources distribution. Look for a directory called holidays, it contains a README file. If you need assistance contact the author. Please consider contributing the plug-in so other people from your country can share the benefits.

Name of the command: cmeHolidaysConf.

5.7.1.27 Advice dialogs

In some situations the editor offers some advice to guide new users. These are called advice dialogs. They can be disabled using a check box in the dialog.

This option is used to enable or disable any of the advice dialogs. Texts marked with an X indicates the corresponding dialog is enabled. Use the space key to change the desired dialog.

Name of the command: cmeAdviceDiagConf.

5.7.2 Calculator (command/menu)

This command shows the calculator: Calculator .

Name of the command: cmeCalculator. Assigned key: Alt+F4

5.7.3 SDG

Runs the documentation module: see Section SDG Documentation in documentation for SDG .

To configure the SDG module: SDG Options . Name of the command: cmeSDG. Assigned key: F9

5.7.4 Run program

Runs the desired program. To customize which program to run: Run program (which one) .

Name of the command: cmeRunCommand. Assigned key: Ctrl+F9

5.7.5 Grep

This command pops up the Powered Grep dialog. Grep is a very powerful tool to search text in files. To be able to use it you must have the grep tool installed and in the path. It isn't shipped with the editor.

• Pattern Box: The text you want to search for. You can use regular expressions here. Regular Expressions .
• Files to search: The mask used to select the files grep will search through. Wildcards and some limited basic regular expressions are supported here.
• Directories to search: The list of directories where the search will be performed.

• Pattern box is the pattern: grep will search the text indicated in the pattern box.
• Pattern box is a file name: to search words contained in a text file.
• Use clipboard selection: use the clipboard selection instead of the pattern box text. Clipboard .

The Place to search group is used to select which files are examined in the search:

• Use files to search: The files to search content is the mask.
• Search in opened windows: The search is performed in all the opened text files.
• Search in project: The search is performed in all the project files. Project .
• Recurse in subdirs: When enabled the editor will run grep not only in the indicated directories but in any subdirectory contained therein as well. That's the main reason because I call it Powered Grep.

After the search the matched lines are displayed in the message window and by pressing Alt+F7 and Alt+F8 you can examine them.

To learn more about the message window Message Window .

Name of the command: cmeGrepDialog.

5.7.6 HTML Accents

The following options are useful for people using ISO Latin 1 accents in your HTML code. Even when the current code page is different than ISO Latin 1.

It converts all the accents in the text to ISO-Latin-1 HTML tags. That's useful when editing html files because you can type accents naturally and can simply use this option to generate the right tags. It works for any code page selected.

Name of the command: cmeHTMLAccents.

5.7.6.2 Convert tags to accents

It converts all the ISO-Latin-1 HTML tags into accents. That's useful when reading html files because you can convert the tags to symbols. It works for any code page selected.

Name of the command: cmeHTMLTag2Accent.

5.7.7 Export as HTML

This option is used to export the current text file as HTML. The default options generates a very good WYSIWYG result. This option works for any syntax highlighting mode and for any color configuration you want.

Under DOS you can customize the editor's palette, this feature will export the customized colors too.

Note that due to limitations in the HTML language the editor can change the background color on a word-by-word basis only.

The available options are:

• File name as title: uses the full path and name of the file as the title for the generated HTML.
• Same background color as the editor: defines the background of the HTML file to be equal to the background of the editor's window.
• Monospaced font: sets the font for the HTML to Courier New.
• Bold attribute: sets the font for the HTML to bold.

Name of the command: cmeExportAsHTML.

5.7.8 Insert key name

This command brings up a dialog asking you to press a key. When you press a key the dialog is closed and the name of the key is inserted at the cursor position. You can use it to configure the menues (menubind.smn). How to configure the keyboard . Name of the command: cmcInsertKeyName.

5.7.9 Remap code page

With this command you can change the code page encoding of the current document. This operation will translate all the characters from the current encoding to a new one. Characters that don't have an equivalent in the new code page are converted to spaces.

The dialog asks for the original code page ('from' list) and the new code page ('to' list). Additionally you can allow the editor to also translate the first 32 values. Translating the first 32 values can be dangerous; for this reason the editor won't translate carriage return, line feed and tabs even if you choose to remap the first values.

This operation affects the buffer globally so you can't use undo. Therefore you should keep a copy of the file and don't save it if the results aren't what you expected.

This option is very useful to exchange texts between different operating systems.

Name of the command: cmeRemapCodePage.

5.7.10 Profile Editor

This option is used to measure the speed of the editor. Use large files and to make results comparable always use the same one.

Name of the command: cmcProfileEditor.

5.7.11 Redraw screen

This command forces a redraw of the screen. It might be needed if some application running in the background messed up your console.

Name of the command: cmeReDraw.

5.7.12 Paste Emacs mode

Pastes a comment at the start of the file indicating the Emacs mode and the tab size used for this file. That's very useful if the file doesn't have an extension or the extension is ambiguous. It is also a good idea to do it if you'll send the file to another person and want to indicate which tab size you used.

The editor understands this comment and sets the syntax highlighting and tab size to the value indicated.

Name of the command: cmcPasteEmacsMode.

5.7.13 Block quoted printable decode

This option decodes the selected text assuming it is encoded with the quoted printable MIME spec. That's useful if you have an e-mail with non-ASCII characters and it was encoded with this method. That's very useful for spanish accents.

Name of the command: cmcQuotedPrintDecode.

5.7.14 Un/Indent block

This submenu contains the block indentation operations.

Indents a block one space. For more information Indentation . Name of the command: cmcIndentBlkOne.

5.7.14.2 Unindent one character

Unindents a block one character. For more information Indentation . Name of the command: cmcUnIndentBlkOne.

5.7.14.3 Indent one tab or gap

Indents a block as if you used the Tab key in each line. For more information Indentation . Name of the command: cmcIndentBlk.

5.7.14.4 Unindent one tab or gap

Unindents a block as if you used the Backspace key in all of the lines. For more information Indentation . Name of the command: cmcUnIndentBlk.

5.7.14.5 Comment indent

This command inserts a comment at the start of each line of the selected block. The comment used is the one defined in the syntax highlighting file as EOLComment1; if none is defined or the file doesn't have any syntax highlighting this command does nothing. EOLComment1 .

If no text is selected this command first selects the current line and then applies the indentation.

Name of the command: cmcCommentIndent.

5.7.14.6 Comment unindent

This command removes as many chars from each selected line as the length of a comment sequence. The comment used is the one defined in the syntax highlighting file as EOLComment1; if none is defined or the file doesn't have any syntax highlighting this command does nothing. EOLComment1 .

This command doesn't check if each line you selected starts with the defined comment, so be careful.

If no text is selected this command first selects the current line and then applies the indentation.

Name of the command: cmcCommentUnIndent.

5.7.14.7 Arbitrary indent

This command pops up a dialog asking for a text to be used as indentation. The text will be inserted at the start of each line of the selected block. Name of the command: cmcArbitraryIndent.

5.7.15 Delete memorized backups

Deletes all the memorized backups. This includes all the backups created while the current project/desktop file was opened. If you want to also delete backup files created during previous sessions you must enable a special option that makes the editor keep a list across sessions. Editor General .

Name of the command: cmeDeleteBkps.

5.8 Project

The project files are used to indicate groups of files. Each project has its own desktop file so you can have different settings for different groups of files. Desktop Files .

There are several reasons to use projects:

• If you want to work on a group of files and you will be editing these files for a long time use a project. Then you will be able to select which file to edit from the project window, as this window is sorted alphabetically it's easy to make incremental searches (typing the first letters) to find the file. Additionally the editor saves the window position and other stuff for all the files listed in the project, even if they aren't listed in the closed windows list. I use it for my web site files; they are more than 44 and the list of windows (Alt+0) doesn't help.
• If you are using the SDG module to collect the comments of the files you need to use a project to specify them.
• You can use a project to list a set of files to search with grep. Each time you want to search in these files you just open this project and perform the search.

This window shows only the names of the files and the relative path only when names are repeated. You can change it to display the relative path for all files pressing Alt+V when the project window is selected.

Opens a project file. To create a new file just enter a new name in the dialog.

Name of the command: cmeOpenPrj.

5.8.2 Close (Project)

Close the project file.

Name of the command: cmeClosePrj.

5.8.3 Save (Project)

Saves the current project. It's a good idea to save the project after adding or removing a lot of files.

Name of the command: cmeSavePrj.

5.8.4 Save desktop here

Saves a desktop file in the working directory. A desktop file is created even if the editor is configured to use only one central desktop file. This is useful to locally store settings without creating a project.

Name of the command: cmeSaveDesktop.

5.8.5 Export project

Creates a text file containing the names of the project items. The file contains one file per line.

Name of the command: cmeExportPrj.

5.8.6 Import project items

Imports the names given in the file as project items. The file with the file names to import must contain one file per line. Relative paths are recommended. The editor will check if the file exists and if that's a regular file, if not the item will be rejected.

At the end of the import process the editor informs how many items were added, how many were already in the project and how many file names didn't correspond to existing files.

Name of the command: cmeImportPrj.

5.9 Help

Well, I think you figured it out, that's the help.

Name of the command: cmeInfView. Assigned key: F1

5.9.2 Another InfView

It opens another InfView window. The editor always opens one window that's used by the help system. When you close this window the editor just hides it and when you press F1 the window is un-hided and the help is displayed. That allows the existence of the Previous help command. But some times you could want to brise one or more help files without losing the help window, in this case you need more than one InfView opened.

Name of the command: cmeAnotherInfView.

5.9.3 Tip of the day

Once a day the editor shows a usage tip when you start it. Each tip talks about one interesting feature that most of the people overlook. Reading them you'll discover a lot of interesting things about the editor.

Each tip has one or more buttons at the right, which represent a link to a help topic related to this tip. If you want to learn more about the tip's topic you can browse the help using the buttons.

There are three options at the bottom of the window, they are self explanatory. The first disables the annoying tips ;-), the second shows the tips in a dialog box once a day and the third shows the same text in the message window (once a day of course). The third option is less annoying than the second but you lose the link buttons.

The text displayed by the tips can be found in the editor.tip file. You can edit it to show anything but be careful because the parser isn't very tolerant to typos.

To learn more about the message window Message Window .

Name of the command: cmeTipOfTheDay.

5.9.4 Syntax help

When programming in a language like C you probably can't remember the exact name of all the library functions; the djgpp libc help contains around 650 nodes and the Allegro help around 400. Placing the cursor over the name of a library function and pressing ^F1 you'll get help about this function. If the name isn't exactly typed you'll get a list of the closest matches. The following topics explain how to configure it.

This dialog box allows the configuration of the syntax help. See Syntax help .

The search method used can be:

• Exact: Only exact matches are reported.
• Substring: Partial matches are reported.
• Fuzzy: It uses a special algorithm that reports words similar to the one you are searching.

• Case sensitive: The search interpretes lower case characters as different than uppercase characters.
• Sort by score: The matches are sorted by score when reported. When disabled the sorting criteria is alphabetical. A greater score means the match is more similar to the word you are searching. A score of 1000 means exact match.
• Fuzzy value: That's used only when the selected mode is the fuzzy mode. It indicates the minimal score a word must have to be displayed as a possible match. Experiment with different values and see the scores reported.

5.9.4.2 Files to search (Syntax help)

Here you can indicate in which info files the editor will search the name of the function; the default is OS dependent. Syntax help .

You can specify an info node or just the name of the file. In the first case the editor will read all the cross references found in this node, in the second the editor will use all the nodes of the file. Normally the node that contains all the relevant references is called Index, but there are exceptions; one interesting case is libc.

In the dialog the editor shows which nodes are searched in. If the name has a question mark to the left it means the editor didn't read the file yet, pressing ^F1 over any word the editor will search it and hence will read the help files. If the name has an asterisk it means some error was encoutered when trying to read this file. Finally if no mark is indicated it means the editor successfully read the file, additionally the number of nodes found is indicated to the right. You can add or remove nodes from the list.

Name of the command: cmeSyntaxHelpFiles.

5.9.4.3 Search (Syntax help)

It makes the syntax search and report the matches found. If only one match was found the editor jumps to this node. Syntax help .

Name of the command: cmeSyntaxHelp. Assigned key: ^F1

This file also configures the status bar, that's the line at the bottom of the screen. This line is context sensitive and also contains shortcuts. Some of the shortcuts can be invisible.

Finally you can also configure the menu displayed when you click over an editor window using the right mouse button.

The menues and status bar can be used to complement the keyboard assignments. You can assing editor commands, sLisp macros or small portions of sLisp code to them.

This chapter is a small reference about the commands you can use in the menubind.smn file.

The SubMenu command starts a menu definition. It can be nested. When used at top level defines a new entry in the menu bar. When used inside another SubMenu section defines a child menu.

The EndSubMenu marks the end of a menu section.

The syntax for SubMenu is:

       SubMenu: "Visible name", key
       ...
       EndSubMenu

       SubMenu: "~F~ile", kbAlF

When defining a menu entry you must indicate the name of the key or key combination. The editor have a command specially designed to help you with it, look in the Tool&Ops menu ( Insert key name ). Here is a small explanation about how those names are created.

In menues all key combinations start with the kb preffix. Then follows the key modifiers. They can be:

After the modifier comes the key name. The key name is usually the character you obtain by pressing the key or the name of the character you obtain. For the alphabet characters is quite simple, kbA is just the key that generates the a. The same is for numbers. Function keys are also easy, they are named F and the number of the function key.

Things becomes more complex and even confusing for other characters. At first you must know the name I gave to each symbol and then you must understand a small complexity created by the fact that some shifted keys generates non-related symbols. Here is an example: kbSh1 is valid but you won't get this combination because when you press 1 plus shift what you obtain is !. The editor will interpret it as kbAdmid.

Here is a list of the names, but the best is to use the Insert key name option: OpenBrace, BackSlash, CloseBrace, Pause, Esc, BackSpace, Tab, Enter, Colon, Quote, Grave, Comma, Stop, Slash, Asterisk, Space, Minus, Plus, PrnScr, Equal, Home, Up, PgUp, Left, Right, End, Down, PgDn, Insert, Delete, Caret, Admid, DobleQuote, Numeral, Dolar, Percent, Amper, OpenPar, ClosePar, DoubleDot, LessThan, GreaterThan, Question, A_Roba, Or, UnderLine, OpenCurly, CloseCurly, Tilde, Macro, WinLeft, WinRight and WinSel.

When you have to indicate that no key the kbUnknown name can be used.

6.3 MenuItem entries

To add a menu entry you can use the MenuItem command. The syntax is:

     MenuItem: "Name", Command[, Key [, Context [,"KeyName"]]]

6.4 Commands in menu items

You can use any of the editor commands in the commands field. They are listed in the commands index ( Index of key commands ). Additionally you can specify the name of a sLisp macro or a small piece of sLisp code.

To indicate the name of a sLisp macro just use the following syntax: cm(NAME). To enter a small portion of sLisp code use it: cm((CODE)). Here is an example that just prints a message in the message window: cm((ShowInMessageWindow 'Hi! ;-)')).

6.5 MenuItemC entries

This is the most common way to add a menu entry. The syntax is:

     MenuItemC: "Name", Command[, Key [,"KeyName"]]

6.6 MenuSeparator

It adds a division line to the menu. Use it to visually group related menu entries.

6.7 The special submenu used for the right click

To define the menu associated with the right mouse button you must define a top-level submenu called Editor Right Click. This submenu will pop up when you right click over an edition window and is just like any other submenu.

6.8 Status bar ranges

The content of the status bar is context sensitive. For this reason the content of the status bar is defined for a help context or for a range of help context values. The ranges can overlap and the first match is used. For this reason the order is important.

Ranges are started using the StatusRange command and closed using the EndStatusRange command. The syntax for the first is:

       StatusRange: first_context, number_of_contexts

The syntax for visible entries is:

       StatusEntry: Label, Command, Key

6.10 Invisible status bar entries

The syntax is almost the same used by the visible ones, the most important difference is that they doesn't need a label. Visible status bar entries .

       StatusHiddenEntry: Command, Key

The menubind.smn files support some conditional statements. They are quite similar to the preprocessor conditionals used in C language and can be used to exclude or include some menu entries according to the operating system and other configuration details.

The most important structure is:

       $if CONDITION
       ...
       $else
       ...
       $endif

Contitions can use and, or and not boolean operations. The and and or operators are used for the first two and the ! operator for not. Currently you can use parentheses in conditionals but this is not fully tested.

The available variables to evaluate are:

6.12 Comments in menu files

You can add comments to menu files, they must start with the # character and it must be in the first column. Lines starting with # are ignored when parsing menu files.

The settings are:

This setting controls if the typed characters are inserted in the buffer or replace the original ones. For a detailed explanation Insert and Delete .

7.2 Autoindent

This setting controls what happens when you press ENTER. If this setting is off the cursor goes to the column 1 of a new line. If the mode is on the editor will try to mimic the indentation of the code by inserting spaces or tabs. Optimal Fill .

7.3 Real Tabs

This setting controls what happens when you press TAB. If this setting is on the editor will insert an ASCII 9 at this position.

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. The behavior is configured by the Tab indents option. Read the section about it for more information. Tab indents .

You can also indent using spaces when this option is disabled. For more information consult the Use indent size option. Use indent size .

In the past (versions older than 0.4.44) another thing controlled by this setting was the behaviour of the Backspace key, but now that's controlled by the Backspace unindents option. Backspace unindents .

The editor is much more coherent when you choose to use TABs or not use TABs. If you mix the two modes you'll get some unexpected results, especially in the indentation of the blocks.

If you never use tabs, it's better you work with this setting off. 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 will 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 finish of your work compact all possible spaces and generate a file with tabs. Miscellaneous .

Most tabs users also like to enable the Optimal Fill option. Optimal Fill . I also suggest using the following options to complement the indentation when using tabs: Autoindent ON, Intelligent C indent OFF, Optimal Fill ON, Do not move inside tabs ON, Tab smart indents OFF, Use indent size OFF and Backspace unindents OFF.

7.4 Persistent Blocks

This setting controls the behaviour of the selected area.

The "Block modes" chapter for a detailed explanation. Block modes .

7.5 Intelligent C indent

This mode was designed to be used jointly with the Pseudo Macros ( Pseudo Macros ) and the Real Tabs mode off to achieve an easy way to indent the code that does a better job than the Autoindent mode.

In this mode the spaces inserted after pressing ENTER depend on the first word in the last line. For example, if you have:

     if (a==b)_

     if (a==b)
       _

     if (a==b)
       {
        _

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

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

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

Another important thing is that this indentation has a personal style, my style ;-), so it may be you don't like it. If that's the 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 cpmacros.pmc file ( Pseudo Macros ), actually this file is coherent with this mode.
• The editor isn't configurable like Emacs or Brief using a language, but is written in C++. If you know C++ contact me and I'll help you to write the routines that you need to get an indentation in your own style :-).

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

Each time you press ENTER the editor inserts a rn string in your text, after that the editor searches one line located above the new line that has at least one character on it. This line is taken as reference. The editor analyzes this line searching for:

• The first non-blank character on this line.
• The first word on this line.
• The first parenthesis.
• The balance of parentheses on the line.
• The last non-blank and non-comment character in the line.

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

If the line starts with a C++ comment the effect is the same as in Autoindent. Autoindent .

If the line starts with a C comment the editor will try to skip the comment and analyze 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 has more ( than ) the editor will go to the column of the first non-blank after the first (.

If the line has more ) than ( the editor will search the line where the number of parentheses is balanced, then will analyze this line. If the whole line still generates an unbalanced situation the editor will go to the first used column in the line that was found the first time. But if this line will leave all brackets balanced the editor will take the first word on the line and will use it as reference.

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

Seasick? Do you have more examples? .

Note: Some of these features were added in v0.2.14 of the editor based on a suggestion of stud73@nortel.ca about the behaviour of the mode on a line like this printf("Num: %d", with the rest of the parameters on the next line.

7.5.2 Do you have more examples?

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

Example 1: (similar to one 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]

     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]

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

     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]

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

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

7.6 Column cursor

This setting enables a strange feature of the editor. When on the column where the cursor is is highlighted. This feature is very good to check if parts of your code are aligned correctly.

If you like this mode but think it's very uncomfortable to use all the time contact me and if I get enough feedback I'll create a hotkey for it to be turned on/off quickly.

7.7 Row cursor

This setting is similar to the column cursor 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.

7.8 Match pair highlight

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 highlighted, 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 useful when you are typing complex parenthetical expressions or a very nested code. You can use it together with the cmcSearchStart, cmcSearchEnd, cmcSearchOpPar, cmcSearchClPar, cmcSearchOpCor and cmcSearchClCor commands. Miscellaneous .

If you want to get highlight not only after typing but also when moving the cursors you'll need to enable the Match pair on the fly option. Match pair on the fly .

7.9 Match pair on the fly

This mode is very similar to the Match pair highlight mode. If you don't know how it works please read the Match pair highlight section first. Match pair highlight .

The main difference is that this mode highlights the pair when the cursor is over the character to search.

The highlight is done half a second after you stop typing to avoid interfering with your typing. But if you have a fast machine, not just a 386, you can configure the editor to do the search without waiting. Do not wait to search the pair .

7.10 Do not wait to search the pair

This option works only when Match pair on the fly is enabled. When enabled the editor doesn't wait to do the search of the complementary pair. I think this could impact the performance of scrolling on very slow machines and that's why it's optional. Match pair on the fly .

7.11 Transparent Blocks

When this mode is on you can see the syntax highlighting of selected blocks. Normally the selection affects the background and foreground colors, but when using transparent blocks only the background is affected.

7.12 Optimal Fill

This mode was added for the people that use ASCII 9 tabulators in their code ( Real Tabs ). Normally the editor uses spaces to indent the code or, in general, to fill any gap in the text. When you enable this mode the editor will use as many tabs as possible to fill these gaps. That's what the tab users normally expect.

7.13 Wrap Words

Even when the editor is mainly intended for programmers it became apparent that some other user groups want to use it too.

The word wrap added to the editor is a very simple one, it just inserts a new line if you type a word beyond the wrap column, that's all. You won't get automatic reformat functions like in text editors intended for love letters (like the one from the Bill Gates company).

The wrap column box is used to enter the column that triggers the wrap.

7.14 Do not move the cursor on Paste

That's a global setting. When it's on the cursor isn't moved after pasting. Normally the cursor is moved to the end of the pasted block, but sometimes it's better if the cursor isn't moved.

7.15 Scroll Lock centers

When this mode is on the Scroll Lock key has a special meaning. If the Scroll Lock LED of your keyboard is on then the editor centers the current line in the window. The effect is very strange but the advantage is that you don't need to follow the movement of the line with your eyes because it's always in the same place.

7.16 See Tabs

In this mode the tabs are highlighted, two colors are used for this purpose, one for even and the other for odd numbered tabs. In this way you can clearly see where a tab is located and the size of the tab. The colors can be customized from the Colors menu option. Customize Colors .

This mode was introduced in v0.4.23 and is globally enabled by default.

7.17 Do not move inside tabs

In this mode the cursor can't be placed inside a tab character. This definition is fuzzy and confusing so here I'll try to explain it better. One tab character can be expanded to one or more characters when displayed on the screen. Normally you can place the cursor in any of the spaces that belong to a tab character. I think this behavior is the best because you are free to move the cursor to any place you want, but tab users get confused when they type and discover they had the cursor in the middle of a tab. It produces a cursor jump. To avoid this kind of surprise a lot of editors don't allow to position the cursor in these spaces, only in the first space.

This mode was introduced in v0.4.23 and is globally enabled by default.

7.18 Tab indents

When Use real tabs option is disabled the editor will insert enough spaces to move the cursor to the next tab-stop or indent position. But if this option is enabled the editor will insert enough spaces to move the cursor to the beggining of the next word in the previous line. Confused? Sorry for my English, an example will clarify that:

This is a line above the line you are

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

After pressing TAB you'll get:

This is a line above the line you are

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

Now you'll 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 option is to indent like the Tab key but using a size different than the tab size. This can be done disabling this option and enabling Use indent size. Use indent size .

7.19 Use indent size

When the Real Tabs and Tab indents options are disabled you can indent with the tab key but using spaces. Sometimes people want to use tabs of eight spaces because this is the most common value for consoles and printers but, at the same time, they want to indent by a different amount of spaces pressing tab. In this situation you must enable this option and configure the indentation amount in the Indent size box.

7.20 Keep trailing whitespace

Normally the editor purges any space after the last visible character in a line. That's very useful to save disk space and to avoid problems with end of line continuation sequences, like in C language. But sometimes you may want to avoid it for some reason. Enabling this option the editor won't try to remove extra spaces at the end of lines.

7.21 Backspace unindents

When this option is enabled the Backspace deletes as many spaces as necessary to move the cursor to the first used column of the previous line. Basically it keeps the indentation. However, this is true only when all the characters located to the left of the cursor are spaces or tabs.

In versions older than 0.4.44 this option was implicitly enabled when the Real Tabs option was disabled. When loading old desktop files the editor enables/disables this option based in the Real Tabs option.

7.22 Column Markers

Column markers highlight a column of text. This option is useful for programming languages where the column is important or when you just need to have some column positions as references.

You can set various column markers at the same time, just enable this option and enter a list of columns in the associated text box. The columns should be separated by spaces and sorted incrementally. The editor will format the list in this way.

7.23 Syntax Highlighting

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

• No highlighting, all the code is with the same color.
• C/C++ Highlighting.
• Pascal Highlighting.
• Clipper Highlighting.
• User defined. Including already defined for:
  • 4DOS batch files
  • 80x86 assembler (AT&T syntax)
  • 80x86 assembler (Intel syntax)
  • 8x51 assembler
  • Ada
  • BASIC
  • C/C++
  • Cascading Style Sheets version 2
  • Clipper 5.x
  • Command Line Errors File
  • Environment files
  • Flat assembler
  • Fortran
  • HTML
  • Internationalization files (.po)
  • Java
  • Java Script
  • Lua
  • Makefiles
  • Menu files
  • Modula 2
  • Netwide Assembler (NASM)
  • Objetive C
  • Pascal
  • PDP11 assembler
  • Perl
  • PHP
  • PIC assembler (Microchip)
  • PLM/51
  • PMacros files
  • PostScript
  • POV-ray
  • Python
  • Ruby
  • SDG format files
  • sLisp macros
  • SQL
  • The syntax highlight file itself
  • TCL/Tk
  • TeX
  • Texinfo
  • Turbo Vision configuration files
  • UNIX shell scripts
  • VHDL
  • XML
  • WML

The editor also supports the convention used for UNIX script files. If a file starts with #! this line indicates the program that must be executed to interpret the script. The editor reads this line and extracts the name of this program and searches it in the ShellScript definition.

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

The Pascal highlighting was designed for the GNU Pascal compiler.

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

The highlighting can be customized, Syntax Highlighting File .

The file declares the settings for each kind of files. Each declaration ends with an End marker. The # acts as a start of command if it appears in the first column.

Important things you have to know to add a new syntax highlighting:

• In previous versions when adding a new highlight mode it ought to have been added at the end of the file, now this isn't mandatory.
• The editor remembers various settings of loaded files even after closing the file. This includes the syntax highlighting, so if you add a new one or added a new extension to the list and you open a file that you already opened the editor will remember the last settings and doesn't use the new setting. In this case you must force it by hand.
• If you feel that this new highlight mode can be used by other users send it to me and I'll include it in the next release. Many of the currently included syntax highlightings were contributed by users.

If you want to add some keywords to a language for personal use don't do it in the Keywords section because you will need to edit this file each time you install a new release of the editor. The editor provides another file for it and also a nice user interface to add and delete words defined by the user. User Words .

The next sections covers the supported settings.

Some languages include symbols inside names, you can list these symbols here. Normally the editor allows letters, digits and underscore. These characters are allowed inside the names and not at the start of the name. CanStartAName .

8.2 CanStartAName

Some languages includes symbols at the start of names, you can list these symbols here. Normally the editor allows letters and underscore. These characters are allowed at the start of the name and not inside. AllowedInsideNames .

8.3 Case

When this setting is 1 all the keywords become case sensitive. If the keywords aren't case sensitive don't use it.

This should be declared as one of the first settings because it affects how other definitions are loaded in memory. I suggest using it before Name and Files and after the others.

8.4 CloseComment1

Used to indicate the end of a multiline comment. The lenght is limited to four characters. If the file format has two different terminations use CloseComment2 for the second.

For more information Format of short syntax highlighting definitions .

8.5 EmacsModes

It indicates which Emacs modes will use this highlighting. The modes must be separated by commas. The modes are't case sensitive.

As in Emacs the editor looks at the first kilobyte of text and at the last three kilobytes for the mode delimited by -*-.

The priority is as follows: EmacsModes, ShellScript and finally the extension (Files). ShellScript . Files .

8.6 EOLCInFirstCol

When this setting is on the one line comments starts only if the sequence of characters is present in the first column.

8.7 EOLCInFirstCol1

That's like EOLCInFirstCol but affects only the EOLComment1 and not both. EOLCInFirstCol .

8.8 EOLCInFirstCol2

That's like EOLCInFirstCol but affects only the EOLComment2 and not both. EOLCInFirstCol .

8.9 EOLCInFirstUse1

That's like EOLCInFirstCol1 but the starting sequence may be the first non-blank character and does not need to be located in the first column. EOLCInFirstCol1 .

8.10 EOLCInFirstUse2

That's like EOLCInFirstCol2 but the starting sequence may be the first non-blank character and does not need to be located in the first column. EOLCInFirstCol2 .

8.11 EOLComment1

Used to indicate the start of a comment that ends at the end of the line. The lenght is limited to four characters. If the file format has two different terminations use EOLComment2 for the second.

For more information Format of short syntax highlighting definitions .

8.12 Escape

Indicates which character acts as escape character inside strings or to concatenate lines.

8.13 EscapeAnywhere

Indicates that escape characters can be found anywhere, not just inside strings or at the end of lines like in C.

8.14 Files

It indicates which extensions will use this highlighting mode. The extensions must be separated by commas. The extensions are case sensitive, be careful.

The editor can also choose the highlighting using the Emacs mode or the program used to execute the file if that's an UNIX script.

The priority is as follows: EmacsModes, ShellScript, FullNameMatch, NameMatch and finally the extension (Files). ShellScript . EmacsModes . FullNameMatch . NameMatch .

8.15 FullNameMatch

It can be used to indicate a regular expression to match the full path and name of the file. If the expression matches the editor will use this syntax highlighting.

The regular expression must be in Perl format. You can read about it in any book about Perl.

8.16 HexMarker

This setting indicates what prefix is used for hexadecimal numbers. No postfix is supported yet. The lenght is limited to four characters.

For more information Format of short syntax highlighting definitions .

8.17 Keywords

It can be used as many times as needed and is used to indicate the reserved keywords of the language. The separator is the comma.

8.18 Name

It sets the name of the syntax highlighting. This name is used in the local settings dialog (cmcSetLocalOptions).

8.19 NameMatch

It can be used to indicate a regular expression to match the name of the file. If the expression matches the editor will use this syntax highlighting mode.

The regular expression must be in Perl format. You can read about it in any book about Perl.

8.20 NoCheckNumbers

When this setting is on the numbers aren't highlighted.

8.21 OpenComment1

Used to indicate the start of a multiline comment. The lenght is limited to four characters. If the file format has two different starts use OpenComment2 for the second.

The maximum length is four characters, for more information about the format: Format of short syntax highlighting definitions .

All the characters after the equal sign are taken as part of the field. Blank spaces after the equal sign are ignored, so Field= // is equivalent to Field=//.

As the field may start with spaces and spaces at the end of line are invisible you can quote the text using the double quote letter. If you do it the first character after the equal sign must be the double quote, if you left an space like this: Field= " the double quote will be interpreted as part of the field.

When quoting text the back slash is the escape character, so this: Filed=""" will be interpreted as asigning " to Field.

8.22 PartialKeywords

When this setting is enabled the list of the editor will highlight partial matches of the keywords. For example, suppose a keyword is defined as key and you type keytable, in this case the editor will highlight the key part of the word. This feature is experimental and makes the highlighting quite slower.

8.23 PMacros

Indicates the name of the pseudo macros file used for this kind of files. Using different files for different formats you can assign common triggers to different actions. For example, you can use i( to trigger an if() {} else {} in C and an if then else in BASIC. Pseudo Macros .

8.24 Preprocessor

Indicates which symbol starts a preprocessor line.

8.25 RelaxNumberCheck

This is used when a number can start a name and that isn't a error. Normally the editor takes it as a wrong number but when this option is enabled the check for numbers is relaxed and they aren't highlighted as wrong values.

8.26 ShellScript

It indicates which scripts will be highlighted. You must indicate the names of the programs associated with this script. The names are case sensitive.

The editor looks for the #! characters at the start of the file, if found the name of the program is extracted and searched in this list.

The priority is as follows: EmacsModes, ShellScript and finally the extension (Files). EmacsModes . Files .

8.27 ShortString

Used to indicate the start and end of strings, used for small strings or characters. The string ends at the end of line if not explicitly closed.

8.28 SpecialSymbol

That's used to mark pairs of characters that form a particular symbol that will generate problems if the editor sees them as separated symbols. It was created to avoid problems with $# in Perl and bash scripts and with @@ in Texinfo files. You can define more than one character here.

The characters that can be combined with it are specified using the SpecialSymbolCont definition.

8.29 String1

Used to indicate the start and end of strings, used for long strings. You can specify more than one character, in this case any of them can open or close the string.

The editor supports up to three diferent strings declared as String1, String2 and String3.

8.30 Symbols1

Used to indicate which characters are allowed to be symbols, normally used for boolean and arithmetic symbols.

8.31 Symbols2

Used to indicate what characters are allowed to be symbols, normally used for flow control and subindex symbols.

8.32 UseInternal

That's optional. When a highlighting mode has this setting the editor will use the internal routines and will ignore almost all the settings. Only the extensions ( Files ) and pseudo macros ( PMacros ) settings are used.

The value assigned can be: 1 for GNU C highlighting, 2 for standard Pascal and 3 for Clipper.

So now, What's a Pseudo Macro? It's like a macro but it's triggered by two things: one the text before the cursor, and two the ^Space combination.

And what's the result? The result is customizable, but by default there are some predefined behaviours. For example, in a C source window type the following two characters: #i and then press ^Space ... (to create an empty file with .c extension go to File|Open and type a new name, foo.c for example).

Surprised? I bet! You got: #include <.h> and the cursor just at 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 ^Space ...

I bet this time you had an inkling of what will happen so you aren't that 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 wrote the hello world program at a very good speed.

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

9.2 How can I customize that?

It's very easy. Each syntax highlighting has its own pseudo macros file. Which file belongs to which syntax highlighting is indicated in the syntaxhl.shl file. Syntax Highlighting File . In the case of C/C++ the file is called cpmacros.pmc and is located in the same directory where the rest of the configuration files are installed. This file contains the definitions for each pseudo macro that can be triggered in C/C++ files. You can define as many pseudo macros as you want. Configuration files location .

Important: If you are using RHIDE consult the RHIDE documentation to know where the cpmacros.pmc file is stored.

The cpmacros.pmc file is a very good example and is self-explanatory but I'll include one example here.

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

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

• Overwrite Overwrite .
• Autoindent Autoindent .
• Use Tabs Real Tabs .
• Persistent blocks Block modes .
• Intelligent C indent Intelligent C indent .

The rest is the code to insert enclosed 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 be positioned at the beginning of the file. The places marked with @1, @2 and @3 are saved in the markers 7, 8 and 9.

Currently I defined pseudo macros only for C/C++ and Perl. I did it in a way that you can use the same pseudo macro for both languages. For example: #i is expanded to #include <.h> for C/C++ files and to request ""; for Perl files. If you write similar pseudo macros for other languages please send me the file and I'll add it to the next release.

The macros can be assigned to keys ( How to configure the keyboard ), selected from the Macro menu or from the menu. From the Macro menu you can choose a macro from the list. If you want to repeat it you can do so with one keystroke.

To add a new macro to the list you must edit the macros.slp file. You can write the new macro by hand or you can use the Macro menu to record a macro and then generate the sLisp code for this macro.

To assign a macro to a menu entry you must edit the menubind.smn. The macros are called using cm(name) where name is the name of the macro you want to trigger.

To assign a piece of sLisp code to a menu entry you must use cm((code)). Here is an example:

      MenuItemC: "Test macro from menu", cm((ShowInMessageWindow "Hi! ;-)"))

You can also assing a piece of sLisp code to a key. How to configure the keyboard .

I'll show you an example and then I'll explain each part of the example:

     (defmacro 'Testing 1 2 3 ;-)'
      (eval
       (SendCommands cmcLineEnd)
       (InsertText (+ 'Hi!' CR 'How are you?'))
       (SendCommands cmcLineUp cmcLineEnd)
      )
     )

10.2 How strings are parsed

sLisp strings can be delimited by single or double quotes (' or "). Currently both produce the same result but in the future it could change to be similar to Perl.

A few C escape sequences are supported inside strings. This means the character has a special meaning. Here are the values supported:

There is a sLisp command called RunProgram. It takes a string as parameter which can contain one or more programs separated by ; or the commands separator used by your command shell.

The standard output and error are redirected and the results are sent to the Message Window. If the program is a GNU tool and reported errors the editor will parse these errors and will allow you to directly jump to the file and line where the error was reported.

To learn more about the message window Message Window .

10.4 Editor specific commands

This section describes commands related to files being edited.

(AskString title message)

Pops up a dialog asking for user input. The text is returned as an sLisp string variable. If the user canceled the input, the string has zero length.

10.4.2 BindKey

(BindKey key_seq macro) (BindKey key_seq command ...)

This command creates a key binding data type. It doesn't change anything alone and must be used with the KeyBindings command.

You can assign a defined sLisp macro or a piece of sLisp code using the first syntax. When assigning a sLisp code it must begin with ( and end with ).

You can also assign a one command or a sequence of commands using the second syntax. The commands are specified using the same constants used for SendCommands. SendCommands .

The key_seq argument must be a string containing the key sequence used to trigger this definition.

The following example defines two keyboard sequences. The first is triggered when Ctrl and K are pressed together, then released and then Z is pressed (all in lower case mode). This sequence moves the cursor one line up and then one character to the left. The second sequence (^K-X) triggers a small sLisp sentence that prints a message in the message window.

     (KeyBindings
      (BindKey "CtK,Z" cmcLineUp cmcCharLeft)
      (BindKey "CtK,X" "(ShowInMessageWindow 'Hi! ;-)')")
     )

An important detail is that this command can replace already defined keys and can even replace a group of assignments by the new definition. You can assign a command to CtK removing all the ^K assigments during this operation.

10.4.3 ComplChoose

(ComplChoose options delimiter [flags])

Brings up a floating drop-down list with the options. The options parameter is a delimited string, the delimiter is specified by the delimiter parameter.

The function returns the option selected by the user or an empty string if the user aborted.

The list is sorted alphabetically, the user can choose the item using the cursors or doing an incremental search. Only characters allowed for reserved words are accepted, any symbol will choose the currently selected item, other characters will abort.

The flags parameter fine tunes the behavior of the routine. Currently only one thing can be changed. By default the string returned contains the character that produced the selection appended at the end of the string. Passing 1 for flags the character isn't concatenated.

10.4.4 defmacro

(defmacro name expression)

Defines a new editor macro called name. When this macro is called the expression is evaluated. How to write a sLisp macro .

10.4.5 EvalString

(EvalString string)

Executes the sLisp code contained in the string variable.

10.4.6 FindAgain

(FindAgain)

Repeats the last search. It should be used when you didn't gave control to the user since the last search because the user could perform a different search changing the compiled search. Returns the text found or an empty string if no match could be found. FindString .

10.4.7 FindString

(FindString string [options_flags])

Performs a search for the provided string. Returns the text found or an empty string if no match could be found. This operation moves the cursor position as in an interactive search. The match becomes temporally highlighted in the text.

Even when the options_flags argument is optional it is strongly recommended to provide it. If nothing is provided the user options will be used instead. The options are provided as flags combined with the | operand. Some of the flags doesn't have any sense when combined with others, you should avoid doing it. The available flags are:

Search style:

• edfCaseSensitive: perform a case sensitive search.
• edfWholeWordsOnly: don't match partial words.
• edfRegularEx: the string is a regular expression. Note this flag must be indicated in adition to the type of regular expressions used.

• edfSearchInComm: search only inside comments.
• edfSearchOutComm: search only outside comments.
• edfOnlySelection: search only inside the selected text.
• edfFromCursor: start searching from the cursor position. That's the default action.
• edfFromBeggining: start searching from the beggining of the selected scope.

• edfBasicRegEx: use basic POSIX regular expressions. Used in combination with edfRegularEx.
• edfExtendedRegEx: use extended POSIX regular expressions. Used in combination with edfRegularEx.
• edfPerlRegEx: use Perl regular expressions. Used in combination with edfRegularEx.
• edfOptimizeRegEx: if the string to search doesn't contain special characters and regular expressions are enabled perform a normal search. This makes the search much more faster. This is the default action so you don't really need to specify this flag.
• edfNoOptimizeRegEx: it is the opposite of edfOptimizeRegEx flag. It disables the optimization. Use it when you are sure the string is a regular expression even when it doesn't look like a regular expression. This option was created just in case the optimization fails to detect a real regular expression.

• edfShowFuncName: display the name of the function where the match was found in the status line.