Draft only - not yet for public distribution.



                   The CHEF Installer's Guide

                            J.E.L.Peck
                  University of British Columbia
                               and
                           M.A.Maclean
                     Univeristy of Canterbury


     This  paper  gives  directions  for  the installation of the
CHristchurch Edit Facility.    Presumably  you  will  now  be  in
possession  of a magnetic tape or other vehicle which conveys the
source code for the editor.  The files are labelled EF0,...,EF18,
the content of these files being as follows:

         EF0             The CHEF header
         EF1,...,EF10    BCPL Source code for CHEF
         EF11a,e         The CHEF message files  (ASCII,EBCDIC)
         EF12            A directory creator (BCPL source)
         EF13            "The Construction of a portable editor"
         EF14            "The CHEF edit facility"
         EF15            "CHEF - a versatile portable text editor"
         EF16            This document
         EF17            Program to generate EF10 bitmap
         EF18            "A programmer's word processor"

     The  files  EF13  to  EF16  are documents concerning CHEF as
follows: EF14 is the user's Manual, EF15 is a discussion  of  the
design   philosophy  of  CHEF,  EF13  is  a  description  of  the
implementation details of  the  CHEF  work-space,  EF16  is  this
Installer's  Guide  and  EF17  describes  wordprocessing in CHEF.
Perusal of these documents before you begin is recommended.

The BCPL compiler

     In order to install CHEF you will need a BCPL  compiler  for
your  system.   The  distributors  of  CHEF  are  not  yet in the
business of distributing the compiler also.  The  source  assumes
that your BCPL compiler has the following enhancements

         a) byte subscripting,
         b) conditional compilation.

If it does not support  these  facilities,  then  don't  give  up
immediately, for all is not lost.

     The byte subscripting  facility  is  a  convenient  mode  of
expression which  can  be written otherwise in standard BCPL.  If
your compiler does not possess byte subscripting, then  you  will
need  to take some editor and change all occurences of 'x := a%b'
to 'x := getbyte(a,b)' and all  occurrences  of  'a%b  :=  x'  to
putbyte(a, b,  x).   In combination, this means that 'a%b := c%d'
must be changed to 'putbyte(a, b, getbyte(c, d))'.

     Conditional    compilation   allows   the   code   for   all
implementations on all systems to reside in the same source file.
In BCPL this means that any condition 'c' (e.g., IF c THEN,  TEST
c  THEN,  c  ->  a,b)  will  be  examined  to see whether it is a
constant.  If this is the case then the code for  the  part  that
will never be visited is not emitted.  If your BCPL compiler does
not have conditional compilation, you need not despair, for again
some  editorial  changes  to the source will come to your rescue.
You may wish to proceed  directly  anyway  to  get  CHEF  running
possibly  with redundant code.  An alternative is to look closely
at EF10 and to excise those parts which are not needed.

The source code

     A  short  description  of  the content of each of the source
files follows.

  EF0: This  is  the header file.  It contains the declarations
  of manifest constants which are used throughout all  sections
  and the  declaration  of globals.  Each of the other sections
  EF1,...,E10 contain a GET directive for this file.  Check the
  first few lines of each of the files EF1 to EF10 to make sure
  that the name of the file EF0 is  correct  for  your  system.
  You  may  have inherited a source in which this name has been
  modified to suit a particular system.

  EF1: contains the routine 'start'  in  addition  to  routines
  that handle warning and error messages.

  EF2: is involved with lexical analysis of commands.

  EF3: is concerned with the syntactic analysis of a command.

  EF4: deals with the interpretation of a command.

  EF5: has delicate pattern matching and scanning procedures.

  EF6: is  the  work space manager.  This section is autonomous
  in the sense that, if the implementation of the work-space is
  changed, then changes need be made only in this section.

  EF7: is concerned with the system independent part  of  input
  and output to files or devices.

  EF8: is  entirely  devoted to the code necessary for the undo
  command, the U operator.

  EF9: is concerned with text justification, or the J operator.

  EF10: is the system interface section, and the one  on  which
  you will need to devote most of your attention.

     In  general,  the  procedures  in each section are listed in
alphabetical order, except for  a  start-up  procedure  which  is
given  first.   Section  EF10  is organized a little differently.
Here the procedures are grouped according to their  purpose,  but
within each group are again listed alphabetically.

File philosophy

     Before installing CHEF for the first time, it is appropriate
to  consider  the various file philosophies of operating systems.
Unfortunately this is an area of great disparity.  Some  systems,
for example, have files both with fixed and variable line length.
Conversion  from  one  to the other must then be done by a system
utility routine.  In such a system CHEF should be implemented  to
handle  those  files  which  are  most useful to programmers.  If
these are fixed line length files, then it should be  CHEFs  duty
(or  the  duty  of the BCPL interface) to convert them to its own
internal (variable) format and to reconvert them when writing the
files out again.

     Another problem is that CHEF requires  random  access  files
for its own use.  Here again some systems may set the position in
a  file  by byte number or by word number or by record (or block)
number or by line  number.   In  this  connection,  there  is  an
important  constant  in  EF0,  'line_files',  which  is  true for
systems (e.g., MTS) where random access files  are  set  by  line
number.   It is also possible that in one system one can specify,
say a record number, at the time of reading or  writing,  whereas
in  another  system  this may not be possible, so that a separate
call to set a position is necessary.  All these differences  lead
to complications in EF10.

The critical system constant

      If  we  examine  the  first  few  lines  of EF0 we find the
definition of a manifest constant 'computer'  (around  line  20).
You  may,  for  example,  have inherited the source code in which
that line is

                   computer = mts.sys

If this is the case, and your system is the MTS operating system,
then perhaps you are lucky, for you will not need to  change  it.
If  not,  then  search  the  lines above for the operating system
which might be yours (e.g., 'unix.sys') and change the right hand
side of that declaration to, for example,

                   computer = unix.sys                         .

This  change  will  then  direct conditional compilation for your
system.  If you have an operating system which is not  recognized
as  one  of  those on which CHEF is already implemented, then you
have a more difficult task the description of which will be given
later.

Other system constants

     There are two other constants in EF0 which may bear  looking
at before the sections are compiled.  These are

         grab_bsz   -  the number of bytes per grab
         block_gsz  -  the number of grabs per block

The concept of a 'grab' is explained fully in EF13.   It  may  be
wise first to check that the product 'block_gsz*grab_bsz' (around
line  93  in  EF0) yields a number of bytes which is a convenient
number for your system when doing  block  transfer  to  a  random
access file.  On the other hand, you may wish to proceed with the
implementation  immediately  and  to  tune up these things later.
The document EF13 contains a full discussion of this topic.

Method of installation

     We  will assume first that you have already had CHEF running
and  you need only to install a new version.  As mentioned above,
the first thing to do is to check the declaration  of  'computer'
in EF0 (around line 20) to make sure that it matches your system.
Next  you should observe that EF10 has another GET directive to a
file called "SYSHDR".  You should make sure that  you  have  this
file  available and that the name in the GET directive of EF10 is
correct.  This file SYSHDR  should  contain  the  declaration  of
constants necessary for your BCPL interface to  its  host  system
and  is  the  responsibility of your BCPL implementer rather than
CHEF.  To give some idea of what is wanted, the  following  is  a
minimal  SYSHDR  for  a  particular  implementation of BCPL under
UNIX.

  GLOBAL
  { unix:5; read:100; write:101; seek:103; fork:109; wait:110;
    execl:111 }

  MANIFEST
  { sys_unlink:10 }

     Note that because this BCPL-UNIX implementation uses globals
above  100  as  system globals, EF0 takes care of shifting global
numbers automatically for this implementation  (see  around  line
194 in EF0).

Compilation

     The next step is to compile sections  EF1  to  EF10  and  to
link them.  If the new version of CHEF now  runs,  you  may  find
that  the  help  or  error messages are not correct.  If they are
not, then you may need to reconstruct the message file directory.
In  doing  this  it  may  be  advisable first to replace your old
message file with the new version of EF11a or  EF11e  before  the
directory  is reconstructed, because the number of error messages
may have changed.

The message file and its directory

     It is important to notice that you  are  supplied  with  two
versions  of  EF11 (e - for EBCDIC and a- for ASCII) and that the
directory in EF11e is line oriented whereas that in EF11a is byte
oriented.  A spot check  on  the  directory  is  that  the  first
integer  in  the  file should be the line number in EF11 (or byte
number) of the message "Attention interrupt".   It  will  be  the
line number in EF11e and the byte number in EF11a.

     To reconstruct the message file directory use EF12, which is
the  BCPL  source of a utility program that reads EF11 and writes
new directory  on  another  file.   Make  sure  that  the  system
dependent constants in EF12 have been set correctly.  Now replace
the  directory  in  your message file with the new one.  You just
may need to iterate this step a couple of  times  until  the  new
directory  converges,  because  EF12  may count bytes and the new
directory may have a different byte count.  If the  messages  are
still  garbled,  then  examine  carefully  the description of the
directory which is given in EF11 immediately after the  directory
itself.   Also  examine  again  the system dependent constants in
EF12.   There  it  is  important  to  observe whether or not your
system supports access to files by line number.

Changes in the message file

     Note  that  on  an EBCDIC system some very useful characters
are not normally available and others are used instead.   A  list
of these is as follows.

          ASCII       EBCDIC
            ^           @            left margin
            \           |            backward scan
           [ ]         < >           class brackets

If you have inherited a message file associated with  EBCDIC  and
your system is in ASCII or vice versa, then you should look again
at the  distribution  tape.  Perhaps the other message file is on
it.  If not, then you will need to  alter  the  message  file  to
reflect the  proper  use of these characters.  There is a special
concern with the character '@' which in EBCDIC is used both as  a
left margin  symbol  and as a control designator.  In ASCII these
are two distinct symbols, the left margin symbol is '^'  and  the
control designator  is  '@'.   For this reason the number of help
messages in the EBCDIC message file is one less than in the ASCII
file.  You will see this fact reflected in EF12 around line 34.

Generating a new version of CHEF

     This  will  take a little more time, but most of the work is
in section EF10 which we shall now examine in detail.    We  have
mentioned  already  that  this  section is divided into groups of
procedures which are related by  their purpose.

Local options

     Look first at the section headed 'local options'.  Note that
the  function  'chef_parameters'  reflects  the difference in the
left margin  symbol  between  EBCDIC  and  ASCII.   The  function
'echo_string' initializes control +. This string will be executed
automatically as a CHEF command line after every one-line command
that alters the work-space.  Next are two routines which give the
names  of  the  two  files  that  CHEF  will need.  The first one
'name_of_msg_file' should yield the name  of  the  message  file,
EF11, on your system.  The other, 'name_of_work_file', yields the
name  of  the  file  used  for  block  transfer.   That  file  is
manipulated in random access fashion.  It  will  be  created  and
deleted by the editor for each edit session.  The last routine of
this group, 'show_prefix', handles the writing of the CHEF prefix
'>',  where it is desirable that the cursor should be left on the
same line of the screen.  This is where each BCPL  interface  may
have a different method of dealing with it.

Block transfer

     The next important group is  headed  'block  transfer'.   It
contains  two  routines  for reading and writing blocks.  The two
parameters are 'buffer', which is the address  of  the  block  in
memory,  'b',  which is the non-negative block number.  Note that
on some systems 'b=0' will give trouble so that for those systems
'b+1' is used instead.
instead.

File manipulation

    This group is concerned with  file  manipulation  other  than
block  transfer.   Each  procedure  has  a comment describing its
purpose.  You should have little  trouble  adding  the  necessary
parts  for  your system after an examination of the many examples
for other systems.  A point of  importance  is  that  the  second
parameter   of   'find_stream',   which   is  'find',  is  either
'findinput' or 'findoutput'.

System communication

     As  is  the  case in the group above, there should be enough
comments and examples to show what has to  be  done  here.   Note
that  'sys_return'  is called when one issues the CHEF command QS
which allows a temporary return to the operating system with  the
possibility of restarting CHEF where it left off.  Also note that
'sys_command(s)'  occurs  in response to the CHEF command 'QS s',
where 's' is a string.  The action here is to pass the string 's'
to the command line interpreter  of  your  operating  system  for
action, after which an immediate return to CHEF is made.  If your
BCPL  implementation  does  not support such actions you may have
difficulty here.  If you cannot implement one of  them  then  use
'warn(m_syntax)',  which  will  regard  this usage as a syntactic
error.

Device support

     The two functions  'accept_delete'  and  'accept_tab'  allow
CHEF  to  handle  the delete and tab characters, when coming from
the console.  If your  console  or  your  system  device  support
already  does  this, then these should merely return the value of
the parameter.  The 'recover_eof' seems to be needed only  for  a
special problem with MTS.

Optimization

     The group  headed  'optimization'  is  collected  here,  not
because the procedures are system dependent.  In fact, you really
need not do anything about them.  On the other hand, you may have
hardware  with  special user instructions in which these routines
could be  efficiently  implemented.    Don't  bother  with   this
optimization until you have CHEF running properly.

Byte counting

     The  procedures  in  this section overcome the difficulty of
counting more than 32K bytes on a system with a 16-bit cell.  You
will note that under MTS, with a 32-bit cell, most of  this  code
is not used.

Menu selection

     As  described  in EF13, the installer of CHEF may choose not
to implement  certain  features,  thereby  saving  code.     This
elimination  of  code  can be achieved merely by changing certain
manifest constants in EF0.   A  prime  example  is  the  constant
'menu_u' whose  declaration  is  in  EF0  (around line 36).  This
constant is related to the undo command, or U operator.   If  the
constant  is  set  to  FALSE,  then  conditional compilation will
eliminate all code related to the undo feature of CHEF  and  will
make the  use of the operator U a syntactic error.  Unfortunately
the error message file will still suggest that such  an  operator
is valid.   However there are fourteen such constants and to have
one message file for each combination of  menu  selections  would
mean  the  provision  of  around  16000  different message files.
Thus, the installer who makes an excision from CHEF is invited to
take  the  full message file and use CHEF to edit its own message
file to remove, or change the appropriate message, not forgetting
the reconstruction of the  directory  as  discussed  above.   The
reduction in code by setting 'menu_u' to FALSE is about 5% of the
code of the full implementation of CHEF.

     As we have remarked, 'menu_u' is just one of  some  fourteen
such constants.  Another is 'menu_j'.  It controls the generation
of code  for  the  operator  J which does text justification.  An
installer may be desperate indeed to excise this feature, but the
saving in code from the full editor is about 8%.

     A  list  of  such  menu  selections,  taken  from  EF0,   is
reproduced here.

        menu_class            // character classes
        menu_closure          // closure in patterns
        menu_j                // The operator J
        menu_pl               // operator L
        menu_macro            // control line macro expansion
        menu_new              // operators N and O
        menu_qs               // return for system command
        menu_t                // The operator T
        menu_u                // operator U
        menu_window           // window facility
        menu_x                // operator X
        menu_xf               // execute from a file
        menu_z                // operator Z
        menu_control          // control store option

Consistent compilation

     File  EF0  contains  a  constant 'version' (around line 10).
This value is added with another constant  which  represents  the
operating system and the result is given to 'computer' which then
has a  unique  number  for  each  version on each system.  In EF1
there is a routine 'check_system' which takes  three  parameters.
The  last  is the section number and the first two are the values
of 'computer' from EF0 and from the section in question.  If  for
any  section  these  two  numbers  do  not  agree,  then  CHEF is
immediately aborted with a message indicating which  section  has
not been  compiled  compatibly.   In this way it is impossible to
run CHEF unless all sections have been  compiled  with  the  same
setting  of  those constants which determine the operating system
and the version.  When generating CHEF for more than  one  system
simultaneously  by cross compilation, such checks become vital in
avoiding embarrassing versions of CHEF which  can  damage  users'
files.

Copyright

     Installers of CHEF should note that the source code  is  the
property  of J.E.L.Peck and M.A.Maclean, and therefore should not
be distributed without their  consent.   The  intention  of  this
copyright  is  not  to restrict the use and distribution of CHEF,
but rather to allow the authors to  know  where  the  source  has
gone.   This  has  one advantage in that users might then be told
about recent changes or improvements to CHEF, although  there  is
no guarantee that this will happen.  Those who wish to exploit or
sell  CHEF  for personal gain should of course, make arrangements
with the authors for a written contract.

