HELP QUERY                                       John Williams, Nov 1990

    <ENTER> ? word
    <ENTER> ?? word

Ved commands for locating information on word.


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

  1   Introduction
  2   Terse Mode (<ENTER> ?)
  3   Verbose Mode (<ENTER> ??)
  4   Getting information on data types
  5   How to look for words that match a pattern
  6   Where does the information come from?
  7   Accessing your own documentation via <ENTER> ? and ??
  8   Futher reading


-----------------------------------------------------------------------
1  Introduction
-----------------------------------------------------------------------

    <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.

In either case, if the argument word is not given on the Ved command
line, the item to the right of the cursor is used instead.

The Ved commands <ENTER> ? and ?? replace the obsolete <ENTER> what(s).


-----------------------------------------------------------------------
2  Terse Mode (<ENTER> ?)
-----------------------------------------------------------------------

Try the command:

    <ENTER> ? member

This should cause the following to be displayed on the status line of
the current file:

    member(item, list) -> bool

This says that the procedure member takes two arguments, an item and a
list, and returns one result, bool.

Sometimes <ENTER> ? produces too much information to fit on the status
line, in which case it will be displayed in a temporary Ved file
instead. (An example is <ENTER> ? newanyproperty).

If you wish, you can force <ENTER> ? to always use a temporary file, by
setting the variable ved_??_status_display false, like this:

    false -> ved_??_status_display;


-----------------------------------------------------------------------
3  Verbose Mode (<ENTER> ??)
-----------------------------------------------------------------------

For more detailed information, try the verbose form, e.g.

    <ENTER> ?? member

This will display the following text in a temporary Ved file (named
something like info1x8347):

  REF * LISTS
  member(item, list) -> bool                          [procedure variable]
          The default value of this variable is a procedure which  returns
          true if item is an element of the list list, otherwise false.

The first line of output is a cross-reference to the source of the
information, in this case the file REF * LISTS.

The information available to the verbose form is sometimes very verbose
indeed (for example, the description of newanyproperty in REF * PROPS
occupies 69 lines). For convenience, <ENTER> ?? never displays more than
12 lines of text. If the information has been truncated, this is
indicated by the symbol "-Etc-". You can alter the maximum number of
output lines by assigning a number other than 12 to the variable
ved_??_max_lines.


-----------------------------------------------------------------------
4  Getting information on data types
-----------------------------------------------------------------------

It is often possible to get an explanation of the data type names used
in descriptions of procedures. For example, try:

    <ENTER> ? BOOL

(BOOL was mentioned in the information on member, quoted above).

The following explanation should appear on the status line:

    Boolean: true or false

The file REF * REFFORM lists many of the data type names used in the
descriptions of Pop-11 identifiers.


-----------------------------------------------------------------------
5  How to look for words that match a pattern
-----------------------------------------------------------------------

If the argument ends with a '*', e.g.

    <ENTER> ? data*

then information on all words starting with "data" will be displayed. In
this example, these would include datakey, datalist, dataword, etc.

If the argument begins with a '*', e.g.

    <ENTER> ? *data

then information on all words ending with those letters will be
displayed. In this example, these would include appdata, copydata,
mapdata, etc.

If the argument begins and ends with a '*', e.g.

    <ENTER> ? *data*

then information on all words including those letters will be displayed.
In this example, these would include appdata, class_dataword, datakey,
etc.

At present an asterisk may not be used anywhere except at the beginning
and/or end of the word.


-----------------------------------------------------------------------
6  Where does the information come from?
-----------------------------------------------------------------------

Like other documentation access commands, <ENTER> ? and ?? make use of a
search list, i.e. a list of directories in which to look for the
required information.

(Search lists are discussed in detail in HELP * SEARCH_LISTS).

The particular search list used by <ENTER> ? and ?? is kept in the
variable ved_??_list. Its standard value is the list:

    [vedreflist]

The variable vedreflist is the list of directories searched by the REF
command.

In other words, the information retrieved by <ENTER> ? and ?? comes from
the REF files.

<ENTER> ? and ?? make use of the documentation indexing system described
in HELP * MKREFINDEX.


-----------------------------------------------------------------------
7  Accessing your own documentation via <ENTER> ? and ??
-----------------------------------------------------------------------

To make your own documentation accessible via <ENTER> ? and ??, the
following steps must be taken:

    1)  The documentation must be formatted correctly.

    2)  Each documentation directory must be indexed.

    3)  The names of the documentation directories must be added to
        ved_??_list.

HELP * MKREFINDEX explains how to format and index documentation in the
correct manner.


-----------------------------------------------------------------------
8  Futher reading
-----------------------------------------------------------------------

See also:

    HELP * DOCUMENTATION    - General overview of Poplog documentation
    HELP * MKREFINDEX       - How to format and index documenation files

The procedures and variables used to implement <ENTER> ? and ?? are
described in:

    REF * DOCUMENTATION     - Procedures for locating online documents


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