allbery@uunet.UU.NET (Brandon S. Allbery - comp.sources.misc) (06/11/89)
Posting-number: Volume 7, Issue 23
Submitted-by: fox@marlow.UUCP (Paul Fox)
Archive-name: crisp1.9/part03
#!/bin/sh
# this is part 2 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file help/crisp/concept/Macros.hlp continued
#
CurArch=2
if test ! -r s2_seq_.tmp
then echo "Please unpack part 1 first!"
exit 1; fi
( read Scheck
if test "$Scheck" != $CurArch
then echo "Please unpack part $Scheck next!"
exit 1;
else exit 0; fi
) < s2_seq_.tmp || exit 1
echo "x - Continuing file help/crisp/concept/Macros.hlp"
sed 's/^X//' << 'SHAR_EOF' >> help/crisp/concept/Macros.hlp
Xgo, without having to parse the data in the file.
X
X> Files and Macros
X
XA macro file can contain any number of macro definitions.
XWhen a macro file is read into memory, CRISP maintains a
Xtable of the defined macros.
X
XCRISP supports the concept of 'autoloading'. Rather than
Xpreload the entire set of macros on startup, which would
Xbe expensive in terms of time and memory use, CRISP can be
Xtold where to find a macro, via an autoload list. The
Xautoload list is a filename and a list of macros defined
Xin that file. If CRISP sees a reference to one of these
Xmacros, it will automatically load the file containing the
Xmacro definition. (See (autoload) for more details of this).
X
SHAR_EOF
echo "File help/crisp/concept/Macros.hlp is complete"
chmod 0644 help/crisp/concept/Macros.hlp || echo "restore of help/crisp/concept/Macros.hlp fails"
mkdir help help/crisp help/crisp/concept >/dev/null 2>&1
echo "x - extracting help/crisp/concept/Register.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/concept/Register.hlp &&
XRegistered macros are a means of creating a macro which
Xgets called when certain events internal to CRISP happen.
XThere are a number of pre-defined events:
X
X REG_TYPED
X REG_EDIT
X REG_ALT_H
X REG_UNASSIGNED
X REG_IDLE
X REG_EXIT
X REG_NEW
X REG_CTRLC
X REG_INVALID
X
XThese definitions are #define'd in the crisp.h macro file.
XThey are described below.
X
XAny macro can be registered for one of these events by
Xcalling the (register_macro) primitive. Whenever the event
Xis triggered the macro will be called. A macro can be
Xunregistered by calling the primitive (unregister_macro).
X
XAn arbitrary number of macros may be registered for the
Xsame event. If more than one macro is registered for the
Xsame event, then the macros are called in the order they
Xwere registered.
X
XRegistered macros are convenient short-hand ways of
Xintercepting certain operations within CRISP.
X
X> Type 0 (REG_TYPED) - Character Typed
X
XThis macro is called every time a character is inserted
Xinto a buffer via (self_insert).
X
X> Type 1 (REG_EDIT) - Different File Edited.
X
XThis macro is called whenever (edit_file) is called.
X
X> Type 2 (REG_ALT_H) - Context Help
X
XThis macro is called whenever the user presses <Alt-H>
Xwhilst at the command prompts.
X
X> Type 3 (REG_UNASSIGNED) - Unassigned key
X
XThis macro is called if the user presses a key which does
Xnot have a macro bound to it.
X
X> Type 4 (REG_IDLE) - Idle Timer
X
XThis macro is called whenever the idle timer goes off. The
Xidle timer is set by the CRISP command line switch (-i).
XIt defaults to 60 seconds.
X
X> Type 5 (REG_EXIT) - Exit from CRISP
X
XThis macro is called when CRISP is about to exit. It is
Xdesigned to allow macros to tidy up after themselves (e.g.
Xdelete temporary files).
X
X> Type 6 (REG_NEW) - New file Edited.
X
XThis macro is called whenever a new file is read into a
Xbuffer via (edit_file).
X
X> Type 7 (REG_CTRLC) - Interrupt Key Pressed
X
XThis macro is called whenever the interrupt key is
Xpressed. To avoid confusion, CRISP sets the interrupt key
X'out of the way' to <Ctrl-Y>. (<Ctrl-C> is usually mapped
Xto the center-line-in-window macro).
X
XThis feature allows macros to be interrupted. Following
Xthe usual safe programming style, it is only a good idea
Xto set a flag in the interrupt handler and test its value
Xin the main-line macro.
X
X> Type 8 (REG_INVALID) - Invalid Key Pressed.
X
XThis macro is called if the user types an invalid key at
Xthe command prompt. This macro allows the abbreviations
Xand command history feature to be implemented.
X
SHAR_EOF
chmod 0644 help/crisp/concept/Register.hlp || echo "restore of help/crisp/concept/Register.hlp fails"
mkdir help help/crisp help/crisp/concept >/dev/null 2>&1
echo "x - extracting help/crisp/concept/Proc.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/concept/Proc.hlp &&
XCRISP supports the ability to access sub-processes and
Xmonitor the output sent to and from the sub-process. This
Xallows you to run sub-shells, for example, from within a
Xbuffer in a similar fashion to a bit-mapped windowing
Xsystem, but only using the facilities of a character based
Xterminal.
X
XThere are a number of CRISP primitives which allow the
Xstatus of the sub-process to be monitored and altered, and
Xthe CRISP macros contain examples of the sorts of things
Xthat can be achieved with these primitives.
X
XThe processes are also referred to as pty's. This term (as
Xfar as I know) originates from the ancient TOPS-10
Xoperating system (circa late 60's). A PTY is like a normal
Xterminal, except there is no physical manifestation of the
Xterminal. Instead of input coming from a real user, the
Xinput comes from another program; output from the PTY can
Xbe read by the controlling program.
X
XIn CRISP, each buffer may optionally be associated with
Xone pty. This association is set up via the (connect) macro.
X
XPTYs in CRISP are controlled by CRISP itself. PTYs are
Ximplemented as sub-shells; the communications mechanism is
Xeither the standard Unix pipe, or the BSD pty driver (if
Xavailable). Data is sent to a sub-process by inserting the
Xdata in the buffer associated with the PTY.
X
XPTYs are very powerful mechanisms. A number of versions of
XUnix offer different mechanisms for accessing sub-jobs.
XOutput from the PTYs is done either by polling every
Xsecond, or by using the select() system call (if available)
X
XText can be sent to a PTY via the (insert_process)
Xprimitive. The shell.m macros implement a means for
Xtalking to pty's and echoing input typed by the user can
Xbe sent either a character at a time or a line at a time
Xto the process.
X
XWhen CRISP is waiting for keyboard input, it will check
Xthe sub-processes every second for output. It does not
Xcheck for input whilst other macros are running.
X
SHAR_EOF
chmod 0644 help/crisp/concept/Proc.hlp || echo "restore of help/crisp/concept/Proc.hlp fails"
mkdir help help/crisp help/crisp/env >/dev/null 2>&1
echo "x - extracting help/crisp/env/Env.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/env/Env.hlp &&
XCRISP uses various environment variables to control its
Xactions. These environment variables allow users to tailor
Xwhere they want to place certain parts of the CRISP
Xsupport environment, (eg help files and macros) or setup
Xdefault options.
X
XSome of these are used internally by the code itself (eg
XBFLAGS), others by the support macros, (eg BHELP).
X
XAll environment variables start with a 'B' for
Xcompatability with BRIEF.
X
X> BBACKUP
X
XThis is the name of a directory to contain backup files.
XThe directory should be writable by the user. CRISP
Xattempts to 'mv' the file to the backup directory. If the
X'mv' fails, e.g. backup directory is in a different file
Xsystem, the 'mv' fails, and CRISP renames the backup file
Xwith a '.bak' extension instead. The BBACKUP variable is a
Xsemi-colon delimited path of directories. CRISP tries to
Xmove the old file to each directory named. Thus, typically
Xthe super-user might create a /backup directory in each
Xfile-system, and setup BBACKUP to each such directory name.
X
XAlternatively, the user can create his own backup
Xdirectory (~/backup) and set BBACKUP to this value for a
Xprivate backup directory.
X
X> BFILE
X
XIf no file arguments are given on the command line, then
Xby default CRISP places the user in the buffer labelled
X'newfile'. Setting the BFILE environment variable allows
Xthe user to specify an alternate default file name.
X
X> BFLAGS
X
XThis environment variable can be used to augment the
Xdefault command line switches. CRISP processes the
Xswitches specified in BFLAGS after processing the flags on
Xthe command line.
X
XThe BFLAGS environment variable provides a simple way to
Xset up a private macro file to be invoked on start up. For
Xexample, setting BFLAGS to:
X
X BFLAGS="-i60 -mfox"
X
Xcauses the idle timer to be set to 60 seconds, and the
Xmacro file fox.cm to be executed. (fox.cm will be looked
Xfor in the default BPATH list or in the user's home
Xdirectory).
X
X> BHELP
X
XThis variable contains the path where the CRISP help files
Xare located. If it is not specified, CRISP uses the
Xinternal default:
X
X /usr/local/crisp/help
X
XSetting it to another value allows a site to put the help
Xfiles under a different path.
X
X> BKBD
X
XThis variable is used to define a macro file which is used
Xto define the labels which appear on your keyboard. CRISP
Xuses the PC keyboard names internally. This macro is only
Xrelevant to the 'Command Summary' option of the help menu
Xso that the keyboard keys are given meaningful labels to
Xyou. Currently there are two defined keyboard layouts -
X'pc' for generic PC keyboards and 'sun3' for a Sun type 3
Xkeyboard.
X
X> BLEVEL
X
XThis environment is set by CRISP when it is run, so that
Xnested invocations of CRISP can show to what level of
Xnesting has occurred. This is a hangover from the PC
Xversion of BRIEF which displays the level number in the
Xbottom right corner. This is done so that the user can
Xrealise he has nested invocations of CRISP.
X
X> BPACKAGES
X
XThis macro is reserved for use by the BRIEF/CRISP macro
Xlanguage sensitive editing modes. CRISP currently does not
Xsupport language sensitive editing (unless used with the
XBRIEF macros).
X
X> BPATH
X
XThis is similar to the standard PATH variable, and is used
Xby CRISP when it is trying to autoload a macro. The
Xdirectories should be separated by semi-colons, since some
Xmacros hardwire the parsing of the string. (This is in
Xcontrast to the PATH variable which is usually colon
Xdelimited).
X
X> BTERM
X
XBTERM is similar to the TERM environment variable, and is
Xused to access the special terminal description file which
XCRISP uses to define special escape sequences and function
Xkey bindings. If this environment variable is not set,
Xthen CRISP uses the value of TERM instead.
X
XWhen CRISP starts up, the macro file crisp.m causes the
Xfile tty/$BTERM.cm to be loaded as well. For example, if
XBTERM is set to 'sun', then the file tty/sun.cm gets
Xloaded. The tty/*.m files are responsible for configuring
XCRISP for the appropriate keyboard and screen layout.
X
X> BTMP and TMP
X
XCRISP creates files in a temporary directory. This is
Xusually /tmp. The files it creates here are for holding
Xthe undo buffer. (The file will not usually appear in
Xdirectory listings since the file is deleted as soon as it
Xis opened). If /tmp on your system is not very large and
Xyou wish to use an alternate directory, then you can
Xspecify this in the BTMP or TMP environment variables.
X
XCRISP looks in BTMP first; if this is not defined it tries
XTMP. If this isn't defined, it defaults to /tmp.
X
SHAR_EOF
chmod 0644 help/crisp/env/Env.hlp || echo "restore of help/crisp/env/Env.hlp fails"
mkdir help help/crisp help/crisp/env >/dev/null 2>&1
echo "x - extracting help/crisp/env/Tree.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/env/Tree.hlp &&
XThis section describes the layout of the files and
Xdirectories used by CRISP. This layout is the 'standard'
Xlayout. System administrators may opt for moving the top
Xlevel tree elsewhere in the file system, but the
Xsub-directories underneath should always be present.
X
X> The /usr/local/crisp Tree
X
XThis is the top level of the CRISP file hierarchy. The
Xfollowing sections describe the sub-directories located
Xwithin it.
X
X> The /usr/local/crisp/help Directory
X
XThis directory and all the sub-directories located within
Xit contain the help files used by the help macros. These
Xfiles are also used to form the CRISP reference manual.
X
X> The /usr/local/crisp/src Directory
X
XThis directory contains all the macros in source form (.m
Xand .h files) which come as part of the CRISP distribution.
X
X> The /usr/local/crisp/macros Directory
X
XThis directory is used to stored the compiled forms of the
Xmacros found in the /usr/local/crisp/src directory.
X
X> The /usr/local/crisp/utils Directory
X
XThis directory contains an odd assortment of files, some
Xof which derive from postings on the USENET.
X
Xkbd.c and keyboard.fox are my updated version of the
Xmapstr utility. This runs under 386/ix Unix V.3.2. and
Xcombines the features of the previous separate strings and
Xkeys file. You should compile this up and run it from your
X~/.login file if you are running under Unix V.3.2/386. It
Xhas not been tested with the latest versions of Xenix, but
Xit should work with them.
X
XThe file m286.malloc is a replacement for the malloc() code
Xlocated in /lib/libc.a for Microport 286 2.2 & 2.3
Xsystems, which is totally brain damaged. For users with
Xaccess to CRISP source code, this version of malloc should
Xbe used instead of the standard one. This file is not
Xreally relevant to other non-286 systems.
X
Xkeys.sv386 is a shell script for setting up some extended
Xkey definitions for Microport V.3/386 systems via the
X/etc/setkeys utility. It is used for things like
X<Ctrl-Left> and <Ctrl-Right> (the word-left and word-right
Xmacros).
X
Xstrings is a file which should defines the function key
Xmappings for Xenix 2.2.1 and later systems. This file is
Xused by the mapstr system utility. This file will need to
Xbe modified since the key definitions are defined using
Xthe \x escape convention, which mapstr does not
Xunderstand. keys is the keyboard mapping for Xenix. It
Xredefines things like the ALT-x keys so that they generate
Xkey sequences in agreement with the strings file.
X
XThe termcap file included in this directory is there for
Xpeople who have problems in that their system does not
Xprovide a termcap file (IBM 6150s) or their termcap file
Xappears to be 'wrong' when trying to use CRISP.
X
SHAR_EOF
chmod 0644 help/crisp/env/Tree.hlp || echo "restore of help/crisp/env/Tree.hlp fails"
mkdir help help/crisp help/crisp/env >/dev/null 2>&1
echo "x - extracting help/crisp/env/Switches.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/env/Switches.hlp &&
X> Command Line Switches
X
XCRISP has a number of command line switches for setting
Xvarious options when starting up. The CRISP usage string is:
X
X cr [-4bdfpstwE] [-i n] [-e n] [-K n] [-m macro] [+nn] file ..
X
XThe switches are described below. An arbitrary number of
Xfile names may be specified on the command line. Each file
Xmentioned is read into a separate buffer. The cursor is
Xleft in the buffer associated with the first file.
X
XSpaces are not necessary between switches and their
Xarguments. This is contrary to the standard AT&T practice
X(as specified by getopt(3)). This is done to preserve
Xcompatibility with the BRIEF software. This is also useful
Xfor arguments defined in the BFLAGS environment variable.
X
X> The -b switch
X
XThis switch controls the creation of backup files. If
Xspecified, CRISP will not create backup files.
X
X> The -d and -f switches
X
XThe -d switch is equivalent to executing the (debug) macro
Xbefore any of the standard macros are read in. This is
Xprovided so that it is possible to debug macros which
Xcause CRISP to crash on start up.
X
XThe -f switches is used to control flushing of the debug
Xlog file. Normally CRISP uses the stdio package to write
Xto the crisp.log file. If this switch is specified, then
Xevery call to trace something is immediately written to
Xdisk. This switch is provided because if a macro causes
XCRISP to crash, then the last partial buffer of output may
Xbe lost. The -f switch significantly slows CRISP down on
Xlarge debug traces.
X
X> The -i switch
X
XThis switch allows the user to change the default idle
Xtimer. The idle timer is used to allow registered macros
Xto be called after a certain amount of keyboard inactivity.
X
XThe argument specifies the number of seconds of keyboard
Xactivity. The default is 60 seconds.
X
X> The -m switch
X
XThis switch specifies a macro or macro file to execute on
Xstartup. The macro name may or may not be separated from
Xthe '-m' by a space. (For compatability with BRIEF). If
Xthe macro name is an internal primitive then that is
Xexecuted; otherwise CRISP looks for a macro file with the
Xname specified and executes the macro in that file with
Xthe same name.
X
XThe macro file can be placed in the users home directory.
X
X> The -w switch
X
XThis switch controls the (read_char) macro. Under DOS
Xrunning BRIEF, the (read_char) macro is used to poll the
Xkeyboard and returns -1 if there is no input pending. Some
Xmacros use the (read_char) primitive in a busy poll loop
Xwaiting for character input. This is an antisocial thing
Xto do under Unix, as it steals the CPU from other processes.
X
XBy default CRISP does not allow (read_char) to return -1,
Xbut instead will block until a character is available.
XThis may affect some macros which rely on this feature.
XRunning CRISP with -w makes (read_char) run compatibly
Xwith BRIEF.
X
XThis switch is antiquated and should be removed - it would
Xbe better to control this feature via an argument to
X(read_char).
X
X> The -e switch
X
XThis switch is similar to the (echo_line) macro primitive.
XIt is used to set the flags controlling the appearance of
Xthe echo status line (eg whether the Line:, Col:, etc
Xfields should be there).
X
XThe argument is the same argument as passed to
X(echo_line). Refer to this macro for further details.
X
X> The -K switch
X
XThis switch controls the size of the internal keyboard
Xmacro buffer. The default size is 512 characters.
X
XThis switch should not really exist - CRISP should
Xdynamically allocate space for the buffer.
X
X> The -t switch
X
XThis switch is similar to the (use_tab_char) macro. If
Xspecified, then CRISP will use soft tabs (inserts spaces
Xinstead of tabs); if omitted, then the default of using
Xhard tabs in buffers is in effect.
X
X> The +nn switch
X
XIf an argument of '+nn' is given (where nn is a line
Xnumber) then CRISP places the cursor on line nn in the
Xfirst file specified. This is provided for compatibility
Xwith vi.
X
X> The -4 switch
X
XThis switch is available only to users running on the
Xconsole of Xenix 386 rel 2.2, or Unix V.3.2. It is used to
Xput the screen into 43 line mode (available for EGA or VGA
Xscreens only).
X
XOn those systems which support 43-line EGA mode, CRISP
Xwill honor the current video mode setting. E.g., starting
XCRISP up in 43-line mode will cause it to use all 43 lines
Xwithout switching to 25-line mode.
X
X> The -E switch
X
XBy default, on startup, CRISP does not enable the display
X(ie no output appears). This is done so that the start-up
Xmacros can work out what screen display is in effect.
XTurning this switch on causes CRISP to use the internal
Xdisplay characters.
X
XThis switch is not recommended.
X
X> The -p switch
X
XThis switch can be used to turn on CRISP profiling
Xactivity. It is only useful to people with source code
Xaccess to CRISP for fine tuning of the code. If it is
Xspecified and CRISP has been compiled with the cc -p
Xoption, then CRISP will produce a mon.out output file.
X(See the (profile) macro).
X
X> The -s switch
X
XThis switch is used to print out some internal statistics
Xabout the execution of CRISP upon exit.
X
X
SHAR_EOF
chmod 0644 help/crisp/env/Switches.hlp || echo "restore of help/crisp/env/Switches.hlp fails"
mkdir help help/crisp help/crisp/env >/dev/null 2>&1
echo "x - extracting help/crisp/env/Startup.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/env/Startup.hlp &&
XThis section describes the sequence of events when
Xstarting up CRISP. It is provided for you to understand
Xthe interaction of the different start up macros in the
Xmacros directory.
X
XWhen CRISP starts up, it firstly initialises all its
Xinternal data structures. It then parses the command line
Xand remembers the names of all the macro's specified in
Xthe -m switches.
X
XIt then autoload's the macro (crisp). Since no autoload
Xdefinition is given for this macro, it looks to see if it
Xcan find a crisp.cm or crisp.m in its BPATH directory
Xlist. It normally resolves this into
X/usr/local/crisp/macros/crisp.cm. The CRISP macro is
Xresponsible for setting up the terminal and display
Xconfigurations (via the tty/*.m) files, and setting up the
Xautoload definitions for all the other macros provided
Xwith CRISP. Normally, users or system administrators will
Xnot modify this macro.
X
XThe CRISP macro is responsible for enabling the display
X(see (display_enable)). The display is not enabled until
XCRISP has worked out which terminal the user is using.
X(See the BTERM environment variable).
X
XIt then does the same thing for a macro called (startup).
XThe (startup) macro is provided for compatability with
XBRIEF. The startup macro is designed to allow system
Xadministrators to specify system defaults for certain
Xmacros, eg whether indentation is on, color of windows etc.
X
XCRISP then executes each macro specified by the -m
Xswitches, in the order specified. This allows the user to
Xset up an alias for CRISP, eg:
X
X alias cr cr -mmy_name
X
Xwhich will cause CRISP to execute a users personal macro
Xafter all the system defaults. If CRISP cannot find the
Xnamed macro, then the users home directory will be searched.
X
XAfter all of this, the files specified in the command line
Xare read in.
X
SHAR_EOF
chmod 0644 help/crisp/env/Startup.hlp || echo "restore of help/crisp/env/Startup.hlp fails"
mkdir help help/crisp help/crisp/env >/dev/null 2>&1
echo "x - extracting help/crisp/env/Kbd.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/env/Kbd.hlp &&
X
XThis section describes how a keyboard mapping may be set
Xup so that physical keys on your keyboard will call the
Xmacros you define them to.
X
X> Top-down Design
X
XThis section describes how the keyboard parsing works
Xwithin CRISP from a top down point of view, ie from the
Xpoint you hit a key, until a macro gets called.
X
XWhen a key is hit on the keyboard it will usually be a key
Xwith a label on it, e.g. a normal 'qwerty' key, or maybe a
Xfunction key. Different keyboards have different layouts,
Xand this is especially true of the markings on the
Xso-called function keys.
X
XWhen a key is hit, it will normally send either a single
Xcharacter to the host computer or a sequence of characters
Xif it is a function key. All function keys on a keyboard
Xnormally share a set of prefix characters, so that
Xkeyboard drivers in the operating system and applications
Xsoftware can determine which key is hit.
X
XSingle character keys usually send a value corrsponding to
Xthe ASCII value of the key.
X
XCRISP reads characters from the keyboard one character at
Xa time. If the character read from the keyboard
Xunambiguously defines a key, then CRISP goes onto the next
Xstep. Otherwise, it has to wait for one or more following
Xcharacters to decipher the keystroke. For example, if the
X<F1> key on your keyboard generates the sequence:
X<ESC>[1F, and the <F2> key generates the sequence
X<ESC>[2F, then CRISP cannot tell from the initial <ESC>
Xcharacter whether the <F1> or <F2> key has been hit.
XInstead of processing the <ESC> key directly it saves it
Xin a buffer waiting for subsequent keys to resolve the
Xambiguity. On seeing the '[' character next, it still
Xcannot identify the key. The next character will
Xunambiguously allow CRISP to determine that either <F1> or
X<F2> was pressed. However CRISP will continue reading
Xcharacters from the keyboard until it has not only
Xdetermined a unique key symbol but also has read all the
Xcharacters defining a key-stroke. Thus in this example, it
Xwill read the characters up to the 'F' character.
X
XOne added complication to the above description is what
Xhappens if the user hits the key labelled 'Esc' on the
Xkeyboard. In this case, CRISP cannot determine whether the
X<Esc> value generated is due to the ESC key being hit or
Xas a prefix to one of the function keys. In order to
Xresolve this ambiguity, CRISP will wait 0.5 of a second
Xfor subsequent keystrokes before continuing. For example,
Xif you hit the <Esc> key followed by no other keys, then
XCRISP will delay processing the <Esc> key for 0.5 of a
Xsecond. If you type any other character within 0.5 of a
Xsecond, for example the 'x' key, and CRISP can determine
Xthat '<Esc>x' is not part of a function key definition,
Xthen it will process the <Esc> key separately and then go
Xonto processing the 'x' key.
X
XHaving read in an unambiguous key-stroke, CRISP converts
Xthis to an internal representation. Essentially keystrokes
Xin CRISP are mapped into 8-bit numbers. The internal
Xencodings for characters 0..127 usually, but not
Xnecessarily, correspond to the 7-bit version of ASCII
X(printable characters plus control characters).
X
XNOTE: CRISP has no particular understanding of ASCII. It
Xis possible to input 8-bit characters, and have them
Xinserted directly into the current buffer, etc, but by
Xdefault the characters in the range 128..255 are mapped to
Xvarious macros. It is intended that maybe in a future
Xrelease CRISP will use 16-bit keycodes, but at present it
Xdoes not do so. It is not difficult to amend the code to
Xdo so (I think it should just be a matter of changing a
X#define and a few hardcoded constants in the code).
X
XThe 8-bit key code is used to directly index into a
Xkeyboard map table (refer to the (keyboard_push),
X(keyboard_pop) macros). A keyboard map is essentially an
Xarray of 256 elements, each element pointing to the name
Xof a macro or a list of commands to execute when the key
Xis executed.
X
XThus from here, we have a very simple 'inner' loop of the
XCRISP code - read character/function-key, lookup entry in
Xkeyboard map, execute macro assigned to keystroke.
X
X> Attributes of a Keyboard Description
X
XThere are two main aspects of a keyboard description which
Xcause problems when moving from one type of keyboard to
Xanother. Firstly, CRISP must be told what function keys
Xgenerate which key-sequences, so it can parse them
Xcorrectly and thus map each keystroke into its internal
X8-bit form.
X
XSecondly, the macros which CRISP is provided with assume
Xan IBM/PC style of keyboard.
X
XThe second problem aggrevates the first. Some of the
Xinternal code of CRISP 'just knows' that you have a key
Xcalled <F1> on your keyboard. Unfortunately, you may not
Xactually have such a key, and thus any C code or macro
Xcode which makes reference to the <F1> key will not work
Xon a keyboard which doesn't actually have an <F1> key.
X
XThere are three main pieces of code in CRISP which 'knows'
Xabout your keyboard. In the file config.c there is a set
Xof initial keyboard macro bindings which are used when
XCRISP starts up, and these tend to get overridden by the
Xcrisp.m macro file. These bindings are mainly there so
Xthat CRISP can be run in a very naive mode when debugging
Xnew startup code, or whilst setting up new macro
Xdefinitions.
X
XThe other two areas of code is the code which maps
Xkey-strings to the internal 8-bit character format (refer
Xto (assign_to_key), (key_to_int) and (int_to_key)). E.g.
Xthere is code in CRISP which 'knows' how to convert the
Xstring "<F1>" to the magic number 128.
X
XThe macros themselves refer to key labels with respect to
Xmy PC/AT keyboard. This is partly due to the desire to
Xmaintain compatability with the original BRIEF editor, but
Xalso it served as a starting point in getting CRISP up and
Xrunning.
X
XWhere things get complicated is when you look at something
Xlike the (buffer_list) macro, or the Command line prompt.
XThe (buffer_list) macro remaps the keyboard so that for
Xexample, when you press the <Down> key, the current
Xhilited line will be unhilited and the line below it (if
Xthere is one) will be hilited. When the <Enter> key is
Xpressed, the buffer currently hilited will be selected.
XThe (buffer_list) macro manipulates 'virtual keys' or
X'symbolic keys'. Ie these are not actually hardcoded
Xvalues, but names which are mapped internally by the
Xinternals of CRISP.
X
XWhen you press the <Down> key, the CRISP keyboard driver
Xconverts this into an internal value, and executes the
Xmacro assigned to this key-sequence.
X
XYou - as a porter of CRISP to your system - will have set
Xup a set of keyboard bindings, via the the tty/*.m files
Xusing the (set_term_characters), (set_term_features) and
X(set_term_keyboard) macros.
X
XWhat you have to do is ensure that if your keyboard has a
Xkey labelled, for example <Undo> that CRISP is told what
Xthe character sequence which makes up this keystroke is
Xdefined (via the (set_term_characters) macro).
X
XThe big problem a number of prospective porters face is
Xthat there may not be a one-to-one correspondence between
Xthe keys which are available on a PC/AT keyboard, and the
Xkeys on your keyboard. Eg, a VT-100 keyboard has a very
Xdifferent and less functional layout compared to a PC
Xkeyboard.
X
XThus, the first step is to make a list of function keys on
Xyour keyboard and find out how they map to the keys
Xavailable inside of CRISP. Eg you may decide that the key
Xlabelled <L1> on your Sun keyboard is to have the same
Xfunctionality as the <F1> key on the AT keyboard, or
X<LEFT-A> is to be the same as <ALT-A> on a PC keyboard.
X
XOnce you have set up your terminal description file, we
Xare nearly ready to go.
X
X> Getting Things Wrong
X
XThere is a deficiency in the way CRISP does things at the
Xmoment, and that is the way in which CRISP is very
Xfamiliar with the PC/AT keyboard, and you, the porter,
Xhave to do a fair amount of work to get your keyboard
Xlayout correct.
X
XIf you get your keyboard layout wrong, then you may
Xexperience problems. There are two major problems - not
Xdefining a key, and defining a key with the wrong internal
Xmagic number.
X
XLets say you dont define an <F1> key. Things aren't too
Xbad, but any macro which binds the <F1> key to a macro
Xwill not be accessible. <F1> isn't too harsh, but consider
Xwhat will happen if you dont bind the <Down-Arrow> key. In
Xthis case you will not be able to scroll down pop-up menus
Xor move the cursor down within the text buffer. Thus at a
Xbare minimum you should set up definitions for things like
X<Right-Arrow>, <Left-Arrow>, <Up>, <Down>.
X
XThe other thing to get wrong, is to bind your
X<Right-Arrow> key to the wrong internal magic number. In
Xthis case the messages displayed by the macros will be
Xvery misleading.
X
XFor example, suppose you map <Up> to the internal value
Xrepresented by the <F1> key. In this case, whenever you
Xpress the <Up> key, CRISP will think you pressed the <F1>
Xkey. If you've bound the <F1> key (via (assign_to_key)) to
Xthe macro primitive (up), then you wont experience any
Xproblems. But now lets suppose you call up one of the
Xpop-up menus, eg (buffer_list) again. The (buffer_list)
Xmacro creates a new keyboard mapping, and sets up bindings
Xfor <Up>, <Down>, etc, but NOT <F1>. Thus when you select
Xthe (buffer_list) macro, you will not be able to move the
Xcursor upwards because the buffer list macro does not
Xassign anything to the <F1> key.
X
XThe moral of this story is - please do not get your
Xmappings wrong - and also - I must make things easier. I
Xdo try, but obviously things are not as easy as they
Xcould/should be.
X
X> The BKBD Environment Variable
X
XThe BKBD environment variable is a mechanism for fixing
Xone half of the problems in the keyboard driver. The
Xproblem it fixes is allowing macros to generate messages
Xwhich are keyboard independent. For example, the (grep)
Xmacro prints a message saying that you can use the <ALT-E>
Xkey to edit the output from the GREP command. It is pretty
Xpointless saying 'Use the <ALT-H> key for help' if you
Xhave no <ALT-H> key on your keyboard.
X
XYour bindings may be different to mine. The BKBD
Xenvironment variables provides a means in which on a Sun
Xkeyboard, for example, you will get a message saying
Xsomething like '<LEFT-H> for help' instead of '<ALT-H> for
Xhelp'.
X
XAs has been described before, the BTERM environment
Xvariable is used to form part of the name of a macro (the
Xtty/*.m) macros so that terminal specific features of a
Xscreen maybe defined. The BKBD variable allows the
Xdescription of a terminal to be split into the display
Xpart (BTERM) and the keyboard part (BKBD). The BTERM
Xenivironment variable causes a macro file tty/$BTERM.m to
Xbe loaded. The BKBD variable causes a macro file
Xkbd/$BKBD.m to be loaded.
X
XThe kbd/*.m files simply defining a global list containing
Xthe key-top labels for all the function keys on your
Xsystem. Currently there are keyboard definitions for PC/AT
Xtype keyboards and for a Sun keyboard/type 3.
X
XIt is not as important to get this file correct as it is
Xto get the tty/*.m files correct. Getting a keyboard
Xdescription file wrong will only cause message labels on
Xpop-up windows to refer to the wrong key.
X
X> Future Possibilities
X
XI may move the keyboard mapping features of the
X(set_term_characters) macro out of the tty/*.m files into
Xthe kbd/*.m files.
X
XI may also add a feature which allows you to override the
Xinternal magic numbers in CRISP so that you dont need to
Xmap your keyboard keys to PC/AT type keytops.
X
XIn general, if you make make any changes to CRISP to
Xsupport your keyboard/screen, then I will be happy to
Xaccept them into my standard release. This means that
Xwhen/if I change the organisation of the keyboard binding
Xcode, you wont have to make the same edits that I have to.
X
XI am always open to suggestions and
Xperformance/ease-of-use improvements to make all our lives
Xeasier.
X
X
SHAR_EOF
chmod 0666 help/crisp/env/Kbd.hlp || echo "restore of help/crisp/env/Kbd.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Compile.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Compile.hlp &&
XCRISP contains a number of macros to help simplify the
Xtask of building software.
X
XCurrently, two macros are defined - (make) and (lint).
XThese are both accessible from the <F10> Command: prompt.
X
X> The (make) Macro
X
XThe make macro is designed to get over the problem of
Xissuing a make command to a shell prompt, only to have any
Xerror messages get scrolled off the screen. The usual
Xsolution to this is to redirect the output of make to a
Xfile. However, Murphy usually strikes and the one time you
Xforget to redirect output is the one time when you have a
Xmillion and one errors.
X
XThe make macro not only captures the output of a make
Xcommand but also is designed to understand the error
Xmessages coming from the standard Unix C compiler. (Other
XC compilers can be catered for by modifying the make macro
Xto understand the syntax of the error messages).
X
XThe simplest way to invoke make, is to simply hit <F10>
Xand type 'make<CR>'. The make macro pops up a window which
Xcontains the output from the running make. Note that
Xwhilst this is happening it is not possible to use CRISP.
XIf any keys are struck whilst the make window is on the
Xscreen, then CRISP closes the pop up window, and continues
Xwhere it left off. This is a bug which at the moment has
Xnot been fixed. The reason this bug exists is that I am
Xdebating about providing a user interface for supporting
Xpop-up windows in an Xwindows style of window manager.
XCurrently the user interface is designed around tiling,
Xwhich is insufficient for macros which take a long time,
Xlike (make). If a key is accidentally hit, the compilation
Xcontinues in the process buffer allocated for the make. In
Xthis case the thing to do is to switch to the buffer named
X'Compilation-Buffer' (eg try <Alt-B>). Then the progress
Xof the make can still be viewed.
X
XWhen the make finishes (ie the sub-shell terminates),
XCRISP will search the log buffer to see if there are any
Xerror or warning messages from the compiler. If so, the
Xmake macro will put the cursor on the line of the first
Xerror in the appropriate file. The actual error which
Xappeared in the log file will appear on the status line
X(slightly trimmed to make it fit).
X
XThe make macro cannot cope with syntax errors in files
Xwhich do not appear in the current directory. This is a
Xlimitation due to the syntax of the error messages
Xgenerated by the C compiler.
X
XAfter the make macro has finished execution, it reassigns
Xthe macro for the <Ctrl-P> and <Ctrl-N> keys. Typing
X<Ctrl-N> will take you to the next line which has an
Xerror; <Ctrl-P> will take you to the previous error. When
Xthe last error has been displayed, the message 'No more
Xerrors.' will be displayed on the status line. Pressing
X<Ctrl-P> or <Ctrl-N> again will continue to loop through
Xthe errors.
X
XIf the make completes successfully, then the message 'Make
Xcompleted successfully.' will appear in the status line.
X
XThe make macro understands about making different targets
Xin the make file. To make a target different to the
Xdefault, type the target name after the 'make' command.
XFor example, to compile and install the software might be
Xachieved by typing:
X
X <F10> make install<CR>
X
X> The (lint) Macro
X
XThe lint macro is similar to the (make) macro described
Xabove. It calls the make macro with an argument of lint.
X(ie (make lint)). Thus, it expects there to be a makefile
Xin the current directory with a target of lint within it.
X
XThe lint macro is provided to overcome the problems of
Xgetting reams of output from lint, and having to
Xcontinually flick backwards and forwards between the
Xoutput from lint and the source files with portability
Xproblems.
X
XThe (lint) macro firstly performs a 'make lint' in the
Xmake compilation window, and then masturbates the output
Xfrom lint so that each line of output from lint looks like
Xa warning/error message from the compiler. Once the lint
Xmacro has finished, the user can scan through the errors
Xvia <Ctrl-N> and <Ctrl-P>. (See above for details).
X
SHAR_EOF
chmod 0644 help/crisp/features/Compile.hlp || echo "restore of help/crisp/features/Compile.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Filename.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Filename.hlp &&
X> The (display_file_name) Macro
X
XThis macro is a utility macro to display the current file
Xname on the status line. When editing a buffer, it is
Xsometimes difficult to distinguish between two buffers if
Xthey contain files with the same filename but different
Xpath names. Since the title of a window is the file-name
Xpart of the full path, it helps to have a command
Xavailable to display the full unambiguous name.
X
XThe (display_file_name) macro is selectable from the
Xfeatures menu (The 'Current Filename' option).
X
XIf the filename is too long to fit on the status line,
Xthen the filename is truncated at the right and three dots
X'...' are inserted to show that the filename has been
Xtruncated.
X
SHAR_EOF
chmod 0644 help/crisp/features/Filename.hlp || echo "restore of help/crisp/features/Filename.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Grep.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Grep.hlp &&
X> The (grep) Macro
X
XThis macro is used to overcome the usual problems of grep
Xdisplaying more than a screen full of output, and
Xforgetting to use 'more' or 'pg' to capture the output. In
Xaddition the grep macro allows the user to visit each file
Xwhich contains the pattern selected.
X
XThe format of the grep macro is:
X
X (grep "pattern" "filename(s)")
X
XGrep is normally called directly from the keyboard (either
Xusing the selection from the Features menu, or by typing
X'grep' at the Command: prompt).
X
XIf (grep) is called without any parameters, then it
Xprompts for the pattern and filenames. Filenames can be
Xwildcarded (they are passed to the shell for processing).
X
XWhilst grep is operating it prints the message:
X
X Locating text...
X
XWhen the grep process has finished, a pop-up window is
Xdisplayed on the screen containing the output from the
Xgrep command. The user can move around this buffer with
Xthe usual cursor movement keys. The current entry is
Xhighlited. Pressing <Enter> on any particular line will
Xcause the grep macro to edit the file in which that line
Xoccurs and go directly to the line selected.
X
XThe grep macro also re-maps the <Ctrl-N> and <Ctrl-P>
Xkeys. Pressing <Ctrl-N> will take you to the next
Xfile/line in the output from grep. <Ctrl-P> takes you to
Xthe previous line. Thus, repeated use of <Ctrl-N> allows
Xthe user to easily see the context (lines around the
Xmatching pattern) within each file.
X
XThe (grep) macro also supports a 'Change-Mode'. In this
Xmode, the user can modify the lines in the grep pop up
Xwindow, eg to make global substitutions, and by hitting
Xthe <Esc> key, all the changes can be made to the
Xdifferent files in one go. This is useful for example, in
Xorder to make a change to a variable name across all
Xsource files.
X
SHAR_EOF
chmod 0644 help/crisp/features/Grep.hlp || echo "restore of help/crisp/features/Grep.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Options.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Options.hlp &&
XThe options menu allows the user to temporarily change
Xvarious modes and flags in CRISP during the course of the
Xcurrent editing session. Permanent changes can be placed
Xin one of the CRISP start-up macros.
X
XThese options are collected together in one menu, since it
Xis usually difficult to remember the particular macro name
Xor options to these macros. These options tend to get
Xchanged when the user has to perform a task which is out
Xof the ordinary. For example, a programmer will normally
Xhave his keyboard layout set up for easy manipulation of
Xprograms, but occasionally (yes I know its difficult) will
Xhave to produce a memo or write some documentation.
X
XBecause writing documentation is something which may not
Xbe performed often, the user may forget which macros and
Xoptions are available to him/her. Therefore the options
Xmenu is designed to have all those easy to forget features
Xto hand.
X
XThe options menu currently has the following selections:
X
X Autoindenting
X Documents
X Status Line
X Searching
X Tabs
X
X> Autoindenting
X
XCRISP provides a macro for performing auto-indenting.
XAuto-indenting comes into operation when the user hits the
X<Enter> key.
X
XThe auto-indent macro works by going to the beginning of
Xthe current line to find out in which column the current
Xline starts. It then moves the cursor to the next line
Xwith the cursor underneath the first white space character
Xin the line above.
X
XThe auto-indenting macro understands about whether you
Xhave selected hard or soft tabs. This is necessary, since
Xif you need to un-indent on a successive line, you will
Xpress the <Backspace> key. Therefore to allow <Backspace>
Xto operate properly, the auto-indent macro inserts enough
Xspaces or tabs to take the cursor to the same column as
Xthe first non-space character in the previous line.
X
XAuto indenting is implemented via the (autoindent) macro
Xwhich is automatically called from the Options menu. When
Xthe autoindent option is selected, the macro asks whether
Xyou want autoindenting on or off:
X
X Turn autoindent on (y/n) ?
X
XIf you specify 'y', then autoindenting is turned on. If
Xyou specify any other response then autoindenting is
Xturned off. If you wish to abort the selection, just type
X<Esc>.
X
X> The Documents Option
X
XThe documents option collects together some of the
Xpreferred options for editing text files. There are three
Xoptions available at present - the setting of the right
Xhand margin where word wrap is to appear, whether text is
Xto be filled to have an even right hand margin or whether
Xthe margins are to be left ragged, and auto word-wrap.
X
XThere are two ways to do word-processing like
Xjustification of input text - autowrap and manual
Xreformatting. Autowrap causes the cursor to wrap around to
Xthe next line when the right hand margin is reached.
XAutowrap is a very CPU intensive activity. Manual
Xreformatting occurs by selecting a paragraph or a group of
Xparagraphs highlited with <Alt-A>, <Alt-M> or <Alt-L>).
XOnce the region has been highlited, the area can be
Xreformatted with the <Ctrl-F> key or from the 'Region
XManipulation' option in the Features menu. (See section on
XRegion Manipulation in the Features section).
X
X> The Status Line Option
X
XThis option lets the user turn on and off various fields
Xon the status line. This macro is simply an interface to
Xthe (echo_line) macro primitive which actually controls
Xthe appearance of the status fields.
X
XThere are four fields on the status line which may be
Xturned on and off:
X
X The Line: field
X The Col: field
X The percentage field
X The time field
X
XBy default, CRISP displays the line, column and time fields.
X
XThe Line: field is used to display the current line number
Xin the file.
X
XThe Col: field displays the current column position.
X
XThe percentage field displays how far through the file you
Xare as a percentage. If you are on the first line of a
Xbuffer, then this is displayed as 0%; the last line of the
Xbuffer displays as 'END'.
X
XIt is useful to display the line and column number, but
Xsome people may prefer to turn these options off.
X
XOn slow terminals, it is useful to avoid displaying all
Xfields, as they cause a lot of cursor movement.
X
X> The Searching Option
X
XThe searching option controls three parameters when
Xsearching:
X
X regular expressions
X case sensitivity
X block searching
X regular expression syntax mode
X
XThe regular expressions option control whether strings
Xentered at the search prompts should be treated as regular
Xexpressions or whether they should be treated as literal
Xstring patterns.
X
XCase sensitivity controls whether alphabetic characters
Xshould be compared as equivalent if they only differ in
Xtheir case, ie whether 'A' should match 'a'.
X
XBlock searching controls what happens when a search is
Xrequested and the current buffer is highlited. If this
Xoption is turned off then the search is performed as if
Xthe buffer was not highlited. If this option is on then
Xthe search starts from the beginning of the currently
Xselected region and continues until a pattern is found or
Xthe end of the region is reached.
X
XRegular expression syntax mode indicates whether regular
SHAR_EOF
echo "End of part 2"
echo "File help/crisp/features/Options.hlp is continued in part 3"
echo "3" > s2_seq_.tmp
exit 0
--
===================== Reuters Ltd PLC,
Tel: +44 628 891313 x. 212 Westthorpe House,
UUCP: fox%marlow.uucp@idec.stc.co.uk Little Marlow,
Bucks, England SL7 3RQ