HELP DOCUMENTATION                                Andrew Law, April 1987
                                               updated A.Sloman Dec 1988

This file describes some of the ways of finding on-line documentation
and other sources of information. It assumes some knowledge of how to
use the Ved editor.

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

  1   Introduction to Poplog on-line documentation
  2   Searching for on line documentation files
  3   ved_?/ved_??
  4   Searching within files
  5   Creating and searching for section headings
  6   Searching for cross references
  7   General Search
  8   Other sources of information
  9   Library information
 10   Source file information
 11   Associated functions
 12   Information on terminal keys and their associated functions
 13   Directory Structures
 14   Related Documentation


-----------------------------------------------------------------------
1  Introduction to Poplog on-line documentation
-----------------------------------------------------------------------

There are hundreds of online documentation files in Poplog, divided into
four main categories:

HELP - the class of general help files providing relatively short
descriptions of facilities in the three Poplog languages, the editor,
and the facilities for accessing the operating system or tailoring the
environment. Some of the HELP files describe a single facility, some
give summaries of a whole range of facilities, and some define a
sub-area or Poplog, and introduce its key concepts, e.g. the available
CONTROL facilities.

    HELP * HELPFILES     - an annotated overview
    HELP * INDEX         - an index of HELP files

REF - these files provide documentation on the language Pop-11, the core
Poplog mechanisms and facilities such as text itemisation, compilation,
arrays and records, input-output facilities, etc. There are also files
describing key features of the Poplog virtual machine, used to implement
all the Poplog languages.

    REF * REFFILES       - an annotated overview
    REF * INDEX          - an index of REF files

TEACH - these provide tutorial introductions with more verbose
explanations than those found in HELP files. They are suitable for
beginners. There are also some introductions to Artificial Intelligence
concepts and techniques, including parsing, building expert systems,
searching, etc.

    TEACH * TEACHFILES   - an annotated overview
    TEACH * INDEX        - an index of TEACH files

DOC - these are primarily intended for printing out in the form of
manuals. These may be accessed online, but this is not their primary
use, and some DOC files may require formatting before they can be read.
See HELP * DOC.

    DOC * DOCFILES       - an annotated overview
    DOC * INDEX          - an index of DOC files

It is also possible to treat some of the program libraries provided with
Poplog in the same way as documentation files.


-----------------------------------------------------------------------
2  Searching for on line documentation files
-----------------------------------------------------------------------

All categories of documentation can be accessed from inside Ved by using
the corresponding editor commands:

    <ENTER> help <filename>
    <ENTER> ref <filename>
    <ENTER> teach <filename>
    <ENTER> doc <filename>

From outside Ved, you can read HELP and TEACH documentation with the
commands

    help <filename>
    teach <filename>

given to the top-level prompt.

These commands work whichever language subsystem you are using: Pop-11,
Prolog, Common Lisp or Standard ML. Many documentation files are
applicable to all languages -- like this one -- but each subsystem also
has its own files which provide information particular to that language.
Whenever you ask for documentation, the file will be sought first in the
documentation specific to the subsystem you are currently using, and
then in the general pool. All the languages have their own HELP files,
while Prolog also has its own TEACH files and Lisp has its own REFfiles.

Sometimes you may want to read documentation from a language subsystem
different to the one you are currently using. You can do this from
inside Ved just by prefixing the command with the name of the language
you are interested in, e.g for HELP files:

    <ENTER> pop11 help <filename>
    <ENTER> prolog help <filename>
    <ENTER> lisp help <filename>
    <ENTER> pml help <filename>

Compare the results from the commands:

    <ENTER> pop11 help strings
    <ENTER> prolog help strings

Pop-11 also defines two macros for accessing Prolog documentation
directly:

    ploghelp <filename>
    plogteach <filename>

See HELP * SUBSYSTEMS for more information about Ved and language
subsystems.

Some of the documentation files have unusual names, so it is sometimes
necessary to hunt for the information you want. The index files provide
a list of most existing documentation files, see:

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

Sometimes it will not be possible to find an existing file in the index
and/or it will not be possible to guess its name. There are several
files which provide annotated overviews of domains covered by the
documentation, see:

    HELP * HELPFILES      - overview of HELP and PLOGHELP files
    HELP * LIBFILES       - overview of library files
    TEACH * TEACHFILES    - overview of TEACH files
    REF * REFFILES        - overview of REF files
    DOC * DOCFILES        - overview of DOC files

At the end of all HELP files, there should be a list of related
documentation. This will be a list of other documentation files also
relevant to the current topic. For an explanation of how documentation
files should be organised see HELP * STANDARDS.

If you know a documentation file exists but you only know part of its
name then HELPFOR can be used, e.g.

    <ENTER> helpfor <part_of_name>

This is used like the help command but it prints out a list of the files
containing <part_of_name> as a full title or as a part of the title.
<ENTER> H is a more flexible version of HELPFOR. See HELP * HELPFOR

You can read documentation from Pop-11 without using the Ved editor: see
HELP * EXPLAIN.


-----------------------------------------------------------------------
3  ved_?/ved_??
-----------------------------------------------------------------------

    <ENTER> ? <word>
    <ENTER> ?? <word>

These Ved commands search through the Poplog online documentation for
information on <word>.

The argument <word> may be the name of any program "entity" in any
Poplog language: a Pop-11 procedure or variable, a Lisp function, a
Prolog predicate, etc.

There are two forms of this command. The "terse" form, invoked by
<ENTER> ?, produces a brief summary (generally only one line). The
"verbose" form, (<ENTER> ??), gives more detailed information, if
available.

For more information, see HELP * QUERY.


-----------------------------------------------------------------------
4  Searching within files
-----------------------------------------------------------------------

Many of the documentation files are quite long. Several mechanisms have
been provided to allow the user to search through them efficiently.


-----------------------------------------------------------------------
5  Creating and searching for section headings
-----------------------------------------------------------------------

Many of the documentation files have section headings (like this file)
and a table of contents at the beginning. A mechanism has been provided
so that users can use the table of contents to move back and forth
between the table and the relevant sections of the file.

There are also Ved commands for creating new headings and for building
or re-building a table of contents, such as the one at the top of this
file. These mechanisms are therefore available in files created by users
also.

See HELP * ENTER_G for a tutorial introduction. For a more general
description of the facilities see HELP * VED_INDEXIFY.


-----------------------------------------------------------------------
6  Searching for cross references
-----------------------------------------------------------------------

Many of the documentation files contain cross references to other files.
Most cross references are marked by a "*" character. Three escape
sequences allow you to search for and invoke these cross references:

    <ESC> n - find next cross reference below this point
    <ESC> N - find next cross reference above this point
    <ESC> h - fetch cross reference that is under the cursor

E.g., if you use <ESC> n or <ESC> N to place the cursor at the asterisk
on the following line, then type <ESC> h

    HELP * STRINGS/substring

HELP STRINGS will be invoked, and the first occurrence of "substring"
located automatically. The word before the asterisk can specify a
different category of documentation, e.g.

    TEACH * VED, HELP * VED, LIB * GRAMMAR

The <ESC>h command uses the preceding category name to determine which
directory search list to use.

This facility works not only in system documentation files, but also
with cross-references found in files created by users, as long as they
are in the appropriate format. Moreover, the categories of
cross-references can be extended by users. E.g. a teacher might have a
collection of files concerned with searching, and use cross references
like

    SEARCH * DEPTH_FIRST, SEARCH * BREADTH_FIRST

HELP * VEDGETSYSFILE explains in more detail how the <ESC> h key
sequence works, and how users can extend the categories of
cross-references that it can handle. (The mechanism is partly like a
"hypertext" mechanism, but works on ordinary VDUs as well as bit-mapped
screens.)


-----------------------------------------------------------------------
7  General Search
-----------------------------------------------------------------------

A more general search mechanism is provided in Ved. This allows users to
search for any strings and substrings (possibly with "wild cards" in
them) in the current file. For full details see:

    HELP * VEDSEARCH

The general search facility can be combined with the cross reference
invoking mechanism mentioned above to allow the user to invoke a target
file and place the cursor at a specified position in the file. For
example, <ESC> h when the cursor is above the "*" character in the
following line;

    HELP * VEDCOMMS /ved_

will invoke HELP * VEDCOMMS and place the cursor at the first occurrence
of the string 'ved_'. Some documentation files contain cross references
of this form.


-----------------------------------------------------------------------
8  Other sources of information
-----------------------------------------------------------------------

Some of the information you require may not be in a documentation file.
You may need to know how a system procedure or a library procedure is
defined. The following facilities are provided in these cases.


-----------------------------------------------------------------------
9  Library information
-----------------------------------------------------------------------

    <ENTER> showlib <lib_file_name>

SHOWLIB is both a Pop-11 macro and a Ved command, for reading program
library files into a Ved buffer. See HELP * SHOWLIB to view libraries
from other languages, prefix the SHOWLIB command with the language name,
as described above for HELP files. For example:

    <ENTER> prolog showlib <lib_file_name>
    <ENTER> lisp showlib <lib_file_name>

There's also a Pop-11 macro

    plogshowlib <lib_file_name>

for reading Prolog library files. See HELP * PLOGSHOWLIB. For more
information on libraries see HELP * LIBFILES.


-----------------------------------------------------------------------
10  Source file information
-----------------------------------------------------------------------

For users with source licences, system sources can be accessed using the
command:

    <ENTER> src <filename>

The Pop-11 macro SRC, and the Ved <ENTER> SRC command take <filename>,
and look for that file in the Pop-11 system source directory. The
relevant file is then read into the editor, in protected mode. This
enables system sources to be examined, although not all sources are
supplied to users without a source licence.

    <ENTER> sourcefile <procedure_name>

This looks through an index of libraries and source files to find a file
where a procedure with name <procedure_name> is defined, and shows the
source on the screen. If you do not have a source library, the core
system sources will not be available. However library sources will be,
so this command may be useful in some cases.

-----------------------------------------------------------------------
11  Associated functions
-----------------------------------------------------------------------

    popindex(<word>|<string>);

Given a word or a string, this returns a list of strings indicating the
source files for system procedures which contain the given item as an
initial substring.

See HELP * POPINDEX


    popwhere(<word|string>);
    <ENTER> popwhere <item>

Given a word or a string this prints all the entries in the index of the
system and library procedures which contain the item as an initial
substring indicating the sourcefiles for all the procedures defined in
the system source and library directories.

See HELP * POPWHERE


    wordswith(<word|string>) -> <list of dictionary words>

This procedure returns a list of words from the dictionary that contain
<string> as a substring (part of the name). If the string is empty, it
will print out all the words in the dictionary, words in your own
programs will be included. Words in library programs that have not been
loaded will not be included. It is usually best invoked using the pretty
print arrow "==>", e.g.

    wordswith('word') ==>
    ** [Lisp_keyword_package
    class_dataword consword dataword destword isword subword
    syscancelword undefword vedconvertword vedvarskeywords vedwordleft
    vedwordleftdelete vedwordright vedwordrightdelete vvedworddump word
    word_identifier wordright wordswith]

See  HELP * WORDSWITH


-----------------------------------------------------------------------
12  Information on terminal keys and their associated functions
-----------------------------------------------------------------------

You can find which procedure is currently mapped onto a key or key
sequence by Ved if you give the command:

    <ENTER> hk

See HELP * VEDKEYS


-----------------------------------------------------------------------
13  Directory Structures
-----------------------------------------------------------------------

The diagram below represents the major Poplog directories related to
finding on-line information. The first subdirectory of a directory is
indicated by a "---" with further subdirectories directly below the
first.

    usepop --- pop --- help
                       teach
                       ref
                       doc
                       src
                       lib ---  database
                                flavours
                                turtle
                                ved
                                demo
                                auto
                                data
                                lib
                       lisp --- help
                                ref
                                auto
                                src
                       plog --- help
                                teach
                                lib
                                auto
                                src
                       pml ---  help
                                lib
                                src

Help subdirectories contain help files specific to the part of the
system they are located in, hence $usepop/pop/plog/help contains the
Prolog help files. The same applies to ref teach and doc subdirectories
(see above for a description of the differences between these types of
file).

Auto subdirectories contain autoloadable libraries - that is files
containing programs/data which are automatically loaded but only when
needed - say on the invocation of some command.

Lib directories contain non autoloadable library files

Src directories contain sourcecode (defining built in functions
compilers etc. though they ar not supplied to all users).

For more information on the Poplog directory structure see DOC * SYSSPEC


-----------------------------------------------------------------------
14  Related Documentation
-----------------------------------------------------------------------

For annotated overviews of domains covered by Poplog documentation see:

    HELP * HELPFILES
    TEACH * TEACHFILES
    PLOGHELP * HELPFILES
    PLOGTEACH * TEACHFILES
    DOC * DOCFILES
    REF * REFFILES

For lists of documentation files in Poplog see:

    HELP * INDEX
    TEACH * INDEX
    PLOGHELP * INDEX
    PLOGTEACH * INDEX
    DOC * INDEX
    REF * INDEX

For review of new Poplog features and associated documentation see:

    HELP * NEWS


--- C.all/help/documentation
--- Copyright University of Sussex 1991. All rights reserved.
