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.