
Contents of This Directory
==========================

This directory contains a complete distribution of the Nonpareil
document editing system:

  README         This file
  compiler       Subdirectory holding Nonpareil compiler source code
  doc            Subdirectory holding documentation
  gpl_license    GNU General Public License, the license for Nonpareil
  makefile       Make file for installing Nonpareil
  system         Subdirectory holding one Nonpareil system


Nonpareil Installation Guide - Simple Version
=============================================

Assuming that you have just unpacked this Nonpareil distribution,
changed into this directory, and are reading this Guide, here is
a very simple way to install and run Nonpareil.

(1) Set variable NP_BIN_DIR in file "makefile" to the directory where
    you want Nonpareil's executables, "np_init" and "np", to be stored.
    This will be an existing directory, lying on your command path, for
    which you have write permission, for example /home/foo/bin.
    
(2) Type "make" in this directory.  This will create binaries "np_init"
    and "np" and move them to NP_BIN_DIR, then execute "np_init".

(3) You are now ready to run Nonpareil from anywhere in your
    directory space:  just type the command "np".

To reinstall, type "make clean" and then "make".


Nonpareil Installation Guide - Complicated Version
==================================================

You need a complicated installation if something goes wrong or you
are trying to do something different, such as develop your own
Nonpareil module.


Step 1: compiling the compiler ("make npc" in this directory)
-------------------------------------------------------------

The first step is to compile the Nonpareil compiler, "npc".  Its
source files, written in ANSI C, are in directory "compiler" of
this distribution.  There is a separate makefile for compiling
"npc", also in that directory.  Compiling the compiler means
typing "make" in directory "compiler".  The resulting executable,
"npc", is placed into directory "compiler".  It's best to leave
it there, unless you expect to be compiling a system repeatedly
(e.g. when you are developing your own Nonpareil module), when
you might prefer to move it to a directory on your command path.

See "compiler/makefile" and "compiler/lib/README" for more information.


Step 2: compiling a system ("make sys" in this directory)
---------------------------------------------------------

The result of Step 1 is a compiler for the Nonpareil language, "npc".
To use this compiler to compile a Nonpareil system, make that system's
directory your current directory and execute "npc" there.  Given the
way this particular distribution is set up, starting from this
directory you might actually type

    cd system
    ../compiler/npc

This compiles the system and places the resulting compiled Nonpareil
executables, "np_init" and "np", in its "ccode" directory.

Compiler "npc" compiles the Nonpareil source files to C, adds some C
files from "compiler/lib" to them, and then invokes the C compiler
to compile all these files into executables "np_init" and "np".
Backup versions of the C files, ending in ~, are also created by
"npc", and used to speed up the C compilation stage:  if a ".c" file
equals its backup version, and all ".h" files included in that ".c"
file equal their backup versions, then the ".c" file does not need
to be recompiled.  Directory "system/ccode" contains all these C files.

The full path name of the system directory is compiled into "np_init"
and "np".  This is taken from the environment variable PWD.  If your
environment does not contain a PWD variable, you need to supply this
full path name using the -s flag:

    ../compiler/npc -s/home/foo/nonpareil/system

for example.  The full name is needed so that "np_init" and "np" can
find this directory no matter where they are invoked from.

Type "npc -u" for more "npc" usage information.  An alternative that is
mainly useful for maintaining the Nonpareil compiler is "npc -i".  This
causes "npc" to enter an interactive phase after completing the compile,
in which it will parse type and other expressions, print the list of
features of a given class, etc.  Type "help" at the "npc:" prompt for
more information.


Step 3: initializing a system ("make init" in this directory)
-------------------------------------------------------------

A compiled Nonpareil system has two components:  its executable,
"np", created by Step 2, and a binary data file, whose creation is
the job of Step 3.  Having this binary data already calculated is the
key to getting an ordinary run of "np" (Step 4) to start up quickly.

In principle this binary data should be a part of the executable, but
sadly there seems to be no way to get Unix to do that for us.  It is
created by executing "np_init":

    np_init

The binary data will be created and stored in the system directory,
whose full path name is compiled into "np_init" and "np" as described
above.  The data file is "system/data_be" or "system/data_le" depending
on whether "np_init" is running on a big-endian or little-endian machine
(it works this out for itself when it runs).  A networked environment
may have multiple "np_init" and "np" binaries of mixed endianness:  just
initialize once for each endianness, creating both files.

When a system is recompiled, its binary data must be initialized
(or reinitialized) using "np_init" before any other run of "np".
The binary format begins with a magic number which allows an
ordinary run of "np" to check that this has been done.


Step 4: an ordinary run
-----------------------

An ordinary run of "np" is carried out by typing just

    np

The run must be able to find file "system/data_be" or "system/data_le"
at the full path name compiled into "np" as described above.
