cooledit(1)

NAME
cooledit-3.11.6 - Full featured text editor for the X Window System, Version 11.

USAGE
cooledit [-AabCEhiPsSUVv?] [options] [[+<line>] [<path>/]<file>] [[+<line>] [<path>/]<file>] ...

DISCLAIMER
The information in this file is provided without warranty for its accuracy or completeness. Use of this file or its information is entirely at your own risk.

DESCRIPTION

This is a portable, fast X Window text editor with beautiful 3D widgets. It requires only the X11 library to run. The engine is the same as that used for the internal editor of the Midnight Commander and hence cooledit represents a X Window version of that editor. The library that comes with Cooledit is now standalone. You can use it to write your own Cool applications. Check out the included programs Coolman and Smalledit.

OPTIONS

-d, -display <display>
    The X server and display you would like to display to.

-g, -geom, -geometry <geometry>
    Main window size and position on the screen, eg cooledit -geom 630x490+95+5. If cooledit is envoked with the size, the size will be saved on exit. If cooledit is envoked with the position, the position will be saved on exit. cooledit -geom + envokes the default size.

-lines <n>
    Size of the edit window in text lines.

-columns <n>
    Size of the edit window in mean character widths.

-vis, --visual <visual-class> (experimental)
    Without this option, the visual class is selected from a list of preferred classes and depth ranges. Use cooledit -vis help for more information.

-C, -cmap, --own-colormap (experimental)
    Force use of own colormap. If Cooledit is started after other colour-hungry application, and you are using one of the colour-palette visuals (like PseudoColor) the colors may look poor. In this case, use this option for a separate colour palette. (Contact me if you are forced to use this option.)

-defcmap, --default-colormap (experimental)
    Force use of default colormap. If Cooledit is started with a visual other than the default, then it creates its own colormap. This overrides this behaviour. (Contact me if you are forced to use this option.)

-bg, --background-color <color>
    Specifies the background color for a solid background. If <color> is igloo (default) then a background color is not used, and the background is set to the igloo logo.

-R, --foreground-red <value>
    Red component of actual widget colors (buttons, windows), default: 0.9.

-G, --foreground-green <value>
    Green component, default: 1.1.

-B, --foreground-blue <value>
    Blue component, default: 1.4.

-f, -fn, -font <font-name>
    The font you would like to use. All ISO fonts are now supported. Default: 8x13bold. (See FONTS below.) If <font-name> is default then the default font is envoked. If <font-name> is -? or -h then a list of example fonts are printed. If <font-name> is a number, then the example font of that number is used, eg cooledit -font 3

-S, --suppress-load-files
    Don't load saved desktop on startup.

-U, --suppress-load-options
    Don't load any saved options on startup.

-E, -no-override
    Command line must not override any options already set in the initialisation file.

-I, --use-initialisation-file <file>
    Use alternative intialisation file. Default: ~/.cedit/.cooledit.ini

-i, --international-characters
    Display international characters (i.e. non-US) and enable multi-key composition. (See INTERNATIONAL CHARACTERS below. Default: treat characters above 127 as non-printable binary characters.

-noi --no-international-characters
    Do not display international characters.

--word-wrap <length>
    The maximum length of a line. See the next two options.

--type-writer
    This option causes a newline to be inserted when the line you are typing becomes longer than --word-wrap length.

--auto-paragraph
    This is a more advanced form of the option above: it causes the entire paragraph to be reformatted with each edit of a paragraph. See WORD PROCESSOR MODE below.

-t, -tab, --tab-spacing <spacing>
    Interpret the tab character as being the length of <spacing> characters. Default is 8. You should avoid using other than 8 since most other editors and text viewers assume a tab spacing of 8. Use -fake-half-tabs to simulate a smaller tab spacing.

-s, -space, --space-filled-tabs
    Never insert a tab space. Rather insert spaces (ascii 20h) to fill to the desired tab size.

-nospace, --no-space-filled-tabs
    Default.

-a, --auto-indent
    Pressing return will tab across to match the indentation of the first line above that has text on it (default).

-noautoi, --no-auto-indent
    Turn off auto tabs.

-b, --backspace-through-tabs
    Make a single backspace delete all the space to the left margin if there is no text between the cursor and the left margin.

-noback, --no-backspace-through-tabs
    Default.

-half, --fake-half-tabs
    This will emulate a half tab for those who want to program with a tab spacing of 4, but do not want the tab size changed from 8 (so that the code will be formatted the same when displayed by other programs). When editing between text and the left margin, moving and tabbing will be as though a tab space were 4, while actually using spaces and normal tabs for an optimal fill. When editing anywhere else, a normal tab is inserted.

-no-half, --no-fake-half-tabs
    Turn off half tabbing.

-toolbar
    Edit windows have a toolbar on the left: default.

-no-toolbar
    Edit windows do not have a toolbar.

-m, --minimal-main-window
    This is used internally to create a new main window with one edit window when the user activates `New Main Window' from the Window menu. You can also use it to force the main window to be just large enough to hold all the sub-windows.

-A, -save-setup
    Save options on exit (default).

-P, -no-save-setup
    Don't save options on exit.

-W, --whole-chars-search <chars>
    Characters that constitute a whole word when searching, default: 0-9a-z_ (typed out in full)

-w, --whole-chars-move <chars>
    Characters that constitute a whole word when moving and deleting, default: 0-9a-z_; ,[](){} (typed out in full)

-verbose
    Print info about X intialisation.

-h, -H, -?, --help
    Print out commandline options summary.

-V, -v, --version
    Print out version number.

Commandline examples

cooledit +10 hello.c -S -geom +
    Start cooledit with one file, with minimum geometry, with cursor at line 10.

cooledit hello.c program.c
    Start cooledit with two files, the file hello.c being the current file. The previous files are also loaded underneath these two files.

MAILING LIST
To join, email majordomo@mail.obsidian.co.za with the line subscribe cooledit in the body of the message. Patches, and anything you would like to say about cooledit, are welcome at cooledit@mail.obsidian.co.za .

Features
Cooledit supports multiple edit windows and has all the conveniences of MSW/MAC text editors. The interface has a beautiful 3D look and feel vaguely like Motif. It has an extensible file size limit of 64Mb and edits binary files flawlessly. Besides typical functions of a basic editor, cooledit has the following features: a builtin Python interpretor for Python programmability; spell-check as you type with red wavy lines; graphical C/C++ debugger; Key for key undo; shift-arrow text highlighting; macro recording; a generic shell execution facility that can be used to run make, sort or any user defined shell function on text or editor files; easy key redefinition; mouse text highlighting; XDND drag and drop; double-click on a gcc error message to go immediately to the file and line number; desktop and cursor position memory; easy window cycling; comprehensive search and replace; input histories; and lots more. The editor is very easy to use and requires no tutoring. To see what keys do what, just consult the appropriate pull-down menu. A complete set of key definitions follows.

DEFAULT KEY DEFINITIONS
Keys may be redefined using an easy to use key learner. See the next section on how to get this to work. The following is a partial list of all default key bindings and their actions, for reference. You will probably never need to refer to it because most of the editor actions can be found in the menus. Note that F14 is analogous to Shift-F4 etc. Also be aware that on some machines, what X percieves as an Alt/Meta is actually some other modifier key (our Sun-Sparc uses the diamond key).
Movement keys:
   Left                    left one char
   Right                   right one char
   Up                      up one line
   Down                    down one line
   Home                    beginning of line
   End                     end of line
   PgUp                    up one screen full
   PgDn                    down one screen full
   Ctrl-PgUp               beginning of file
   Ctrl-PgDn               end file
   Ctrl-Home               beginning of page
   Ctrl-End                end of page
   Ctrl-Left               left one word
   Ctrl-Right              right one word
   Ctrl-Up                 up one paragraph
   Ctrl-Down               down one paragraph
   Meta/Alt-Up             scroll up one line
   Meta/Alt-Down           scroll down one line
Highlight keys:
   Shift with any of the above keys will highlight
   at the same time.
Column highlighting:
   Holding down the Control key while using the mouse to highlight text,
   will cause the highlighted text to be displayed in inverse colour. You
   will be able to select columns (arbitrary rectangles) of text and
   drag and drop them as usual.
Input History:
   When editing an input line, Shift-Up or Shift-Down
   will bring up a history of previous inputs.
Editing keys:
   Delete                  delete char to the right
   Backspace               delete char to the left
   Meta/Alt-Del            delete to line end
   Meta/Alt-Backspace      delete to line begin
   Meta/Alt-Right          delete word to the right
   Meta/Alt-Left           delete word to the left
   F5                      copy highlighted text to cursor
   F6                      move highlighted text to cursor
   F8                      delete highlighted text
   Ctrl-y                  delete line
   Shift-Enter             insert a newline
   Enter                   insert a newline with auto indent (default)
   Tab                     insert a tab (see options menu)
   Insert                  toggle insert/overwrite
   Ctrl-q                  quote - the next key pressed will be
                           interpreted as a literal
Undo:
   Ctrl-u
   Ctrl-Backspace
File
   Ctrl-F1                 man page
   F2                      save
   F12 or
   Shift-F2                save as
   Ctrl-o                  load
   Ctrl-n                  new
   Ctrl-f                  save highlighted text as
   Shift-F5 or
   F15                     insert file at cursor
Mark:
   F3                      toggle highlight
   Ctrl-b                  toggle highlight columns
Search and replace:
   F7                      search
   F17 or
   Shift-F7                search again
   F4                      replace
   F14 or
   Shift-F4                replace again
X Clipboard:
   Ctrl-Ins                copy to clipboard
   Shift-Ins               paste to clipboard
   Shift-Delete            cut to clipboard
   Ctrl-Delete             delete highlighted text
   Meta/Alt-Ins            insert from selection history
General:
   F10                     exit (current editor)
   Ctrl-F3                 new edit window
   Shift-F3                new main window
   Alt-F6                  maximise the window
   Ctrl-F6                 window cycle
   Ctrl-F10                exit application
   Meta/Alt-x              save all and exit
   Ctrl-F2                 save state of desktop
   Ctrl-d                  insert date and time
   Meta/Alt-l              goto line number
   Meta/Alt-F7             run make
   Meta/Alt-t              sort
   Ctrl-r                  start/end record macro
   Ctrl-a                  execute macro
   Ctrl-p                  spell check highlighted text
   Shift-F9                C formatter
   Ctrl-Tab                Complete word
New shell scripts will be added from time to time. Consult the Scripts menu for the hotkeys that envoke these.

EMERGENCIES
keywords: hang, crash, halt, pause, stop, infinite loop, SIGHUP, SIGUSR1. There are some circumstances when Cooledit may go into an infinite loop, like if there is a bug in the editor movement commands, or if you create a recursive macro. In this case, you can restore Cooledit by using the kill shell function. Try kill -SIGUSR1 pid where pid is the process ID of cooledit from: ps | grep cooledit, for example. This will send SIGUSR1, a user signal, which, for Cooledit, will force a jump into its main loop, and restore operation. It is a good idea to then save what you have done and exit immediately in case there has been memory corruption.

KEY REDEFINING
The Options menu has a key binding learner which is easy to use. The key learning dialog contains a list of every re-definable action that the editor can perform. Simply click on the action you want to associate a key to, and press that key. An 'X' will appear next to the action to indicate the recording of a binding. To clear that binding click on the Clear Line button (or the Clear All button to clear all the bindings). You can even bind the same action to two separate keys: for instance using either the key pad arrows, or the normal arrows for cursor movement --- just click on that action again, and hit another key --- where two X's will appear. Up to three keys can be associated with an action. The binding is also sensitive to the keyboard 'state' (i.e. whether Control, Shift, Alt, Meta, or Hyper is pressed, and any combination of these) so binding Shift-Left to an action will work, and will be considered a different key stroke to Shift-Control-Left, and will also be considered a different key stroke to Shift-Left with NumLock on. Note that the difference between 'Enter' and 'Return' is that the one does an auto-indent. The key binding records X11 key-codes. These are the actual hardware codes that come from the keyboard, so the key binding works on the lowest possible level of interpretation. The editor checks for these user defined keys before any hard-coded key bindings, so user binded keys will override the default key bindings. This means user defining keys will always work, but may be specific to the hardware you are using. To redefine hardcoded keys (i.e. the default keys), modify the file edit_key_translator.c and then recompile. It contains simple C code which gets incorporated directly into the program during compilation. Note that the first function it calls is to get the user defined action for the key if there is one. To recompile, remove the file edit.o and run make in the top directory. This will allow you to change any key-binding. The editor menu however will have to be modified separately to reflect the changes you've made (see editmenu.c). A detailed explanation is given in the commentary of edit_key_translator.c. (I added key redefinition mainly because different X Servers seem to interpret the same keys differently. It seems ridiculous that this should happen in the face X11's thorough key definition standard. The new X11R6.3 for Linux does seem to interpret keys properly and all the keys should work as expected on the PC; so there should be no need to redefine keys under Linux. You can however easily emulate another editor as you like.)

SPELL CHECK AS YOU TYPE
As of version 3.10.0, Cooledit spell checks typed words on the fly, placing the traditional wavy red line under miss-spelled words. This works by feeding typed words through ispell and placing them amidst the syntax highlighting rules if ispell returns a non-match. These rules expire after 60 seconds - which mean they won't stay underlined indefinitely. Word feeding is initiated by most key presses and applies only to the word under the cursor. To look up a word, merely move the cursor over it.

THE INTERACTIVE GRAPHICAL DEBUGGER
As of version 3.9.0, Cooledit features an interface to gdb(1) under the new Debug menu. This means that you can seamlessly debug C/C++ programs from within Cooledit just like you used to with your DOS Turbo Debugger. This is extremely cool. You can set and clear breakpoints (the line is bookmarked in red) and follow the program flow with the green cursor line. Please remember that this an interface to gdb: Cooledit has no debugging features of its own. If you do not have the correct version of gdb, then a warning will be displayed on startup. Interfaces are given to the common gdb commands. Any other commands can be executed with the Enter Command menu item. Automatic variable displays will soon be available though. When a program stops for some reason (either a breakpoint or a signal), Cooledit tries to determine the file and line number. If this cannot be done, a backtrace is displayed. Backtraces do not contain full paths, hence files cannot be located if they are not already loaded. If the file is already loaded, then hitting enter on a file:line backtrace line will jump to the currect line number. Programs must of course be compiled with the -g option and preferably the -O0 option (without -O0 gcc's optimizations may make the program flow appear a little strange and some variables will not be accessible). Break-points are set and cleared from the menu or with Meta-F2. If you set a break point manually (with Meta-F1) it will not display in the edit window. Similarly if you clear a break point manually or close a window (thus clearing the breakpoints) there will be discrepancy between the book marks and the actual breakpoints. The same goes if you modify a file without restarting gdb. Variables can be displayed by selecting Display variable.... A listbox will show all the variables you have selected. Click on the listbox and press Del to delete from this list. Use Ins to highlight a variable - this will cause a watchpoint to be inserted for this variable (i.e. the program will thereafter stop whenever the value of that variable changes). The listbox will also show an X in the second column if the variable has been altered since the last time the listbox was refreshed - this enables you to easily see which variable changes as you step through the lines of your program. Everything else you need to know is obvious from the menu. You would do well to read gdb's info pages if you have never used a debugger under Unix before.

PYTHON MACRO PROGRAMMING
As of version 3.8.0, Cooledit has a builtin Python interpretor. This means that Cooledit can execute arbitrary Python scripts from within its environment and bind scripts to keys and so forth. This is analogous to the way that Emacs uses a Lisp interpretor. Python is an object orientated scripting language like java, but with a much saner syntax. It is used for Rapid Application Development, and as a replacement for other intepretor languages like Perl, Tcl and Lisp. On startup, Cooledit reads the top level Python file lib/cooledit/global.py, and then the user's personal file ~/.cedit/global.py. Any Python code can go into these files. No other files are explicitely read, but the code within global.py will call other Python files. The location of the directory lib/cooledit/ is dependant on your installation and is added to the default search path for modules. To learn to program in Python, consult the tutorials and reference manuals that come with the Python sources. One of the reasons for the python interpretor is to enable emulation of other editors such as vi and Emacs. It is quite feasable to write python scripts that will emulate all of the functions of these editors, and have user dialogs and menu items to switch between different editor emulations...

def get_ctrl_x_key():
    status ("\034Press \030s\033\035")
    k, m = get_key ()
    if m == 0:
        if k == "s":
            command (Save_As)
key ("x", ControlMask, "get_ctrl_x_key()")

The \034 and \035 means to draw a bevel around the enclosed text. The other escape characters cause colour changes (1 - 26, 27 = black).

Another powerful capacity is to have utilities specific to the particular file type that is being edited. When the type of an edit window is changed, the function type_change() from the global.py script is run. This function must run an appropriate file for the given file type which defines keys and creates menu items in that window's Util menu. The following low level function are defined for manipulating the edit buffers. The functions operate on the current edit buffer. This is usually the one with the focus.

move(int)
    Moves the cursor relative to its current position in units of one character.

move_to(int)
    Moves the cursor to an absolute position in the buffer.

move_lines(int)
    Moves the cursor relative to its current position up or down.

int buffer_size()
    Returns the size in bytes of the edit buffer.

insert(string)
    Types out the given string at the current cursor position.

indent([int])
    Inserts tabs and spaces according to the current half-tab and tab settings. The inserted margin copies the margin from the first non-blank line above the current line. If an argument is given, then it makes the margin bigger or smaller by this many tabs. i.e. insert ("\n"); indent (3) is like hitting Enter and then hitting Tab three times.

insert_ahead(string)
    Inserts the given string ahead of the current cursor position.

back_space(int)
    Deletes the given number of characters behind the cursor.

delete(int)
    Deletes the given number of characters ahead of the cursor.

int current()
    Returns the current absolute cursor position.

int current_line()
    Returns the current line number counting from zero for the first line.

int bol(int)
    Returns the absolute offset of the start of the given line.

int eol(int)
    Returns the absolute offset of the end of the given line.

int find_forwards(int, string)
    Searches forward from the given offset and returns the absolute offset of the found string.

int find_backwards(int, string)
    Searches backward from the given offset and returns the absolute offset of the found string.

int line(int)
    Returns the line number of the given offset. Repeated calls to this function will be slow.

string get_text([int[, int]])
    Returns a string containing the characters between the given offsets. If the second argument is omitted, then this returns a string one character in length at the given offset. If both arguments are omitted then this returns the character under the cursor.

string get_line([int[, int]])
    Returns a string containing the characters between the given lines inclusive. If the second argument is omitted, then this returns a string containing the given line. If both arguments are omitted, then this returns the current line of the cursor. The trailing newline is not included.

The following functions allow binding of arbitrary python code to menu items and keys:

key(string, int[, string])
    Binds a python statement to a key. The last argument contains python code. If it is omitted then the action is to unbind the key if it is bound. The first argument is the string representation of a key from the keysymdef.h X Window header file (with or without the XK_ prefix). The second argument is zero or the inclusive OR of any of the following modifiers:

    ShiftMask

    LockMask

    ControlMask

    AltMask

    Mod1Mask

    Mod2Mask

    Mod3Mask

    Mod4Mask

    Mod5Mask

    AltMask is defined in the global.h header file in the distribution and is system dependant. The usual usage of this function is to bind a key to a short python statement. The statement itself would then call functions that were previously defined. The key binding will be seen through all edit windows.

bind(string, string, int[, function])
    Binds a python function to a range of keys in the current editor. If the last argument is omitted then the action is to unbind those keys if they are bound. The first two arguments are the string representation of a range of keys from the keysymdef.h X Window header file (with or without the XK_ prefix) (for example bind ("A", "Z", ControlMask, control_keys), which binds the keys A through Z to the function control_keys). The third argument is the modifier as with the key() function. The bound function must take two arguments: the key name as a string and the modifier as an integer.

    The key binding will be seen in the current (focussed) editor window only. If the same key is bound globally (using the key() function), then it will be overridden by bind().

    This is useful for binding particular keys depending on the type of text being edited. bind() should hence be used within the type_change() function.

menu(string, [string[, string]])
    Creates a menu item. The last argument contains python code. If it is omitted then the action is to remove the menu item if it exists. The first argument is the name of one of the menus and can be one of File, Edit, Search, Command, Options, Readme or Util. The second argument is the menu item text to be added to the given menu. The Util menu is specific to each editor window, hence this is useful for defining tools specific to a particular file type. The Util menu is activated by pressing on the Util tool button of each editor window, or Meta-U. If only one argument is given, then this command clears the menu of all its items.

The following functions return information about the current edit buffer:

string file()
    Returns the file-name excluding the path.

string directory()
    Returns the directory.

int modified()
    Returns the flag to indicate if the buffer has been modified since the last load or save.

int overwrite([int])
    Returns the overwrite flag (indicating type-over mode). If an integer is given, then this sets the overwrite flag and returns the previous value of the overwrite flag.

(int, int, int, int, int) markers([int, int[, int, int, int]])
    Returns the state of the markers. The five values returned are: the starting marker, the ending marker, a flag indicating whether column highlighting mode is on, the starting column and the ending column. The last two values should be ignored if column highlighting (the third value) is found to be zero. If nothing is highlighted then this function returns None. If values are passed to the function, then the state of the markers will be set to those values. Note that if the end marker is -1, then the ending marker is the cursor and movements of the cursor will change the selection. If the third argument is zero then that last two arguments are ignored.

The following functions display and return information to/from the user:

(tuple, tuple) generic_dialog(string, tuple, tuple, tuple, tuple, tuple, tuple, tuple [[, int], int])
    This function takes a string value as the title to a dialog, then displays the dialog, returning the results of various checkboxes or input widgets. The dialog has the same format as what you will see when doing a Find file from the File menu. An arbitrary number of input widgets or check boxes can be specified. The arguments passed to generic_dialog are as follows.

    string
        Title of the dialog.

    (string, string, ...)
        A list of default strings to go into each of the input widgets.

    (string, string, ...)
        A list of labels to go above each of the input widgets.

    (string, string, ...)
        A list of names used internally to store histories of entries to that input widget. These can be anything, although a descriptive name, of about 20 characters in length, will ensure uniqueness for each widget. This is actually the internal name of the widget which must be unique within the entire application. Something of the form dialogname.entryname for each input widget is fine.

    (string, string, ...)
        A list of tool hints for each input widget. Elements may be null or there may be less elements than the number if widgets.

    (int, int, ...)
        A list of values for check boxes - either 0 for off or 1 for on.

    (string, string, ...)
        A list labels for each check box.

    (string, string, ...)
        A list of tool hints for each checkbox. Elements may be null or there may be less elements than the number if widgets.

    int An optional width of the dialog. This is in units of the mean character width for the current font. The default value is 60.

    int An optional options integer being the inclusive OR of one or more of the following values:
            INPUTS_WITH_OPTIONS_BROWSE_LOAD_1
            INPUTS_WITH_OPTIONS_BROWSE_SAVE_1
            INPUTS_WITH_OPTIONS_BROWSE_DIR_1
            INPUTS_WITH_OPTIONS_BROWSE_LOAD_2
            INPUTS_WITH_OPTIONS_BROWSE_SAVE_2
            INPUTS_WITH_OPTIONS_BROWSE_DIR_2
            INPUTS_WITH_OPTIONS_BROWSE_LOAD_3
            INPUTS_WITH_OPTIONS_BROWSE_SAVE_3
            INPUTS_WITH_OPTIONS_BROWSE_DIR_3
        This indicates that a `Browse' button should accompany the entry widget. The browse button will open a file with behaviour appropriate to loading, saving or selecting a directory.

    The return values are two tuples containing a list of the values of the input widgets and checkbox's respectively. If the dialog was canceled, the return value is null.

    As an example, the find file dialog can be reproduced as follows:

x = generic_dialog ("Find file",                                \
    (".", "*.[ch]", ""),                                        \
    (   "Starting directory",                                   \
        "Filenames matching glob expression",                   \
        "Containing" ),                                         \
    (   "find-start_dir",                                       \
        "find-glob_express",                                    \
        "find-containing" ),                                    \
    (   "Starting directory for the recursive search",          \
        "Glob expressions such as *.[ch] or *.doc",             \
        "Check if file contains this sequence" ),               \
    (0, 0, 0, 0),                                               \
    (   "Containing reg. exp.",                                 \
        "Containing case insens.",                              \
        "Search follows symlinks",                              \
        "Search is case insens." ),                             \
    (   "Enter regular expression pattern to find within file", \
        "Match case insensitively when searching within files", \
        "Dive into symlinks to directories",                    \
        "Filenames are matched case insensitively" ),           \
    60, INPUTS_WITH_OPTIONS_BROWSE_DIR_1                        \
)
if x:
    inputs = x[1]
    checks = x[2]

The following are more simplistic utility dialogs:

string input_dialog(string, string, string)
    Brings up an input dialog. Takes a title, prompt string and default value as input. Returns the entered string or None if cancelled.

string save_file_dialog(string, string, string)
    Brings up a file browser dialog. Takes a title, a starting directory and a default value as input. Returns the entered string or None if cancelled.

string load_file_dialog(string, string, string)
    This has a slightly different behaviour to save_file_dialog - if a non existing file is entered, it reports an error.

message_dialog(string, string)
    Brings up a message dialog with the given title and message.

error_dialog(string, string)
    Brings up an error dialog with the given title and message.

int query_dialog(string, string, string, ...)
    Brings up a query dialog. Takes a header, a prompt and a number of alternative buttons. Returns the button number or -1 on cancel.

status(string)
    Sets the status line of the current editor. The status line will return to its usual when a key is pressed. This can be used with getkey() to inform the user of possible key presses.

string status_input(string, string)
    Sets the status line to an entry widget with the first argument as the prompt string, and the second argument as the default text. Returns the entered text or None if Esc is pressed.

(string, int) get_key()
    This blocks waiting for a key press, and grabs the application. It returns the string equivalent of the key press as in the X Window header file keysymdef.h without the XK_ prefix. It also returns the current state of the keyboard modifiers, being the inclusive or of ShiftMask ... etc. as listed above.

The following function allows display of shell output as those in the Scripts menu.

int shell_output(string, string, string)
    This displays the output of a shell command continuously in its own window in the background. As always, clicking on file:line type messages will cause the editor to jump to that file and line number.

    The arguments are: the title of the output dialog, the shell program (which should begin with #!/bin/sh or similar), and a unique descriptive magic string that identifies the dialog. An example of a magic string is FindfIlEmAgiC used by the find file dialog - if you use the same magic string, then a new window will not be created if the find file display window exists.

The following functions manipulate editor windows:

(string, ...) get_editors()
    Returns a tuple with an entry for each editor window. These are the full path names of the open files.

set_editor(string)
    Sets the current editor with the full path name. This allows manipulation of a different edit buffer, but does not set input to that buffer.

focus()
    Raises and the current editor window and sets the input focus to the current editor.

close_window(int)
    Close the current edit window. If a non-zero value is passed, then this forces a close, regardless of whether the buffer is modified or not.

new_window()
    Create a new editor window with no text in it.

load(string)
    Load a file into the current window. This will replace any text in the current edit window.

The following are further miscellaneous commands:

command(string)
    Executes an arbitrary editor command. These are listed in the Define Keys dialog.

redraw_page()
    After the edit buffer has been modified, the window must refresh. Usually just the current line is redrawn. If you have made changes which may reflect a different display on other lines, then call redraw_page() before returning to ensure that the entire screen displays correctly.

SYNTAX HIGHLIGHTING
As of version 3.6.0, cooledit has syntax highlighting. This means that keywords and contexts (like C comments, string constants, etc) are highlighted in different colours. The following section explains the format of the file ~/.cedit/syntax. The file ~/.cedit/Syntax is rescanned on opening of any new editor file. It contains a list of file types and how to identify what rule set the text you are editing belongs to. The file token dictates how to match up your text. On the same line as a file token must appear a regular expression to match the filename, a string to be displayed on the left of the editor window for description purposes, and a regular expression to match the first line of the file. If either of the regular expressions match, the file is deemed to have the particular type. For example

file ..\*\\.(py|PY])$ Python\sProgram ^#!\s\*/.\*/python

Will cause a file to be labelled as Python Program if it contains say, #!/usr/bin/python, on the first line OR of it ends in say .py. Note that *, + and \ have to be escaped with a \, and space must be presented with a \s. After the file keyword may come the include keyword. The include keyword says to load a rule set from a separate file, and is the preferred way of adding new rule sets. The path from where it loads defaults to cooledit/syntax/ under the lib/ directory where you installed Cooledit. See the examples in your own Syntax file and in this directory. Each rule set is divided into contexts, and each context contains keyword definitions. A context is a scope within the text that a particular set of keywords applies to. For instance, the region within a C style quote (i.e. between " quotations) has its own separate colour and hence its own separate context. Within it, the normal C tokens, like if and while, will not apply, but %d should be highlighted in a different colour. Contexts are usually for when you have something that must be coloured across multiple lines. The default context contains the list of keywords to fall back on should there be no other applicable context. This is usually normal programming code. A trivial C programming rule set might look like this:

file .\*\\.c C\sProgram\sFile (#include|/\\\*)
wholechars abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_
# default colors
context default
  keyword  whole  if       yellow/24
  keyword  whole  else     yellow/24
  keyword  whole  for      yellow/24
  keyword  whole  while    yellow/24
  keyword  whole  do       yellow/24
  keyword  whole  switch   yellow/24
  keyword  whole  case     yellow/24
  keyword  whole  static   yellow/24
  keyword  whole  extern   yellow/24
  keyword         {        brightcyan/14
  keyword         }        brightcyan/14
  keyword         '*'      green/6
# C comments
context /\* \*/ brown/22
# C preprocessor directives
context linestart # \n brightred/18
  keyword  \\\n  yellow/24
# C string constants
context " " green/6
  keyword  %d    yellow/24
  keyword  %s    yellow/24
  keyword  %c    yellow/24
  keyword  \\"   yellow/24

Each context starts with a line of the form:
context [exclusive] [whole|wholeright|wholeleft] [linestart] delim [linestart] delim [foreground] [background]
One exception is the first context. It must start with the command
context default [foreground] [background]
or else cooledit will return an error. The linestart option dictates that delim must start at the beginning of a line. The whole option tells that delim must be a whole word. What constitutes a whole word are a set of characters that can be changed at any point in the file with the wholechars command. The wholechars command at the top just sets the set exactly to its default and could therefore have been omitted. To specify that a word must be whole on the left only, you can use the wholeleft option, and similarly on the right. The left and right set of characters can be set separately with,
wholechars [left|right] characters The exclusive option causes the text between the delimiters to be colourised, but not the delimiters themselves. Each rule is a line of the form:
keyword [whole|wholeright|wholeleft] [linestart] string foreground [background]
Important to note is the line
  keyword  \\\n  yellow/24
This line defines a keyword containing the \ and newline characters. Because keywords have a higher precedence than context delimiters, this keyword prevents the context from ending at the end of a line if the line ends in a \ thus allowing C preprocessor directive to continue across multiple lines. The colours themselves need to apply to the Midnight Commander internal editor as well as to Cooledit. Therefore the form
    midnight-commander-color/cooledit-color
is used. See some of the many rule sets given, for examples on using this. Usually the background colour is omitted, thus defaulting to the usual background colour. Context or keyword strings are interpreted so that you can include tabs and spaces with the sequences \t and \s. Newlines and the \ are specified with \n and \\ respectively. Since whitespace is used as a seperator, it may not be used explicitedly. Also, \* must be used to specify a *, and a \+ to specify a +. The * itself is a wildcard that matches any length of characters. The + is like the * but matches a length of non-whitespace characters only. For example,
  keyword         '+'      green/6
  keyword         '\s'      green/6
colours all C single character constants green. You could also have used
  keyword         "*"      green/6
to colour string constants, except that the matched string may not cross newlines. The \{ wild card matches any characters that exists between it and its matching \fP. For example, the following matches C style octals:
  keyword '\\\{0123\01234567\01234567' brightgreen/16

The \[ \] wild card is similar and matches any number of characters. All wild cards may be used within context delimiters as well, but you cannot have a wildcard as the first character of a context delimiter. In addition, using a wildcard as the first character of a keyword, impacts hugely on performance. The colours themselves are numbered 0 to 26 and are explained below in FURTHER BEHAVIOURAL OPTIONS. You can also use any of the named colors specified in /usr/lib/X11/rgb.txt, though only one word versions of them. It is better to stick to the numerical colors to limit use of the color palette. Comments may be included on a line of there own and begin with a #. Because of the simplicity of the implementation, there are a few intricacies that will not be coped with correctly but these are a minor irritation. On the whole, a broad spectrum of quite complicated situations are handled with these simple rules. It is a good idea to take a look at the syntax file to see some of the nifty tricks you can do with a little imagination. If you can't get by with the rules I have coded, and you think you have a rule that would be useful, please email me with your request. However, do not ask for regular expression support, because this is flatly impossible. A useful hint is to work as much as possible with the things you can do rather than try to do things that this implementation can't cope with. Also remember that the aim of syntax highlighting is to make programming less prone to error, not to make code look pretty.

HTML SYNTAX HIGHLIGHTING
Html syntax highlighting supports highlighting of legal attributes within tags. This means that legal keywords between < > sequences will be highlighting. As of this writing, about half of all HTML tags have been added with their attributes. Only attributes common to Netscape as well as IE are listed. W3C was also taken into account, hence you can be fairly certain that the attribute is portable if it gets highlighted. Note that the Netscape tags reference was used to compile these syntax rules and obeys the convention that tags are in uppercase and attributes are in lower case. The syntax highlighting is therefore case-sensitive. By the time you read this, all tags may have been added.

COMPLETION
This feature was added in version 3.3.2. This would typically be used by typing in half a word (for example "str") and then pressing the completion key, "Ctrl-Tab" (Note that anything can be completed eg. email addresses.) A list box will then appear showing you all the words on your system that begin with str: strcat, strchr, strcpy etc. You can select the word to type out. If there is only one match then the word will be completed without showing the list box. If there is no match then nothing will happen. Note that completion is case sensitive Thanks to Michael Zagorsky for this idea. Unfortunately, a word-list of completion words is highly dependent on your system and the programming language you are using. It is very easy to create your own word-list though. The word-list must reside in the file "/.cedit/cooledit.completion". The file is simply a list of words separated by newlines, preferably with no duplications. It may have leading or trailing blank lines, but there must be no blank lines in the text. Of course, having a word in the word-list therefore has nothing to do with whether the word will or will not be accepted by the programming language you are using. The easiest way to create a really comprehensive word-list for C programming is just to concatenate, sift and sort all the system header files. This is done with the shell script below. If your system commands do not support some of the options used, you should replace them with GNU versions from your sunsite mirror. On my system, the script creates a file of about a megabyte in size, 83k words, which is reasonably small. The word-list will be loaded when you first press the completion key. You can append to the word-list email addresses, TeX commands, shell commands or any other kind of data. You need not sort the entries as I have done here, but you should ensure that there are no duplicate entries, or the word-list is going to be very long - of course 'sort -u' is the easiest way of avoiding duplications. Here is an example script that generates a completion list for TeX and C. You will have to change TEXDIR and INCLUDEDIR to point to locations for your system. This script uses a lot of memory and may take a long time to run.

#!/bin/sh
#
TEXDIR="/usr/lib/tex /usr/local/lib/tex /usr/lib/texmf /usr/local/lib/texmf"
INCLUDEDIR="/usr/qt/include /usr/local/include /usr/include /usr/openwin/include"
#
cat `find $INCLUDEDIR \
-follow -regex '.*\.h'` \
| sed -e 's/[^A-Za-z0-9_#]/\
/g' | sed \
-e 's/^[0-9].*$//g' \
-e 's/^#[0-9#].*$//g' \
-e 's/^[A-Za-z0-9_#]$//g' \
-e 's/^[A-Za-z0-9_#][A-Za-z0-9_#]$//g' \
-e 's/^[A-Za-z0-9_#][A-Za-z0-9_#][A-Za-z0-9_#]$//g' \
| cat -s | sort -u > ~/.cedit/cooledit.completion
cat `find $TEXDIR -follow -regex '.*\.tex'` | \
sed -e 's/[A-Za-z0-9]\\/&\
\\/g' | \
sed -e 's/\\$//g' | \
sed -e 's/[^A-Za-z0-9\\]/\
/g' | \
sed -e 's/\\\\*/\\/g' | \
sed -e 's/^[A-Za-z0-9].*$//g' \
-e 's/^\\$//g' \
-e 's/^\\[A-Za-z0-9\\]$//g' \
| cat -s | sort -u >> ~/.cedit/cooledit.completion

DRAG AND DROP
Cooledit supports the XDND drag and drop protocol versions 0 through 2. Cooledit used to support the Dnd, up to version 3.6.3. To copy or move text, highlight it with the mouse, then click somewhere in the middle of the text and drag. The cursor will change to indicate that you are dragging. The text will be copied to the window that you release the mouse button on. If you drag with the left button, text will be copied while if you drag with any other button, text will be moved. If you drag a file-name to an edit window from the file browser, that file will be inserted into the text at the position you release the mouse button. You can also drag from the man page and from any text box. If you find drag and drop to not work with other applications, then check that they support the same protocol.

SCRIPT EXECUTION
The Scripts menu has a list of commands that can be executed from hot-keys. You can create your own scripts by clicking on New script and filling in the various fields of the dialog. Several predefined examples are given in the menu. To get a feel for how this works click on Edit a script and select a predefined script from the list. The switches you see in the dialog box are self explanatory. They cause cooledit to perform various functions before and after the execution of the script and provide for seamless interfacing between cooledit and compilers or shell commands. The script text may also contain the % character to substitute for the editor's file-name, path, etc. For instance, if %f is found in the script, it will be, before execution, replaced with the file-name of the file you are currently editing. The complete list of substitutions is as follows:

%d  The current directory as set from the Command menu.

%f  The full file-name of the file you are currently editing, without the path.

%n  The file-name without the extension.

%x  The file-name extension only.

%p  The full path of the file-name without the trailing slash.

%t  The name of a temporary file if needed.

%b  The name of the block file.

%c  The name of the clipboard file.

%e  The name of the error message file.

%a  The string typed in by the user if they where prompted.

%F  The current font, or 8x13bold if the current font is a proportionally spaced font - use for terminal apps.

%O  The current font regardless of its size.

%%  Inserts a literal %.

Typically commands will process the editor file, or some highlighted text, and then output error messages to the error file, which might be displayed for viewing. Studying the examples will give an explanation of this. Note that the options "Display script's stdout/err continuously" must not be set simultaneously with "Insert stdout/err on completion". If both are set, the former take precedence. Also, if the script runs in the background, none of the on completion options will have effect.

WORD PROCESSOR MODE - AUTO PARAGRAPH FORMATTING
If the Auto paragraph formatting option is on (Select General from the Options menu) then paragraphs will be reformatted as you type. The Word wrap line length option specifies the paragraph's maximum width. The key Alt-p (`Paragraph_Format' in the Define keys dialog) will force a paragraph to be formatted when Auto paragraph formatting is off, and will find a paragraph between the illegal lines defined below. A paragraph start and end are specified by two consecutive newline characters. A "non"-paragraph is one of the following (non-paragraphs are not formatted except with with Alt-p):

-   Paragraphs containing any line that begins with the characters: -+*.;:&>.

-   Paragraphs containing any line (other than the first line) that begins with a space or tab character. The first line may contain an indent for example.

This means that all contiguous blocks of text can be bordered by a blank line, and they will be nicely paragraphed. Because of the above rules, you can pretty much leave paragraph formatting on even when programming, since program text will break these rules every time. One difference though is that pressing `Enter' in the middle of a line will properly break a paragraph with a double newline, unlike normal mode, where a only a single newline is inserted.

One other nifty feature is the formatting of fully indented paragraphs. If a paragraph's lines are all identically indented (like a quote), then the indent will be retained, while normal formatting occurs. This may be a problem when you are trying to type something that must be indented, but must not be paragraphed, like a postal address. In this case you can make one line begin with an illegal character, or make one line be indented more or less than the other lines.

See also the command-line option "--auto-paragraph", above.

MISCELLANEOUS USAGE
The input widget can be found in most dialogs and allows the editing of one line of text. By pressing Shift-Up or Shift-Down, you can see a history of previous entries. This is the same as pressing the input widget's button. Pressing Meta/Alt Ins in the editor will show you a history of cuts/copies you made to the X buffer. Pressing Space or Enter will insert the selected selection. The quote key Ctrl-q can be used to insert any decimal or hexidecimal number. Ctrl-q and then an ordinary key press interprets that key literally, eg. Ctrl-q then Ctrl-m inserts an ascii Carriage Return or 13 decimal. This is useful to convert DOS text files to Unix and back. Just do a search and replace with Ctrl-q Ctrl-j Ctrl-q Ctrl-m as one string, and Ctrl-q Ctrl-j as the other. You can insert any character from 0 through 255 by exploiting the following: Ctrl-something AND's something with 011111Binary, and Alt-something OR's something with 010000000Binary, eg. Ctrl-q Ctrl-Alt-a inserts a 129. You can also type out a three digit decimal number after Ctrl-q to insert that number. Hexidecial numbers can be inserted by typing the two digit number and then pressing the h key. E.g. Ctrl-q 0 6 4 inserts an @ symbol decimal 64; the sequence Ctrl-q 1 4 2 or Ctrl-q 8 e h inserts an 8E hexidecimal. To cut and paste to and from the Midnight Commander's internal editor, you can save a block to the clip-file and then do an insert file. To copy text to an xterm, highlight the text with the mouse, and then click on the xterm with button 2 as usual. To copy from an xterm, highlight in the xterm and then press Shift-Insert in the editor. To define a macro, press Ctrl-R and then type out the key strokes you want to be executed. Press Ctrl-R again when finished. You can then assign the macro to any key you like by pressing that key. The macro is executed when you press Ctrl-A and then the assigned key. The macro is also executed if the key is pressed on its own and is not assigned to any other function. Once defined, the macro commands go into the file .cedit/cooledit.macros in your home directory. The macro will overwrite any existing definition that was assigned to that same key. You can also delete macros from the command menu. The maximum number of macros you are allowed is 1024, thereafter you may get a crash. Do not delete or edit the macro file without restarting cooledit because cooledit caches the macros hot-keys in memory. This also means that macros will not be available to other cooledit's that are running simultaneously without them being restarted.

Running Make and Man
Cooledit has an interactive man page reader. To bring up a man page, type it out in the editor, highlight it with the mouse or cursor, and then press Ctrl-F1. The browser will appear in the root window. Inside the browser, you can double-click on words to bring up new man pages. You can also highlight text, drag it, and drop it into an edit window.

Press Alt-F7 to run make in the current directory. As of version 2.3.4 make is run via the generic script execution feature (see SCRIPT EXECUTION ). The current directory can be changed in the Command menu. The output of make will go to a viewer in the root window. Here you can double-click or press enter on an error message to take you directly to the file and line number where the error appears (provided the file is already open).

Search and Replace
You can use scanf search and replace to search and replace a C format string. First take a look at the sscanf and sprintf man pages to see what a format string is and how it works. An example is as follows: Suppose you want to replace all instances of say, an open bracket, three comma separated numbers, and a close bracket, with the word apples , the third number, the word oranges and then the second number, you would fill in the Replace dialog box as follows:
Enter search string
(%d,%d,%d)
Enter replace string
apples %d oranges %d
Enter replacement argument order
3,2
The last line specifies that the third and then the second number are to be used in place of the first and second. Note that the scanf() C function treats whitespace as being elastic. Read about the scanf format %[ in the scanf man page: it is very useful for scanning strings, and whitespace. For example, here is how to change C++ comments into C comments: For the search string type `/' `/' `%' `[' `^' Ctrl-q Enter `]', then in the replace string enter `/' `*' `%' `s' ` ' `*' `/'. Then make sure that you have depressed the scanf option button, and replace all. Also, the Case sensitive switch should be turned on when using scanf strings. The conversion specifiers in scanf and printf (i.e. search and replace respectively) must match exactly in their type - float must match with float etc. Searching with %f and replacing with %f, may not work, since, if you read the man page, scanf treats %f as a type float, while printf treats it as a type double. Instead use %lf to search, and replace with %f - both of type double. Regular expression substring replacement is available. (For those breathing a huge sigh of relief: note that you could always use Sed under the Scripts menu to do this anyway.) Substrings are not indicated by \1 \2 ... as with sed(1), but with %s. You must then use the Enter argument order field to specify the order of subtrings replacement. Hence the above example becomes:
Enter search string
\( *([0-9]*) *, *([0-9]*) *, *([0-9]*) *\)
Enter replace string
apples %s oranges %s
Enter replacement argument order
3,2
The option Backwards is provided to reverse search and replace. Although this is fully functional, it is not an efficient implementation of reverse searching, even to the extent that searches using scanf or regexp may be extremely slow. Hence beware, and remember that you can kill -SIGUSR1 pid to restore Cooledit.

OPTIONS MENU
Besides the define keys menu item, there is a general options item, a switches item, and a save mode item. The options in the general and switches options dialogs are analogous to those on the command line. The save mode dialog allows you to change the method of saving a file. Quick save saves the file by immediately, truncating the disk file to zero length (i.e. erasing it) and then writing the editor contents to the file. This method is fast, but dangerous, since a system error during a file save will leave the file only partially written, possibly rendering the data irretrievable. When saving, the safe save option enables creation of a temporary file into which the file contents are first written. In the event of an problem, the original file is untouched. When the temporary file is successfully written, it is renamed to the name of the original file, thus replacing it. The safest method is create backups. Where a backup file is created before any changes are made. You can specify your own backup file extension in the dialog. Note that saving twice will replace your backup as well as your original file.

FURTHER BEHAVIOURAL OPTIONS
Other options may be set by hand through editing the file ~/.cedit/.cooledit.ini (see FILES below). The section [Options] contains various settings (search for the string [Options]). Most of the settings are self explanatary. Unless otherwise stated, the setting is 0 for off and 1 for on. Some of these settings can be set from the Options menu, while others only take effect on startup and should therefore be edited by hand. Some of the settings are explained as follows:

option_edit_bottom_extreme
    (and its counterparts) These define the extents of cursor movement within the edit window. Text will be scrolled to keep the cursor this distance from the edit window border. The units are in character widths and heights.

option_find_bracket
    Sets whether matching brackets will be highlighted.

option_pull_down_window_list
    Sets whether the Window menu will be displayed when cycling through edit windows or opening a new file.

option_cursor_blink_rate
    Changes the cursor blink rate per second. This also effects the rate at which background script file outputs are updated. Use option_flashing_cursor = 0 to turn off cursor blinking.

option_xor_cursor
    Changes the cursor style to an exclusive OR cursor.

option_flashing_cursor
    Turn on/off cursor flashing.

option_hint_messages
    Tells how often (in seconds) to change the window title hint message; 0 disables.

options_text_ and options_editor_
    These settings set the colours of text display boxes (usually having a pinkish backround) and the editor (usually having a dark blue background). The colour palette is 3x3x3 for red, green and blue. The formula is R*3^2 + G*3^1 + B*3^0 = ColourValue. Where R, G and B are the red, green and blue components of the colour and range from 0 to 2. Hence option_editor_bg_normal = 1 is a dark blue and option_editor_fg_normal = 26 is a bright white.

option_man_cmdline
    Sets the shell command that will be used to run the man command. %m will be substituted for the man page entered. The -a option is preferred because it forces man to display all matching man pages across all sections. This may not be supported on some systems.

option_text_line_spacing
    Number of pixel widths between lines. You can specify this as 0 for condensed text or a larger number for broadly spaced lines.

option_mouse_double_click
    Maximum time-out to recognise a double click in milliseconds. Default is 300.

option_max_undo
    This is the maximum number of keypresses recorded. Each key press is recorded on an undo stack. Memory space set aside for the stack starts off small, but is doubled whenever the stack is filled. This option sets the maximum size that the stack is allowed to reach, and should be a power of 2. The amount of memory used in bytes will be four times this number (eight times on 64 bit machines). Beware of making this number to large because memory will eventually be used up. The default is 8192 which is roughly 10 pages of C program code.

option_interwidget_spacing
    Pixel distance between each widget's bounding box. Set to 5 or 6 widen things up a bit.

option_toolbar
    Causes a vertical convenience tool-bar to be displayed to the left of each edit window, default: on.

option_interpret_numlock
    Cooledit can try to be clever by checking for the numlock key to switch between arrow keys and numeric keys on the keypad. May not be a good idea, default: off.

option_long_whitespace
    For proportional fonts, the space character (ASCII 32 decimal) can be so thin that programming code is difficult to manipulate. This option doubles its width, default off.

NATIVE LANGUAGE SUPPORT (NLS) AND INTERNATIONAL CHARACTERS
International character support has changed as of version 3.10, and now properly uses the libc6 locale functionality. Hence you should set the LANG and LC_ALL environment variables to reflect your locale, and install the appropriate locale files. Most distributions will have these locale files installed already in say
    /usr/share/i18n/locales/
You can then type, for example,
    export LC_ALL=cs_CZ
    export LANG=cs_CZ
    cooledit

A full list of locales on my system is: POSIX, cs_CZ, da_DK, de_AT, de_BE, de_CH, de_DE, de_LU, el_GR, en_AU, en_CA, en_DK, en_GB, en_IE, en_NZ, en_US, en_ZA, es_AR, es_BO, es_CL, es_CO, es_DO, es_EC, es_ES, es_GT, es_HN, es_MX, es_PA, es_PE, es_PY, es_SV, es_US, es_UY, es_VE, et_EE, eu_ES, fi_FI, fo_FO, fr_BE, fr_CA, fr_CH, fr_FR, fr_LU, ga_IE, he_IL, hr_HR, hu_HU, id_ID, in_ID, is_IS, it_CH, it_IT, iw_IL, ja_JP, kl_GL, lt_LT, lv_LV, nl_BE, nl_NL, no_NO, pl_PL, pt_BR, pt_PT, ro_RO, ru_RU, ru_SU, ru_UA, sk_SK, sl_SI, sr_YU, sv_FI, sv_SE, tr_TR, uk_UA, zh_CN. You should also choose an appropriate font for your locale if it requires other than the normal iso8859-1 character set, such as the koi8 fonts for Russian language support. For example, cooledit -font '-cronyx-fixed-medium-r-normal--20-200-75-75-c-100-koi8-r' Characters that are deemed to be unprintable, either because they are out of range of the font, or because they are considered unprintable in the current locale, are printed in hex, or using ^X notation if they are control characters. If you don't want to bother with a proper locale setting, but just want to display characters above 128 instead of hex, set the `Display characters outside of locale' in the Options --> Switches menu or use the --all-characters option when starting Cooledit. The setlocale(3) man page contains a few sketchy details on locale support. Also see the ABOUT-NLS for details about package translations in general, how it works and how you can contribute.

COMPOSING INTERNATIONAL CHARACTERS
To insert international characters, multi-key composing is supported. To compose characters, the right control key is used with the first character in the sequence. (The left control key continues to have the usual behaviour.) Composing is quite intuitive: just think how you would create a Latin character from plain ascii characters and that is probably how you would compose it. For example, to insert a Latin-Capital-Letter-a-with-Ring-Above press Ctrl-Shift-a together, and then press o on its own. The 'Shift' will capitalise the letter a, and the o will insert the ring above. A copyright sign is done similarly with Control-o c. All the key combinations can be used in reverse (i.e. Control-c o also works for the copyright symbol). A complete list of key combinations is given in the file INTERNATIONAL which comes with the source distribution. I havn't looked at how other applications compose characters, so these key combinations may change in the future to be more standard.

BINARY FILES
When displaying binary files, non-printable ascii characters are displayed as follows on black:

0   ^@

1-26
    ^A - ^Z

27, 28, 29, 30, 31
    ^[, ^ ^], ^^, ^_

31-127
    Displayed as standard ascii in the normal background colour.

127-159
    Display in hex eg 139 is displayed as 8Bh

160-255
    Displayed as normal if international characters option is on, otherwise displayed in hex.

TABBING OPTIONS
A variety of tabbing and auto indent options are available. One of the problems I've encountered with tabbing is that the programmer often wants to indent code with half tabs (four spaces) instead of the standard tab (eight characters). It would be easy to mearly change the tab width to four, but then the resulting code would not display correctly under viewers or other character devices. To solve this, a Fake Half Tabs option is available. This makes it appear as though you are using a half sized tab by inserting and moving through four space characters when you are to the left of your text. When eight space characters are inserted, they are automatically replaced with a tab.

FONTS
The default font is 8x13bold which is an alias for
-misc-fixed-bold-r-normal--13-120-75-75-c-80-iso8859-1
and is similar to the PC's vga text font. Basic recommended fonts are 5x7, 5x8, 6x9, 6x10, 6x12, 6x13, 6x13bold, 7x13, 7x13bold, 7x14, 7x14bold, 8x13, 8x16, 9x15, 9x15bold, 10x20, 12x24. As of version 3.0.4, Cooledit supports proportional font spacing. This means you can use any ISO font (an ISO font is one with an extended ascii character set. The font name will end in -iso8859-* ). Non ISO fonts will probably cause a program crash on startup. In this section I'll give a partial guide to the font naming conventions of The X Window System so that you can try some fonts without having to refer to other documentation. A font name is a list of words and numbers separated by hyphens. A typical font name is -adobe-courier-medium-r-normal--12-120-75-75-m-60-iso8859-1 Use xlsfonts to obtain a list of fonts. The fields have the following meanings:

adobe
    The name of the font's maker.

courier
    The font family. Others are charter, times, helvetica etc.

medium
    The font weight: it can be medium or bold.

r   Indicate that the font is roman, i is for italic and o is for oblique.

normal
    Character width and inter-character spacing. It can also be condensed, narrow or double.

12  The pixel size.

120 The size in tenths of a printers point.

75-75
    Horizontal and vertical resolution for which the font was designed.

m   The font spacing: m for monospaced and p for proportional.

60  The average width of all characters in the font in tenths of a pixel.

iso8859-1
    The ISO character set. In this case the 1 indicates ISO Latin 1, a superset of the ascii character set.

As an example, start cooledit with

cooledit -font '-*-times-medium-r-*--20-*-*-*-p-*-iso8859-*'
cooledit -font '-*-helvetica-bold-r-*--14-*-*-*-p-*-iso8859-*'

These envoke a newspaper font and an easy reading font respectively. A * means that the X server can place default vales into those fields. This way you do not have to specify a font exactly. For proportional fonts, a tab width is a factor of the width of the space character, hence a tab spacing of eight is the same width as eight spaces. A screen with proportional fonts will redraw slightly slower than with fixed-spaced fonts due to complications with the variably spaced text.

FILES
$HOME/.cedit/

    User's own temporary directory.

$HOME/.cedit/.cooledit.ini

    Initialisation file. This stores a list of files that were open when the user last exited cooledit. It also stores scripts, options, and user defined keys. The file is broken into sections separated by double newlines. Each section is headed by the section name in square brackets on it own line.

$HOME/.cedit/cooledit.macros

    is generated automatically when macros are recorded. Each line in the file represents a macro definition. Do not edit this file while cooledit is running unless you are not going to run a macro during that cooledit session.

$HOME/.cedit/cooledit.block

    When the option Save block on commance is on in the script editor, the block will be saved with this file-name, on execution of the script.

$HOME/.cedit/cooledit.clip

    This is the default file to use when you save a highlighted block to a file. A copy of the highlighted text is also saved to this file whenever you cut or copy to the X buffer.

$HOME/.cedit/cooledit.temp

    This is a temporary file you can use in your shell scripts.

$HOME/.cedit/cooledit.script

    This is a file-name of the shell script when it is saved for execution. You can view it for debugging purposes.

ENVIRONMENT
The environment variables applicable to any of the shell commands must be set correctly for them to work. See the man and the sort man pages to see what I mean. Note that the man command formats text for the width of the current terminal, so starting cooledit from a very wide terminal (or xterm) will cause the output to be difficult to read.

The environment variables LANGUAGE and LANG may be set to one of the codes listed about under NATIVE LANGUAGE SUPPORT (NLS).

Thanks
Thanks to Linus Torvalds, Richard Stallman, David Mackenzie, Miguel de Icaza, and GNUmans everywhere.

Thanks to
  Evgeny A Cherkashin  <eugeneai@icc.ru>
for his Russian translation.

Thanks to the following people for their bug reports, suggestions, extensions and fixes:

Scott Billings         <aerogems@netins.net>
David M. Cook          <davecook@home.com>
Miguel Cruz            <mnc@diana.law.yale.edu>
Liviu Daia             <daia@stoilow.imar.ro>
Derkjan de Haan        <j.d.j.dehaan@student.utwente.nl>
Martin Dufour          <dufm02@pollux.GEL.USherb.CA>
Yuriy Elkin            <yury@intruder.mktg.stratus.com>
Alex Fortuna           <alex@transtelecom.ru>
Andreas Haack          <ahaack@bigfoot.com>
I. Ioannou             <roryt@hol.gr>
Johnny Johansson       <johnnyj@clarus.se>
Juha Laukala           <juha.laukala@tekla.fi>
Alex Maranda           <amaranda@spider.com>
ET Mogaswa             <MOGASET@alpha.unisa.ac.za>
Frank Niessink         <frankn@cs.vu.nl>
Oleg Yu. Repin         <repin@ssd.sscc.ru>
Pavel Roskin           <pavel_roskin@geocities.com>
Ronald Rietman         <rietman@natlab.research.philips.com>
Mark N Summerfield     <Mark.Summerfield@chest.ac.uk>
Paul Seelig            <pseelig@trudi.zdv.Uni-Mainz.DE>
Jeroen R. v.d. Werven  <asmodai@wxs.nl>
Norbert Warmuth        <k3190@fh-sw.de>
Max Xu                 <max@crosslight.ca>
Pierfrancesco Zuccato  <pf.zuccato@alinet.it>
(anyone I left out?)

STATISTICS OF COOLEDIT USAGE
Cooledit mailed me when it first ran on the following machines.

unknown                          83
alpha-dec-osf2.1	         1
alpha-dec-osf3.2	         12
alpha-dec-osf4.0	         13
alpha-dec-osf4.0d	         3
alpha-unknown-linux	         56
alpha-unknown-linux-gnu	         7
alphaev5-dec-osf4.0b	         3
alphaev5-dec-osf4.0d	         1
alphaev5-unknown-linux-gnu	 2
alphaev5-unknown-linux-gnulibc1	 4
alphaev56-dec-osf4.0b	         1
alphaev56-dec-osf4.0d	         7
alphaev56-dec-osf4.0e	         1
alphaev56-unknown-linux-gnu	 2
arm-linux-elf	                 1
arm-unknown-linux-gnu	         1
arm-unknown-linux-gnuelf	 7
hppa1.0-hp-hpux10.20	         2
hppa1.1-hp-hpux10.01	         3
hppa1.1-hp-hpux10.10	         36
hppa1.1-hp-hpux10.20	         220
hppa1.1-hp-hpux11.00	         1
hppa1.1-hp-hpux8.07	         1
hppa1.1-hp-hpux9.01	         3
hppa1.1-hp-hpux9.03	         9
hppa1.1-hp-hpux9.05	         7
hppa1.1-hp-hpux9.07	         1
hppa2.0-hp-hpux10.20	         1
i386-pc-bsdi4.0	                 1
i386-pc-linux-gnu	         1
i386-pc-solaris2.6	         2
i386-pc-solaris2.7	         3
i386-unknown-bsdi2.1	         3
i386-unknown-bsdi3.0	         1
i386-unknown-freebsd2.1.5	 1
i386-unknown-freebsd2.1.6	 4
i386-unknown-freebsd2.1.7	 1
i386-unknown-freebsd2.2	         4
i386-unknown-freebsd2.2.2	 4
i386-unknown-freebsd2.2.5	 16
i386-unknown-freebsd2.2.6	 8
i386-unknown-freebsd2.2.7	 12
i386-unknown-freebsd2.2.8	 1
i386-unknown-freebsd3.0	         9
i386-unknown-freebsd3.1	         12
i386-unknown-freebsd4.0	         2
i386-unknown-linux	         11
i386-unknown-netbsd1.1	         1
i386-unknown-netbsd1.3.2	 2
i386-unknown-none	         4
i386-unknown-openbsd2.3	         1
i386-unknown-openbsd2.4	         2
i386-unknown-openbsd2.5	         1
i386-unknown-solaris2.5.1	 4
i386-unknown-solaris2.6	         2
i486-ibm-linux	                 1
i486-pc-linux-gnu	         40
i486-pc-linux-gnulibc1	         67
i486-unknown-linux	         1514
i486-unknown-linuxaout	         6
i486-unknown-linuxoldld	         1
i486-unknown-solaris2.5.1	 1
i586-intel-linux	         4
i586-intel-none	                 4
i586-pc-linux-gnu	         1021
i586-pc-linux-gnulibc1	         499
i586-pc-none	                 1
i586-pc-sco3.2v5.0.2	         1
i586-redhat-linux	         1
i586-unknown-linux	         2798
i586-unknown-linuxaout	         5
i586-unknown-none	         12
i586-unknown-sco3.2v4.2	         1
i586-unknown-sco3.2v5.0.2	 1
i586-unkown-linux	         2
i686-pc-linux-gnu	         3793
i686-pc-linux-gnulibc1	         496
i686-pc-none	                 1
i686-unknown-linux	         6
i686-unknown-linux-gnu	         2
m68k-apple-netbsd1.3.3	         1
mips-dec-ultrix4.3	         1
mips-sgi-irix5.3	         36
mips-sgi-irix6.2	         30
mips-sgi-irix6.3	         8
mips-sgi-irix6.4	         1
mips-sgi-irix6.5	         16
mips-unknown-linux	         2
powerpc-ibm-aix3.2.5	         2
powerpc-ibm-aix4.1.4.0	         3
powerpc-ibm-aix4.1.5.0	         3
powerpc-ibm-aix4.2.1.0	         12
powerpc-ibm-aix4.3.1.0	         1
powerpc-unknown-linux	         1
powerpc-unknown-linux-gnu	 2
rs6000-ibm-aix4.1.4.0	         1
rs6000-ibm-aix4.2.0.0	         1
sparc-sun-solaris2.4	         15
sparc-sun-solaris2.5	         60
sparc-sun-solaris2.5.1	         153
sparc-sun-solaris2.6	         132
sparc-sun-solaris2.7	         11
sparc-sun-sunos4.1.3	         2
sparc-sun-sunos4.1.3_U1	         6
sparc-sun-sunos4.1.4	         8
sparc-unknown-linux	         3
sparc-unknown-linux-gnu	         6

There were a total of 7911 unique addresses as of March 1999. I don't know if it completely worked on these machines, but it certainly compiled and ran. I also don't know if the user's had to make modifications to get it to compile. (Note that Cooledit won't send mail if mcedit has been used on that machine, so actual figures are much higher.)

LICENSE
This program is distributed under the terms of the GNU General Public License as published by the Free Software Foundation. See Copying in the Readme menu for details on the License and the lack of warranty.

AVAILABILITY
The latest public release of this program can be found at
ftp://sunsite.unc.edu/pub/Linux/apps/editors/X/ http://www.netins.net/showcase/Comput-IT/cooledit/index.html

The latest development release can be optained from:
ftp://lava.obsidian.co.za/pub/unix/cooledit/

SEE ALSO
mc(1), mcedit(1), X(1), scanf(3), coolman(1), coolicon(1), smalledit(1).

AUTHORS
Paul Sheer (psheer@icon.co.za)

BUGS

*   Libtool is not yet complete and gives some harmless warnings when installing.

*   On openwindows, the left mouse button sometimes doesn't work properly. The right button can be used instead. (I think olwm is at fault here.)

*   May crash if you delete directories containing files you are still editing and then create new windows that point to those directories.

*   Sunos 4.1.3 crashes on startup. Other machines may also crash because of non-standardness. Define CRASHES_ON_STARTUP at the beginning of stringtools.h and recompile if this happens.

*   Man pages rely on the man page command. Its formatting is sometimes filtered for terminals and won't be in colour. Try using GNU man instead, or starting cooledit with a different TERM (environment variable) definition.

*   Some proportional fonts leave trails where they print out of their bounding box.

*   Redraws and cursor movements near the end of very long lines ( lines > 64k characters ) slow down in proportion to the line length. This is not nearly as bad with cooledit as with some other popular editors though.

*   Large cursor jumps ( jump > 1M characters ) are slow, worse than some other popular editors.