HELP INCLUDE                                       James Goodlet, Nov 89
                                              Updated A.Sloman Sept 1990

LIB INCLUDE and the list POPINCLUDELIST defined therein generalise the
#_INCLUDE mechanism described in REF * PROGLIST.

A paradox which often faces programmers when trying to produce good,
modular code is how to organise shared fragments and declarations,
without resorting to global declarations.  The command

    include <filename>;

supports this objective by compiling <filename> as part of the current
compilation stream.  Thus, using INCLUDE in tandem with lexically scoped
declarations in the included files (see *LEXICAL), allows blocks of code
to be shared between any number of modules, without clogging up the main
name space.

Contrast the INCLUDE mechanism with *LOAD and *LIB, which compile files
in separate contexts.

The default filename extension for POP11 INCLUDE files is '.ph' (i.e.
with an 'h' for header appended to the normal '.p').  If no extension is
specified on a filename given to INCLUDE, the default will be used.  For
example:

    include bar;

will INCLUDE the file 'bar.ph', whereas

    include bar.p;

will INCLUDE 'bar.p'.

INCLUDE searches a list of directories contained in the user modifiable
variable POPINCLUDELIST.  If this list is not defined, the default
directory list is:
    [   '$poplib/include'
        '$poplocal/local/include'
        '$usepop/pop/lib/include'
    ]

INCLUDEing can be traced by assigning an appropriate procedure to the
user procedure variable, PRINCLUDEWARN.  This procedure takes a single
argument, which is the full filename of the file being INCLUDEd.  By
default, *ERASE is bound to this procedure, disabling tracing.  Standard
tracing can be achieved by assigning the predefined system procedure,
SYSPRINCLUDEWARN (defined in LIB INCLUDE), to PRINCLUDEWARN.

The VED procedure * VED_SHOWINCLUDE can be used to search directories in
POPINCLUDELIST in roughly the same way that VED_SHOWLIB searches
directories in POPUSESLIST. E.g. to look for the pop11_flags.ph file
do
    <ENTER> showinclude pop11_flags

If LIB VED_SHOWINCLUDE has been compiled, then cross references in help
files in the following format will work: See INCLUDE * VM_FLAGS
See also:

    HELP * COMPILE            - the normal compile procedure
    HELP * USES, * LIB        - structuring code into global modules
    REF  * POPCOMPILE         - detailed analysis of compilation in POP11
    REF  * PROGLIST/#_INCLUDE - the low-level INCLUDE mechanism
    REF  * VED_SHOWINCLUDE    - the VED facility described above

--- C.all/help/include -------------------------------------------------
--- Copyright University of Sussex 1990. All rights reserved. ----------
