#449569: Ensure shell/macro accelerators also have accelerator fix

[nedit.git] / README

                    NEdit Version 5.2.0beta,  July 2001

$Id: README,v 1.13 2001/08/18 11:48:37 jlous Exp $
             
NEdit is a multi-purpose text editor for the X Window System, which combines a
standard, easy to use, graphical user interface with the thorough functionality
and stability required by users who edit text eight hours a day.  It provides
intensive support for development in a wide variety of languages, text
processors, and other tools, but at the same time can be used productively by
just about anyone who needs to edit text.

As of this version, NEdit may be freely distributed under the terms of the GNU
General Public License (see the file COPYRIGHT which is also part of this
distribution).

AUTHORS

NEdit was written by Mark Edel, Joy Kyriakopulos, Christopher Conrad,
Jim Clark, Arnulfo Zepeda-Navratil, Suresh Ravoor, Tony Balinski, Max
Vohlken, Yunliang Yu, Donna Reid, Arne Førlie, Eddy De Greef, Steve
LoBasso, Alexander Mai, Scott Tringali, and Thorsten Haude.

The regular expression matching routines used in NEdit are adapted (with
permission) from original code written by Henry Spencer at the University of
Toronto.

Syntax highlighting patterns and smart indent macros were contributed
by: Simon T. MacDonald,  Maurice Leysens, Matt Majka, Alfred Smeenk,
Alain Fargues, Christopher Conrad, Scott Markinson, Konrad Bernloehr,
Ivan Herman, Patrice Venant, Christian Denat, Philippe Couton, Max
Vohlken, Markus Schwarzenberg, Himanshu Gohel, Steven C. Kapp, Michael
Turomsha, John Fieber, Chris Ross, Nathaniel Gray, Joachim Lous, Mike
Duigou, Seak Teng-Fong, Joor Loohuis, Mark Jones, and
Niek van den Berg.

NEdit sources, executables, additional documentation, and contributed software
are available from the NEdit web site at http://nedit.org.

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

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

VERSION 5.1

Version 5.1 is the first release of NEdit under the GNU General Public
License, and the first release to be done entirely by volunteer effort.

The most significant enhancements in this release are:

  * New regular expression code, boosts highlighting performance by 40%,
    and introduces many new and powerful features to regular expression
    operations and syntax highlighting.
  
  * Incremental search, and optional search bar.
  
  * New ctags code with full support for Exuberant Ctags, better
    handling of tag collisions, multiple tag file support, on-demand
    loading of tag files, and automatic reload of modified tag files.

  * Optional display of line numbers along the left side of the text.

  * NEdit can now read and write MS DOS format files.
  
  * New built-in syntax highlighting patterns for Lex, PostScript, SQL,
    and Matlab, and improved SGML/HTML and Java patterns.  Many minor
    improvements to other patterns.
    
  * Improved international character set input
  
  * New macro subroutines: list_dialog, getenv, set_language_mode.
  
  * Optional warnings about external modifications to files
  
  * Clearcase awareness
  
  * Session manager restart capability
     
There are also many smaller improvements and bug fixes, see the release
notes for details.


BUILDING NEDIT

Pre-built executables will be available for most major Unix and VMS systems, so
check the NEdit web page (http://nedit.org), first. 
Requirements to build NEdit are: 

 - ANSI C89 system (compiler, headers, libraries)
 - make utility
 - X11 development stuff (headers, libraries)
 - Motif 1.2 or above (Motif 1.1 might work, but is no longer supported)
   This GUI library is a standard part on most systems which have 
   an X11 installation. Most commercial Unix systems feature this, 
   others may require a separate installation. 
   A free version of Motif, called LessTif, is now available and stable enough 
   to run NEdit reasonably well on these systems. See the LessTif section 
   under PLATFORM SPECIFIC ISSUES for details.
 
Optionally one may use:
 
 - yacc (bison)


The two directories called 'source' and 'util 'contain the sources for NEdit.
Util should be built first, followed by source.  The makefile in this directory
can be used to build both in sequence if your system is one of the supported
machines and no modifications are necessary to the makefiles.  To build NEdit
from this directory, issue the command: "make <machine-type>"; where
<machine-type> is one of suffixes of a Makefile in the directory "makefiles". 
For example, to build the Silicon Graphics version, type:

        make sgi

If everything works properly, this will produce an executable called nedit in
the directory called source.


The Source Directories

Since executables are already available for the supported systems, you are
probably not just rebuilding an existing configuration, and need to know more
about how the directories are organized.

The util directory builds a library file called libNUtil.a, which is later
linked with the code in the source directory to create the nedit executable.

The makefiles in both source directories consist of two parts, a machine
dependent part and a machine independent part.  The machine dependent makefiles
can be found in the directory called "makefiles", and contain machine specific
header information.  They invoke a common machine independent part called
Makefile.common.  To compile the files in either of these directories, copy or
link one of the system-specific makefiles from the directory "makefiles" into
the directory, and issue the command:

    make -f Makefile.<machine-type>
    
(where <machine type> is the Makefile suffix).  Alternatively, you can
name the file "Makefile" and simply type "make".

If no makefile exists for your system, check the NEdit web site at:
http://nedit.org for more contributed Makefiles.  If you can't find one that's
close, start from Makefile.generic.  See the comments in Makefile.generic for
more porting information.

 
Building NEdit on VMS Systems

Command files are provided for compiling and linking files in the source
and util directories.  comutil.com compiles the files in the util directory
and produces two library files, vmsutils.olb and libutil.olb.  comnedit.com
compiles and links the files in the source directory to produce the nedit.exe
executable.


Additional Settings

Some C preprocessor macros may be used to en/disable certain
parts of the code. Usually this correponds to some non-important
features being selected or certain workarounds for platform-specifc
problems. Those which might be useful on more than one platform
are documented in makefiles/Makefile.generic.

Note that a special compilation flag, namely REPLACE_SCOPE, is currently
available. Its purpose is to allow the evaluation of two alternative
(but functionally equivalent) Replace/Find dialog box layouts. 
By default, NEdit is built with a Replace/Find dialog containing 2 rows
of push buttons. Compiling with the REPLACE_SCOPE flag enables an 
alternative layout with a row of radio buttons for selecting the scope of 
the replace operations. Eventually, one of these alternatives will
probably disappear, but up to now, the NEdit developers have not been able
to decide which one to drop. Please give them both a try and let us know 
which one you prefer (via the discuss mailing list, for instance).


INSTALLATION

NEdit consists of a single, stand-alone executable file which does not require
any special installation.  To install NEdit on Unix systems, simply put the
nedit executable in your path.  On VMS systems, nedit must be defined as a
foreign command so that it can process command line arguments.  For example,
if nedit.exe were in the directory mydir on the disk called mydev, adding the
following line to your login.com file would define the nedit command:

        $ ned*it :== $mydev:[mydir]nedit.exe

To use NEdit in client/server mode, you also need the nedit client program, nc,
which, again, needs no special installation, except in the VMS case, as above.
On some systems, the name nc may conflict with an existing program.  In that
case, choose a different name for the executable and simply rename it.  The
recommend alternative is "ncl".


RUNNING NEDIT

If you are accessing a host Unix system from a remote workstation or X terminal,
you need to set the Unix environment variable for your display:

        % setenv DISPLAY devicename:0
        
where devicename is the network node name of the workstation or X terminal
where you are typing.  On VMS systems, the equivalent command is:

        $ set display/create/node=devicename

To run NEdit, simply type "nedit", optionally followed by the name of a file or
files to edit.  On-line help is available from the pulldown menu on the far
right of the menu bar.  For more information on the syntax of the nedit command
line, look under the heading of "NEdit Command Line."


PLATFORM SPECIFIC ISSUES

Systems with LessTif, rather than Motif libraries

As of Lesstif 0.92.26, NEdit is very stable with Lesstif. 
You can get the latest LessTif version from http://www.lesstif.org.
If you are having trouble building with LessTif, remember there are
pre-compiled statically linked executables available from http://nedit.org.
Known bugs which might show off in NEdit linked with LessTif include:

  1) Some dialogs which are intended to be modal (prevent other activity
     while up) are not, and doing other actions while these dialogs are
     up can cause trouble (.89.9+)
     
  2) Switching to continuous wrap mode, sometimes the horizontal scroll
     remains partially drawn after the change, rather than disappearing
     completely as it should. (.89.9+)
  
  3) Secondary selection operations are not yet supported in text fields.


Linux Systems

The default key bindings for arrow keys in fvwm interfere with some of the
arrow key bindings in NEdit, particularly, Ctrl+Arrow and Alt+Arrow.  You
may want to re-bind them either in NEdit (see Customizing -> Key Binding
in the Help menu) or in fvwm in your .fvwmrc file.

Some older Linux distributions are missing the /usr/X11R6/lib/X11/XKeysymDB
file, which is necessary for running Motif programs.  When XKeysymDB is
missing, NEdit will spew screenfulls of messages about translation table syntax
errors, and many keys won't work.  You can obtain a copy of the XKeysymDB file
from the contrib sub-directory of the NEdit distribution directory.  

SGI Systems

Beginning with IRIX 6.3, SGI is distributing a customized version of NEdit
along with their operating system releases.  Their installation uses an
app-defaults file (/usr/lib/X11/app-defaults/NEdit) which overrides the
default settings in any new nedit version that you install, and may result in
missing accelerator keys or cosmetic appearance glitches.  If you are
re-installing NEdit for the entire system, just remove the existing app-
defaults file.  If you want to run a newer copy individually, get a copy of
the app-defaults file for this version the contrib sub-directory of the
distribution directory for this version on ftp.nedit.org (/pub/<version>/
contrib/nedit.app-defaults), and install it in your home directory or set
XAPPLRESDIR or XUSERFILESEARCHPATH to point to a directory and install it
there.  In all cases, the file should be named simply NEdit.

No additional installation or resource settings are necessary on IRIX systems
before 6.3

HP-UX Systems

If you are using HPVUE and have trouble setting colors, for example part
of the menu bar stubornly remains at whatever HPVUE's default is, try setting:

   nedit*useColorObj: False

IBM AIX Systems

Due to an optimizer bug in IBM's C compiler, the file, textDisp.c, must be
compiled without optimization on some AIX systems.

Solaris (SunOS 5.3 and beyond) Systems

The nedit_solaris executable may require the environment variable OPENWINHOME
to be set to the directory where Open Windows is installed.  If this is not set
properly, NEdit will spew screenfulls of messages about translation table
syntax errors.

Solaris 2.4 -- Add -DDONT_HAVE_GLOB to the CFLAGS line in Makefile.solaris.

Solaris 2.5 -- Solaris 2.5 systems were shipped with a bad shared Motif
library, in which the file selection dialog (Open, Save, Save As, Include,
etc.) shows long path names in the file list, but no horizontal scroll bar,
and no way to read the actual file names.  Depending on your system, the
patch is one of ID# 103461-07, # 102226-19, or # 103186-21.  It affects all
Motif based programs which use the library.  If you can't patch your system,
you might want to just try the nedit_sunos executable (from ftp.nedit.org
/pub/<version>), which is statically linked with a good Motif.  You can also
set the X resource: nedit.stdOpenDialog to True, which at least gives you a
text field where you can enter file names by hand.

Solaris 2.6 -- If you're experiencing performance problems (windows come up
slowly), the patch for Sun's shared Motif library is ID# 105284-04.  Installing
the patch alone will improve nedit's performance dramatically.  The patch also
enables a resource, *XmMenuReduceGrabs. Setting this to True will eliminate the
delay completely.

SunOS 4.x Systems

On some SunOS systems, NEdit will also complain about translation table syntax
errors.  This happens when Motif can't access the keysym database, usually
located in the file /usr/lib/X11/XKeysymDB.  If this file exists on your
system, but NEdit fails to locate it properly, you can set the environment
variable XKEYSYMDB to point to the file.  If you can't find the file, or if
some of the errors persist despite setting XKEYSYMDB, there is a XKeysymDB
which you can use to update or replace your /usr/lib/X11/XKeysymDB file
available in the contrib sub-directory of the NEdit distribution directory.
If you don't want to change your existing XKeysymDB file, make a local copy
and set XKEYSYMDB to point to it.

If you find that some of the labeled keys on your keyboard are not properly
bound to the corresponding action in NEdit, try the following:

  1) Get a copy of motifbind.sun (for Sun standard keyboards), or
     motifbind.sun_at (for Sun PC style keyboards) from the NEdit contrib
     directory on ftp.nedit.org:/pub/<version>/contrib.
  2) Copy it to a file called .motifbind in your home directory.
  3) Shutdown and restart your X server.


COMPATIBILITY WITH PREVIOUS VERSIONS

Existing .nedit Files

NEdit 5.1 makes significant changes to the syntax of regular expressions.
Mostly, these are upward compatible, but two changes; introducing the brace
operator, and changing the meaning of \0; are not.  Brace characters must now
be escaped with backslash, and & must be used in place of \0 in substitutions.

NEdit 5.1 employs a new built-in upgrade mechanism which will automatically
detect pre-5.1 .nedit files and fix regular expressions which appear in
user-defined highlight patterns.  The automatic upgrade mechanism, however, can
not fix regular expression problems within user-defined macros.  If you have
a macro which is failing under NEdit 5.1, you will have to fix it by hand.

If you are upgrading from a pre-5.0 version of NEdit, there are significant
changes to the macro language, and you are best off simply editing out the
nedit.macroCommands section of your .nedit file, generating a new .nedit file,
and then re-introducing your user-written commands into the new file.  Most
macros written for previous versions will function properly under the new macro
language.  The most common problems with old macros is lack of a terminating
newline on the last line of the macro, and the addition of "<", ">", and now
"{" to the regular expression syntax.  These characters must now be escaped
with \ (backslash).  Also, if you have been using a font other than the default
for the text portion of your NEdit windows, be sure to check the Preferences ->
Default Settings -> Text Font dialog, and select highlighting fonts which match
your primary font in size.  Matching in height is desirable, but not essential,
and sometimes impossible to achive on some systems.  When fonts don't match in
height, turning on syntax highlighting will cause the window size to change
slightly.  NEdit can handle unmatched font sizes (width), but leaving them
unmatched means sometimes columns and indentation don't line up (as with
proportional fonts).


FURTHER INFORMATION

More information is available in the file nedit.doc in this kit, from NEdit's
on-line help system, and from the enclosed FAQ file.  There is also a web page
for NEdit at: http://nedit.org.  For discussion with other NEdit users, or to
receive notification of new releases and news about news, you can subscribe to
one or both of the NEdit mailing lists, discuss@nedit.org, and
announce@nedit.org.  The NEdit on-line help has information on subscribing
under Help -> Mailing Lists.


REPORTING BUGS

The NEdit developers subscribe to both discuss@nedit.org and develop@nedit.org,
either of which may be used for reporting bugs.  If you're not sure, or you
think the report might be of interest to the general NEdit user community,
send the report to discuss@nedit.org.  If it's something obvious and boring,
like we misspelled "anemometer" in the on-line help, send it to develop.  If
you don't want to subscribe to these lists, please add a note to your mail
about cc'ing you on responses.