Installing the expander package
===============================

Steps to follow:

1. Build expander, by executing the build script. It requires
   a single parameter indicating the directory to where the compiled
   executables in the package are to be placed. For instance,
   
     build $HOME/bin

   If the package destination directory (here, $HOME/bin) does not
   exist, an attempt is made to create it. Note that the first time
   that this is done, the script will save copies of your
   $HOME/.nedit and $HOME/.neditmacro files in the $HOME directory
   under the names nedit_B4installExpander and
   neditmacro_B4installExpander, respectively. This allows you to
   restore them if you decide not to use the expander package.
   Remember to include the package destination directory in the
   PATH environment variable, otherwise NEdit will not be able
   to locate the executable files found in the directory.

   (Hint: Make sure that they have been created after the build
   script does its work for your own peace of mind prior to going
   on any further).

   If you receive compiler messages indicating that the function
   strtok_r is being redefined, append a second argument onto the
   build line, such as 'build $HOME/bin no_strtok_r', which tells
   the build process not to include the internal definition of the
   strtok_r function, because the local system has one of its own.

2. Copy from the macros directory, expander.nm, system.nm,
   revision_history.nm, and general.nm to the location where you
   store your macros. ($HOME/.neditutil ?). Include the getenv.nm
   macro only if your version of NEdit is earlier than 5.1.1,
   because later versions of NEdit have the getenv function
   embedded internally.

   Edit $HOME/.neditmacro and include the following lines. (See
   dot_neditmacro file in the misc directory). The example assumes
   that the macros were copied to $HOME/.neditutil directory.
      
       $HOME     = shell_command( "echo -n $HOME", "" )
       $NEDITDIR = $HOME "/.neditutil/"

       load_macro_file( $NEDITDIR "system.nm" )

       system_init()

       load_macro( $NEDITDIR "getenv.nm"    ) # only for <= 5.1.1
       load_macro( $NEDITDIR "general.nm"   )
       load_macro( $NEDITDIR "expander.nm"  )

       expander_init()
   
   Your mileage may vary on how you set $HOME and $NEDITDIR.
   (echo -n, works with C-shell, but not with Bourne shell.
    Some systems have printf defined as a command, so that
    could be used in place of echo -n.)

   The expander_init() macro reads the necessary configuration information at
   NEdit server startup. The system_init macro instantiates needed variables.
   
   Also install the macro menu entries in expanderPlus.import (found in the
   misc directory) using the NEdit -import command line option, to get easy
   keyboard bindings to expander package items. The bindings found in
   expanderPlus.import for the expansion and the next field functionality are
   Ctrl-X and Ctrl-C respectively. (Since I have a Sun Workstation keyboard, I
   do not use Ctrl-C and Ctrl-X as copy and cut keys. If this is a problem for
   you, just change the keybindings after NEdit is activated).

   Install the appropriate version of highlight pattern set, which will be
   needed when you start customizing expander dictionaries. The following
   assumes the current directory is the misc directory in the expander package.

    nedit -import expander-5.0.pats -import expanderPlus.import
    nedit -import expander-5.1.pats -import expanderPlus.import

   After NEdit brings up a window, save the imported patterns by selecting
   Save Defaults from the Preferences menu. This will change $HOME/.nedit.
   
3. Set the necessary environment variables.

   The expander package comes with a Bourne shell script which assumes
   that the package directory is going to be the reference for
   EXPANDER_DIR. If that is the shell which is being used, sourcing it
   will set all the needed to set the minimum set of variables needed
   to use the expander facility. The script is called expander_env.sh.
   Edit it the file, if necessary.
   
   The build from step one will produce a C-shell script with the 
   expander package environment variables. It is called expander_env.csh.
   
   An overview of the variables follows (also available by invoking the
   expander executable with a -h option).
   
    EXPANDER_DIR
        contains the directory in which files related to expander are stored

    EXPANDER_DEF
        contains the directory in which the language specific abbreviation
        dictionaries are stored (eg. $EXPANDER_DIR/defs)
    
    EXPANDER_TPL
        contains the directory in which expansion template files are stored.
        (eg. $EXPANDER_DIR/templates) Note that this particular one exists
        because some of the definitions in the package access templates
        in the package. If templates are not used, this variable does not 
        need defining.

    EXP_DEFINITIONS 
        name of abbreviation primary definitions file
        (eg. $EXPANDER_DEF/generic.def)

    EXP_DATE_FORMAT
        strftime format for 'date' abbreviation

    EXP_TIME_FORMAT
        strftime format for 'time' abbreviation

    EXP_DTIME_FORMAT
        strftime format for 'dtime' abbreviation

    EXP_INDENT_SIZE
        when undefined, default is 4 columns

    EXP_USE_TABS
        when undefined or zero, spaces are used to indent. otherwise, numeric
        value represents tab size (that is, 1 tab (\t) character for every 'N'
        columns). when value is non-numeric (eg. 'yes'), the default 8 is used.

    EXP_NO_AUTOFIELD
        when defined, field marker NOT automatically added to any expansion
        which is missing one.

    EXP_KEYWORD_DELIM
        used to define keyword delimiters, default is ' \t'.
    
    EXP_EXTENT
        used to change the default file extension of the abbreviation
        dictionaries. When not specified, ".def" is the default.

    EXP_USER
        for use within definition files. Default values come from the
        environment variables LOGNAME, or USER.

                                    NOTE

      When the expander code is invoked from within an editor, the invocation
      may start by using a Unix shell causing slow behavior. The following is
      one example of how to get around this problem with the C-shell.
      These lines should be placed as the 1st lines in the shell startup file,
      ".cshrc".

         # short circuit access to remainder of shell command file"
         # to make non-interactive commands run faster."

         if ( $?prompt == 0 ) exit

4. Test expander facility

   In the USAGE file, a small example of using expander and boxcomment is
   given. If you don't like expander, you can bail out by copying back your
   .nedit and .neditmacro files saved in step 1, and running the clean script.

5. Customize

   Read the USAGE, on how to customize expander abbreviation dictionaries.
   
