DRAFT

DRAFT NOTES ON THE POPLOG ENVIRONMENT
http://www.cs.bham.ac.uk/research/projects/poplog/V16/poplog-environment.txt

Aaron Sloman
http://www.cs.bham.ac.uk/~axs

Installed: 28 Jul 2021

As a result of work being done by others (notably Waldek Hebisch and Steve Leach),
there are likely to be significant changes in procedures for installing,
maintaining and using poplog and its various sub-systems and packages.

There will be consequences related to ways in which individual users and groups of
users sharing a poplog installation are able to set up preferences of many kinds,
including which code and documentation libraries should be accessed via commands
like these

for accessing documentation:
    teach, help, ref, doc
for importing libraries or extending libraries and documentation
    lib, uses

This is a first draft (likely to be revised) attempt to summarise the situation in
the version of poplog that is installed by following download instructions on this
web site including this document and documents and scripts referred to in it.

http://www.cs.bham.ac.uk/research/projects/poplog/V16/AREADME.txt

Top-level environment variable:

    $poplib

This may or may not be set explicitly by the user before poplog is invoked.

If it is set it should identify a directory (either unique to the user, or shared
between a group of users) in which many user options are set up, some of which
specify commands for starting poplog , e.g.

    pop11, plog, clisp,

while others create or extend search lists or define environment variables that
are used either when starting up poplog or while programs are running.

The above are all set up and/or accessed before poplog itself starts up.

How it starts can vary in at least these ways:

   whether the mininal basepop11 runs without loading saved images, but
    reading the user's startup scripts to find out what to compile and in
    some cases run, which could include creating a new saved image and possibly
    running it!

Other environment variables set up particular facilities after poplog starts, e.g.
determining which editor commands are made available, which code (pop11, prolog,
lisp, etc.) libraries are either compiled or made available in search lists for
use if needed.

To this extent poplog is comparable to an operating system, that can be used very
differently by different users.

The value of the top level environment variable $poplib controls provision of
information that can be used either before running any code (e.g. specifying
where the main introductory user and system documentation files are), or when
running poplog in order to determine effects of commands like

    teach, help, ref (for accessing documentation)
    load, lib, showlib (for accessing poplog code libraries)

is for (and there
are more details scattered around REF SYSTEM).

Poplog is meant to be VERY VERY VERY tailorable! That includes allowing
individual users or groups of users (e.g. a group of students taught on a
particular course) to modify or extend almost any portion of poplog as it
appears to them (or their students and friends).

This is partly done through a variety of search lists, for files or directories
containing any (or all) of, in no particular order:

user-specified, or group specfied, or system specified (defaults for all users)

    saved images (defining the commands pop11, prolog, clisp,

        etc. also xved and others that invoke saved images).

    code libraries,

        including
        whole packages with their own subdirectories, like popvision, popneural,
        poprulebase, sim_agent (which uses poprulebase), etc.

    documentation libraries (teach,  help, ref, doc, demo) which may be parts of
        packages (e.g. part of popvision) or standalone, e.g. teach arith.
        teach decimals.

This tailoring is done via the environment variable $poplib.

If users invoke poplog without defining $poplib poplog treats $poplib as
referring to

    $usepop/pop/packages/setup/Poplib

That Poplib directory used to be a core part of Poplog but when the packages
subtree was added Poplib was located there, to allow the files in Poplib to
specify extensions to poplog for the user (or group of users sharing a
poplog system, e.g. a group of students, or a research project team).

Also uses this user-, or system- extendable directory:

    $usepop/pop/packages/lib/*.p

The Poplib directory (above) contains a collection of lists that set up a whole
lot of defaults for current users:

    Poplib/Poplogfiles
        explains (too tersely) what the directory is for.

    Poplib/Xdefaults.poplog
        stuff about bitmaps, terminals, colours, fonts, ...

    Poplib/init.ml
        stuff for pml (??) (Should we get rid of the Pml subsystem, as its
        designers have informed me that it is out of date and buggy?)

    Poplib/init.p
        starts up various pop11 and system stuff inside pop11.

    Poplib/init.pl
        ditto for prolog
            obscurely: contains only one line: library(useful)
            I assume there's a default prolog useful.pl somewhere, which can be
            redefined by users.

    Poplib/vedfiletypes.p
        specifies various types of files used for various purposes in various
        subsystems.

        Users can add new types, with new suffixes to identify them, and then
        provide code libraries for dealing with them!

    Poplib/vedinit.p

        sets up a large collection of defaults for specifying the behaviour of
        ved/xved (the poplog editor, which can do much more than just editing
        -- e.g. it can invoke the language compiler or other things),

        including types of font, behaviour of the mouse when editing,
        how to behave according to the type of terminal, mouse and keyboard
        e.g. standard xterm, or graphical terminal, standard querty
        keyboard or something else (e.g. sun workstation keyboard),

            I am sure that the set of alternatives is badly out of date!!!

            Any volunteers to produce a more sane and up to date version, for
            this and the other initialisation files? Not a trivial task and
            details may change as technology changes.

            E.g. there should be options for voice commands for the editor, in
            the user's language!

NB NB
A user who doesn't like the defaults can copy and edit the contents of

    $usepop/pop/packages/poplib

into a new directory (possibly shared by a team...) and then redefine the
environment variable $poplib somewhere in their login scripts to refer to that
directory -- as I do.

NB the stuff in the user's $poplib may be a minor variant of the default
version, or it may include *major* extensions, e.g. packages as big and
important as popvision, for example, or a collection of documentation and code
libraries to be used by a whole group of students, or a project team.

Similar remarks apply to individual packages that can be copied and edited:

    rclib, neural, teaching, vedlatex, emacs ...

The packages don't all share the same structure. Several of them, e.g. the
'teaching' package started life as simply a collection of stuff I removed from
the default poplog libraries, where they could (and sometimes did) get in the
way using the original default autoloading or library loading mechanisms.
Later various additional tutorials were added.

It is also possible for other packages, e.g. popvision, poprulebase, simagent,
etc. to include their own tutorials, in which case the 'teach' search list
should be extended appropriately when those packages are added.
Likewise help, ref, doc, lib, auto, ... search lists

Of course the user added search lists can shadow the default search lists,
which is a reason for being very careful about choice of names for packages
and their files, etc.

If I were starting again I would probably introduce a more fine-grained
structure, and perhaps a different design. But I have no idea what it should now
be!!