Cooledit v3.10.0  by  Paul Sheer   psheer@obsidian.co.za
See the file COPYING for copying permissions.
See the file INSTALL on how to build and install cooledit.

This distribution was created on 15 May 1999.

Cooledit is a full featured text editor for the X Window System,
with 3D widgets and multiple edit windows. See Features below
for more info.

(This file is a plain-text copy of the man page cooledit.1)


CONTENTS:
---------

1: NAME
2: USAGE
3: DISCLAIMER
4: DESCRIPTION
5: OPTIONS
6: Commandline examples
7: MAILING LIST
8: Features
9: DEFAULT KEY DEFINITIONS
10: EMERGENCIES
11: KEY REDEFINING
12: SPELL CHECK AS YOU TYPE
13: THE INTERACTIVE GRAPHICAL DEBUGGER
14: PYTHON MACRO PROGRAMMING
15: SYNTAX HIGHLIGHTING
16: COMPLETION
17: DRAG AND DROP
18: SCRIPT EXECUTION
19: WORD PROCESSOR MODE - AUTO PARAGRAPH FORMATTING
20: MISCELLANEOUS USAGE
21: Running Make and Man
22: Search and Replace
23: OPTIONS MENU
24: FURTHER BEHAVIOURAL OPTIONS
25: INTERNATIONAL CHARACTERS
26: NATIVE LANGUAGE SUPPORT (NLS)
27: BINARY FILES
28: TABBING OPTIONS
29: FONTS
30: FILES
31: ENVIRONMENT
32: Thanks
33: STATISTICS OF COOLEDIT USAGE
34: LICENSE
35: AVAILABILITY
36: SEE ALSO
37: AUTHORS
38: BUGS






cooledit(1)                                           cooledit(1)


NAME
       cooledit-3.10.0 - Full featured text editor for the X Win-
       dow 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 beauti-
       ful 3D widgets. It requires only the X11 library  to  run.
       The  engine is the same as that used for the internal edi-
       tor of the Midnight Commander and  hence  cooledit  repre-
       sents  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 Pseu-
              doColor)  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.)



                           15 May 1999                          1





cooledit(1)                                           cooledit(1)


       -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  back-
              ground.  If <color> is igloo (default) then a back-
              ground 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.



                           15 May 1999                          2





cooledit(1)                                           cooledit(1)


       --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 inden-
              tation 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  pro-
              grams). When editing between text and the left mar-
              gin, moving and tabbing will be  as  though  a  tab
              space  were 4, while actually using spaces and nor-
              mal  tabs  for  an  optimal  fill.   When   editing



                           15 May 1999                          3





cooledit(1)                                           cooledit(1)


              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  geome-
              try, 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.




                           15 May 1999                          4





cooledit(1)                                           cooledit(1)


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: 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 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 bind-
       ings 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 analo-
       gous 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



                           15 May 1999                          5





cooledit(1)                                           cooledit(1)


          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



                           15 May 1999                          6





cooledit(1)                                           cooledit(1)


          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 sig-
       nal, 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.





                           15 May 1999                          7





cooledit(1)                                           cooledit(1)


KEY REDEFINING
       The  Options  menu  now 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 dif-
       ference 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 inter-
       pretation. 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 con-
       tains simple C code which gets incorporated directly  into
       the program during compilation.  Note that the first func-
       tion 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 eas-
       ily emulate another editor as you like.)





                           15 May 1999                          8





cooledit(1)                                           cooledit(1)


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 dis-
       played. 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  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).

       The interface will give an error message if you try to run
       a  command  while another is already running. This has the
       side effect that some hot-keys will give error messages if
       the  key  is held down and repeated.  This is because com-
       mands are being sent to gdb too quickly  for  them  to  be
       processed.

       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.






                           15 May 1999                          9





cooledit(1)                                           cooledit(1)


PYTHON MACRO PROGRAMMING
       As  of version 3.8.0, Cooledit has a builtin Python inter-
       pretor.  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 Develop-
       ment, 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 loca-
       tion 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 ("Press s")
           k, m = get_key ()
           if m == 0:
               if k == "s":
                   command (Save_As)

       key ("x", ControlMask, "get_ctrl_x_key()")

       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 func-
       tion 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  manipu-
       lating the edit buffers. The functions operate on the cur-
       rent 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.



                           15 May 1999                         10





cooledit(1)                                           cooledit(1)


       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.

       insert_ahead(string)
              Inserts  the given string ahead of the current cur-
              sor 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.




                           15 May 1999                         11





cooledit(1)                                           cooledit(1)


       string get_text([int[, int]])
              Returns a string containing the characters  between
              the  given offsets. If the second argument is omit-
              ted, 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 argu-
              ment 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.



                           15 May 1999                         12





cooledit(1)                                           cooledit(1)


       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  argu-
              ment 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  spe-
              cific  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.

              If only one argument is given,  then  this  command
              clears the menu of all its items.

       The  following functions return information about the cur-
       rent 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 highlight-
              ing 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.



                           15 May 1999                         13





cooledit(1)                                           cooledit(1)


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

       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 functions manipulate editor windows:




                           15 May 1999                         14





cooledit(1)                                           cooledit(1)


       (string, ...) get_editors()
              Returns a tuple with an entry for each editor  win-
              dow.  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 a  any
       new editor file. The file contains rules for highlighting,
       each of which is given on  a  separate  line,  and  define
       which  keywords  will  be  highlighted to what colour. The
       file is also divided into sections, each beginning with  a
       line   with  the  file  command,  followed  by  a  regular



                           15 May 1999                         15





cooledit(1)                                           cooledit(1)


       expression. The regular expression dictates the file  name
       that  that  set  of  rules applies to. Following this is a
       description to be printed on the left of the editor window
       explaining  the  file  type  to the user. A third optional
       argument is a regular expression to match the  first  line
       of  text  of the file. If either the file name matches, or
       the first line of text, then those rules will be loaded.

       A section ends with the start of a new section. Each  sec-
       tion  is  divided into contexts, and each context contains
       rules. A context is a scope within the text that a partic-
       ular  set  of  rules  belongs to. For instance, the region
       within a C style comment (i.e. between /* and */) has  its
       own  colour.  This  is a context, although it will have no
       further rules inside it because there is probably  nothing
       that we want highlighted within a C comment.

       A trivial C programming section might look like this:

       file .\*\\.c C\sProgram\sFile (#include|/\\\*)

       wholechars abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_

       # default colors
       context default
         keyword  whole  if       24
         keyword  whole  else     24
         keyword  whole  for      24
         keyword  whole  while    24
         keyword  whole  do       24
         keyword  whole  switch   24
         keyword  whole  case     24
         keyword  whole  static   24
         keyword  whole  extern   24
         keyword         {        14
         keyword         }        14
         keyword         '*'      6

       # C comments
       context /\* \*/ 22

       # C preprocessor directives
       context linestart # \n 18
         keyword  \\\n  24

       # C string constants
       context " " 6
         keyword  %d    24
         keyword  %s    24
         keyword  %c    24
         keyword  \\"   24

       Each context starts with a line of the form:
       context      [exclusive]      [whole|wholeright|wholeleft]



                           15 May 1999                         16





cooledit(1)                                           cooledit(1)


       [linestart] delim [linestart]  delim  [foreground]  [back-
       ground]

       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 simi-
       larly 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 delim-
       iters to be highlighted,  but  not  the  delimiters  them-
       selves.

       Each rule is a line of the form:
       keyword  [whole|wholeright|wholeleft]  [linestart]  string
       foreground [background]

       Context or keyword strings are interpreted so that you can
       include tabs and spaces with the sequences \t and \s. New-
       lines 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  *.
       The  *  itself  is  a  wildcard that matches any length of
       characters. For example,
         keyword         '*'      6
       colours all C single character constants green. You  could
       also have used
         keyword         "*"      6
       to colour string constants, except that the matched string
       may not cross newlines. The wildcard may  be  used  within
       context delimiters as well, but you cannot have a wildcard
       as the last or first character.

       Important to note is the line
         keyword  \\\n  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.



                           15 May 1999                         17





cooledit(1)                                           cooledit(1)


       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. How-
       ever, do not ask for regular expression  support,  because
       this is flatly impossible.

       A useful hint is to work with as much as possible with the
       things you can do rather than try to do things  that  this
       implimentation 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.



COMPLETION
       This  feature was added in version 3.3.2. This would typi-
       cally 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 dupli-
       cations.  It may have leading or trailing blank lines, but
       there must be no blank lines in the text. Of course,  hav-
       ing  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.



                           15 May 1999                         18





cooledit(1)                                           cooledit(1)


       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 ver-
       sions 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 com-
       mands  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 ver-
       sion  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



                           15 May 1999                         19





cooledit(1)                                           cooledit(1)


       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 exe-
       cuted 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 sub-
       stitutions 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.




                           15 May 1999                         20





cooledit(1)                                           cooledit(1)


       %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.   Study-
       ing  the  examples will give an explanation of this.  Note
       that the options  "Display  script's  stdout/err  continu-
       ously"  must  not  be set simultaneously with "Insert std-
       out/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 Gen-
       eral from the Options menu) then paragraphs will be refor-
       matted as you type. The Word wrap line length option spec-
       ifies the paragraph's maximum width. The key Alt-p (`Para-
       graph_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 speci-
       fied by two consecutive newline characters. A  "non"-para-
       graph is one of the following (non-paragraphs are not for-
       matted 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 charac-
              ter. The first line may contain an indent for exam-
              ple.

       This means that all contiguous blocks of text can be  bor-
       dered  by  a  blank  line,  and  they will be nicely para-
       graphed. 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  dif-
       ference though is that pressing `Enter' in the middle of a
       line will properly break a paragraph with  a  double  new-
       line, 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 iden-
       tically indented (like a quote), then the indent  will  be
       retained,  while  normal  formatting occurs. This may be a



                           15 May 1999                         21





cooledit(1)                                           cooledit(1)


       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  his-
       tory  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,  high-
       light 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



                           15 May 1999                         22





cooledit(1)                                           cooledit(1)


       home directory. The macro will overwrite any existing def-
       inition  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 simulta-
       neously 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,



                           15 May 1999                         23





cooledit(1)                                           cooledit(1)


       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 dia-
       log  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 writ-
       ing 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  ren-
       dering  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



                           15 May 1999                         24





cooledit(1)                                           cooledit(1)


       problem, the original file is untouched.  When the  tempo-
       rary  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
       '[Option]').  Most of the settings are  self  explanatary.
       Unless  otherwise  stated,  the setting is 0 for off and 1
       for on.  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  =



                           15 May 1999                         25





cooledit(1)                                           cooledit(1)


              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 spec-
              ify 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.   Mem-
              ory 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 mem-
              ory  will eventually be used  up.  The  default  is
              8192  which is roughly 10 pages  of C program code.

       option_widget_spacing
              Pixel distance between each widget's bounding  box.
              Set to 3 or 4 to squash things up a bit.

       option_toolbar
              Causes  a  vertical convenience tool-bar to be dis-
              played 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



                           15 May 1999                         26





cooledit(1)                                           cooledit(1)


              difficult to manipulate. This  option  doubles  its
              width, default off.


INTERNATIONAL CHARACTERS
       International   character  support  is  enabled  with  the
       --international-characters  option  or  from  the  Options
       menu.  When  not  enabled,  non-US characters will be dis-
       played as hex.  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  com-
       pose 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 combina-
       tions can be used in reverse (i.e. Control-c o also  works
       for the copyright symbol). A complete list of key combina-
       tions 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.


NATIVE LANGUAGE SUPPORT (NLS)
       As  of  version  3.3.3, Cooledit has support for NLS. This
       means that the translator's files are set up and ready  to
       be  translated for many of the languages supported by get-
       text.  As yet (Oct 13 1997), no translating has been done.
       The  programming  work,  however,  has  been completed for
       translated text to be added. If you  would  like  to  con-
       tribute to translating this or other GNU software, see the
       file ABOUT-NLS in the  distribution.  To  envoke  Cooledit
       with  a  different  language, set the environment variable
       LANGUAGE and LANG to  one  of  the  following  two  letter
       codes: (ABOUT-NLS contains more detail on this)

           zh         Chinese
           cs         Czech
           da         Danish
           nl         Dutch
           en         English
           eo         Esperanto
           fi         Finnish
           fr         French
           de         German
           hu         Hungarian
           ga         Irish
           it         Italian
           id         Indonesian



                           15 May 1999                         27





cooledit(1)                                           cooledit(1)


           ja         Japanese
           ko         Korean
           la         Latin
           no         Norwegian
           fa         Persian
           pl         Polish
           pt         Portuguese
           ru         Russian
           sl         Slovenian
           es         Spanish
           sv         Swedish
           tr         Turkish

       You  may  specify a list of prefered languages in the LAN-
       GUAGE environment variable like sv:de, but not in the LANG
       variable.   As  a  test, I translated the word 'File' from
       the file menu for a few of the languages listed. Try,
           setenv LANGUAGE fr
           setenv LANG fr
           cooledit
       and see what happens (and forgive me  if  my  translations
       are wrong).  There are liable to be some problems with the
       non-english language  support  though:  hot-keys  are  not
       always  going  to  work.  With  most buttons, hot-keys are
       assigned dynamically, so these will always work themselves
       out,  but  in the case of some buttons and the menu items,
       the hot-keys are especially assigned. So you won't  always
       have  the  'S' nicely underlined in the `Search' menu, for
       example.


BINARY FILES
       When displaying binary files, non-printable ascii  charac-
       ters 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 back-
              ground 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.






                           15 May 1999                         28





cooledit(1)                                           cooledit(1)


TABBING OPTIONS
       A  variety  of  tabbing and auto indent options are avail-
       able. 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  dis-
       play  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 charac-
       ters 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 recom-
       mended  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,  hel-
              vetica 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.




                           15 May 1999                         29





cooledit(1)                                           cooledit(1)


       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  pro-
              portional.

       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 propor-
       tional 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.



                           15 May 1999                         30





cooledit(1)                                           cooledit(1)


       $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  high-
              lighted  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  SUP-
       PORT (NLS).


Thanks
       Thanks  to Linus Torvalds, Richard Stallman, David Macken-
       zie, Miguel de Icaza, and GNUmans everywhere.

       Thanks to the following people for their bug reports, sug-
       gestions, 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>



                           15 May 1999                         31





cooledit(1)                                           cooledit(1)


       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                          82
       alpha-dec-osf2.1                 1
       alpha-dec-osf3.2                 12
       alpha-dec-osf4.0                 13
       alpha-dec-osf4.0d                1
       alpha-unknown-linux              53
       alpha-unknown-linux-gnu          3
       alphaev5-dec-osf4.0b             3
       alphaev5-dec-osf4.0d             1
       alphaev5-unknown-linux-gnu       1
       alphaev5-unknown-linux-gnulibc1  2
       alphaev56-dec-osf4.0b            1
       alphaev56-dec-osf4.0d            2
       arm-linux-elf                    1
       arm-unknown-linux-gnu            1
       arm-unknown-linux-gnuelf         6
       hppa1.0-hp-hpux10.20             2
       hppa1.1-hp-hpux10.01             3
       hppa1.1-hp-hpux10.10             34
       hppa1.1-hp-hpux10.20             178
       hppa1.1-hp-hpux11.00             1
       hppa1.1-hp-hpux8.07              1
       hppa1.1-hp-hpux9.01              3
       hppa1.1-hp-hpux9.03              6
       hppa1.1-hp-hpux9.05              7
       hppa1.1-hp-hpux9.07              1
       i386-pc-bsdi4.0                  1
       i386-pc-solaris2.6               2
       i386-unknown-bsdi2.1             3
       i386-unknown-bsdi3.0             1
       i386-unknown-freebsd2.1.5        1
       i386-unknown-freebsd2.1.6        4



                           15 May 1999                         32





cooledit(1)                                           cooledit(1)


       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-freebsd3.0          8
       i386-unknown-freebsd3.1          1
       i386-unknown-freebsd4.0          1
       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          1
       i386-unknown-solaris2.5.1        4
       i386-unknown-solaris2.6          2
       i486-ibm-linux                   1
       i486-pc-linux-gnu                30
       i486-pc-linux-gnulibc1           52
       i486-unknown-linux               1506
       i486-unknown-linuxaout           6
       i486-unknown-linuxoldld          1
       i486-unknown-solaris2.5.1        1
       i586-intel-linux                 3
       i586-intel-none                  4
       i586-pc-linux-gnu                629
       i586-pc-linux-gnulibc1           343
       i586-pc-none                     1
       i586-redhat-linux                1
       i586-unknown-linux               2747
       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                1515
       i686-pc-linux-gnulibc1           281
       i686-pc-none                     1
       i686-unknown-linux               6
       i686-unknown-linux-gnu           2
       mips-dec-ultrix4.3               1
       mips-sgi-irix5.3                 35
       mips-sgi-irix6.2                 29
       mips-sgi-irix6.3                 6
       mips-sgi-irix6.4                 1
       mips-sgi-irix6.5                 12
       mips-unknown-linux               1
       powerpc-ibm-aix3.2.5             2
       powerpc-ibm-aix4.1.4.0           3
       powerpc-ibm-aix4.2.1.0           11
       powerpc-ibm-aix4.3.1.0           1
       powerpc-unknown-linux            1
       powerpc-unknown-linux-gnu        2



                           15 May 1999                         33





cooledit(1)                                           cooledit(1)


       rs6000-ibm-aix4.1.4.0            1
       rs6000-ibm-aix4.2.0.0            1
       sparc-sun-solaris2.4             14
       sparc-sun-solaris2.5             54
       sparc-sun-solaris2.5.1           138
       sparc-sun-solaris2.6             106
       sparc-sun-solaris2.7             1
       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          4

       There were a total of 5769 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



                           15 May 1999                         34





cooledit(1)                                           cooledit(1)


              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  string-
              tools.h and recompile if this happens.


       *      Man pages rely on the man page command. Its format-
              ting  is sometimes filtered for terminals and won't
              be in colour. Try using GNU man instead, or  start-
              ing  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.






















                           15 May 1999                         35


