HELP PROGRAMMING                                     Andrew Law Apr 1987
                                         Revised: Adrian Howard Mar 1992

This help file describes some of the file relating to programming in the
POPLOG environment.

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

 -- Overviews of the different languages
 -- Programming in VED (The POPLOG Visual EDitor)
 -- Mixed language programming
 -- ... General
 -- ... Prolog and POP-11
 -- ... Common LISP and Prolog
 -- ... Common LISP and POP-11
 -- ... ML and POP-11
 -- ... Using Non-POPLOG Languages
 -- Debugging aids
 -- ... General
 -- ... POP-11
 -- ... Prolog
 -- ... Lisp
 -- ... ML
 -- Timing Procedures and Efficiency
 -- Errors, Warning messages and Interrupts
 -- ... General
 -- ... ML
 -- ... LISP
 -- Saved Images
 -- Sections
 -- Virtual Machine
 -- Memory, Memory Limits, And Garbage Collection
 -- Datatypes
 -- ASSOCIATED DOCUMENTATION


-- Overviews of the different languages -------------------------------

HELP *POP
HELP *CLISP
HELP *PROLOG
HELP *FLAVOURS
HELP *PML


-- Programming in VED (The POPLOG Visual EDitor) ----------------------

TEACH * VED --- Introduction to VED
HELP * VED  --- General overview of VED (programming in it and of it)


-- Mixed language programming -----------------------------------------

The following files give information on writing programs in more than
one language.


-- ... General --------------------------------------------------------

HELP * SUBSYSTEMS
REF * SUBSYSTEM
    Access to the different POPLOG language subsystems


-- ... Prolog and POP-11 ----------------------------------------------

PLOGHELP *MIXED_LANGUAGES
    Methods of interfacing Prolog and other languages

DOC *CONTINUATION
    Paper describing Prolog programming as continuation passing

PLOGHELP *SIMPLEPOP
    Library to do simple things in POP-11 from Prolog

PLOGHELP *TERMSINPOP
    POP-11 procedures for manipulating Prolog terms and variables

PLOGHELP *PROCESSES
    How to create POP-11 processes which use Prolog procedures

PLOGHELP *POPTOPLOG *PLOGTOPOP, HELP *PLOGINPOP
    How to call Prolog from POP-11 and vice versa

PLOGHELP *POPSTRING
    Using POP-11 strings in Prolog

PLOGHELP *IS
    Evaluating POP-11 and arithmetic expressions which return one result

PLOGHELP *ARE
    Library for evaluating POP-11 expressions from Prolog

PLOGHELP *PROLOG_BARRIER_APPLY
    POP-11 procedure which applies a procedure inside a Prolog 'barrier'

PLOGHELP *PROLOG_LANGUAGE
    Predicates and library package for switching from Prolog to POP-11

PLOGHELP *PROLOG_VARS
PLOGHELP *PROLOG_LVARS
    Library packages for easier declaration of prologvars from POP-11


-- ... Common LISP and Prolog -----------------------------------------

PLOGHELP *LISPINPLOG
    Accessing LISP from Prolog

Lisp HELP file *PROLOG
    Accessing Prolog from LISP


-- ... Common LISP and POP-11 -----------------------------------------

HELP *POPLISP
    Accessing POP-11 from LISP and vice versa.


-- ... ML and POP-11 --------------------------------------------------

The ML HELP file MLINPOP
    Mixed-language programming in ML and POP-11.


-- ... Using Non-POPLOG Languages -------------------------------------

HELP * EXTERNAL
HELP * NEWEXTERNAL
    Mechanisms for easily declaring, loading, and unloading procedures
    compiled externally to POPLOG.

REF * EXTERNAL
    Loading external data and calling external functions.

REF * EXTERNAL_DATA
    External data structures.

HELP * PASCAL (VMS only)
    Compiling PASCAL programs from VED.


-- Debugging aids -----------------------------------------------------

The following sections give references to documentation on various
POPLOG debugging aids.


-- ... General --------------------------------------------------------

HELP * VED_WIGGLE
REF *VED_WMP *VED_MP
    Visual demonstration of bracket opening/closing pairs

REF * VED_MM
    Move to the "end" of a syntactic structure

HELP * BUGREPORT
    Sending in reports on bugs in POPLOG

HELP * CUCHARTRACE
    Variable controlling where trace output appears

HELP * POPGCTRACE
    Tracing garbage collections

HELP * SHOWCODE
    Tracing code planting instructions

REF * POP_DEBUGGING
    General indication of whether programs are being compiled in
    debugging or "real-use" mode


-- ... POP-11 ---------------------------------------------------------

HELP * TRACE
REF * TRACE
    General tracing of procedure execution

HELP *POPREADY
    Invoking the compiler from a program

REF *FASTPROCS
    Dangers of non-checking "fast" procedures

HELP * DEBUGGER
    A source level debugger for POP-11

REF *FTRACE *FTRACEALL *UNFTRACE *UNFTRACEALL
HELP * FTRACE_MESSAGE
    The Flavours tracing mechanism

REF * VEDDEBUG
    Procedure used in debugging VED procedures


-- ... Prolog ---------------------------------------------------------


PLOGHELP *DEBUG
    Overview of the debugging facilities provided by POPLOG Prolog

PLOGHELP * TRACER (also TEACH * TRACER in Prolog)
    Library program for tracing the action of simple predicates

PLOGHELP *SPY, *DEBUGGING
    Placing "spypoints" on Prolog predicates

PLOGHELP *QUIETSPY
    Predicate to prevent SPY from printing out messages when spypoints
    are placed or removed.

PLOGHELP *NOSPY *NODEBUG
    Predicates to remove spypoints from specified predicates

TEACH *WHY in Prolog
    Providing justifications for Prolog programs

PLOGHELP *LEASH
    Predicate which causes each spypoint to prompt user for action

PLOGHELP *CHATTY
    Debugging tool to make clauses print commentary during their
    execution

PLOGHELP *UNLEASH
    Predicate which causes spypoints to print out messages without
    prompting

PLOGHELP *PLOGDEBUG
    List of PROLOG Debugging options

PLOGHELP *UNDEFS, *UNKNOWN
    For altering the action taken when encountering undefined predicates

PLOGHELP *SHOWTERM
    Library package for displaying a tree representing a term

PLOGHELP *DISPLAY
    Predicate which writes argument to current output in prefix format


-- ... Lisp -----------------------------------------------------------

The following are all LISP documentation files:

HELP *INSPECT
    LISP version of the POP-11 LIB *INSPECT

HELP *DEBUG
    General LISP debugging tools

*DEBUG-IO* and *TRACE-OUTPUT* in REF *STREAMS in LISP
    Streams used for debugging and trace output

REF *TRACE *UNTRACE in Lisp
    Tracing of LISP functions


-- ... ML -------------------------------------------------------------

The following are all ML documentation files:

HELP * GCTRACE
    Flag controlling the display of garbage collection statistics

HELP * TRACEBACK
    Display extra information when an exception is raised

HELP * BUGS
    Known bugs in POPLOG ML


-- Timing Procedures and Efficiency -----------------------------------

REF *TIMES      --- System timing procedures

HELP *TIME      --- Timing procedures

HELP *PROFILE   --- Profiling where the system is doing the most work

HELP *EFFICIENCY
REF *FASTPROCS  --- Efficiency


-- Errors, Warning messages and Interrupts ----------------------------

The following sections give pointers to documentation on errors,
warnings, and interrupts.

See also relevant sections in HELP *CLISP, PLOGHELP *HELPFILES and
HELP *POP.


-- ... General --------------------------------------------------------

REF *LOADWARNING *SYSLOADWARNING
    Warnings when files are compiled.

HELP *MISHAP
    Summary of POP-11 error procedures.

HELP *PRMISHAP *SYSPRMISHAP, REF *VEDPRMISHAP *POP_DEFAULT_PRMISHAP
    Printing procedures for error messages

REF *POP_MISHAP_DOING_LIM
    Controls the number of procedures displayed in the "DOING" list of a
    mishap message.

HELP *POPMISHAPS
    Summary of the last mishap message.

HELP *INTERRUPT
    POP-11 interrupt procedures (default is HELP *SETPOP)

HELP *SETPOP
    Resetting the POP-11 system

HELP *WARNING
    Slightly different MISHAP procedure without HELP *INTERRUPT

HELP *PRWARNING *SYSPRWARNING, REF *NEWPRWARNING
    Procedures for indicating automatic variable declaration.

HELP *POPWARNINGS
    Variable which lists automatically declared variables

HELP *PRAUTOLOADWARN, REF *SYSPRAUTOLOADWARN
    Warnings of autoloading libraries

REF *MISHAP_CODES
    Summary of mishap acronyms.

REF * MISHAPS
    Details of mishap and warning procedures

REF * POP_FILE_WRITE_ERROR
    Procedure called when there is an error writing to a device

REF *VEDERROR *VEDENDERROR *VEDTOPERROR *VEDSYSFILEERROR
    VED error procedures


-- ... ML -------------------------------------------------------------

HELP *ERROR *Error
    General purpose error function.

HELP *WARNINGS
    Controls warnings produced by the compiler.


-- ... LISP -----------------------------------------------------------

REF *ERRORS
    Summary of LISP error mechanisms.


-- Saved Images -------------------------------------------------------

HELP *SYSSAVE, *SYSRESTORE
    Saving and restoring saved images (POP-11)

HELP *SYSSAVEINCR
    On saving part of an image

REF *SYSUTIL
    For further details

HELP *INITIAL
    Starting up and tailoring POPLOG

HELP *PARAMETERS
    Running POP-11 with parameters

PLOGHELP *SAVE, *RESTORE
    Saved images in Prolog


-- Sections -----------------------------------------------------------

HELP *SECTIONS
    General introduction

HELP *POP_SECTION
    The top-level section record.

HELP *CURRENT_SECTION
    Accessing and changing current section

HELP *SECTION_CANCEL
    How to cancel a section

HELP *SMATCH
    Using MATCHES within sections

HELP *GLOBAL
    The use of global identifiers in POP-11

HELP *VARS, *DEFINE
    Declarations in POP-11

HELP *SYSCANCEL
    Breaking the link between a word and its current identifier

HELP *SYSCANCELWORD
    Removing a word completely from the dictionary

REF *SECTIONS, REF *IDENT, REF *WORDS
    More technical details.


-- Virtual Machine ----------------------------------------------------

TEACH *VM, *POPSYS, *GC
    Introduction to Virtual machines

REF *VMCODE
    Virtual machine code

HELP *PROGLIST, REF *POPCOMPILE
    Compilation Processes and Procedures

REF *ITEMISE
    Itemisation

REF *SYSIO, *SYSUTIL
    System level I/O

HELP *POPDEVIN, *POPDEVOUT, *POPDEVERR
    Redirecting POP I/O

HELP *IO
    General I/O


-- Memory, Memory Limits, And Garbage Collection ----------------------

TEACH * GC
    Tutorial Introduction

HELP * SYSGARBAGE
    Initiating a garbage collection

HELP * POPGCTRACE
    Prints out a message when a garbage collection occurs

REF * POPGCRATIO
    Determines the weighting of garbage-collection time

HELP * POPGCTIME
    Holds the total CPU time spent on garbage collections

HELP * SYS_LOCK_HEAP
    Locks the heap

HELP * POPMEMLIM
    On setting the maximum memory size

REF * POPMEMUSED
    Holds total memory used at last garbage collection

PLOGHELP * TRIMCORE
    Prolog predicate which causes a garbage collection.

REF * POP_CALLSTACK_LIM
    Active variable specifying depth limit for procedure calls


-- Datatypes ----------------------------------------------------------

There are several types of data-structures in POP-11 (types of object
that your program can manipulate). Each type is associated with a
'dataword' and a class structure called a key. Below is a complete list
of data types available in POPLOG, together with their dataword

 Dataword        Reference           Description
 ----------------------------------------------------------------------
 XptDescriptor  REF  * XptDescriptor X Toolkit Interface Descriptor
 biginteger     REF  * NUMBERS       Arbitrary-precision integers
 boolean        HELP * BOOLEAN       The unique items in TRUE and FALSE
 complex        REF  * NUMBERS       Complex numbers
 ddecimal       HELP * DECIMALS      Double precision decimals
 decimal        HELP * DECIMALS      Single precision decimals
 device         HELP * DEVICE        Input/Output device
 dstring        REF  * STRINGS       Display strings
 external_ptr   REF  * EXTERNAL_DATA Pointers to external objects
 ident          REF  * IDENT         Identifier
 integer        REF  * NUMBERS       Simple integer
 intvec         REF  * INTVEC        Integer vector
 key            REF  * KEYS          Class keys
 nil            REF  * NIL           The unique item -nil-.
 pair           REF  * LISTS         Pairs and lists
 procedure      HELP * PROCEDURE     Procedures, closures, properties,
                                     and arrays
 process        HELP * PROCESS       POP-11 processes
 prologterm     REF  * PROLOG        Prolog terms
 prologvar      REF  * PROLOG        Prolog variables
 ratio          REF  * NUMBERS       Ratios
 ref            HELP * REFERENCES    References
 section        HELP * SECTIONS      Sections
 shortvec       REF  * INTVEC        Vector of short integers
 stackmark      REF  * POPSTACKMARK  Stackmark records
 string         HELP * STRINGS       Strings
 termin         HELP * TERMIN        The unique item in -termin-
 undef          HELP * UNDEF         Undef records
 vector         HELP * VECTORS       Vectors
 word           HELP * WORDS         Words

Other related files include:

   HELP *DATASTRUCTURES - Overview file
   HELP *CONSPROCS      - Procedures for building data-structures
   HELP *DESTPROCS      - Destructor procedures
   HELP *ARRAYS         - Multidimensional structures indexed by numbers
   HELP *MORELISTS      - Summary of list manipulating procedures
   HELP *PROCASDATA     - Procedure (This includes CLOSURES, PROPERTIES,
                           ARRAYS)
   HELP *CLASSES        - Information on user defined classes
   HELP *DEFCLASS       - Defining new record and vector classes
   HELP *BITVECTORS     - Creation of simple bit vectors
    REF *PROPERTIES     - Generalised association tables

For fuller details, see the REF files, described in REF *REFFILES.


-- ASSOCIATED DOCUMENTATION -------------------------------------------

TEACH * INDEX
HELP  * INDEX
REF   * INDEX
DOC   * INDEX



--- C.all/help/programming ---------------------------------------------
--- Copyright University of Sussex 1987. All rights reserved. ----------
