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.
