[Date Prev] [Date Next] [Thread Prev] [Thread Next] Date Index Thread Index Search archive:
Date:Mon Aug 19 08:21:10 2000 
Subject:Re: Stupid question about VED documentation files 
From:Aaron Sloman See text for reply address 
Volume-ID:1000819.02 

[NOTE CAREFULLY: To reply replace "Aaron.Sloman.XX" with "A.Sloman"]

dpeschel@eskimo.com (Derek Peschel) writes:

> Date: 19 Aug 2000 05:47:51 GMT
>
> This is a dumb question, but then I'm a complete Pop novice.

It's not a dumb question, actually. I guess I should put something
about this in the primer, when I have time.

> Looking through printed manuals (like the PostScript version of the primer)
> I see references to VED commands like this: "teach teach", "teach ved", etc.
> But looking through the files as they are stored on disk, and also in a VED
> session, I see references like this: "teach * teach", etc.  What is the
> asterisk for?

This is a relic of the days when the editor was being developed in
the early 80s before we had bit-mapped displays with mice, and the
only way to move the cursor was via keys on the keyboard. Someone
had the bright idea that a cross reference in a documentation file
had an asterisk preceding them then the keyboard sequence
    ESC n
("n" for "next") could be mapped onto a Ved procedure vednexthelp,
which would search forward to the next one.

It was already the case by then that
    ESC h
would read the item to the right of the Ved cursor and fetch the
help file corresponding to it, if possible. So with the cursor on
the asterisk here: * STRINGS, the ESC h sequence would fetch the
HELP strings file. (Upper case was mapped to lower case. Many of the
documentation files used upper case to make the cross references
stand out).

This was further generalised as follows. If one of the key- words
"TEACH", "HELP", "REF", "DOC", "SRC", "LIB" (and others which could
be added as needed) was found immediately to the LEFT of the cross
reference (before the asterisk, if an asterisk was used, which was
optional), then that key-word would determine what sort of cross
reference it was. E.g. using ESC h with TEACH * MATCHES would get
the file called 'matches' first found in the list of teach directories
(vedteachlist) whereas "HELP * MATCHES" would get the first file called
'matches' found in the list of help directories, vedhelplist.

Those lists usually overlap, so if there's no corresponding teach file
it might look for the help file. E.g. TEACH * STRINGS will actually get
you the help strings file.

The "LIB" or "SHOWLIB" keyword will invoke ved_showlib (= ENTER showlib)
and search in the list popuseslist, which contains a list of program
source directories.

The "REF" keyword (like the "ENTER ref" command) had an extra feature:
if a file was not found with the appropriate name (E.g. REF strings)
then a special index could be used to find an entry WITHIN an
appropriate REF file, (e.g. REF substring)

All this allowed Ved's online documentation and program libraries to
function as a huge self-referencing hypertext system.

If you want to know more about the mechanisms used, see
    HELP vedsysfile, HELP vedgetsysfile

For people who are used to it and become fluent with ESC h, and related
facilities, it provided a very  useful source of information about a
very large and complex toolkit. For novices it could be very confusing.
Various attempts were made to provide helpful routes into the
documentation to facilitate the learning process, but you can't learn to
drive a car or play a violin in a few days.

See: HELP documentation, HELP LIBRARIES, HELP HELPFILES,
TEACH TEACHFILES,  REF REFFILES

Incidentally a lot of the AI teach files and associated libraries that
come with poplog are out of date, and some use old, out of date, pop-11
syntax or programming style (e.g. with "vars" for local variables
instead of "lvars", and "-> y -> x" instead of "->(x, y)" for
multiple assignment).

There are many new versions of the teaching files and programs developed
in Birmingham, with associated libraries in the Free Poplog directory

    http://www.cs.bham.ac.uk/research/poplog/

e.g. in the teach/ help/ auto/ and lib/ subdirectories. The most useful
of these, at least for our teaching purposes, have been combined in the
gzipped tar file:
    bhamteach.tar.gz
which can be unpacked in the $poplocal/local/ directory.

One of the files contains a useful summary of Ved commands and key
sequences (as mapped onto the terminals we use):
    http://www.cs.bham.ac.uk/research/poplog/teach/quickved

a more extensive overview is in
    http://www.cs.bham.ac.uk/research/poplog/teach/vednotes

Both are in the bhamteach.tar.gz file.

Comprehensive documents included with Poplog are
    HELP vedkeys, REF vedcomms, HELP VEDSEARCH
and many more referred to in those files!

A further point: in the early 90s a decision was taken by the poplog
developers to replace plain ascii text files with files containing
special character sequences that Ved would interpret as indicating that
graphical characters or special fonts (bold, underlined) should be used.
These files include "character attributes" documented in REF ved_chat.

This made many of the documentation files look better in VED but spoiled
them completely for people using Emacs or other editors. I thought that
was a drastic error and have never used the new format for any of my
documentaion.

However the free poplog site contains an Emacs package for Poplog users
which provides a partial solution.
    http://www.cs.bham.ac.uk/research/poplog/emacs.tar.gz I don't know
if it can be made to work with emacs on windows.

I hope that helps.

Aaron
===
Aaron Sloman, ( http://www.cs.bham.ac.uk/~axs/ )
School of Computer Science, The University of Birmingham, B15 2TT, UK
EMAIL A.Sloman AT cs.bham.ac.uk   (ReadATas@please !)
PAPERS: http://www.cs.bham.ac.uk/research/cogaff/
TOOLS: http://www.cs.bham.ac.uk/research/poplog/freepoplog.html