HELP NEWPOP                                     Robert Duncan, July 1991
                                       Revised Robert Duncan, April 1993

Building a new Poplog system.


         CONTENTS - (Use <ENTER> g to access required sections)

  1   Introduction
  2   WARNING
  3   Notation
  4   The NEWPOP Environment
  5   Functions of NEWPOP
  6   Options to NEWPOP
  7   Linking "newpop11"
  8   Linking "newpop11" for X
  9   Installing the "basepop11" Command
 10   Building Supporting Libraries
 11   Making the Standard Saved Images
 12   Defining Other Poplog Commands
 13   Making Documentation Indexes
 14   Removing Ved Special Characters from Documentation
 15   Running Local NEWPOP


------------------------------------------------------------------------
1  Introduction
------------------------------------------------------------------------

The command script NEWPOP located in the Poplog source directory
($popsrc) is used to build a new Poplog system.

The command synopsis is:

    For the Unix C shell:

        % setenv usepop <poplog-root-directory>
        % $popsrc/newpop [options] [config-file]

    For the Unix Bourne shell:

        $ usepop=<poplog-root-directory>; export usepop
        $ $popsrc/newpop [options] [config-file]

    For VMS:

        $ assign <poplog-root-directory> usepop
        $ @popsrc:newpop [options] [config-file]

The command installs a new Poplog system in the directory denoted by the
path <poplog-root-directory>.

If you have deleted the source directory to save space, you must recover
it from your distribution tape before trying to run NEWPOP.


------------------------------------------------------------------------
2  WARNING
------------------------------------------------------------------------

NEWPOP installs a completely new Poplog system in the directory
identified by the environment variable (or logical name) "usepop". If
you have an existing Poplog system at that location, it will be
overwritten. You must ensure that "usepop" has been set to the correct
directory name before you run NEWPOP.


------------------------------------------------------------------------
3  Notation
------------------------------------------------------------------------

In order to avoid tedious repetition of examples using different
syntaxes and notations, the following conventions are adopted throughout
the remainder of this file.

    1)  Environment variables (logical names) are written in the Unix
        style, prefixed with a '$' sign, e.g.

            $popsys         (for the Poplog executable directory)
            $popsrc         (for the Poplog source directory)

        VMS users should simply ignore the leading '$'.

    2)  Filenames are written in the Unix style, e.g.

            $poplocal/local/com/    (for the local command directory)

        which corresponds to the VMS pathname

            poplocal:[local.com]

        The procedure * sysfileok on VMS systems will perform this
        conversion automatically, e.g. try

            sysfileok('$poplocal/local/com/')=>

    3)  Examples of operating system commands are written to assume the
        Unix shell. The arguments to commands are the same for all
        systems, only the syntax for denoting the command script varies.
        Thus the example:

            $popsrc/newpop -link

        corresponds to the VMS DCL command:

            @popsrc:newpop -link

    4)  The word NEWPOP is used in the text to stand for the command:

            $popsrc/newpop


------------------------------------------------------------------------
4  The NEWPOP Environment
------------------------------------------------------------------------

NEWPOP runs in an environment initialised by reading the standard Poplog
login script

    $popcom/poplog

(see HELP * INITIAL). This depends on an initial setting of the
environment variable $usepop; other environment variables are then
defined relative to that. The principal environment variables used by
NEWPOP are

    $popsrc         (the Poplog source directory)
    $popsys         (the Poplog executable directory)
    $popsavelib     (the Poplog saved image directory)
    $popcom         (the Poplog command directory)
    $poplocal       (the Poplog local directory)

If you are unfamiliar with the Poplog environment, you should read
DOC * SYSSPEC.


------------------------------------------------------------------------
5  Functions of NEWPOP
------------------------------------------------------------------------

NEWPOP performs the following functions:

    1)  Linking the newpop11 executable image in $popsrc.

    2)  Installing the newpop11 image as the base Poplog executable in
        $popsys.

    3)  Building supporting executables and libraries.

    4)  Making the standard saved images in $popsavelib.

    5)  Creating definitions for other Poplog commands: prolog,
        clisp etc.

    6)  Making documentation indexes (and optionally removing Ved
        special characters from documentation files).

    7)  Running the local version of NEWPOP for site-specific tailoring.

Any of these functions can be omitted or controlled by means of
appropriate options.


------------------------------------------------------------------------
6  Options to NEWPOP
------------------------------------------------------------------------

The behaviour of NEWPOP is completely option-driven: only those actions
explicitly selected by options are performed. The available options are
summarised in Table 1; their meanings are discussed in more detail in
the sections which follow.

  --------------------------------------------------------------------
  |              Table 1 : Summary of Options to NEWPOP              |
  |------------------------------------------------------------------|
  |                                                                  |
  | link            Link $popsrc/newpop11, including:                |
  | x               ... X System support                             |
  | rsv             ... RSV (delivery system) support                |
  |                                                                  |
  | install         Install the basepop11 executable in $popsys      |
  |                                                                  |
  | xpw             Build the Poplog Widget Set archive library      |
  |                 (requires option x)                              |
  |                                                                  |
  | startup         Make the startup saved image                     |
  | images          Make other saved images, selected from:          |
  | eliza           ... the eliza demo image                         |
  | prolog          ... the Prolog language image                    |
  | logic           ... the Prolog logic tutor image (requires       |
  |                     option prolog)                               |
  | clisp           ... the Common Lisp language saved image         |
  | pml             ... the Standard ML language saved image         |
  | xved            ... the XVed saved image (requires option x)     |
  |                                                                  |
  | commands        Define shell/DCL commands for the standard       |
  |                 languages, and for Ved functions selected from:  |
  | ved             ... the Ved command                              |
  | ve*d            ... the Ved command with abbreviation (VMS only) |
  | help            ... the HELP command                             |
  | hlp             ... the HELP command                             |
  | ref             ... the REF command                              |
  | teach           ... the TEACH command                            |
  | doc             ... the DOC command                              |
  | im              ... the IM command                               |
  | vt100           ... the VT100 command                            |
  |                                                                  |
  | indexes         Build documentation indexes                      |
  | stripdoc        Strip Ved special characters from all            |
  |                 documentation files (implies option indexes)     |
  |                                                                  |
  | local           Run the local NEWPOP command,                    |
  |                 $poplocal/local/com/newpop                       |
  |                                                                  |
  --------------------------------------------------------------------

Table 1 lists only the "enabling" options: specifying any of these
implies the inclusion of some particular step in the NEWPOP process. For
each one there is a corresponding "disabling" option which suppresses
that same feature, obtained by prefixing the option name with no: e.g.
nolink, noprolog etc.

Also, certain options (described below) allow for an extra "qualifier"
argument separated from the option name by an "=" sign:

    option = qualifier

option and qualifier together make up a single item.

The case of options is not significant, as all options are converted
internally to lower case.

NEWPOP obtains its options from two sources:

    1)  a configuration file

    2)  the command line

The configuration file provides the primary control; command-line
options are used to refine its behaviour. The default configuration file
is

    $popsrc/newpop_options

This contains all the options necessary to build a standard
configuration Poplog system (with slight variations between Unix and
VMS). So running the NEWPOP command with no options will regenerate this
standard configuration. You can provide an alternative configuration
file as the last argument to the NEWPOP command, e.g:

    $popsrc/newpop $poplocal/local/newpop_options

In this case, the default file is not consulted at all: only the options
specified in your own file will be acted upon. If you want to write your
own configuration file, a good idea is to copy the default version and
delete or modify lines as appropriate. Within a configuration file, each
option (together with any associated qualifier) must appear on a line by
itself. End-of-line comments can be indicated with the usual Poplog
';;;' convention, and blank lines are ignored.

Regardless of which configuration file is to be used, you can also
specify options on the command line to override those in the file.
Command-line options are the same as those from Table 1 above, but
prefixed with a '-' sign, e.g.

    $popsrc/newpop -link

Disabling options are particularly useful on the command-line, where
they can be used to suppress features requested in the configuration
file, e.g. the command:

    $popsrc/newpop -nolink -nolocal

runs the default NEWPOP, but omitting the link and local steps.

If you add a qualifier to a command-line option, remember that the two
must be passed as a single item, so will probably need quoting. Any
special characters in the qualifier will need quoting too. This is not a
problem with options in a file.

If the number or complexity of command-line options becomes too unwieldy
(particularly on VMS systems, where a limit is imposed on the number of
arguments) you can place the options into a file and use the options
flag to get that file consulted, e.g:

    $popsrc/newpop -options tempfile

This file is read in addition to the configuration file.

Finally, if you want to ignore configuration files altogether and supply
all the options on the command line, you can use the special word only
in place of the configuration file name; e.g. the command:

    $popsrc/newpop -link only

will perform only the link step.


------------------------------------------------------------------------
7  Linking "newpop11"
------------------------------------------------------------------------

Step 1 of the NEWPOP process is to link a new version of the Poplog
executable -- newpop11 -- in $popsrc. This step is enabled with the link
option.

Within the link step, there are two further parameters of variation:
whether to include X support within Poplog and whether to build an RSV
image for delivery systems.

X support is included by default. In order to make use of it, your
system must have an implementation of the X Toolkit and Xlib libraries
(X11 Release 4 or later) available to the system linker. NEWPOP will
look for these in standard places -- exactly where depends on your
system. If this fails to work, or if you want to do something different,
then read the next section.

If your system doesn't have X, or if you're sure you're not going to use
it and want to reduce the size of the Poplog images, then you can
exclude it from Poplog by specifying the option nox.

RSV support is not included by default: it must be enabled with the rsv
option. This causes a special copy of the newpop11 image to be made as
$popsrc/rsvpop11. This image is required for delivery systems.

Linking newpop11 requires the Poplog "external" library

    $popexternlib/libpop.olb

If this does not exist, NEWPOP will rebuild it.

As well as the executable image itself, NEWPOP may also create in
$popsrc a symbol table file for external loads ($popsrc/newpop11.stb)
and a map file for debugging ($popsrc/newpop11.map).


------------------------------------------------------------------------
8  Linking "newpop11" for X
------------------------------------------------------------------------

The newpop11 image created by the NEWPOP link step will include support
for X unless you override it with the nox option.

As described in the section Poplog Image X Link Specification in
REF * X, X linking is controlled by the values of Unix environment
variables/VMS logical names, whose names have the form

    POP_XPREFIX_EXLIBS

where XPREFIX is a short prefix corresponding to the X link type. The
format of the NEWPOP x option is thus

    x = -xprefix

where (lowercase) xprefix selects the corresponding (uppercase) variable
name. Standard values for -xprefix include

    -xm         (selects POP_XM_EXLIBS,   for Motif)
    -xol        (   "    POP_XOL_EXLIBS,   "  OpenLook)
    -xt         (   "    POP_XT_EXLIBS,    "  MIT)

If the '= -xprefix' qualifier is omitted, it default to -xlink, which
selects POP_XLINK_EXLIBS. This variable is set to give the appropriate
host-specific default.

For example, to link a system with MIT only, use

    $popsrc/newpop -link -x=-xt

See REF * X for further details.


------------------------------------------------------------------------
9  Installing the "basepop11" Command
------------------------------------------------------------------------

Step 2 of the NEWPOP process is the installation of the newpop11 image
as the base Poplog executable:

    $popsys/basepop11

This step is enabled with the install option.

The first stage of the installation is to clear out any existing
executables and saved images from the $popsys and $popsavelib
directories: it's primarily for this reason that you must be sure that
you have set $usepop correctly before you run NEWPOP, to avoid your
existing Poplog system from being deleted in this way. However, if there
is an existing basepop11 executable in $popsys, it is renamed as
"oldpop11" rather than being deleted, so you can recover it if something
goes wrong.

The newpop11 executable, symbol table and map files are then moved from
$popsrc to $popsys and renamed as basepop11. There must be a newpop11
executable in the $popsrc directory. In the normal progress of events,
it will have been created by a preceding link step. If you have chosen
to omit this step, you should ensure that the newpop11 executable has
been created by some other means: either by manual linking, or by
copying an existing executable from $popsys.

NEWPOP also creates a new "popenv" file in $popsys for definitions of
command symbols for Poplog shell/DCL commands such as "pop11", "ved",
"prolog", etc. This file is consulted by the standard Poplog login
script, $popcom/poplog. It wil always contain at least the definition of
the command "pop11".


------------------------------------------------------------------------
10  Building Supporting Libraries
------------------------------------------------------------------------

Step 3 of the NEWPOP process involves building executables and libraries
needed for Poplog run-time support. Currently there is just one such
object: the archive library for the Poplog Widget Set (Xpw).

The Poplog Widget Set is enabled with the xpw option. This causes NEWPOP
to run the command $popcom/mkXpw which will rebuild and install the
Poplog Widget Set archive library in $popexternlib. This option is
ignored if you have selected nox.


------------------------------------------------------------------------
11  Making the Standard Saved Images
------------------------------------------------------------------------

Step 4 of the NEWPOP process is to build the standard saved images in
$popsavelib. The full set of standard images consists of:

    startup.psv         # Default start-up code
    prolog.psv          # Prolog language subsystem
    clisp.psv           # Common Lisp language subsystem
    pml.psv             # Standard ML language subsystem
    xved.psv            # XVed (X based version of Ved)
    eliza.psv           # Eliza demo (not built by default)
    logic.psv           # Logic demo (uses Prolog; not built by default)

For each image there is a corresponding option -- startup, prolog,
clisp, etc. -- such that selecting the option causes NEWPOP to build the
image. The default configuration file includes options for all the
images except eliza and logic; if you want these two built as well, use
the command:

    $popsrc/newpop -eliza -logic

The status of the startup image is special in that (if it exists) it is
loaded by default with all Poplog commands. In particular, all
subsequent saved images are layered on top of the startup image. The
image contains code which is viewed as part of the base Poplog system,
but which is not part of the Poplog executable itself. It may well be
customised on a per-site basis, depending on how Poplog is used at each
site.

Other dependencies exist between images: you can't build the logic image
without prolog, and you can't have xved without x. Also, none of the
images (except startup) will be built if you specify noimages.

Images are normally built using command scripts from $popcom. You can
specify your own commands instead, by qualifying the image-name argument
with the command to use: the qualifier is simply executed as a Shell or
DCL command without interpretation. For example, the option

    prolog = $poplocal/local/com/mkprolog       # Unix

    prolog = @poplocal:[local.com]mkprolog      # VMS

would use a local version of the "mkprolog" command in place of the
system-supplied one. If such an option is to be given on the command
line, make sure that you add the required amount of quoting to allow the
option to be read as a single item, e.g:

    $popsrc/newpop -"prolog = $poplocal/local/com/mkprolog"


------------------------------------------------------------------------
12  Defining Other Poplog Commands
------------------------------------------------------------------------

Step 5 of the NEWPOP process consists of writing to the $popsys/popenv
file definitions of any additional Poplog shell/DCL commands which are
to be made available to users on login. This step is associated with the
commands option and is always performed unless you disable it by
specifying nocommands.

If this step is enabled, NEWPOP will create command definitions for any
of the following standard saved images you have chosen to build:

    prolog      # Run Prolog
    clisp       # Run Common Lisp
    pml         # Run Standard ML
    xved        # Run XVed

Beyond that, there are several other commands which you can request to
have defined:

    ved
    help
    ref
    teach
    doc
    vt100

which provide various entry points to the Ved editor. Note that on VMS
systems, the commands ved and help are normally replaced with the
commands

    ve*d
    hlp

The first allows for command abbreviation; the second is to avoid
conflict with the DCL help command.

Having each command specified individually allows you to avoid any which
conflict with existing command names. For example, some Unix sites may
also prefer not to have the help command enabled, so the command-line
option:

    $popsrc/newpop -nohelp

would suppress that.


------------------------------------------------------------------------
13  Making Documentation Indexes
------------------------------------------------------------------------

Step 6 of the NEWPOP process is making the documentation indexes. This
means creating an index file in each HELP, TEACH and REF directory, and
also creating the DOC_INDEX database for the <ENTER> ?? command. This
step is enabled with the indexes option.

The standard Poplog system is distributed with indexes already built, so
if you are rebuilding a system, using the same documentation directories
as before, it is unlikely that you will need to rebuild the index files.
The command-line option

    $popsrc/newpop -noindexes

will suppress the index-building stage and save a little time.

Indexes are built with the command $popcom/makeindexes.


------------------------------------------------------------------------
14  Removing Ved Special Characters from Documentation
------------------------------------------------------------------------

An additional function performed by $popcom/makeindexes is to strip all
documentation files of Ved special character encodings.

Files written by Ved use extra control characters to represent
attributes like bold and italic, as well as a special graphics character
set. Since they are not recognised by editors other than Ved, the extra
control characters will show up explicitly when a file is viewed with
another editor.

One way round this problem is to use the command 'pop11 stripvedfile' to
filter individual files (see LIB * STRIPVEDFILE). This removes Ved
encodings from a file and writes the result either to standard output or
to another file, from whence another editor can access it.

On the other hand, if you will mainly be using other editors to examine
Poplog documentation, you have the option of employing

    $popsrc/newpop -stripdoc

to (permanently) remove special encodings from all documentation files
(this implies the indexes option).

                           NOTE
    Even if you prefer not to use Ved for your normal editing, in an
    X environment you always have the option of using XVed to view
    Poplog documentation. This will in no way interfere with the
    operation of another editor.


------------------------------------------------------------------------
15  Running Local NEWPOP
------------------------------------------------------------------------

The final stage in the NEWPOP process is to run the local NEWPOP command
script:

    $poplocal/local/com/newpop

This step is enabled with the local option.

This file need not exist; if it does, it may contain any commands for
tailoring the newly-installed Poplog system, e.g. adding local command
definitions, building local saved images in $poplocalbin etc.


--- C.all/help/newpop
--- Copyright University of Sussex 1997. All rights reserved.
