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.
Select headings to return to index
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.
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.
<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.
Many of the documentation files are quite long. Several mechanisms have been provided to allow the user to search through them efficiently.
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.
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.)
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.
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.
<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.
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.
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
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
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
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.