REF DOCUMENTATION John Williams, Feb 1992
COPYRIGHT University of Sussex 1992. All Rights Reserved.
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< POPLOG DOCUMENTATION >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
This file briefly describes the procedures and variables used to
implement the Poplog online documentation system. For details of how to
use Poplog's documentation, see HELP * HELP and HELP * DOCUMENTATION.
CONTENTS - (Use <ENTER> g to access required sections)
1 Locating Documentation
2 Documentation Cross-references
3 DOC Files
4 HELP Files
5 INCLUDE Files
6 LIB Files
7 MAN Files (Unix only)
8 REF Files
9 SRC Files
10 TEACH Files
11 The HELPFOR and SHOWLIB Commands
12 <ENTER> SOURCEFILE
13 Indexing Documentation Files
14 <ENTER> ??
15 Indexing A Poplog Directory Tree
16 Obsolete Facilities
-------------------------
1 Locating Documentation
-------------------------
The following set of procedures are used to locate and edit
documentation files. They are also documented in HELP * VEDSYSFILE.
vedgetlibfilename(search_list, word, lib_name) [procedure variable]
-> filename_or_false
Uses syssearchpath to search for a file named lib_name. If the
search is successful then lib_name is assigned to the value of
the variable word, and the full pathname of the file is
returned.
If word is "vedlibname" (i.e. a library file is being searched
for), and lib_name does not include a file extension, then the
value of pop_default_type is appended to lib_name before passing
it to syssearchpath.
The search proceeds as follows. First, a subsystem-specific
search list is tried. If lib_name cannot be located there, then
the search_list given as argument is tried.
The subsystem-specific search list is determined by executing:
subsystem_searchlist(word, veddocsubsystem);
except in the case where word is "vedlibname" and lib_name has a
non-empty file extension. In this case, the subsystem-specific
search list is:
subsystem_searchlist(word, sys_fname_extn(lib_name));
vedgetlibfilename returns a vector instead of a file name when
multiple index entries for lib_name occur in the "doc_index"
subdirectory of one of the directories in the search lists
(assuming that there is no file called lib_name). Each element
of the vector is itself a vector, of the type produced by
sys_parse_doc_index_entry (see below).
vedsysfile(word, search_list, p) [procedure]
Attempts to locate and edit the documentation file named in
vedargument. search_list is a list of directories through which
vedsysfile will search (using vedgetlibfilename). If the file is
found, then its name is assigned to be the value of the variable
named word. If vedargument is empty, then the value of word is
used. The procedure p is run when the file is opened, to set up
any special defaults (if p is false, vedhelpdefaults is used).
vedargument may also contain a second argument to set
* vvedgotoplace. This must be separated from the file name by
space(s), and must be of the form /search_string or
@line_number; vvedgotoplace to is then set to the string
search_string or the integer line_number.
If no suitable file is found, then the procedure vedsysfileerror
is called, which by default signals an error.
In the case where vedargument names an identifier which is
documented in more than one REF file (in the same REF
directory), a temporary Ved buffer is created which contains
pointers to those REF files, in cross-reference format. The user
can then select the entry they prefer.
vedsysfilelog(word, string, filename_or_false) [procedure variable]
Each time vedsysfile is used to locate a piece of system
documentation, it checks whether vedsysfilelog is a procedure
with pdnargs equal to 3. If so, vedsysfilelog is applied to the
following arguments:
Argument Meaning
-------- -------
word: The name of the procedure that invoked
vedsysfile (e.g. the word "ved_help")
string: The name of the requested document.
filename: The full pathname of the document
(<false> if the document wasn't found).
The default value of vedsysfilelog is identfn, which has pdnargs
0, and is therefore ignored by vedsysfile.
vedsysfileerror(doc_type, name) [procedure variable]
Called by vedsysfile when an attempt to locate a piece of
documentation fails. doc_type is a string specifying a
documentation category, e.g. 'HELP', 'REF', 'TEACH' etc. name is
also a string, the name of the file that could not be found. By
default, vedsysfileerror prints a message of the form:
<doc_type> <name> not found - Try <doc_type> <DEFAULT>. This
procedure may be redefined by users.
doctypelist -> list [variable]
list -> doctypelist
A list containing the name of each document type (HELP, TEACH
etc) and the variable associated with each one, which contains
the default file, if no filename is given as argument to a
documentation request.
vedhelpdefaults() [procedure]
Sets up values of Ved variables for HELP and TEACH files after
calling vedveddefaults.
---------------------------------
2 Documentation Cross-references
---------------------------------
The following procedures are used to implement the cross-referencing
mechanism described in HELP * HELP.
consvedcrossref(doctype, name, gotoplace) [procedure]
Constructs a dstring representing a standard Ved cross-
reference. (This could be inserted into a Ved buffer with
vedinsertstring). doctype should be a word or string specifying
the document type (e.g. HELP or REF). name is the name of the
document. gotoplace may be a string or integer specifying a
search string or line number within the document, or it may be
false (the usual case).
For example:
vedinsertstring(consvedcrossref("help", "news", 200))
would insert:
HELP * NEWS/200
Note that the doctype and name are converted to uppercase
italics, and that the spaces around the `*' are special Ved
no-break spaces (character `\Ss`). The entire cross reference is
`active' in colour 2A.
vednexthelp() [procedure]
Searches for the next occurrence of an asterisk in the current
file.
vedprevioushelp() [procedure]
Searches for the nearest previous occurrence of an asterisk in
the current file.
vedgetsysfilepdr() [procedure]
A property table associating documentation types (e.g. "HELP",
"REF", etc) to access procedures (e.g. ved_help, ved_ref, etc).
Used as part of the documentation browsing facility. See
HELP * VEDGETSYSFILEPDR.
vedgetsysfile() [procedure]
Get appropriate documentation file for next text item in the
file, usually mapped to <ESC> h (see HELP * VEDGETSYSFILE).
This procedure just calls * ved_do_text_action with appropriate
arguments, and will therefore also execute embedded text actions
(see SHOWLIB * vedgetsysfile).
------------
3 DOC Files
------------
The DOC files are intended as hard-copy manuals. See DOC * DOCFILES.
veddocdirectory -> dir [variable]
dir -> veddocdirectory
The main DOC file directory.
veddoclist -> search_list [variable]
search_list -> veddoclist
List of directories where DOC files may be found.
veddocname -> string [variable]
string -> veddocname
The name of the most recently accessed DOC file.
ved_doc filename [ /search_string | @line_number ] [procedure]
Uses vedsysfile to search through the directories in veddoclist
for a DOC file named filename, and then reads it into Ved.
If supplied, the buffer is positioned initially at search_string
or line_number.
ved_qdoc filename [ /search_string | @line_number ] [procedure]
Quits current file, and then calls ved_doc with the given
argument(s).
doc [syntax]
Syntax word for accessing DOC files from Pop-11.
-------------
4 HELP Files
-------------
The HELP files document a large number of Pop-11 procedures, and some
library packages. Also see HELP * HELPFILES.
vedhelpdirectory -> dir [variable]
dir -> vedhelpdirectory
The main HELP file directory.
vedhelplist -> search_list [variable]
search_list -> vedhelplist
List of directories where HELP files may be found.
vedhelpname -> string [variable]
string -> vedhelpname
The name of the most recently accessed HELP file.
ved_help filename [ /search_string | @line_number ] [procedure]
Uses vedsysfile to search through the directories in vedhelplist
for a HELP file named filename, and then reads it into Ved.
If supplied, the buffer is positioned initially at search_string
or line_number.
ved_qhelp filename [ /search_string | @line_number ] [procedure]
Quits current file, and then calls ved_help with the given
argument(s).
help [syntax]
Syntax word for accessing HELP files from Pop-11.
----------------
5 INCLUDE Files
----------------
These are library files containing identifier declarations. See
HELP * INCLUDE and REF * PROGLIST.
ved_showinclude filename [ /search_string | @line_number ] [procedure]
Uses vedsysfile to search through the directories in
popincludelist for an INCLUDE file named filename, and then
reads it into Ved.
If supplied, the buffer is positioned initially at search_string
or line_number.
See HELP * INCLUDE, HELP * SHOWLIB, #_INCLUDE, popincludelist,
REF * LIBRARY.
showinclude [syntax]
Syntax word for accessing INCLUDE files from Pop-11.
------------
6 LIB Files
------------
These are program library files. See REF * LIBRARY and HELP * LIBFILES.
vedlibname [variable]
The name of the last file accessed via ved_showlib.
ved_showlib filename [ /search_string | @line_number ] [procedure]
Uses vedsysfile to search through the directories named in
popuseslist for a library file named filename, and then reads it
into Ved.
If supplied, the buffer is positioned initially at search_string
or line_number.
ved_qshowlib filename [ /search_string | @line_number ] [procedure]
Quits current file, and then calls ved_showlib with the given
argument(s).
showlib [syntax]
Syntax word for accessing library files from Pop-11.
------------------------
7 MAN Files (Unix only)
------------------------
The following procedures provide a mechanism for accessing Unix manual
files from Ved. See HELP * MAN.
vedmandefaults() [procedure variable]
This procedure is executed when a Unix 'man' file is read into
Ved via the command ved_man.
ved_man topic [procedure]
Invokes the Unix 'man' command with the argument topic given.
The manual file is read into a Ved buffer and underlining
removed, using ved_noul. See HELP * MAN.
ved_qman topic [procedure]
Quits current file, and then calls ved_man with topic as
argument.
man [syntax]
Syntax word for accessing Unix manual files from Pop-11.
------------
8 REF Files
------------
The REF files provide definitive documentation of the Poplog system. See
REF * REFFILES.
vedrefdirectory -> dir [variable]
dir -> vedrefdirectory
The main REF file directory.
vedreflist -> search_list [variable]
search_list -> vedreflist
List of directories where REF files may be found.
vedrefname -> string [variable]
string -> vedrefname
The name of the most recently accessed REF file.
ved_ref filename [ /search_string | @line_number ] [procedure]
Uses vedsysfile to search through the directories in vedreflist
for a REF file named filename, and then reads it into Ved.
If supplied, the buffer is positioned initially at search_string
or line_number.
ved_qref filename [ /search_string | @line_number ] [procedure]
Quits current file, and then calls ved_ref with the given
argument(s).
ref [syntax]
Syntax word for accessing REF files from Pop-11.
------------
9 SRC Files
------------
These are the main source files for the Pop-11, LISP, Prolog, and PML
subsystems. See HELP * SRCFILES.
vedsrclist [variable]
List of directories where SRC files may be found.
vedsrcname [variable]
The name of the most recently edited SRC file.
ved_src filename [ /search_string | @line_number ] [procedure]
Uses vedsysfile to search through the directories named in
vedsrclist for a file named filename, and then reads it into
Ved.
If supplied, the buffer is positioned initially at search_string
or line_number.
ved_qsrc filename [ /search_string | @line_number ] [procedure]
Quits current file, and then calls ved_src with the given
argument(s).
src [syntax]
Syntax word for accessing SRC files from Ved.
---------------
10 TEACH Files
---------------
The TEACH files contain tutorial style explanations of how to use Poplog
as a program development environment for AI applications. See
TEACH * TEACHFILES.
vedteachdirectory -> dir [variable]
dir -> vedteachdirectory
The main TEACH file directory.
vedteachlist -> search_list [variable]
search_list -> vedteachlist
List of directories where TEACH files may be found.
vedteachname -> string [variable]
string -> vedteachname
The name of the most recently accessed TEACH file.
ved_teach filename [ /search_string | @line_number ] [procedure]
Uses vedsysfile to search through the directories in
vedteachlist for a TEACH file named filename, and then read it
into Ved.
If supplied, the buffer is positioned initially at search_string
or line_number.
ved_qteach filename [procedure]
Quits current file, and then calls ved_teach with the given
argument(s).
teach [syntax]
Syntax word for accessing TEACH files from Pop-11.
------------------------------------
11 The HELPFOR and SHOWLIB Commands
------------------------------------
The <ENTER> helpfor and <ENTER> showlib commands allow you to find all
the documentation and library files whose names match a given word.
ved_helpfor word [procedure]
Lists all HELP, TEACH, REF and DOC files which feature word in
their name. See HELP * HELPFOR.
helpfor [syntax]
Syntax word for using the <ENTER> helpfor command from Pop-11.
ved_showlibs word [procedure]
Lists all LIB files that match word. See HELP * SHOWLIBS.
----------------------
12 <ENTER> SOURCEFILE
----------------------
The following procedures provide indexed access to procedure definitions
in the main Poplog source directories. See HELP * SOURCEFILE,
HELP * POPINDEX, and HELP * POPWHERE.
popindex(strword) -> list [procedure]
Given a word or string, popindex returns an alphabetically
sorted list of strings indicating the source files for all the
procedures defined in the system source and library directories
which contain the given item as an initial substring. Each
string in the list returned contains the procedure name followed
by a single space and the source file for that procedure, unless
the procedure is an UPDATER when "updaterof" is sandwiched
between the name and the file. See HELP * POPINDEX for examples.
popwhere(strword) [procedure]
Given a word or string, popwhere prints all the entries in the
index of system and library procedures which contain the given
item as an initial substring, indicating the source files for
all the procedures defined in the system source and library
directories
ved_sourcefile word [procedure]
Uses popwhere to locate and edit the source code for procedures
whose names match word. Only procedures defined by the syntax
word define can be located. See HELP * SOURCEFILE.
vedsrcfiledefaults() [procedure variable]
Run by ved_sourcefile when it sets the source file on screen.
Calls vedhelpdefaults, assigns <false> to vednotabs, and sets
vedfileprops to "lib" if the source code is located in a Poplog
library file, and "src" otherwise. User-assignable.
--------------------------------
13 Indexing Documentation Files
--------------------------------
The procedures described below implement a mechanism for indexing a set
of documentation files so they can be accessed by commands like
<ENTER> ? and <ENTER> ??. See HELP * MKREFINDEX.
mkrefindex(dir) [procedure]
Indexes the directory dir. An error is signalled if dir does not
have a sub-directory named "doc_index".
The following procedures are called by mkrefindex to determine where a
description starts and ends. Each may be redefined by the user.
description_hdr_start(line) -> bool [procedure variable]
Should return true if the line of text line commences a
description.
description_hdr_end(line) -> bool [procedure variable]
Should return true if line terminates the header part of a
description. (Also, by definition, true if line commences the
text part of a description).
description_hdr_name(line) -> string [procedure variable]
Given the first line of a description, should return the name
under which the description is to be indexed.
The following procedures are used to access the index:
sys_parse_doc_index_entry(string) -> vec [procedure]
Converts a string (normally a line from an index file) into a
five-element vector, containing the five components of an index
entry. string should consist of five space-separated text items.
sys_search_doc_index(name, dir, flags) -> n [procedure]
Searches the index associated with dir for entries listed under
name. Returns the number of matching entries (n), followed by
the entries themselves. Each entry is a five element vector, of
the type produced by sys_parse_doc_index_entry.
The argument flags should a positive integer, which is
interpreted as a series of bit flags controlling various aspects
of the search. Currently only the bottom two bits are inspected.
Bit 0 indicates that `*` characters at the beginning and end of
name are to be interpreted as wild cards. Bit 1 specifies
whether sys_search_doc_index should return as soon as it finds a
matching entry, or return all matching entries.
For compatibility with previous versions of Poplog, flags may
also be a boolean, with true being equivalent to 2:11, and false
being equivalent to 2:00.
--------------
14 <ENTER> ??
--------------
The commands <ENTER> ? and <ENTER> ?? use the indexes created by
mkrefindex to locate and display documentation. These commands are
documented fully in HELP * QUERY.
ved_? word [procedure variable]
ved_?? word [procedure variable]
These commands search Poplog's online documentation for an
explanation of word. The results of this search are displayed
either on the status line (ved_?) or in a temporary Ved file
(ved_??). See HELP * QUERY for a full description.
ved_??_list -> search_list [variable]
search_list -> ved_??_list
The list of directories searched by ved_? and ved_??. May
include words and identifiers, which denote "nested" search
lists. The default value is vedreflist. See HELP * QUERY.
ved_??_status_display -> bool [variable]
bool -> ved_??_status_display
If true (the default value), ved_? will attempt to display
information on the status line of the current file (if there is
enough room). Otherwise, ved_? uses a temporary Ved file, like
ved_??. See HELP * QUERY.
ved_??_max_lines -> n [variable]
n -> ved_??_max_lines
The maximum number of lines of descriptive text displayed by
ved_??. The default value is 12. See HELP * QUERY.
ved_??_tmpfile -> filename [variable]
filename -> ved_??_tmpfile
The name of the temporary Ved file used by ved_? and ved_?? for
display. The value of this variable is initially false,
indicating that no such display has taken place.
ved_??_defaults() [procedure variable]
Run when ved_??_tmp_file is first created. By default, it simply
calls vedhelpdefaults.
ved_??_search_doc_index [procedure]
ved_do_?? [procedure]
ved_try_do_?? [procedure]
System procedures used to implement ved_? and ved_??.
------------------------------------
15 Indexing A Poplog Directory Tree
------------------------------------
The library LIB * MAKE_INDEXES provides facilities for automatically
indexing all the documentation directories in a Poplog directory tree of
a "standard" shape. This involves creating indexes for use with the
<ENTER> ? and <ENTER> ?? commands (using LIB * MKREFINDEX), and separate
cross-referenced index files (like HELP * INDEX and TEACH * INDEX.) For
full information see HELP * MAKE_INDEXES.
The following, provided by LIB * MAKE_INDEXES, creates the documentation
indexes.
make_indexes(path, skip_paths, prefix, suffix, doc_types) [procedure]
make_indexes(path, skip_paths, prefix, suffix, doc_types, strip)
ROOT is the root directory of the tree which is to be indexed.
skip_paths is a list of directories which should be ignored.
prefix is the word or string which should be added to the start
of all index files created. suffix is the word or string which
should be added to the end of all index files created. doc_types
is a list of the documentation types whose indexes should be
created.
If the optional boolean arg strip is true, all documentation
files for which indexes are built are also stripped of Ved
character attributes and graphics characters.
For full details of the use of make_indexes see HELP
MAKE_INDEXES.
mi_indexing_commands -> list [variable]
list -> mi_indexing_commands
Procedures or Unix/DCL scripts for updating "doc_index"
directories.
mi_verbose -> bool [variable]
bool -> mi_verbose
Unless false, warning and trace information is displayed when
make_indexes is running.
The following variables control the form of the index files created by
the make_indexes procedure.
mi_num_columns -> integer [variable]
integer -> mi_num_columns
The number of columns available in an index file.
mi_pr_index_header(doc_type, index_name, [procedure variable]
index_path, other_indexes)
mi_pr_index_footer(doc_type, index_name, [procedure variable]
index_path, other_indexes)
The procedures used to create the top and bottom of index files
like HELP * INDEX. See HELP * MAKE_INDEXES for full information.
-----------------------
16 Obsolete Facilities
-----------------------
The following commands are obsolete and may be removed from Poplog soon.
ved_h word [procedure]
Tells you about help files on word, and lets you choose one.
Copes with minor spelling errors and truncated topics. See
ved_vh (below).
ved_vh word [procedure]
Equivalent to
<ENTER> ?? ved_word
I.e. prefixes word with "ved_" and then runs ved_??.
ved_ploghelp filename [procedure]
ved_plogshowlib filename [procedure]
ved_plogteach filename [procedure]
Obsolete commands for accessing Prolog documentation and library
files. The file HELP * SUBSYSTEMS explains how to do this.
--- C.all/ref/documentation
--- Copyright University of Sussex 1995. All rights reserved.