Cooledit v3.17.7  by  Paul Sheer   psheer /AT/ icon.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 3 August 2002.

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: HINT MESSAGES
10: DEFAULT KEY DEFINITIONS
11: EMERGENCIES
12: KEY REDEFINING
13: SPELL CHECK AS YOU TYPE
14: UNICODE, UCS AND UTF-8 SUPPORT
15: THE INTERACTIVE GRAPHICAL DEBUGGER
16: PYTHON MACRO PROGRAMMING
17: SYNTAX HIGHLIGHTING
18: COLOURS
19: HTML SYNTAX HIGHLIGHTING
20: COMPLETION
21: DRAG AND DROP
22: SCRIPT EXECUTION
23: WORD PROCESSOR MODE - AUTO PARAGRAPH FORMATTING
24: MISCELLANEOUS USAGE
25: Running Make and Man
26: Search and Replace
27: OPTIONS MENU
28: FURTHER BEHAVIOURAL OPTIONS
29: NATIVE LANGUAGE SUPPORT (NLS) AND INTERNATIONAL CHARACTERS
30: COMPOSING INTERNATIONAL CHARACTERS
31: BINARY FILES
32: TABBING OPTIONS
33: ANTI-ALIASED FONT SUPPORT
34: FONTS
35: SPECIFYING FONTS
36: FILES
37: ENVIRONMENT
38: THANKS
39: STATISTICS OF COOLEDIT USAGE
40: LICENSE
41: AVAILABILITY
42: SEE ALSO
43: AUTHORS
44: BUGS






cooledit(1)                                           cooledit(1)


NAME
       cooledit-3.17.7 - 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.)



                          3 August 2002                         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.)

       --edit-bg <nn>
              Editor  background   colour.   Rather   edit   your
              ~/.cedit/.cooledit.ini  file,  look  for the option
              option_editor_bg_normal and others. This can  be  0
              to 26. Useful options are probably only 1 and 0 for
              dark blue and black.

       -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. (See FONTS  below.)
              If  <font-name>  is  default  then the default font
              8x13bold is invoked. 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

       -no-fontset, --no-fontset
              Turns off use of font sets under X. X has two meth-
              ods of drawing fonts: the old "fontstruct" or "raw"
              method  and  the  new font set method. The font set
              method properly interprets locales and their  char-
              acters sets and is required for creating an X Input
              Method (for  inputting  international  characters).
              Unfortunately,  not  all X servers understand UTF-8
              (Unicode) encoding, hence the old "raw" method  may
              be required when used with --utf8-interpretation.

       -utf8, --utf8-interpretation
              Should  be used in conjunction with --no-fontset if
              required. Enable UTF-8 interpretation. Use for Uni-
              code encoded files.




                          3 August 2002                         2





cooledit(1)                                           cooledit(1)


       --anti-aliasing
              This is depreciated, use font-name/3 instead.

       --interchar-spacing <n>
              Add  extra  pixels of space between each character.
              This  option  works  with   --anti-aliasing   only.
              (Default is 0.)

       --interwidget-spacing <n>
              Spacing  between  widgets  in  dialog  boxes.  Make
              larger for a more spacious. Different defaults  for
              different looks.

       --look [gtk|cool|next]
              Cooledit  can  emulate  the  look  of a Gtk or NeXT
              application. Gtk is now the default,  although  you
              can  invoke  the old look with cooledit --look cool
              --widget-font default.  There is some complexity in
              setting  options  for looks: certain settings, like
              --interwidget-spacing and --font are saved on exit,
              hence  switching  looks  may inherit incorrect set-
              tings. Note that the default Gtk font for real  Gtk
              applications    is   -adobe-helvetica-medium-r-nor-
              mal--*-120-*-*-*-*-*-*,  which  is  very  close  to
              -winfonts-arial-medium-r-nor-
              mal-*-*-120-*-*-*-*-*-*.

       --red-first
              For  LCD  displays  use   R-G-B   pixel   ordering.
              (Default.)

       --blue-first
              For LCD displays use B-G-R pixel ordering. Try both
              of these options and see which looks better.

       -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, --all-characters
              Display characters outside of locale if  there  are
              glyphs for them.  This does not work if you did not
              specify the font completely - Cooledit  would  then
              be  using  a  font  set  (which does not allow non-



                          3 August 2002                         3





cooledit(1)                                           cooledit(1)


              locale characters to be printed).   See  FONTS  for
              more  information. Default: display only isgraph(3)
              characters - i.e. characters  printable  under  the
              current locale.

       --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



                          3 August 2002                         4





cooledit(1)                                           cooledit(1)


              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  any-
              where 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-xim
              Disable XIM support.

       -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



                          3 August 2002                         5





cooledit(1)                                           cooledit(1)


              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 record-
       ing;  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 num-
       ber; desktop  and  cursor  position  memory;  easy  window
       cycling;  comprehensive  search  and replace; input histo-
       ries; and lots more.  The editor is very easy to  use  and
       requires no tutoring.  To see what keys do what, just con-
       sult the appropriate pull-down menu.

       A complete set of key definitions follows.


HINT MESSAGES
       Cooledit displays a new help  message  on  the  title  bar
       every  2  minutes.  All features not obvious from the user
       interface are documented by these hint messages, so  read-
       ing  them should be of considerable help to those who pre-
       fer not to read this man page.

       To look at the complete list of  hint  messages,  see  the
       HINTS   file  in  the  distribution,  or  look  under  the
       doc/cooledit-3.17.7 directory in your file-system.


DEFAULT KEY DEFINITIONS
       Keys may be redefined using an easy to  use  key  learner.



                          3 August 2002                         6





cooledit(1)                                           cooledit(1)


       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
          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



                          3 August 2002                         7





cooledit(1)                                           cooledit(1)


          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



                          3 August 2002                         8





cooledit(1)                                           cooledit(1)


          Ctrl-r                  start/end record macro
          Ctrl-a                  execute macro
          Ctrl-p                  spell check highlighted text
          Shift-F9                C formatter
          Ctrl-Tab                complete word
          Meta/Alt-i              insert unicode character
          Shift/F1                rxvt terminal

       Debug:
          Alt-F2                  toggle breakpoint
          Alt-F3                  continue until cursor
          Alt-F4                  continue
          Alt-F5                  run from beginning
          Alt-F8                  single step, dive into functions
          Alt-F9                  single step, skip over functions
          Ctrl-c                  interrupt program
       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  move-
       ment 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  opera-
       tion.  It  is  a good idea to then save what you have done
       and exit immediately in case there has been memory corrup-
       tion.


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 associ-
       ated  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



                          3 August 2002                         9





cooledit(1)                                           cooledit(1)


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


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.


UNICODE, UCS AND UTF-8 SUPPORT
       As  of  version 3.15.0, Cooledit has Unicode support. What
       kind of unicode support it has, and what unicode, UCS  and
       UTF-8 are is explained as follows:




                          3 August 2002                        10





cooledit(1)                                           cooledit(1)


       UCS  stands for Universal Character Set. UCS is like ASCII
       (see ascii(1)) but instead of  storing  only  128  english
       specific  characters,  UCS goes up to 65535 characters and
       covers every known non-fictional language as well as  sci-
       entific and mathematical symbols etc.

       UCS  theoretically goes beyond 65535 (for example defining
       the very useful Klingon character  set).  However,  it  is
       likely  that  most  implementations  will keep to a 2 byte
       size requirement. Cooledit supports up to 131072  (1FFFFh)
       characters.  UCS  is also called Unicode and is officially
       ISO standard 10646. So wherever you see ISO-10646 it means
       Unicode.  (Actually,  Unicode is a standard to define fur-
       ther things like typographical layout, but for here,  they
       are taken to mean the same thing.)

       2  bytes  (for  UCS)  instead of 1 byte for ASCII posses a
       problem for most programs. For example, the average C pro-
       gram  uses a string function every few lines (that assumes
       a 1 character per byte format).  To  solve  this  we  have
       UTF-8.  UTF-8 stands for UCS Transformation Format.  It is
       an encoding scheme that says that any byte encountered  by
       an application that has a value below 128 is to be treated
       as ordinary ascii characters, but  a  byte  with  a  value
       above  128  means  that a sequence of bytes is forthcoming
       that represents some character in the range 128  to  65536
       (or  above). This enables a stream of single bytes to rep-
       resent the UCS character set,  albeit  with  some  ineffi-
       ciency.  More  information can be had from http://www.uni-
       code.org.

       Hence pure ASCII text is already in UTF-8 format.

       At the time of this writing, I am not quite sure precisely
       what  an application has to be able to do to be classified
       as "Supporting Unicode".  For instance: what about insert-
       ing  characters?  Don't  input  methods  produce tradition
       charset encodings? And why are characters displayed by X's
       Xmb* and Xwc* functions?

       At  the moment Cooledit can display Unicode characters if:
       (1) the "UTF8 Interpretation"  is  on,  (2)  the  "Display
       Characters  outside  locale"  is  on,  (3) you are using a
       non-"fontset" type font - when loading you  get  an  error
       message  "Font  set  not loaded", and (4) if the font is a
       Unicode font - i.e. ending in the font name iso10646-1.

       This may involve you having to install Unicode fonts.  See
       http://www.cl.cam.ac.uk/~mgk25/unicode.html            and
       http://czyborra.com/unifont/.

       For instance
           cooledit --utf8-interpretation --all-characters --no-fontset       -font -gnu-unifont-*-*-*--*-*-*-*-*-*-iso10646-1
       works. The GNU Unicode font is an  attempt  at  supporting



                          3 August 2002                        11





cooledit(1)                                           cooledit(1)


       the  entire  Unicode character set in one font. Most other
       fonts will support a limited range (such as  omitting  the
       20000 Chinese ideographs).

       What  Cooledit  is  supposed to do under a non-US locale I
       have no idea, so please give me a hint sometime.  (Looking
       at  the  yudit  documentation, it seems Gaspar also has my
       problems.

       Note that Cooledit  does  no  character  set  translations
       whatsoever - maybe later versions will.


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  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  vari-
       able....  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



                          3 August 2002                        12





cooledit(1)                                           cooledit(1)


       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  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 ("\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



                          3 August 2002                        13





cooledit(1)                                           cooledit(1)


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

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




                          3 August 2002                        14





cooledit(1)                                           cooledit(1)


       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  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



                          3 August 2002                        15





cooledit(1)                                           cooledit(1)


              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 win-
              dows.

       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 rep-
              resentation of a range of keys from the keysymdef.h
              X  Window header file (with or without the XK_ pre-
              fix) (for example bind ("A", "Z", ControlMask, con-
              trol_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  depend-
              ing on the type of text being edited. bind() should
              hence be used within the type_change() function.




                          3 August 2002                        16





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. If this text contains a
              \t  then the text after the \t will be right justi-
              fied (eg "Open...\tC-o"). 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.

       replace_menu(string, string, string, string)
              Replaces  an  existing  menu  item  with a new menu
              item. The  arguments  are  respectively:  The  menu
              (i.e. File, Edit, etc.), the old menu item, the new
              menu item, and the python code.

       insert_menu(string, string, string, string)
              Inserts a menu item after an  existing  menu  item.
              The  arguments  are  respectively:  The  menu (i.e.
              File, Edit, etc.), the menu item before  which  the
              insertion is to be made, the new menu item, and the
              python code.

       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



                          3 August 2002                        17





cooledit(1)                                           cooledit(1)


              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.

       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 arbi-
              trary 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  descrip-
                     tive 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.



                          3 August 2002                        18





cooledit(1)                                           cooledit(1)


                     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. Ele-
                     ments  may be null or there may be less ele-
                     ments 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 inclu-
                     sive OR of one or more of the following val-
                     ues:
                         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 but-
                     ton will open a file with  behaviour  appro-
                     priate  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 repro-
              duced 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",          \



                          3 August 2002                        19





cooledit(1)                                           cooledit(1)


               "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.





                          3 August 2002                        20





cooledit(1)                                           cooledit(1)


       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 contin-
              uously 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 num-
              ber.

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



                          3 August 2002                        21





cooledit(1)                                           cooledit(1)


       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.

       string file_type([string])
              Forces the current file  type  as  though  you  had
              selected  it  from  the  Options, Syntax highlight-
              ing... menu item.  Forcing the type disables  auto-
              matic  file  type  selection for this window there-
              after. The old file type is returned.

              If no arguments are passed, file_type just  returns
              the  current file type. This is useful for creating
              actions specific to the type of text being  edited.

              New  syntax rule sets are being added all the time,
              but the passed and returns string is least one of:


              None
              Unified Diff Output
              Context Diff Output
              LSM File
              Shell Script
              Perl Program
              Python Program
              NROFF Source
              HTML File
              Pascal Program
              Ada Program
              LaTeX 2.09 Document
              Texinfo Document
              C/C++ Program
              SWIG Source
              Java Program
              SmallTalk Program
              ML Program



                          3 August 2002                        22





cooledit(1)                                           cooledit(1)


              GNU Distribution ChangeLog File
              Makefile
              Mail folder
              Syntax Highlighting definitions



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

       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 direc-
       tory.

       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  con-
       text. This is usually normal programming code.



                          3 August 2002                        23





cooledit(1)                                           cooledit(1)


       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] [lines-
       tart] 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



                          3 August 2002                        24





cooledit(1)                                           cooledit(1)


       similarly  on the right. The left and right set of charac-
       ters can be set separately with,
       wholechars [left|right] characters

       The exclusive option causes the text  between  the  delim-
       iters 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  Com-
       mander  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  exam-
       ples on using this. Usually the background colour is omit-
       ted, 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. 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  *,
       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 \}. 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



                          3 August 2002                        25





cooledit(1)                                           cooledit(1)


       well, but you cannot have a wildcard as the first  charac-
       ter  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. How-
       ever, 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.


COLOURS
       Syntax  colours can be any of the integer values 0 through
       26.   The   options   option_editor_bg_normal   in    your
       ~/.cedit/.cooledit.ini   file   (and   their  counterparts
       option_editor_fg_normal etc.) can also be set to  a  value
       of  0 through 26. Each of these 27 colours' RGB values can
       be set to specific values in  your  ~/.cedit/.cooledit.ini
       file.    They    are    called    option_color_0   through
       option_color_26.  They are in hex with 2 digits  per  Red,
       Green and Blue, (just like HTML specified colours).


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



                          3 August 2002                        26





cooledit(1)                                           cooledit(1)


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

       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



                          3 August 2002                        27





cooledit(1)                                           cooledit(1)


       #
       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
       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



                          3 August 2002                        28





cooledit(1)                                           cooledit(1)


       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.

       %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



                          3 August 2002                        29





cooledit(1)                                           cooledit(1)


       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 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
       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



                          3 August 2002                        30





cooledit(1)                                           cooledit(1)


       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
       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



                          3 August 2002                        31





cooledit(1)                                           cooledit(1)


       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



                          3 August 2002                        32





cooledit(1)                                           cooledit(1)


       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 prob-
       lem, 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:





                          3 August 2002                        33





cooledit(1)                                           cooledit(1)


       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 spec-
              ify this as 0 for condensed text or a larger number
              for broadly spaced lines.



                          3 August 2002                        34





cooledit(1)                                           cooledit(1)


       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_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 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
              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.13, and now properly uses the libc6 locale functionality
       as well as multi-byte (Xmb) encoding. Hence you should set
       the LANG, LC_ALL amd  XCOMPOSE  environment  variables  to
       reflect  your  locale,  and install the appropriate locale
       and font files. THIS IS ALL YOU SHOULD NEED TO  DO.  THERE
       ARE  NO  OPTIONS IN COOLEDIT TO SET THE LOCALE. SETTING UP
       THE LOCALE IS BEYOND THE SCOPE OF THIS DOCUMENT.

       Most distributions will have many locale  files  installed
       already in say
           /usr/share/i18n/locales/
       You can then type, for example,
           export LC_ALL=de_DE



                          3 August 2002                        35





cooledit(1)                                           cooledit(1)


           export LANG=de_DE
           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.

       These  days  the  font is chosen automatically, unless you
       explicitly specify a font with its character set appended.
       In this case, the character set may not match the one that
       X expects. X will fail  to  enable  localisation  support,
       causing  Cooledit to raw load the font itself, effectively
       disabling any localisation support.  See  FONTS  for  more
       information.

       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. Then make sure you specify
       the font in full on the command-line so that it can be raw
       loaded.

       The  setlocale(3)  man page contains a few sketchy details
       on locale support.

       Also see the ABOUT-NLS for details about package  transla-
       tions in general, how it works and how you can contribute.


COMPOSING INTERNATIONAL CHARACTERS
       As of version 3.13.0, Cooledit supports  multi-byte  (Xmb)
       encoding. This has nothing to do with using character sets
       that have more than one byte per character (I  don't  know
       what  Cooledit will do in this case), but rather has to do
       with  X's  Xmb...  functions  that  support   localisation
       through font sets (See FONTS).

       To  insert a non-ascii character, you need to use the com-
       pose key specified in your X Window System settings.  With



                          3 August 2002                        36





cooledit(1)                                           cooledit(1)


       XFree86  your  XF86Config  file  contains  these settings.
       This is usually bound to the right control key, Hence hit-
       ting  right  control, the `o' and the `"' will produce the
       expected character.  Cooledit used to have its own  method
       of  composing characters separate from X. This still func-
       tions, but works by holding down  the  right  control  key
       (and  only the right control key) while pressing the first
       character in the control sequence.

       A complete list of key combinations is given in  the  file
       INTERNATIONAL  which  comes  with the source distribution.
       Note the this has nothing to do with X's method  of  first
       hitting the control key to go into compose `mode'.


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.


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.






                          3 August 2002                        37





cooledit(1)                                           cooledit(1)


ANTI-ALIASED FONT SUPPORT
       Anti-aliasing is specified by appending  /3  to  the  font
       name, for example,
           cooledit -font -winfonts-arial-bold-r-*-*-45-*-*-*-*-*-iso8859-1/3        --red-first
       To  use anti-aliased font drawing in the editor. This does
       not cause Cooledit to  actually  render  any  anti-aliased
       fonts  (as  might  be  done perhaps with some anti-aliased
       version of freetype). Instead, Cooledit  shrinks  whatever
       font  you  give it by a factor of 3. Always use a 45 to 60
       point true type font. Trying to use a font  less  than  45
       points  or  a  non-true type font, will give poor results.
       You may have to install X4 or  xfstt,  the  FreeType  font
       server.

       The --widget-font option also works with this.


FONTS
       The  default font is 8x13bold (or close to it) which is an
       alias             for              -misc-fixed-bold-r-nor-
       mal--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.13.0,  Cooledit  supports  font  sets.   X
       allows  an application to support a locale's character set
       from a list of possible fonts that may cover parts of that
       character  set. The application need only specify the list
       of fonts that it would like to  use  that  may  cover  the
       character set of that particular language. X will sort out
       all the rest.

       Running Cooledit with no command-line options  causes  the
       appropriate font set to be loaded based on the locale set-
       tings.  Note that font sets are incompatible with  Unicode
       support and anti-aliasing support.

       If  you  would  like  to  explicitely  specify a font, the
       --font and --widget-font options control the font  of  the
       edit  window  and  the font of the widget controls respec-
       tively. For example

           cooledit -font "-*-fixed-bold-r-normal--13" \
               --widget-font "-*-helvetica-bold-r-*--13"

       are the defaults. The fonts are partially specified  leav-
       ing XCreateFontSet(3X11) to fill in the appropriate locale
       information (see SPECIFYING FONTS below). You may specifiy
       whole  lists  of fonts as arguments since these get passed
       directly to the XCreateFontSet. See the explanation in the
       XCreateFontSet(3X11) man page.

       However,  font  sets  will  fail if you specify a complete



                          3 August 2002                        38





cooledit(1)                                           cooledit(1)


       font name against a conflicting locale (like if you  spec-
       ify  a  Russian  font while your locale is set to "C"). To
       cope with  this,  Cooledit  will  fall  back  to  its  old
       (non-`font  set')  font  mechanism  and raw load the font,
       giving appropriate error messages to stderr.

       Note that your X and glibc installation must first support
       your  locale  for  Cooledit to work. If other applications
       don't display properly under  your  locale,  neither  will
       Cooledit.

       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.


SPECIFYING FONTS
       In this section I'll give a partial guide to the font nam-
       ing 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.

       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



                          3 August 2002                        39





cooledit(1)                                           cooledit(1)


              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.
              This last bit is the locale setting which you would
              normally  leave  out  to  allow X to decide on them
              based on your locale settings.

       As an example, start cooledit with

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

       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.


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



                          3 August 2002                        40





cooledit(1)                                           cooledit(1)


              highlighted text is also saved to this  file  when-
              ever 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
         Evgeny A Cherkashin  <eugeneai /AT/ icc.ru>
       for his Russian translation.

       Thanks to
         Leif Andersson  <Leif.Andersson /AT/ control.lth.se>
         Gisle Aas       <Gisle.Aas /AT/ nr.no>
       for  allowing  me to convert there i2ps program into C and
       incorporate into Cooledit, all without their permission.

       Thank to Sasha Vasko <Sasha_Vasko  /AT/  osca.state.mo.us>
       for  his NeXT patch to make Cooledit look like a AfterStep
       application.

       Thanks to the authors of Rxvt. Their rxvt-2.6.1 was shame-
       lessly  ripped  and mangled to make librxvt. From the Rxvt
       LSM file:

       John Bovey
       Rob Nation             <nation /AT/ rocket.sanders.lockheed.com>
       Mark Olesen            <olesen /AT/ me.QueensU.CA>
       Oezguer Kesim          <kesim /AT/ math.fu-berlin.de>



                          3 August 2002                        41





cooledit(1)                                           cooledit(1)


       Geoff Wing             <gcw /AT/ pobox.com>

       Thanks to the following people for their bug reports, sug-
       gestions, extensions and fixes:

       Vadim Berezniker       <vadim /AT/ murlosoft.com>
       Scott Billings         <aerogems /AT/ netins.net>
       Ross Campbell          <rcampbel /AT/ us.oracle.com>
       David Chan             <dpc29 /AT/ hermes.cam.ac.uk>
       David M. Cook          <davecook /AT/ home.com>
       Miguel Cruz            <mnc /AT/ diana.law.yale.edu>
       Liviu Daia             <daia /AT/ stoilow.imar.ro>
       Peter Danziger         <danziger /AT/ acs.ryerson.ca>
       Derkjan de Haan        <j.d.j.dehaan /AT/ student.utwente.nl>
       Vaughn Dickson         <vaughn /AT/ obsidian.co.za>
       Martin Dufour          <dufm02 /AT/ pollux.GEL.USherb.CA>
       Hans Dumbrajs          <hansd /AT/ saunalahti.fi>
       Yuriy Elkin            <yury /AT/ intruder.mktg.stratus.com>
       Alex Fortuna           <alex /AT/ transtelecom.ru>
       Jeff Garzik            <jgarzik /AT/ mandrakesoft.com>
       Arpd Gereffy           <arpi /AT/ esp-team.scene.hu>
       Andreas Haack          <ahaack /AT/ bigfoot.com>
       I. Ioannou             <roryt /AT/ hol.gr>
       Johnny Johansson       <johnnyj /AT/ clarus.se>
       Pavel Hampl            <phampl /AT/ chmi.cz>
       Matej Knopp            <matej /AT/ europe.com>
       Juha Laukala           <juha.laukala /AT/ tekla.fi>
       Daniel Lyons           <fusion /AT/ nmt.edu>
       Alex Maranda           <amaranda /AT/ spider.com>
       LeRoy C. Miller III    <qball /AT/ ansic.net>
       ET Mogaswa             <MOGASET /AT/ alpha.unisa.ac.za>
       Rob Nelson             <ronelson /AT/ vt.edu>
       Norbert Nemec          <nobbi /AT/ cheerful.com>
       Frank Niessink         <frankn /AT/ cs.vu.nl>
       Michel Pelletier       <michel /AT/ digicool.com>
       Joao Luis Marques Pinto <Lamego /AT/ PTlink.net>
       Oleg Yu. Repin         <repin /AT/ ssd.sscc.ru>
       Pavel Roskin           <pavel_roskin /AT/ geocities.com>
       Ronald Rietman         <rietman /AT/ natlab.research.philips.com>
       Benjamin Sher          <sher07 /AT/ bellsouth.net>
       Mark N Summerfield     <Mark.Summerfield /AT/ chest.ac.uk>
       Paul Seelig            <pseelig /AT/ trudi.zdv.Uni-Mainz.DE>
       Jeroen R. v.d. Werven  <asmodai /AT/ wxs.nl>
       Norbert Warmuth        <k3190 /AT/ fh-sw.de>
       Nathan Whitehead       <nwhitehe /AT/ math.uiuc.edu>
       Max Xu                 <max /AT/ crosslight.ca>
       Pierfrancesco Zuccato  <pf.zuccato /AT/ alinet.it>
       (anyone I left out?)


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




                          3 August 2002                        42





cooledit(1)                                           cooledit(1)


       unknown                          84
       alpha-debian-linux-gnu           4
       alpha-dec-osf2.1                 1
       alpha-dec-osf3.2                 12
       alpha-dec-osf4.0                 13
       alpha-dec-osf4.0b                2
       alpha-dec-osf4.0d                5
       alpha-dec-osf4.0f                3
       alpha-unknown-linux              62
       alpha-unknown-linux-gnu          28
       alpha-unknown-none               2
       alphaev5-dec-osf4.0a             1
       alphaev5-dec-osf4.0b             3
       alphaev5-dec-osf4.0d             8
       alphaev5-unknown-linux-gnu       2
       alphaev5-unknown-linux-gnulibc1  6
       alphaev56-dec-osf4.0b            4
       alphaev56-dec-osf4.0d            14
       alphaev56-dec-osf4.0e            2
       alphaev56-dec-osf5.0             2
       alphaev56-unknown-linux-gnu      8
       arm-linux-elf                    1
       arm-unknown-linux-gnu            1
       arm-unknown-linux-gnuelf         7
       armv4l-unknown-linux-gnu         2
       hppa1.0-hp-hpux10.20             5
       hppa1.0-hp-hpux11.00             1
       hppa1.1-hp-hpux10.01             3
       hppa1.1-hp-hpux10.10             39
       hppa1.1-hp-hpux10.20             350
       hppa1.1-hp-hpux11.00             5
       hppa1.1-hp-hpux8.07              1
       hppa1.1-hp-hpux9.01              3
       hppa1.1-hp-hpux9.03              10
       hppa1.1-hp-hpux9.05              8
       hppa1.1-hp-hpux9.07              1
       hppa2.0-hp-hpux10.20             4
       hppa2.0n-hp-hpux11.00            11
       hppa2.0w-hp-hpux11.00            7
       i386-gnu-linux-gnu               1
       i386-pc-bsdi3.1                  1
       i386-pc-bsdi4.0                  2
       i386-pc-linux-gnu                1
       i386-pc-sco3.2v5.0.5             1
       i386-pc-solaris2.6               3
       i386-pc-solaris2.7               9
       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



                          3 August 2002                        43





cooledit(1)                                           cooledit(1)


       i386-unknown-freebsd2.2.6        9
       i386-unknown-freebsd2.2.7        14
       i386-unknown-freebsd2.2.8        1
       i386-unknown-freebsd3.0          10
       i386-unknown-freebsd3.1          13
       i386-unknown-freebsd4.0          2
       i386-unknown-freebsdelf3.0       1
       i386-unknown-freebsdelf3.1       3
       i386-unknown-freebsdelf3.2       7
       i386-unknown-freebsdelf3.3       7
       i386-unknown-freebsdelf3.4       5
       i386-unknown-freebsdelf4.0       15
       i386-unknown-linux               11
       i386-unknown-netbsd1.1           1
       i386-unknown-netbsd1.3.2         2
       i386-unknown-netbsd1.4           1
       i386-unknown-netbsd1.4.1         1
       i386-unknown-netbsd1.4I          1
       i386-unknown-netbsd1.4K          1
       i386-unknown-none                4
       i386-unknown-openbsd2.3          1
       i386-unknown-openbsd2.4          2
       i386-unknown-openbsd2.5          6
       i386-unknown-openbsd2.6          4
       i386-unknown-solaris2.5.1        5
       i386-unknown-solaris2.6          2
       i486-ibm-linux                   1
       i486-pc-linux-gnu                84
       i486-pc-linux-gnulibc1           95
       i486-pc-linux-gnuoldld           1
       i486-unknown-linux               1522
       i486-unknown-linuxaout           6
       i486-unknown-linuxoldld          1
       i486-unknown-none                2
       i486-unknown-solaris2.5.1        1
       i586-intel-linux                 4
       i586-intel-none                  4
       i586-k6-linux-gnu                2
       i586-mandrake-linux-gnu          90
       i586-pc-linux-gnu                2792
       i586-pc-linux-gnuaout            1
       i586-pc-linux-gnucoff            1
       i586-pc-linux-gnulibc1           732
       i586-pc-none                     1
       i586-pc-sco3.2v5.0.2             1
       i586-redhat-linux                1
       i586-unknown-linux               2844
       i586-unknown-linuxaout           5
       i586-unknown-none                12
       i586-unknown-sco3.2v4.2          1
       i586-unknown-sco3.2v5.0.2        1
       i686-pc-linux-gnu                14457
       i686-pc-linux-gnulibc1           867
       i686-pc-none                     1



                          3 August 2002                        44





cooledit(1)                                           cooledit(1)


       i686-redhat-linux-gnu            1
       i686-tech-linux-gnu              1
       i686-unknown-linux               6
       i686-unknown-linux-gnu           3
       m68k-apple-netbsd1.3.3           1
       m68k-unknown-linux-gnu           2
       mips-dec-ultrix4.3               1
       mips-sgi-irix5.3                 36
       mips-sgi-irix6.2                 33
       mips-sgi-irix6.3                 13
       mips-sgi-irix6.4                 2
       mips-sgi-irix6.5                 22
       mips-sni-sysv4                   3
       mips-unknown-linux               2
       powerpc-ibm-aix3.2.5             2
       powerpc-ibm-aix4.1.4.0           3
       powerpc-ibm-aix4.1.5.0           5
       powerpc-ibm-aix4.2.1.0           16
       powerpc-ibm-aix4.3.1.0           1
       powerpc-ibm-aix4.3.2.0           2
       powerpc-ibm-aix4.3.3.0           1
       powerpc-unknown-linux            1
       powerpc-unknown-linux-gnu        2
       rs6000-ibm-aix4.1.4.0            3
       rs6000-ibm-aix4.2.0.0            1
       sparc-mandrake-linux-gnu         1
       sparc-sun-solaris2.4             20
       sparc-sun-solaris2.5             63
       sparc-sun-solaris2.5.1           200
       sparc-sun-solaris2.6             224
       sparc-sun-solaris2.7             46
       sparc-sun-solaris2.8             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          16
       sparc64-unknown-linux-gnu        3

       There were a total of 22524 unique addresses as of Septem-
       ber  2000.   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.


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.






                          3 August 2002                        45





cooledit(1)                                           cooledit(1)


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:
       http://cooledit.sourceforge.net/


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


AUTHORS
       Paul Sheer (psheer /AT/ icon.co.za)


BUGS
       *      Reloading  Python  scripts  eats  memory.  This  is
              because  reloading proved to unstable when Cooledit
              tried to clean up Python before reloading.  If  the
              Python  scripts give lots of error messages, things
              may crash. This is only really of concern to devel-
              opers.


       *      Libtool is not yet complete and gives some harmless
              warnings when installing.  On some systems the cor-
              rect  library  or library sequence is incorrect, so
              some fiddling is required to get Cooledit  to  com-
              pile.


       *      Unicode characters do not display inside input wid-
              gets. You can still search and replace them though.


       *      Reverse  displaying  of  Hebrew is a crude hack and
              doesn't work properly.


       *      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.)


       *      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.





                          3 August 2002                        46





cooledit(1)                                           cooledit(1)


       *      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.





































                          3 August 2002                        47


