DOC VEDMANUAL                            Updated Aaron Sloman March 1990

NOTE:
This was originally  intended to be  a printable file.  However, it  got
corrupted a few years  ago, and the original,  from which the  formatted
version was derived,  has been lost.  So it has  been re-formatted  in a
form that makes it easier to  access online, and some minor  corrections
added to bring it up to date.  There are several REF files that  provide
more complete and  up to date  overviews of part  of the information  in
this manual. However, for the present this manual retains its usefulness
for anyone wishing to program VED, until a completely new version can be
provided.

Readers are assumed to have the basic knowhow provided by the tutorial
files: TEACH * TEACH, TEACH * VED, TEACH * BUFFERS.

Useful REF files include
    REF * VED,  * VEDCOMMS,  * VEDPROCS,  * VEDTERMINALS,  * VEDVARS

Useful HELP files include
    HELP * VED, * TERMINAL, * VEDCOMMANDS, * VEDSEARCH, * DOCUMENTATION
    HELP * VEDKEYS, * VEDNEWKEYS, * LOGICAL_KEYS, * VEDSYSFILE

 -----------------------------------------------------------------------

                          VED Reference Manual
                                   by
               Chris Slymon, Aaron Sloman and John Gibson
                         (original version 1983)

               School of Cognitive and Computing Sciences
                         University of Sussex
                          Brighton, BN1 9QH


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

 --  1.0  INTRODUCTION
 --  2.0  STARTING VED
 --  2.1         Entering from Monitor Level
 --  2.1.1       Starting VED on VMS Systems
 --  2.1.2       Starting VED on UNIX Systems
 --  2.2         Starting VED from  within The Poplog System
 --  2.2.1       Editing Files
 --  2.2.2       Examining Documentation And Library Files
 --  3.0  OVERVIEW OF VED PROCESSING
 --  3.1         Initialisation Procedures
 --  3.2         Overview of VED process
 --  3.3         VED top level procedure - vededitor
 --  3.4         VED's interaction manager -vedprocess-
 --  4.0  AUTOMATIC TERMINAL SELECTION
 --  5.0  FILENAMES
 --  5.1         Filename Length
 --  5.1.1       VMS Systems
 --  5.1.2       Version Numbers in VMS
 --  5.1.3       Directories in VMS
 --  5.2         UNIX
 --  5.2.1       Multiple Versions
 --  5.2.2       Directories
 --  6.0  FILE ACCESS
 --  6.1         File protection on VMS Systems
 --  6.2         Unix Systems
 --  7.0  COMMAND EXECUTION
 --  7.1         Character Table Mechanism
 --  7.2         Tables:  Stucture And Access
 --  7.3         Tables:  Alteration
 --  7.4         Command line interpretation
 --  7.5         Command Buffer
 --  7.6         Defining New Commands
 --  7.6.1       Autoloading
 --  7.6.2       Error Handling And Messages
 --  7.6.3.      Error Handling Procedures
 --  7.6.4       Debugging Ved Procedures
 --  8.0  REPRESENTATION
 --  8.1         Text
 --  8.2         Tabs
 --  8.2.1       Vednotabs
 --  8.2.2       Vedhardtabs
 --  8.3         Variables
 --  9.0  BUFFERS
 --  9.1         File Record Maintenance
 --  9.2         Manipulating Buffer Records
 --  9.3         Manipulating arbitrary text blocks
 --  10.0  WINDOW SIZE
 --  10.1        Window Position
 --  10.2        Aligning The Screen
 --  10.3        Putting Files On Screen
 --  11.0  INPUT AND OUTPUT
 --  11.1        Interaction with the terminal
 --  11.2.       Input
 --  11.3        Output to VED buffer or screen
 --  11.3.1      Output to screen
 --  11.3.2      Printing in the editor
 --  11.3.4      Suppressing output to the screen
 --  11.3.5      Refreshing and updating the screen
 --  11.3.6      Screen Control
 --  11.3.7      Graphics
 --  11.4        Files in VED
 --  11.4.1      Reading files from disk
 --  11.4.2      Writing files to disk
 --  11.4.3      Disk Quotas
 --  11.4.4      Procedures For Writing To Disc
 --  11.4.5      Automatic Writing Of Files
 --  11.4.6      Input from VED buffer to program
 --  11.4.7      Output To VED Buffer
 --  11.5.1      Break Mode
 --  11.5.2      Character Insertion
 --  12.0  STATIC MODE
 --  13.0 CURSOR POSITIONING
 --  13.1        Procedures For Changing The Cursor Position
 --  13.2        Syntax Directed Moves
 --  13.3        Testing The Edit Position
 --  13.4        Position Stack Commands
 --  14.0  MARKED RANGES
 --  15.0  DELETE COMMANDS
 --  15.1        Yanking: retrieving deleted text
 --  15.2        Moving And Copying Text
 --  16.0  COMPILE FROM BUFFER COMMANDS
 --  16.1        Compiling From Disc Files
 --  16.2        Compilers
 --  16.3        Compiling Buffers
 --  16.4        Compiling Sections Of The Buffer
 --  16.4.1      Output
 --  16.4.1.1.   Error Messages
 --  16.4.1.2    Interactive programs
 --  16.5        PROLOG Compilation
 --  16.6        Other Languages
 --  17.0  LEAVING VED
 --  17.1        To VED
 --  17.2        Quitting to Poplog
 --  17.2.1      Procedures For Returning Control To Poplog
 --  17.3        To DCL (VMS) or SHELL (Unix)
 --  18.0  SEARCH AND SUBSTITUTE COMMANDS
 --  18.1        vvedsrchstring
 --  18.2        ved_search
 --  18.3        ved_backsearch
 --  18.4        vedtestsearch
 --  18.4.1      vedlocate
 --  18.4.2      vedbacklocate
 --  18.5        Search Strings
 --  18.6        Examples
 --  19.0  COMBINED SEARCH AND SUBSTITUTION COMMANDS
 --  19.1        Interactive Substitution
 --  19.1.1      Replacement Strings
 --  19.1.2      Examples
 --  19.2        Non-interactive Substition
 --  20.0  MISCELLANEOUS PROCEDURES
 --  20.1        Compilation
 --  20.2        Deletion
 --  20.3    Interactive Definition Commands
 --  20.4        ved_dk
 --  20.5        Writing To Disk
 --  20.6        Text Formatting
 --  20.7        Case transformation
 --  20.8        Further ENTER commands
 --  20.9        Text Input Functions
 --  20.10       Pop-11 Format Insertion
 --  21.0  APPENDIX 1: Some important VED variables
 --  22.0  APPENDIX 2: Variables associated with each buffer
 --  INDEX

1.0  INTRODUCTION
-----------------

VED  is  a  display-editor  developed  for  the  Poplog  system  at  the
University of Sussex. It combines a powerful set of basic mechanisms and
facililities making  it possible  to extend  indefinitely the  range  of
commands available.  It  can  work  either  on  a  "dumb"  VDU  or  on a
sophisticated workstation, with either the Poplog Window Manager or  the
X windows system.


VED contains many features not normally found in combination:

   a)  Several  files  may  be  edited  and  displayed  on  the   screen
   simultaneously.

   b) Cursor movement is not confined to the text areas.

   c) Cursor positions can be stored and returned to later.

   d) The screen can scroll horizontally (left and right) to accommodate
   lines that are longer than the screen width.

   e) In-built  syntatic  knowledge  allows  compilation  of  individual
   procedures, syntax-directed searches, etc.

   f) Text and program formatting facilities are provided.

   g) Editing commands typed on the 'command line' are stored and may be
   repeated without retyping, or edited to correct mis-spellings etc.

   h) A portion of a  file may be marked and  the marked range taken  as
   input to a program, or as  commands to a command interpreter.  Output
   may be either interleaved with the commands in the same file, or sent
   to a different file displayed on the screen. So, for example, a  file
   in the editor may function as  a complete log of an interaction  with
   some program, and may subsequently be edited, saved on disc, etc.

   i) The editor can provide a window for interacting with the shell  on
   Unix systems or with  DCL on VMS. This  enbles commands to be  edited
   and redone, and output comes into the editor buffer.

   j) Editor subroutines  may be  accessed from  user programs,  thereby
   enabling VED to  be used  as a general  purpose terminal  independent
   user interface that can  be read and typed  into by human users,  and
   can be  read and  printed into  by programs.  In particular  VED  can
   produce a simple character-based graphical facility.

   k) In combination with search lists and a built in cross  referencing
   mechanism, VED  can  provide  a  hypertext-like  browser  for  online
   documentation  and   program  libraries.   Different  categories   of
   documentation are catered for, and users can add new libraries in the
   basic categories or extend the documentation categories.


VED is written in Pop-11,  an AI language similar  in power to LISP  but
with a syntax  more like PASCAL.  All the editor  procedures are  Pop-11
system procedures  and are  available  to the  user. Similarly  all  the
editor data structures are Pop-11 data structures (strings and vectors).
This allows users who wish to extend  or tailor the editor to their  own
requirements considerable flexibility.

This manual attempts to  explain the internal mechanisms  of VED and  to
describe the range of  VED procedures that  are available. Some  details
concerning VED are  only summarised  here, with pointers  given to  more
elaborate online documentation in Poplog HELP or REF files.

Some Pop-11  procedures are  described in  detail, but  the reader  will
normally be  referred to  the comprehensive  (and labyrinthine)  on-line
help system for information on Pop-11. (See HELP * POPREFS for books  on
Pop-11.)

Some details are operating system specific, either VAX-VMS (tm) or  UNIX
(tm). Poplog runs on a variety  of Unix operating systems. Also some  of
the facilities depend on whether the Poplog Window Manager is in use, or
the X Windows  system. See REF  * VEDTERMINALS for  more information  on
terminal types and how they are recognized by VED.

The editor is under  continuous development. Enhancements are  announced
in the online HELP * NEWS file.

All commands, procedure names, and VED variables are in lower case,  and
a few in a mixture of upper and lower case. In order to make them  stand
out in the text some identifiers may be presented in upper case. In most
cases hyphens  are used  instead,  as in  -vedsetwindow- the  name  of a
procedure.

Some of the VED functions have "logical" names. A partial list is  given
in HELP * LOGICAL_KEYS


2.0  STARTING VED
-----------------

2.1         Entering from Monitor Level
---------------------------------------

For Poplog  users, the  login procedure  will usually  define a  command
"ved" that enables the editor to  be called directly from monitor  level
e.g. to start editing  a file called 'change.me',  users would type,  to
DCL on VMS or the shell on Unix:

    ved change.me

The mechanisms  used for  invoking Poplog  in this  and other  ways  are
described in REF  * SYSTEM  and HELP *  PARAMETERS. The  details of  the
initialisation process, (e.g. compiling  user setup files called  init.p
and vedinit.p) are described below.


2.1.1       Starting VED on VMS Systems
---------------------------------------

The command for running VED must be defined as a 'foreign' command, to
enable  arguments  to  be  passed  to  the image.  This can be done in
either the system's or user's login.com file:

    ved :== $usepop:[pop.pop]pop11 """sysinitcomp(); ved

The three quotes  are DCL string  notation and USEPOP  is the  logical
name for  the home  device of  the [POP...]  directory tree.  See  the
Poplog file $USEPOP:[POP.COM]POPENV.COM and the Poplog Administrator's
Guide for more information.


2.1.2       Starting VED on UNIX Systems
----------------------------------------

The UNIX system works in a similar fashion  using   shell  environment
variables to supply the arguments. See the files

    $usepop/pop/com/poplog
    $usepop/pop/com/popenv

The directory for Poplog executable  images ($popsys) should be  added
to the environment variable PATH. This directory should also contain a
link from a file VED to the Pop-11 image.

The system interprets the name X  under  which  it  is  run  from  the
translation  of  the environment variable "pop_X".  If a translation is
found, it replaces arg0 and  the  other  arguments  are  then  shifted
'right' one place, arg0 becomes arg1, etc.

The environment  variable  popved should  then  be defined  as  it  is
(implicitly) in $usepop/pop/com/popenv

        setenv popved ":sysinitcomp();  ved "


2.2         Starting VED from  within The Poplog System
-------------------------------------------------------

The commands for  entering VED  from within  Poplog are  all defined  as
Pop-11 macros  or  as  special  commands  defined  in  the  other  Poplog
languages: Prolog, Lisp and ML.

These  commands  initialise  the  editor  in  slightly  differing   ways
depending on whether  VED is to  be used for  creating and editing  user
files (using the "ved" command),  or for examining the system's  library
and on-line  documentation  files  (using  one  of  "showlib",  "teach",
"help", "ref" or "doc").

The reader is referred to a later section for advice on the  treatment
of filenames.

2.2.1       Editing Files
-------------------------

Once VED is running  it maintains a  list of current  files in a  Pop-11
list called -vedbufferlist-. There will usually be one or more of  these
files displayed in a window on the terminal, though if control has  been
temporarily handed back to Pop-11 or another language the files will  be
invisible. It  is possiible  to have  more files  in the  list than  are
currently displayed. In particular on simple VDUs there will normally be
only one  or two  files displayed,  though with  window managers  it  is
possible to display each  separate VED file in  a different window.  The
library program described  in HELP  * WINDOWS  shows how  the number  of
files displayed at  once on  a VDU screen  can be  increased beyond  the
normal maximum of 2.

No matter how many  different files are displayed  there will always  be
one file which is the "current" file, and this one is the first file  in
-vedbufferlist-.

Each file is represented by  a number of attributes,  34 of them at  the
time of  Poplog  Version 14,  and  when  a file  becomes  current  these
attributes are assigned to Pop-11 global variables, including -vedline-,
-vedcolumn-, -vedlineoffset-, -vedcolumnoffset-, -vednotabs-, etc.

The Pop-11 macro VED should be used to edit or create files with VED

    ved <filename>

Similar commands are available from other Poplog languages, as explained
in the  Poplog User  Guide and  the VED  User Guide.  The "ved"  command
searches for the named file, in the directory specified in the  filename
or, if no  directory is part  of the  filename then it  searches in  the
current  directory  and  places  it  on  the  screen  if  it  is  found.

Information about extending the list  of directories where VED  searches
is described in HELP * VEDSEARCHLIST

If no filename is given the  filename held as the value of  -vedvedname-
is used. -vedvedname- initially has the value 'temp.p' but each call  of
VED with a filename updates -vedvedname- so that it always refers to the
most recently edited file, if one exists.


The procedure -vedveddefaults- is called by VED every time a new file is
read in to the buffer. This  is initially equal to -identfn-, a  procedure
which does nothing, but may be altered by the user to produce  different
default  values  for   VED  variables,  e.g.   to  set   -vedwriteable-,
-vedbreak-, or -vedcompileable-, depending on the filename. In  addition
the mechanisms described in HELP *  VEDFILETYPES can be used to  control
initialisation of VED buffers.


E.g.  -vedveddefaults- can be defined to make -vednotabs FALSE  for  '.p'
files (this makes VED convert leading spaces to tabs on output).

    define vedveddefaults();
        not(sysisprogfile(vedcurrent)) -> vednotabs
    enddefine;

-vednotabs- is one of several VED variables associated with each file.


2.2.2       Examining Documentation And Library Files
-----------------------------------------------------

The TEACH, HELP, DOC and REF macros can be used to examine the  Poplog
systems on-line documentation files with VED e.g

    ref words
    help vars

The SRC and SHOWLIB macros can be  used  to  examine  files  from  the
Poplog systems source and program libraries with VED e.g

    showlib showlib


All  these  commands  are  all  defined  in  terms  of  the  procedure
-vedsysfile-.  This requires three arguments:

    1) a word whose valof is the filename.
    2) a list containing a directory path to be searched for the file.
    3) an initialisation procedure to be run before editing commences.

E.g.  the TEACH command, which enables  the  user  to  examine  simple
instruction files for computer novices, is defined as

        vedsysfile( "vedteachname", vedteachlist, vedhelpdefaults)

-vedteachname- is the variable holding the name of the TEACH file to  be
examined,  either  a user-supplied filename or a system default (which
is usually either an index or instruction file).

The default name is updated in such  a way that it always refers to  the
most recent TEACH  file or  the system  default. When  quitting a  TEACH
file, VED searches the  current list of files  being edited for a  TEACH
file and if one exists, makes that the value of -vedteachname-.

The default name variables are all of the same form, e.g.  -vedsrcname-,
-vedrefname-. See REF * VEDVARS.

-vedteachlist- is the  list  of  directories  to  be  searched looking
for the specified file, when the "teach" command is used.

The search  procedure is  -vedgetlibfilename-.  This takes  a  directory
list, a default filename and a filename. It searches the directories  in
the list till it  finds a file  of the given name  and returns the  full
path name of the file, also assigning that name to be the new valof  the
default filename, e.g.

    vedgetlibfilename(popuseslist,"vedlibname",'flatten.p')

returns popautolib:flatten.p and makes this the valof (vedlibname).

The directory lists may be altered by the  user  to  include  personal
libraries  or  exclude some system directories.  The initial lists are
arranged so that the  "local"  directories  are  searched  before  the
system directories.

The initialisation procedure  -vedhelpdefaults- is  called every  time a
new file is read in to the buffer. This puts VED into a  write-protected
mode, preventing accidental corruption of the system files.


3.0  OVERVIEW OF VED PROCESSING
-------------------------------

3.1         Initialisation Procedures
-------------------------------------

On entry to both the Poplog system and  VED  an  attempt  is  made  to
compile   certain   initialisation   files   and   run  initialisation
procedures.  This enables users  to  define  their  own  utilities  to
extend  VED  and  to  alter  default  settings of editor variables.  A
listing of the default values for VED variables is in Appendix 1.

On entry to the Pop-11 system an attempt is made to  compile  the  file
init.p.   from  the  POPLIB  directory.   POPLIB  is a user-assignable
logical name/environment variable that should  refer  to  a  directory

that be used for the users library files.  The default assignment will
usually be the user's login directory.

If init.p is NOT found in POPLIB, Pop-11  attempts  to  compile  init.p
from the current directory.

When VED is first called,  it  first  attempts  to  compile  the  file
vedinit.p  firstly  from  POPLIB,  and  failing that, from the current
directory.

It then runs the user definable procedure -vedinit-. This can be defined
in the user's init.p or vedinit.p but defaults to -identfn-, which  does
nothing.

Whenever  a  new  file  is  created,  or  read  in  from   disk,   the
user-definable  procedure -vedveddefaults- is run (default value is also
-identfn-), unless the file is a system library file, e.g.  a  HELP,  or
TEACH,  or  SHOWLIB file (see above), in which case -vedhelpdefaults- is
run. In addition, after running -vedveddefaults- VED runs

    vedsetfiletypes(vedfiletypes)

where -vedfiletypes- is  a user definable  mapping from a  path name  to
initial values of VED variables associated with the file.
 (See HELP * VEDFILETYPES).

After the file has been read in but before it is set on the screen, the
user-definable procedure -vedinitialise- (with no arguments) is run.

Finally if the new VED  buffer is to be made  visible on a VDU then  the
procedure -vedinitfile- (with no arguments) is run. It is also run every
time a user file is set on the screen for editing, even when it has been
in the editor for some time.

The variable -vedfileprops- is associated with the  'current'  file  and
may  be  used by user procedures, e.g.  to record that -vedinitfile- has
been run (this would enable VED to behave differently the first time a
file is edited) .  The default value of -vedfileprops- is FALSE.

3.2         Overview of VED process
-----------------------------------

The following chart summarises the whole process of running VED,
including initialisation:

          MONITOR LEVEL
            |
            V                     Compile init.p
          ENTER Poplog
            |
            V
            |
          ENTER VED
            |                   Compile vedinit.p
            |                          &
            V                     Run -vedinit-
            |               Initialise terminal setup
            |
          START LOOKING FOR FILE (using search list) <-----------*
            |                                                    |
          FOUND FILE                                             |
            |   Run vedveddefaults, and use vedfiletypes         ^
            V                                                    |
          READ IN FILE (or create new empty one)                 |
            |                                                    |
            V   Run vedinitialise                                |
            |                                                    |
          PUT FILE ON   Run -vedinitfile-                        |
           SCREEN                                                |
            |                                                    |
            V                                                    ^
          DO EDITING    Run -vedprocess-                         |
            |        (May include editing several  new files)-->-*
            V         Repeatedly runs -vedprocesstrap- and
            |           -vedcommandtrap-
            |
          QUIT A FILE   Run -vedvedquitfile-
            |
            V
          QUIT VED      Return to Pop-11, Prolog, Lisp or ML
            |          (Return to VED with "ved <name>" command)
            V
            |
          QUIT POPLOG   Runs -vedpopexit- -popexit-


This chart does not include the direct invocation of VED procedures
by user programs, which can happen either inside or outside VED.

Whenever a large init.p  or vedinit.p has to  be compiled, the use  of a
saved image containing the modified VED  will save time. The HELP  files
SYSSAVE and SYSRESTORE explain how to save and restore images.


3.3         VED top level procedure - vededitor
-----------------------------------------------

When VED is running this is in the context of the procedure -vededitor-,
which is called with two arguments

vededitor(<defaults procedure>, <filename>)

    There are two cases  to consider, depending  whether VED is  already
    running (detected by testing whether -vededitor- is TRUE)

    (a) If already in VED then  -vededitor- simply gets the file,  using
    the defaults set up by  the first argument and -vedfiletypes-,  i.e.
    it runs
        vedgetfile(<defaults procedure>, <filename>)

    (b) If it is not already in VED then -vededitor- calls -vedsetup- to
    initalise VED, and starts up  VED, including switching to raw  mode.
    It gets the ved  file, as above, does  anything necessary to  inform
    the window manager that  it has started, then  calls a procedure  to
    run the interaction with the terminal:

        vedprocess()

    If this ever exits then the screen is reset to non-raw mode, and any
    tidying up of windows is done.


3.4         VED's interaction manager -vedprocess-
--------------------------------------------------

This procedure  sets  up some  of  the environment  for  VED,  including
redefining  -interrupt-  to  be  -vedinterrupt-  and  -prmishap-  to  be
-vedprmishap-.

It then repeatedly cycles round a loop, reading in characters from the
terminal and taking action depending on what is typed in.

On each cycle, it tidies up the screen and the status line if necessary,
calls a user-definable procedure of no arguments called -vedprocesstrap-
and then reads in enough characters to identify a command.

This task  is  done  by  the  procedure  -vedprocesschar-,  also  of  no
arguments.

-vedprocesschar- repeatedly reads input via -vedinascii- which returns a
character or procedure, assigned to -ved_last_char-

If ved_last_char is  a procedure it  is obeyed, and  control returns  to
-vedprocess-.

If ved_last_char is a character, then vedgetproctable(ved_last_char)  is
used to read in more characters until a recognizable character  sequence
has been found. This makes use of the character tables  -vednormaltable-
-vedescapetable- and their sub-tables, as described below. The result of
reading in a sequence of characters should be that a procedure is  found
which is then  run. In  many cases there  will simply  be the  procedure
-vedinsertvedchar-, which takes no arguments and simply does:

    vedcharinsert(ved_last_char)

I.e. the character typed in is put in the VED buffer.

If the  ENTER  key is  pressed,  then  the character  sequence  will  be
recognised as  requiring  the  procedure  -vedenter-  to  be  run.  This
transfers the  cursor to  the status  line (command  line) and  allows a
command to be built up. Many  of VED's procedures have to check  whether
they are being invoked  from the status line  or not, using the  boolean
variable -vedonstatus-. Commands on  the status line  go into a  special
VED buffer, and the visible command line is just an ordinary VED  window
showling one line of that buffer.

One procedure  that  has a  different  action  on the  command  line  is
-veddocr-, the  procedure  associated with  the  RETURN key.  In  normal
circumstances -veddocr-  just inserts  a  line break.  If  it is  in  an
"immediate mode" VED file as described in  HELP * IM, then it hands  the
current line to the compiler associated with that file. If invoked on
the status line, however, -veddocr- attempts to get the command obeyed.

It does this by running  the procedure -veddocommand-. This  essentially
has to  work  out  what  command is  intended.  Some,  like  the  search
commands, are  recognized  directly  as  built in,  but  others  can  be
interpreted as commands  to run user-defined  or other procedures  whose
names start "ved_" and end with the command name. Details are  described
below in the section on Command line interpretation, and also in

    HELP * VEDCOMMANDS

The user definable procedure of no arguments, -vedcommandtrap-, is run
just before each command.

Further details of all these processes are described below.


4.0  AUTOMATIC TERMINAL SELECTION
---------------------------------

The initial state  of VED  is dependent  upon the  terminal being  used.
Different terminals require different  command sequences to control  the
screen etc. Selection between terminals may be done automatically on the
first call of VED.  The mechanisms were  drastically revised for  Poplog
Version 14.

Details may be found in REF * VEDTERMINALS  and HELP * TERMINALS.

Further information about initialisation sequences can be found in
    REF * SYSTEM and HELP * INITIAL.


5.0  FILENAMES
--------------

This section describes  the  treatment  of  filenames  by  the  Poplog
system, in particular some possible side effects of the interface with
particular operating systems.


5.1         Filename Length
---------------------------

Whilst there is no limit to the length  of  filenames  within  Poplog,
operating systems tend to impose a limit on filename length.  Whenever
an attempt is made to access a file whose Poplog "name" is longer than
the  host  operating systems limit, the Poplog file handling utilities
will truncate the name to an acceptable length - a process  which  may
have unforseen side effects.

E.g.  on a system that accepts 8 character filenames, with an optional
file type, the command

    :ved longfilenumberone.p

will result in VED reading or creating the file LONGFILE.P.   This  is
the same file that would be edited with the command

    :ved longfilenumbertwo.p

To avoid confusion it is better, if possible, to restrict filenames to
the length allowed by the host operating system.

See also the discussion  of  autoloadable  files  in  the  chapter  on
command mechanism.


5.1.1       VMS Systems
-----------------------

VAX-VMS allows filenames to contain up to 39  alphanumeric  characters
with  a  file  type of  up to 39 characters and a version number, e.g.

    verylongfilename.longfiletype;32

File names that are longer than 39 characters will be truncated to the
initial  39   characters.

VAX-VMS allows underscore characters (_), in filenames in addition  to
alphabetic and numeric characters.

Truncation of file names and file types is done by the procedure
SYSFILEOK, described in REF * SYSUTIL/sysfileok


5.1.2       Version Numbers in VMS
----------------------------------

VED can be used to edit specific versions of a file if supplied with a
version number.  E.g.

    :ved file.lsp.2

Subsequent attempts to write this file to disc may fail if  a  version
of  the file exists with a version number that is one greater than the
currently edited file, e.g.  FILE.LSP.3.

Renaming the file to the current name, without the version number will
allow the file to be written.


5.1.3       Directories in VMS
------------------------------

Directory names  are  not  truncated.  Attempts  to  access  files  in
non-existent directories,  or  from  directories with  more  than  the
permitted number of characters in the name will produce an error.


5.2         UNIX
----------------


Non-Berkeley type UNIX systems  allows filenames to  contain up to  14
characters. Any user defined fields e.g. file types or version numbers
must  be  included  in  these  14  characters.  FILENAME.EXT.1  is  an
acceptable filename but FILENAME.EXT.12 is not.

Poplog asumes that filenames on Unix systems contain only two  fields,
file-name  and  file-type,  separated by a full-stop e.g.  file1.foo -
version  numbers  are  not  supported,  old  versions  of  files   are
distinguished  by  `-` characters appended to the end of the file name
(see below).

File names  that are  longer  than 14  characters will  be  truncated.
Whilst its length permits, only  the file-name will be truncated,  the
file-type will not be altered. E.g. LONGFILENUMBERONE.PLJ- will become
LONGFILE.PLJ-

As Berkeley-type  UNIX systems,  e.g. SUNOS,  Dynix and  HP-UX 6.5  or
later allow  very long  file  names, VED  will  not normally  need  to
truncate.

A dollar sign at the beginning of a filename signifies that  the  next
word  is an environment variable, e.g.  $poplib/FOO refers to the file
FOO in the user's pop-library directory.

Poplog allows filenames containing the cshell metacharacters \, $,  ",
(,  [,  !.   The shell escape character (the backslash \) must be used
when referring to these files from  the  shell.   E.g.   foo[d  is  an
acceptable  filename to Poplog, but this must be referred to as foo\[d
from the shell.


5.2.1       Multiple Versions
-----------------------------

Poplog does not support version numbers for  files  on  Unix  systems.
Instead,  a  chain  of  files  is  maintained where the numbers of `-`
appended to the filenames indicates the generation order of the files.
The  number of versions of files that will be maintained by the system
is POPFILEVERSIONS, i.e.   POPFILEVERSIONS  =  3  means  maintain  the
lastest version (foo1) and two old versions (foo1- and foo1--).


5.2.2       Directories
-----------------------

Attempts  to  access  files  in  non-existent  directories,  or   from
directories   with   more   than   14  characters  in  the  name  e.g.
directorynameandahalf/whynot.try, will produce an error.


6.0  FILE ACCESS
----------------

6.1         File protection on VMS Systems
------------------------------------------

On VAX-VMS systems the default protection for the directory containing
the file applies.  This cannot be altered from within VED.


6.2         Unix Systems
------------------------

The access mode for writing new files is controlled  by  the  variable
POP_FILE_MODE,  for  which  8:0664  (i.e.   -rw-rw-r--) is the default
value.


7.0  COMMAND EXECUTION
----------------------

All actions performed within the editor are affected by the  execution
of  Pop-11  procedures.  There are two command mechanisms for accessing
and executing these procedures:

    1) Key sequences are associated with particular procedures  via  a
    table-lookup mechanism

    2) Certain procedures can be called by name from the command  line
    at the top of the edit window.


7.1         Character Table Mechanism
-------------------------------------

VED maps characters read from the terminal onto Pop-11 procedures of no
arguments  through  a  tree  of  tables  and lists using the following
algorithm (the procedure -vedprocesschar-):

    Read a character.

    Look up the corresponding entry in the vector -vednormaltable-

        If it is a procedure apply it.

        If it is undef, sound the terminal bell.

        If it is a vector or a list, read another character and use it
            to  access  this  structure.   Repeat  this  process until
            either a procedure or undef is found.

In its normal setting -vednormaltable- maps ordinary printing characters
onto the procedure -vedinsertvedchar-  and <ESC> -  (ASCII 27) onto  the
vector -vedescapetable-.  This in  turn, maps  the character  -vedquery-
(default ?, ASCII 63) onto the vector -vedquerytable-

It may be necessary for the user to set up different tables to cater for
non-standard terminals. See REF * VEDTERMINALS and HELP * TERMINALS


7.2         Tables:  Stucture And Access
----------------------------------------

Tables may be either lists or vectors, the different methods used  for
referencing these structures are invisible to the user.

The vectors used by VED are 127 element vectors, each element being  a
Pop-11  procedure,  another table or UNDEF.  These vectors are accessed
using character ASCII codes as subscript values, e.g.   CTRL-A  (ASCII
1)  will  point to the first element of a vector and X (ASCII 88) will
point to the 88th element.

Lists used by VED as a  character  table  must  contain  a  series  of
entries  of  the  form:   character code followed by a procedure.  The
list is accessed by searching the  list  for  the  relevant  character
code.   If  the  code  is  present  in  the list the following item is
returned, otherwise UNDEF.  E.g

    [% `a`, ved_aa,
       `B`, ved_ab %] -> vednormaltable(`a`);

maps the procedure ved_aa onto  the  character  sequence  ab  and  the
procedure ved_aB onto the sequence aCTRL-B.


7.3         Tables:  Alteration
-------------------------------

The character tables use by VED can  be  altered  with  the  procedure
-vedsetkey- :-

    vedsetkey(<string>,<item>);

VED's character tables are altered  so  that  the  characters  in  the
string map onto the item, which must be a procedure or a string.

If the item is a procedure, it will be executed whenever VED reads the
character sequence represented by <string>.

e.g.  to make the sequence <ESC> ? Q  refresh  the  screen,  with  the
procedure -vedrefresh-

    vedsetkey('\^[?Q', vedrefresh);

        (where \^[ represents <ESC> in a string)

When the item is a string, the  characters  in  this  string  will  be
placed in VED's input stream and will themselves be read by VED.

e.g.  to make CTRL-E insert a line containing enddefine;

    vedsetkey('\^E', '\renddefine;\r');
        (where \r represents <RET> in a string)

Attempts to use -vedsetkey- to define abbreviations e.g.

        vedsetkey('def', 'define');

will NOT work.  VED checks that the first string is not  a  sub-string
of  the  second string.  Consider the example above, whenever 'def' is
typed, 'define' will be put into the input stream, 'def' will be  read
again  and  'define'  once  more fed into the input stream.  This will
continue until the system runs out of memory and generates a mishap.

Abbreviations must start with a "special" character e.g.  CTRL-A
        vedsetkey('\^Ad', 'define');

It can be wasteful to use  long  strings  as  the  first  argument  to
-vedsetkey- as several character tables will have to be created.

Strings containing three <ESC>'s in a row should also  be  avoided  as
this sequence is used by some VED procedures.

See also -ved_dk- for an interactive version of -vedsetkey-.

See HELP * VEDKEYS for a  complete listing of the default  key/procedure
mappings. The default mappings preceding Poplog Version 14 are in
 HELP * VEDOLDKEYS

Since Poplog Version  14 a new  syntax has been  provided for  tailoring
VED. This is aimed at  users who do not know  Pop-11 and do not wish  to
learn to use the Pop-11 string notation. See HELP * VEDSET.


7.4         Command line interpretation
---------------------------------------

Any Pop-11 procedure  whose name starts  with the prefix  'ved_' can  be
called directly from the command line  at the top of the edit-window  by
typing the procedure name  without the prefix,  followed by <RET>.  E.g.
typing q<RET> on the command line will cause the procedure -ved_q- to be
run.

As the normal method of  reaching  the  command  line,  the  procedure
-vedenter-,  is usually associated with the ENTER key which can be found
on most terminals, these commands will often be referred to  as  ENTER
commands, e.g.  ENTER q.

A command  normally consists  of  two parts,  the  command name  and  an
(optional) argument string. When a command is given the command line  is
separated into the command  string and an argument  string at the  first
'space' on the command line or at the first change of character type.

There are  a few  commands that  are dealt  with specially  by built  in
mechanisms, namely  the commands  that  deal with  searching,  described
below, i.e. ENTER /  ENTER "  ENTER \  ENTER `

All other commands are recognised in a manner that allows extra commands
to be defined by users. Unless the command name is in a mixture of upper
and lower case, it  is converted to lower  case (all ENTER commands  can
therefore be given in either upper or lower case) and the "ved_"  prefix
is attached. If the  VALOF the resultant word  is a procedure  (possibly
found in the  auto-loading libraries),  this is  executed, otherwise  an
error occurs.

The argument string (which may be empty) is  assigned  to  the  global
variable -vedargument-, where it can be accessed by the procedure.

If a numerical argument is required, the procedure STRNUMBER  must  be
used to convert the argument to a number, e.g.
    strnumber(vedargument) -> vedargument;

The procedure SYSPARSE_STRING can  be  used  to  convert  an  argument
containing  spaces  into  a  list of strings (also converts strings to
integers), e.g.

    sysparse_string(vedargument) -> vedargument;


7.5         Command Buffer
--------------------------

Commands are stored in a temporary 'command buffer'.  The command line
is  a  1-line window into this buffer and can be edited like any other
line in a file.  Sequences of commands can be easily repeated  without
retyping.    Obviously,   only  those  commands  associated  with  key
sequences may be used to edit the command buffer.

There are two procedures that can be used for moving the  cursor  into
the command buffer;

-vedenter- moves the cursor to the start of a blank line at the  end  of
the command buffer.

-vedstatusswitch- moves the  cursor  to  the  previously  held  position
within  the  command  buffer,  or  if  already  in  the command buffer
switches back to the text.  (This can be used for altering  a  command
already  on  the  command  line or for exiting from the command buffer
without executing a command).

A third procedure -vedredocommand- executes the command currently on the
command line.

Cursor movements made on the command line cause the  position  in  the
command  buffer  to change.  -vedenter- called within the command buffer
is equivalent to a move to the end of file.

When the length of the command buffer  exceeds  30  lines,  lines  are
deleted from the top of the command buffer.

A line in the command buffer can  be  executed  by  keying  RETURN  or
-vedredocommand-  with the cursor positioned anywhere on that line.  The
line will be copied to the end of the command  buffer,  unless  it  is
already at the end of the buffer, or the line at the end is the same.

A marked range of commands may be obeyed with  the  procedure  -ved_lmr-
(see below).

-ved_yankc- will 'yank' a copy of the marked range in a  file  into  the
'command' buffer.

vedputcommand(<string>) inserts the string into the command buffer  at
the end of the buffer.

There is only one command buffer  for  all  files  being  edited.   On
switching files the current position in this buffer is retained.


7.6         Defining New Commands
---------------------------------

The user can define Pop-11 procedures  to  provide  extensions  to  the
editor  using  either  of these mechanisms.  E.g.  A command to insert
three semi-colons, the Pop-11 end-of-line  comment  indicator,  at  the
beginning of the next line might be defined as :

        define ved_comment;
            vednextline();
            vedinsertstring(';;;')
        enddefine;

This could then be invoked as

        ENTER comment

or the procedure could be mapped onto the sequence ESC ;  by;

        vedsetkey('\^[;', ved_comment);


7.6.1       Autoloading
-----------------------

The "autoload" facility enables user extensions to  the  Pop-11  system
and VED to be stored in system or personal library directories.  These
procedures will then be compiled only when called.  This  will  result
in  a  slower  response to the first call of the procedure but reduces
the size of the system.  If a  large  set  of  extensions  to  VED  is
regularly used, the use of a 'saved image' containing these extensions
will save time.

Whenever the Pop-11 compiler encounters an unknown word it  searches  a
number  of directories for a file of the same name as the word.  If it
finds such a file it compiles it.

Unless due  care is  taken with  declaration conventions  this may  have
undesirable effects  on operating  systems that  allow only  short  file
names.

For example, some versions  of Unix allow only  14 characters in a  file
name. E.g. if  an autoloadable  library contains the  definition of  the
procedure  ITSALONGNAMEPROC,  in  a  file  called  ITSALONGNAME.P  (i.e.
ITSALONGNAMEPROC truncated to 12  letters and '.P'  added), then if  the
user uses a variable ITSALONGNAME without first declaring it, the Pop-11
autoload mechanism will inadvertently compile the file ITSALONGNAME.P

The list of directories  to search is held  in the variable  POPAUTOLIST.
This can contain either strings or lists or procedures (as explained  in
HELP * SYSSEARCHPATH). Normally it will contain only strings, which  are
names of directories.

In the user's init.p file, which is automatically loaded when starting
Pop-11, POPAUTOLIST can be initialised to include the names of  any
"personal"  library  directories.

E.g on VAX-VMS systems

    [ '[home.library]' ^^popautolist] -> popautolist;

or on Unix systems

    [ 'home/library' ^^popautolist] -> popautolist;


7.6.2       Error Handling And Messages
---------------------------------------

User  extensions  to  the  editor  can  trap  errors  and  interrupts. A
knowledge of Pop-11 error and  interrupt handling is required for  this.
In order  to  prevent interrupts  and  errors  causing a  loss  of  edit
information,  VED  locally  resets  -interrupt-  and  -prmishap-  to  be
-veddointerrupt- and -vedprmishap-.

-veddointerrupt-  returns  control  to  the  top  level  of  VED,   i.e.
-vedprocess-,  calling  -vedpopready-  if  its  current  value  is   not
-identfn-. Thus  for  debugging  purposes  in  VED,  -popready-  can  be
assigned to -vedpopready- enabling -popready- to be invoked when  errors
occur or when CTRL-C is typed.  (When the "load marked range"  mechanism
is used, default values are assumed to -interrupt- and -prmishap- and if
these are to be  changed this must  be done within  the command that  is
executed in  the  marked range,  or  by procedures  invoked  from  those
commands.)

-vedprmishap- resets the value of  -vedprintingdone- to tell the  editor
that the screen has been corrupted,  and prints long data structures  in
an abbreviated form.


7.6.3.      Error Handling Procedures
-------------------------------------

    vederror(string)
        Aborts  current  procedure  and  purges  the   input   stream,
        returning  control  to the top-level editor procedure.  Prints
        string on status line.

    vedinterrupt()
        Abort current processing.  Return to top level of VED.

    vedpopready()
        Null  procedure.   Can  be  redefined  for   debugging,   e.g.
        popready -> vedpopready;

    vedputmessage(string)
        Print message on status line.  Does not cause interrupt.

    vedtoperror()
        Abort processing, and print 'TOP OF FILE' message.


7.6.4       Debugging Ved Procedures
------------------------------------

The library procedure -veddebug- can be  used  to  test  and  debug  ved
procedures.

    veddebug(string)
The input string is printed out on the  status  line  and  the  system
pauses  until a character is typed.  If this character is RETURN, then
the program continues running, otherwise POPREADY is called.

    ved_wtype
Causes information about the current word to be displayed,  e.g.   its
identprops and type of its VALOF if it's an ordinary variable.


8.0  REPRESENTATION
-------------------

This section discusses the  representation  of  text  within  VED,  in
particular ,newline and tab characters.


8.1         Text
----------------

Text is held as a set  of  character  strings  stored  in  the  vector
-vedbuffer,-  each  string  corresponding to a single line in the source
file.  There are normally NO explicit  carriage  return(ASCII  13)  or
line-feed(ASCII 10) characters in VED buffers.  Newline characters are
implied between the lines.  This is  the  equivalent  of  the  VAX-VMS
carriage-return  attribute  file-type.   See the section on input from
disc-files for more detail.

Carriage return or line-feed characters that are present in the  input
file,  e.g.   output from DEC RUNOFF will be read into the buffer, and
represented as control characters.  The screen reresentation of  these
characters  will  be terminal dependent.  E.g.  on the Visual 200, all
control characters are represented by a small raised circle.


8.2         Tabs
----------------

On input to a buffer, tab characters may be turned into an appropriate
number of spaces or retained as tab characters.  Tab stops are assumed
to occur at regular intervals across the page, the size of a tab being
governed   by   the  value  of  -vedindentstep-.   If  retained  as  tab
characters, the tab is either HARD, and attempts to delete  or  insert
text  from 'within' the tab will produce an error or the tabs is SOFT,
and deletion or insertion of text within the tab will cause the tab to
be converted to spaces and the action will succeed.

The conversion  of  tabs is  controlled  by -vednotabs-,  which  can  be
overridden by -vedreadintabs-  to preserve tabs  in existing files.  The
Type of tab characters is controlled by -vedhardtabs-, and the size of a
tab stop by -vedindentstep- (see below).


8.2.1       Vednotabs
---------------------

-vednotabs, which can be TRUE or FALSE, governs the conversion  of  tab
characters into spaces on input to the buffer:

    -vednotabs is TRUE
        This is the default setting for -vednotabs and  signifies  that
        tab  characters  are  to be converted into spaces on input(see
        -vedindentstep-).
    -vednotabs is FALSE
        Tab characters are retained as tabs.  Each tab is  represented
        within  the buffer as a number of tab characters corresponding
        to the number of screen  locations  filled  by  the  tab  (see
        -veddecodetabs-).   Leading  spaces  will  be  converted  to tab
        characters when a file is written to disc.

The procedure -ved_tabs- switches the value of -vednotabs- and  displays
the new value on the status line.


8.2.2       Vedhardtabs
-----------------------

When -vednotabs- is FALSE (or has been FALSE at some  point  during  the
editing  session)  there  will  be  tab  characters present within the
buffer.  -vedhardtabs- governs whether text may be deleted  or  inserted
when the current position lies within a tab.

When -vednotabs- has been TRUE for the whole session, -vedhardtabs-  has
no effect.

    vedhardtabs is TRUE
        The default setting.  Attempts to delete or insert  characters
        when  the  cursor  is positioned within a tab produce an error
        message.  When deleting a character immediately  in  front  or
        behind a tab, the whole tab will be deleted.

    vedhardtabs is FALSE
        The tab will  immediately  be  converted  to  spaces  and  the
        appropriate insertion or deletion will succeed.  When deleting
        a character immediately in front or behind a tab, the tab will
        be turned into spaces and a single space deleted.


8.3         Variables
---------------------

The size of the current line (i.e.  the number of  characters  on  the
line)  is held in the variable -vvedlinesize-.  This may not be the same
as the length of the string holding the text, which may  at  times  be
longer  than  necessary.   This  is  to  reduce  the  need for garbage
collection while providing space for extra characters to be  inserted.
See * VEDSETLINESIZE and * VEDTRIMLINE.

Similarly -vvedbuffersize- holds the current length of  the  file,  i.e.
the  number  of  lines of text in the buffer.  -vedbuffer- may also have
extra space at the end to allow for extra lines to be  inserted.   See
* VEDBUFFEREXTEND * VEDUSEDSIZE.


9.0  BUFFERS
------------

While a file is being edited, information about the current  state  of
that  file  (its  name,  size, the current location, stacked positions
etc.)  and  also  certain  variables  for  controlling   the   editing
environment (break mode, tab size etc.) is held in global variables.
When the focus of attention switches to a different file, the  current
state  of  the  editor  must  be  stored  in  order to save this vital
information.  Each file currently held in  the  editor  is  associated
with  an  edit  record,  a  vector that holds the information (i.e the
current values of the editor global variables) about the current state
of that file.

A file record for each file currently being edited is  stored  in  the
list -vedbufferlist-.  Records are added to or removed from this list as
files are read into VED or exited from.

-vedcurrentfile-, which  indicates  the  file  currently  being  edited,
always points to the first element of -vedbufferlist-.

-vedupperfile- and -vedlowerfile- correspond to  the two windows on  the
screen. One of these is normally the same as -vedcurrentfile-. The other
will be the second element of -vedbufferlist-, if there is one, or FALSE
if there  is either  only one  window on  the screen  or buffer  in  the
editor.


9.1         File Record Maintenance
-----------------------------------

File records  are NOT  updated  automatically whenever  the  constituent
variables change. The  procedures -vedsaveglobals- and  -vedsetglobals-,
must be used to save and restore the current values, as required.

    vedsetglobals(<file>)
        use the contents of a file record to set the editor variables.

    vedsaveglobals(<file>)
        store within a file record the current  values  of  the  state
        variables.

E.g.  to find the value of a variable in a file record  the  following
procedure could be used;

    define vedvalofin(file, word) -> result;
        vedsaveglobals(vedcurrentfile);  ;;;save current file
        vedsetglobals(file);             ;;;restore old file
        valof(word) -> result;           ;;;find value of WORD
        vedsetglobals(vedcurrentfile);   ;;;restore initial state
    enddefine;

Note that -vedsetglobals- and -vedsaveglobals- do not alter the value of
-vedcurrentfile-.

The variables saved by -vedsaveglobals-, i.e.  those variables that  are
specific to individual buffers, are listed in Appendix 2.


9.2         Manipulating Buffer Records
---------------------------------------

The procedure -vedpresent- can be used to test whether a file  is  being
edited:

    vedpresent(<string>)
        The <string> is assumed to be a filename.  -vedpresent-  returns
        the  edit  record  for  that  file,  if  it is currently being
        edited, or FALSE if it is not.   i.e.   vedpresent(vedcurrent)
        == vedcurrentfile must always be TRUE.

There are procedures for accessing and manipulating edit records.

    vedgetfile(<procedure>, <file>)
        This procedure is called by -vededitor- to put <file> on screen,
        reading from disc or creating a new file, if necessary.

    vedopen(filename)
        Produces a file structure for the file, if  necessary  reading
        the file from disc.

    ved_ved {i.e. ENTER ved}
        Assumes that the value of -vedargument- is a string which is the
        name of a file.  If the file has  been accessed previously,  the
        effect is merely  to set the  file on the  screen, if  necessary
        displacing  another  edit  window.  If  no  argument  is   given
        (-vedargument- = '') then the last argument to VED is used,  and
        if there was no previous use, a default file name is used.

    vedselect(<string>)
        Assigns the string to -vedargument- and calls -ved_ved-

    vedobey(<file>,<procedure>)
        <file> can be a file-name or a file structure, as produced  by
        -vedopen-.

        -vedobey- sets the file  on the screen  and runs the  procedure.
        Changes made to  the file will  be shown on  the screen if  they
        occur within the initial window. Otherwise the user program will
        have to  call -vedcheck-  to ensure  the changed  portion is  on
        screen. After running the  procedure, -vedobey- returns  control
        to whatever environment it was called from.

    vedappfiles(<procedure>)
        Cycles  through  -vedbufferlist-,  applying  the  procedure in
        environments  corresponding  to  all the files currently being
        edited (compare *APPLIST).  E.g. a procedure  to  clear  every
        buffer might be defined as

            define ved_allclear();
                vedappfiles( ved_clear);
            enddefine;


9.3         Manipulating arbitrary text blocks
----------------------------------------------

The library package LIB * VEDBLOCKS provides mechanisms for deleting
copying moving and overlaying blocks of text.  The required rectangular
block is indicated by pushing the VED positions at a pair of diagonally
opposite corners of the block, using -vedpushkey-.

Full details are provided in
    HELP * VEDBLOCKS
    HELP * VEDFILLBLOCK,
    HELP * VEDYANKBLOCK
    HELP * VEDREFRESHBLOCK
    HELP * VEDCUTBLOCK

including information about the following commands:

Deleting, saving, moving or copying an indicated block of text:
    ved_dtb
    ved_sdtb
    ved_mtb
    ved_smtb
    ved_ttb
    ved_stb

Re-inserting text previously stored in -vvedblockdump-
    ved_ytb
    ved_sytb
    ved_yotb

Insert spaces into a text-block

    ved_itb
    ved_sitb

Utility procedures:

    getblockargs() -> line1 -> col1 -> line2 -> col2;

    vedfillblock(line1,col1,line2,col2,char);
        See HELP * VEDFILLBLOCK

    vedrefreshblock(line1,col1,line2,col2,dotail);

    vedcutblock(line1,col1,line2,col2,boolean) -> vector;

    vedblockrepeater(vector_of_strings) -> procedure;

    vedyankblock(vector_of_strings);
        See HELP * VEDYANKBLOCK

    vedoverlayblock(vector_of_strings);


10.0  WINDOW SIZE
-----------------

The default version of VED allows one or two files to be on the screen
simultaneously  in  separate  windows.   Library  packages  exist that
provide facilities for multiple windows.

Each window is made up of a  single  command  line  and  an  arbitrary
number  of  text  lines.  The command line is positioned at the top of
the window.  If there are two windows the command line for  the  lower
window acts as a separator between them.

The size of  the window  or windows  is governed  by the  length of  the
screen (-vedscreenlength-) and the value of -vedstartwindow-.

The lower window will contain  -vedstartwindow- lines (i.e. the  command
line with -vedstartwindow- - 1 lines  of text) and the upper window,  if
there is one, fills the remainder of the screen (i.e.  -vedscreenlength-
- -vedstartwindow- lines).

The default setting  is for two  windows of equal  size, but windows  of
unequal size are allowed and a single window may be obtained by  setting
-vedstartwindow- equal to -vedscreenlength-.

Although the length  of the  current window is  stored as  the value  of
-vedwindowlength-, all the procedures that refresh and bring files  onto
the screen (except  -vedrefresh-) use the  value of -vedstartwindow-  to
govern the screen layout.

To illustrate  how the  window variables  affect the  appearance of  the
screen, consider the two procedures -ved_ws- and -vedsetwindow-.

    ved_ws
        Sets -vedstartwindow- to be the value of  -vedargument-  converted
        to a number, and refreshes the screen e.g.

            ENTER ws 16

        sets -vedstartwindow- to be 16, producing (for a 24 line screen)
        two  unequal  windows:   a  16-line lower window and an 8-line
        upper window.

        (If -vedargument- is an  empty  string,  the  current  value  of
        -vedstartwindow- is displayed)

    vedsetwindow()
        resets the value  of  -vedwindowlength-  without  altering  the
        value  of  -vedstartwindow-.   This  produces a temporary escape
        from  the  current  window  size.   The  final  screen  layout
        depending upon the initial values of both variables:-

        1) -vedwindowlength- less than -vedscreenlength-.

            -vedwindowlength- will be  made equal to  -vedscreenlength-,
            resulting in  a full  screen  window, whatever  the  current
            value of -vedstartwindow-.

        2) -vedwindowlength,- -vedstartwindow-  and  -vedscreenlength-
            all equal.

            -vedwindowlength- will be set to half of  -vedscreenlength-,
            thus    successive    calls    of    -vedsetwindow-     when
            -vedstartwindow- =  -vedscreenlength-  will  switch  between
            full and half-screen windows.

        3) -vedwindowlength- equal to -vedscreenlength-
                  and -vedstartwindow- less than -vedscreenlength-
            -vedwindowlength- will be set to -vedstartwindow-

As -vedsetwindow- does not refresh the whole  screen,  production  of  a
window that is less than the whole screen produced will leave the rest
of the screen unchanged.


10.1        Window Position
---------------------------

The cursor is not restricted to the areas of the display that are filled
with text. The variables -vedlineoffset- and -vedcolumnoffset- hold  the
position of the window relative to the file.

-vedlineoffset- is the number of lines preceding the first line  of  the
window.   Thus  the  first visible line is vedlineoffset + 1.  Initial
value is 0.

-vedcolumnoffset- is the number of columns of text to the  left  of  the
edit  window.  Normally this is 0, but is incremented during scrolling
left, and decremented when scrolling right.


10.2        Aligning The Screen
-------------------------------

    vedcursorset()
        Returns TRUE if (vedline, vedcolumn) defines a location in the
        visible window otherwise FALSE.  Causes the cursor to be moved
        to the correct screen location.

    vedsetcursor()
        Moves the screen  cursor  to  the  correct  location,  if  the
        current position is in the visible window.

    vedcheck()
        Checks that cursor position is  in  current  window,  shifting
        window and refreshing or scrolling the screen if not.  Whether
        the screen is scrolled or refreshed depends upon the  distance
        that  would  need  to be scrolled to make the current position
        visible.

    vedalignscreen()
        Aligns the window so that the current location is in a visible
        position.  The window is then refreshed.

    vedsetscreen(<string>)
        Aligns the screen and puts the string on the status line.


10.3        Putting Files On Screen
-----------------------------------

    vedsetonscreen(<file>,<string>)
        Sets file on the screen, with string  as  message.   The  file
        must be a file record.
    ved_ved
        Assumes that the value of -vedargument- is a string which is the
        name of a file.  If the file has been accessed previously, the
        effect is merely to set the file on the screen,  if  necessary
        displacing another edit window.

    vedselect(<string>)
        Assigns the string to -vedargument- and calls -ved_ved-

    vedswapfiles()
        Sets on the screen the last edited file.  If it is already  on
        the  screen moves the cursor into the window for that file.  A
        subsequent call of this procedure  will  switch  back  to  the
        previous  file.   If  -vedstartwindow-  has  a  value  less than
        -vedscreenlength-, then thE two windows remain  on  the  screen,
        and  swapping involves merely moving the cursor into the right
        window.


11.0  INPUT AND OUTPUT
----------------------

This section discusses VED's input  and  output  mechanisms  from  the
point-of-view of a Pop-11 program.  It does not include any information
about the redirection of i-o for POP procedures run from  within  VED,
which is contained in the section on compilation from the buffer.

Three sources of input are considered in turn:  terminals,  disc-files
and  VED  buffers.   First  the  default  mechanisms of the editor are
described and then procedures that  are  available  to  the  user  are
catalogued.


11.1        Interaction with the terminal
-----------------------------------------

Screen handling within VED is described in a separate section.

Pop-11 normally uses CHARIN to read characters typed at  the  terminal,
and CHAROUT to transmit characters to the terminal.

    charin() -> character
    charout(character)

These use the devices POPDEVIN and POPDEVOUT respectively.

VED normally uses  RAWCHARIN and  RAWCHAROUT to  communicate with  the
terminal. These use 'raw' input mode, i.e. the devices POPRAWDEVIN and
POPRAWDEVOUT. This 'raw' mode implies that  there is to be no  echoing
of characters, no formatting of  output, and that all characters  will
be  'break'  characters.  Certain  control  characters  retain   their
functions, e.g.  CTRL-Y  remains  an interrupt  character  on  VAX/VMS
systems.

The procedure  -vedscreenraw-  sets  the terminal  in  'raw'  mode,  and
transmits the escape sequence -vedscreensetpad-. This sets the  terminal
modes required  by VED.  This includes  setting the  terminal's  numeric
keypad (if it has one) to transmit escape sequences.

-vedscreenreset- resets the terminal to its original state.


11.2.       Input
-----------------

In 'raw' mode the  editor reads characters from  the terminal using  the
procedure -vedinascii-. The  characters are  passed to  -vedprocesschar-
which maps them onto procedures (see above).

-vedinascii- works as follows:-

   Flush any output waiting to go to the screen.

   Check whether the list -ved_char_in_stream- is empty.

      If -ved_char_in_stream- is empty.

         Return the first non-null character read  from  the  terminal
         with  -rawcharin-.  Every character is a 'break' character, and
         there is no prompting, or echoing.

      If -ved_char_in_stream- is non-empty.

         Return the first item if it's a non-null character.

         If the first item is a string, explode it, return  the  first
         non-null character and add any others to -ved_char_in_stream-

Items may be  placed  into  the  input  stream  for  VED  (i.e.   into
-ved_char_in_stream)- with the library procedure -vedinput-:

    vedinput(<item>)
        Put the item, which can be either a character  or  string,  on
        the front of -ved_char_in_stream-.  This is defined as

            conspair(item, vedcharinstream) -> vedcharinstream

-vedinascii- will  continue waiting  for something  to be  typed on  the
terminal. To specify a limit for the waiting time, -charin_timeout-  can
be used.

    charin_timeout(integer) -> character or FALSE
        Waits until N hundredths  of  a  second  have  elapsed,  or  a
        character has been pressed at the terminal.

        If a character is pressed, then it is returned.  If not, FALSE
        is returned.

        If several characters are typed during the wait, the first one
        will be lost.

As an example, consider the following procedure, which searches for  the
next occurrence of a character to  be read from the terminal. The  first
version using  -vedinascii- will  wait  forever for  a character  to  be
typed:-

    define ved_next_char();
        vedlocate( consstring( vedinascii(), 1));
    enddefine;

the second version,  using  CHARIN_TIMEOUT  waits  one  second  for  a
character to be typed, before sending an error message.

    define ved_next_char();
        vars char;
        if charin_timeout( 100) ->> char then
            vedlocate(consstring(char,1))
        else
            vederror('NO INPUT DURING READ PERIOD');
        endif;
    enddefine;


11.3        Output to VED buffer or screen
------------------------------------------

11.3.1      Output to screen
----------------------------

Characters are sent to the terminal by -vedoutascii-.

    vedoutascii(<char> or <string>);

    This uses -rawcharout-  and -poprawdevout-. Output  is buffered  and
    characters are sent only when one of th efollowing occurs:

    1) a null character is output (i.e.  rawcharout(0)).

    2) the buffer, which holds 128 characters, is full.

    3) -poprawdevout- is flushed using -sysflush- i.e.
            sysflush(popdrawdevout)

    4) rawcharin() is executed.

    As -vedinascii- uses -rawcharin-,  this last condition ensures  that
    the output buffer will be flushed before each character is read from
    the terminal.

    -vedoutascii- will accept either a  single character or a  character
    string and  outputs the  character or  string of  characters to  the
    terminal.   It    is   used    by   both    -vedscreenoutput-    and
    -vedscreencontrol-:  these   can   also  therefore   accept   single
    characters or strings.

    vedscreenoutput(<char> or <string>)
        Output character to screen.  If the character is >= 8:200 then
        graphic  mode  is  set  before  the  character  is  sent  (see
        -vedgraphon-).  Otherwise graphic mode is reset.

    vedscreencontrol(<string> or <procedure>)
        Outputs  the  string,  which  should  transmit  suitable  screen
        control characters to the terminal, or invokes the procedure.


11.3.2      Printing in the editor
----------------------------------

    vedprmishap()
        A  version  of  -prmishap-  that  is  used  by  VED.  This  sets
        -vedprintingdone- to  be TRUE  so that  the screen  will not  be
        refreshed until the user has been asked to press the return key.

    vedputmessage(<string>)
        Prints a message string on the status line.


11.3.4      Suppressing output to the screen
--------------------------------------------

Output to the terminal can  be supressed by setting -vedediting-  false.
All the procedures  that update  the screen check  that -vedediting-  is
true before sending output to the terminal. -vedediting- can, of course,
be reset locally by procedures that want to suppress screen refreshing.

Making -vedediting- false will not interfere with normal operation of
programs that read from or insert in the VED buffer.


11.3.5      Refreshing and updating the screen
----------------------------------------------

The screen will need updating whenever there  has  been  a  change  in
either the contents of the buffer or the position of the cursor.

For efficiency  reasons, VED  does not  use a  screen map.  Most of  the
procedures that change the contents of the buffer will update the screen
as needed. It may however  be necessary to cause  the screen or part  of
the screen to be refreshed if an explicit change is made to the contents
of  the  buffer  e.g.  by  altering  the  value  of  vedbuffer(vedline).
Procedures for refreshing the screen are described below.

The screen position of the cursor  is checked during each cycle  through
-vedprocess-, by -vedcursorset-. If the  current position of the  cursor
is not in  the window,  -vedcheck- is called  to align  and refresh  the
window. The cursor may therefore be  moved freely about the edit  buffer
by user procedures.

    vedrefresh()
        Refreshes the current window and the associated  status  line.
        Also resets the terminal keypad mode.

    vedrefreshrange(<first>,<last>,<flag>)
        Refresh the current window from  the  BUFFER  lines  first  to
        last,  inclusive.   If  flag  is  TRUE,  all the lines will be
        marked, if FALSE no lines will be marked.  If flag  is  UNDEF,
        checks  whether  each line is in the marked range and marks it
        if necessary.

    vedrestorescreen()
        -vedrestorescreen-  is   called   during  each   cycle   through
        -vedprocess-: when -vedprintingdone- is false this does nothing,
        otherwise it prints a message and  waits for the user to  type a
        character, whereupon it sets  the last edited  file back on  the
        screen. When -vedstartwindow-  is less  than the  length of  the
        screen, the printing (e.g. error messages) will remain  visible,
        above the edit window.

        VED alters -cucharout- locally to ensure that any printing using
        the standard Pop-11  print procedures  or any calls  to DCL  set
        -vedprintingdone-  to  be  TRUE.  -vedprintingdone-  is  checked
        during  each  cycle  of   -vedprocess-  and  when  TRUE   causes
        -vedrestorescreen- to be called when control returns to VED.


11.3.6      Screen Control
--------------------------

All of  the  screen control  procedures  detailed in  this  section  are
available to the user and provide a convenient set of tools for terminal
handling.

VED's screen  control procedures  use a  collection of  variables  whose
names all start with  "vvedscreen". Their values  are either strings  of
characters recognised by the terminal in use or procedures that do  what
is required for various screen  functions, like deleting a line,  moving
the cursor, scrolloing the screen,  etc. The variables are described  in
REF *  VEDTERMINALS. All  communication  with the  screen goes  via  the
procedure -vedscreencontrol- also defined in REF * VEDTERMINALS.

For example the  procedure -vedscreenclear-  uses -vedscreencontrol-  to
send the character sequence -vvedscreenclear- to the terminal. Output of
these control sequences is buffered (see above).

A full account of  the screen control variables  is given in  connection
with identifiers beginning 'vvedscreen' in REF * VEDTERMINALS. There are
many library files that set these variables in the directory

For VDUs which are unable to delete or insert lines in the middle of the
screen, -vednolineinsert- should be set TRUE.  In this case some of  the
following procedures will not alter the screen directly, but change  the
value of  -vedrefreshneeded-.  This records  the  line below  which  the
screen  should  be  completely  refreshed.  Refreshment  occurs  at   an
appropriate time.

    vedscreenreset()
        Prepare to produce normal printout, or read in  characters  at
        bottom of screen, in non raw mode.

    vedscreenxy(<col>,<line>)
        Using real screen coordinates, position the cursor  at  (col,
        line).  The top left-hand corner is (1,1).

    vedscreenbell()
        Ring bell, i.e.  vedoutascii( `\^G`). This can be redefined by
        users who find it irritating. E.g. to make it do nothing:
            identfn -> vedscreenbell;


    vedscreenchardown()
        Move  cursor  down  a  line  ON  THE  SCREEN,   and   increase
        -vedscreenline- by 1.

    vedscreencharleft()
        Move cursor left on screen, and decrease -vedscreencolumn- by 1.

    vedscreencharright()
        Move cursor one character to the right on screen, and increase
        -vedscreencolumn- by 1.

    vedscreencharup()
        Move cursor up the screen, and decrease -vedscreenline- by 1.

    vedscreenclear()
        Clear the  screen, moving  the  cursor to  the top-left  of  the
        screen.

    vedscreencleartail()
        Delete screen line to right of cursor,

    vedscreendeletechar()
        Delete current character ON SCREEN, first switching graphic mode
        OFF.

    vedscreendeleteline(<line>)
        Delete a line on  screen. <line> is  in window co-ordinates  and
        the cursor is moved to  the beginning of the  line if it is  not
        already on that line.

    vedscreengraphoff()
        If -vedgraphicmode-  is  TRUE  then set  graphic  mode  off  and
        -vedgraphicmode- FALSE, see below.

    vedscreengraphon()
        If -vedgraphicmode- is  FALSE  then  set  graphic  mode  on  and
        -vedgraphicmode- TRUE, see below.

    vedscreeninsertchar(char)
        Insert the character on current  line on screen. Checks  whether
        -vedinserting- is true, if not, turns graphic mode off and  sets
        terminal insert mode. Then outputs character to screen. Does not
        turn insert mode off.

    vedscreeninsertline(<line>)
        Inserts a blank line on the screen below screen  line  <line>.
        Moves the cursor to the necessary position.

    vedscreenpulldown(<line>)
        The section of the window above WINDOW line <line>  is  pulled
        down one line, effectively deleting a line from the screen and
        inserting a blank line at the  top  of  the  window.   Doesn't
        affect the status line.

    vedscreenpullup(<line>)
        The section of the window below WINDOW line <line>  is  pulled
        up  one  line, deleting a line from the screen and inserting a
        blank line at the bottom of the window.   Doesn't  affect  the
        status line.

    vedscreenpushdown(<line>)
        The section of the window below WINDOW line <line>  is  pushed
        down one line, inserting a blank line and deleting a line from
        the bottom of the window.  Doesn't affect the status line.

    vedscreenpushup(<line>)
        The section of the window above WINDOW line <line>  is  pushed
        up  one  line, inserting a blank line and deleting a line from
        the top of the window.  Doesn't affect the status line.

    vedscreenright()
        Move to right of window.

    vedsetstatus(<string1>,<boolean1>,<boolean2>)
        (System use). Re-build status line.


11.3.7      Graphics
---------------------

Graphics characters are used by VED on the status line and to indicate
the  current line and marked ranges.  The default values for expressed
as 8:200 + character code.  8:200 is Pop-11 syntax for 128 as an  octal
number.

    vedscreenmark
        Character used to indicate lines in marked range,  a  vertical
        line.  Default value:  8:200 + `x`.

    vedscreenlinemark
        Character after the line number in status line,  a  capital  T
        turned  90  degress counter-clockwise, Default value:  8:200 +
        `t`.

    vedscreencursor
        character for horizontal bar.  Used to indicate  current  line
        when  cursor  is on command line.  Also used as part of status
        line.  Default value:  8:200 + `q`.

    vedscreencursormark
        Character indicating current line, in marked range,  a  little
        cross.  Default value:  8:200 + `n`

    vedscreencommandmark
        Character after command, while it's being obeyed, also  before
        line  number, a T turned 90 degrees clockwise.  Default value:
        8:200 + `u`.

    vedscreencontrolmark
        Character that is  used  to  indicate  control  characters,  a
        degree symbol.  Default value:  8:200 + `f`.

    See HELP * GRAPHCHARSETUP


11.4        Files in VED
------------------------

11.4.1      Reading files from disk
-----------------------------------

On VAX-VMS  systems, files  are read  a single  record at  a time,  each
record being copied into a string  representing one line of text.  Input
files are assumed to have VAX-VMS carriage return attributes, i.e.  they
do not have  explicit carriage  return or line-feed  characters. If  the
source file does contain <CR> or <LF> characters, e.g. files produced by
DEC RUNOFF, these will be read into the buffer.

This behaviour is  simulated in  UNIX systems  where newline  characters
will be treated as end-of-record when reading files.

Tabs are converted to spaces or  not  as  governed  by  the  value  of

-vednotabs (see above)

-vedreadintabs
    If this is true, and -vednotabs- is TRUE, then if there are any  tab
    characters in  the  file  then  -vednotabs- is  set  FALSE  and  tab
    characters are preserved. Set  this TRUE (the  default) if you  want
    files you create to have no tabs (i.e. -vednotabs- is set TRUE)  but
    you don't want to lose tabs in existing files.

-vedbreak- has no effect when files are read from disc.  Lines that  are
longer than -vedlinemax- will not be broken on input.

    vedreadin(<filename> or <device>)
        Requires a filename or a device record as argument and reads a
        file  from  disc,  making a string for each line.  Returns the
        number of lines read.  The strings  are  left  on  the  stack.
        Alters tabs to spaces or not as governed by -vednotabs.

        The device record is of the kind produced by SYSOPEN.

    sysopen(<filename>,<mode>,<organization>)
        Returns a device record for an already existing file, FALSE if
        the file cannot be opened.

        FILENAME should be a string.

        MODE should be 0, selecting read only mode.

        ORGANIZATION should be "record", this implies that the file is
        record oriented and will be read a record at a time.


11.4.2      Writing files to disk
---------------------------------

On VAX-VMS systems,  files are written  as variable-length record  files
with  carriage  return  attributes  i.e.  without  carriage  return   or
line-feed characters  between the  lines.  Each line  in the  buffer  is
written as a single record representing one line of text.

On UNIX  systems  files are  written  as  a sequence  of  bytes,  with a
line-feed character (ASCII 10) output at the end of each line.

Spaces are  converted  to  tabs or  not  as  governed by  the  value  of
-vednotabs- and --vedindentstep-(q.v.).

Trailing spaces are stripped from the  text and empty lines are  removed
from the end of the file.

See also REF * SYSIO for information on more basic Poplog facilities  in
terms of which Poplog is implemented.

11.4.3      Disk Quotas
-----------------------

In VMS disk overdrafts are usable for writing to files that are  already
open (i.e.  new files  can't  be created  when  over quota).  A  warning
message is issued when  first exceeding quota.

When an error occurs in writing to a disk-file device, e.g. because  the
disk is full or the user's quota has been exceeded, then, the device  is
automatically closed, and the  device record is  given to the  procedure
-pop_file_write_error-  which   then   deals  appropriately   with   the
situation.

A Poplog device record contains 2 names: device_open_name(device) is the
name by which the file  was opened, and device_full_name(device) is  the
full name.

VED locally redefines pop_file_write_error(device) to be

        sysdelete(device_full_name(device)) ->;

deleting the latest, incomplete, version of the file. This means that if
you temporarily leave VED in order to  purge files in order to get  back
under disk quota the last complete version of the file will still be  on
the disk.


11.4.4      Procedures For Writing To Disc
------------------------------------------

The following procedures will normally  write only files that have  been
altered and are "writeable" to a disc-file of the same name. The  values
of -vedchanged-  and -vedwriteable-  are checked.  If -vedwriteable-  is
false the file will  not be written. If  -vedchanged- is false the  file
will only be written to a new name.

The  basic  procedure  for  writing  a  buffer  to  a  disc  file   is
-vedwriterange-.

    vedwriterange(<first>,<last>,<filename>)

        Write from line <first> to line <last> of the current buffer  to
        disc-file <filename>. <first> must be less than <last>, and  the
        minimum of  <last> and  -vvedbuffersize- will  be used  for  the
        upper limit.

        On VAX-VMS systems, -vedwriterange- checks whether -vedversions-
        is FALSE. If -vedversions- is  non-FALSE, it must be an  integer
        as the file will  be PURGED so that  no more than  -vedversions-
        copies are retained.

-vedwriterange- is used by all of the following procedures:

    vedwritefiles()
        Cycle through -vedbufferlist- writing all writeable and  changed
        files.

    ved_w
        If -vedargument- is the  null string then  write all files  that
        have been  altered  i.e. -vedwritefiles-.  Otherwise  write  the
        current  buffer  to  the  file  -vedargument-  (locally   resets
        -vedchanged- to force a write).
    ved_w1
        Write only the current file.


11.4.5      Automatic Writing Of Files
--------------------------------------

-vedautowrite- uses -vedchanged- to  count changes to individual  files.
-vedchanged- is incremented every time a change is made to a file.  Each
character typed into or  deleted from the buffer  counts as one  change.
Deleting  or   substituting  a   string  (e.g.   using   -vedclearhead-,
-vedwordrightdelete-,  -ved_s-,  etc.)  counts  as  one  change.  Global
substitutions also count as one change.

When -vedchanged- for a file exceeds -vedautowrite-, then that  file,  and
only  that  file,  is  saved.   A  tolerable value for -vedautowrite- is
probably around  800.   This  facility  may  be  disabled  by  setting
-vedautowrite- to be FALSE.

    ved_autowrite n
        Sets  the  value  of  -vedautowrite-  to  be   N,   N = 0   sets
        -vedautowrite-  to FALSE.  If no argument is given, displays the
        current value.

11.4.6      Input from VED buffer to program
--------------------------------------------

    vedcurrentchar()
        Return or update  character  under  cursor.   Cursor  position
        reamins unchanged.

    vedrepeater() -> character
        Returns next character in the buffer,  and  moves  cursor  on.
        Sets * POPLASTCHAR.

    vedrangerepeater(<line1>,<line2>) -> character-repeater
        Return a character repeater for the range of  lines  from  the
        current  buffer.   This repeater will return TERMIN at the end
        of the range.

    vedthisline() -> string
        Return the string representing  current  line,  equivalent  to
        subscrv(vedline,vedbuffer).  See -veddecodetabs-, -vedthisline-.

    veddecodetabs(<string>) -> string

        Remove the  extra  tabs  that  may  be  put  into  a  string  by
        vedcharinsert(tab).

        When -vednotabs  is FALSE,  lines containing  tabs will  contain
        "extra" tab characters representing the portion of the screen to
        be padded out. -veddecodetabs- converts the character string for
        such a line  to a string  with the right  number of tabs,  using
        -vedindentstep- to determine tab boundaries.

    vedthisstring()-> string

        Unlike -vedthisline-, this returns  a  string  with  the  proper
        number of tabs.  Equivalent to veddecodetabs(vedthisline())

    vedmoveitem() -> item
        Return the next text item in file, moving the cursor past it.

    vednextitem() -> item
        Returns next text item in file, without moving the cursor.


11.4.7      Output To VED Buffer
--------------------------------

Printing characters are inserted into  the file at the current  location
as they are typed, with a procedure, -vedinsertvedchar-. This  procedure
uses variables  that  are  local  to  the  top-level  VED  process  (see
-vedcharinsert- below).

When the  RETURN character  (ASCII 13)  is input,  the current  line  is
broken at  the  current location,  and  any text  following  the  cursor
position is moved on to the next line.

A left margin can be set by altering the value of -vedleftmargin-, which
must be either a positive integer  or a procedure returning an  integer.
When -vedleftmargin- is greater than zero the text on the new line  will
begin after -vedleftmargin- space characters. Excess leading spaces  are
deleted from the beginning of the new line.

When a tab character (ASCII 9) is entered spaces (ASCII  32)  or  tabs
will  be entered into the current line up to the next column that is a
multiple of -vedindentstep-.  (See the section on text representation.)

Control characters and other non-printing characters may  be  inserted
into the buffer with -ved_ic- q.v.


11.5.1      Break Mode
----------------------

In break mode, continuous typing without pressing RETURN will cause  the
line to be broken at word boundaries,  in such a way as to maximise  the
number of words on a line. Spaces are taken to indicate word boundaries.
In this  mode,  the  maximum  length  of  a  line  is  -vedlinemax-  + 1
characters (the text justifying procedures e.g. --ved_j- allow lines  of
only -vedlinemax- characters).

If break  mode is  off,  the screen  will  be scrolled  horizontally  to
accommodate the text.

Break mode is controlled by the  value of -vedbreak-. Break mode is  OFF
when -vedbreak- is FALSE. The  procedure -ved_break- switches the  value
of -vedbreak-, turning break mode on and off.

-vedbreak- is set when the file  is first edited, according to the  file
extension.  The  variable  -vednonbreakfiles-  holds  a  list  of   file
extensions which cause VED to set  -vedbreak- to FALSE when the file  is
edited.


11.5.2      Character Insertion
-------------------------------

The   procedure -vedcharinsert- may be used to insert characters into
the buffer.

    -vedcharinsert-(<char>)
        Insert ASCII  character <char>  at current  location. This  will
        cause the screen to be updated appropriately if -vedediting-  is
        true. Most  characters are  simply inserted  as they  are.  Some
        characters (e.g.  the TAB  character `\^I`  or RETURN  `\^M`  or
        NEWLINE `\^n`  characters)  will  cause  more  complex  actions,
        including breaking a line, padding the current line with  spaces
        or tabs to the next tab stop.


    vedinsertstring(<string> or <word>);
        The characters in the string or word are inserted  immediately
        after  the  current location.  Newline and tab characters have
        the usual effect.  Defined as

            appdata(item, vedcharinsert);

The  library  procedures  for  inserting  Pop-11  constructs  all   use
-vedinsertstring-.  E.g.  -ved_until- defined below:

    define ved_until(); /* Insert template for UNTIL statement */
        vedlinebelow();
        vedpositionpush();
        vedinsertstring(
            '\n\tuntil CONDITION do\n\t\tACTION\n\tenduntil;');
        vedpositionpop();
    enddefine;

See  SHOWLIB  *   VED_DEFINE  for   another  example  of   the  use   of
-vedinsertstring-.

The procedures  -vedlineabove-  and -vedlinebelow-  insert  blank  lines
above or below the current line, moving the cursor to the start of  that
line, as determined by -vedleftmargin-.

ved_r() assumes that -vedargument- holds the name of a  file  and  reads
that file into the current buffer after the current line.

-vedout- returns a character consumer that writes into a buffer.

    vedout(<file>,<returntofile>,<onscreen>,<initialise>,<terminate>)

        the five arguments are as follows:-

        <file> - filename, must be a string or a word.  The buffer  to
        be written into.

        <returntofile> - a boolean value  that  controls  whether  the
        previous window (if different from the one used for insertion)
        is restored after each character is inserted.

        <onscreen> - a boolean value that whether the  insertions  are
        shown on the screen.

        <initialise> - a procedure (e.g.  -vedendfile- or -ved_clear-) to
        be  run  once  on  the  file, before the character consumer is
        created.

        <terminate> -  a  procedure  to  be  run  when  the  character
        consumer is given TERMIN.

If <onscreen> is TRUE, -vedscreenflush- may  have  to  be  called  after
writing  has finished, to make the output appear on the screen, as the
output to the screen is buffered.

If this is called from outside the editor, with <onscreen>  TRUE,  the
screen may get into a confused state.

With RETURNTOFILE TRUE the character consumer may be a very  slow,  as
it will change files after outputting each character.

To avoid  overheads,  the  status  line  is  not  updated  after  each
character.  Hence the line number will be misleading.

    vedbufferextend()
        Ensure there is enough room for at  least  one  more  line  in
        -vedbuffer-

    vedsetlinesize()
        Must be called every time -vedline-  is  changed.   Updates  the
        value of -vvedlinesize-.

    vedtrimline()
        Use this before -vedline- is altered, to remove trailing  spaces
        from the current line.


12.0  STATIC MODE
-----------------

Static mode is controlled by the value of -vedstatic- : static mode is ON
when vedstatic is TRUE.  The procedure -vedsetstatic- switches the value
of -vedstatic-, turning static mode on and off.

Static mode alters the behaviour  of  several  procedures.   The  most
important  change  is  in  the  single-character insertion procedures:
instead of inserting characters at the current location  and  shifting
the  rest  of  the  current  line  to the right, these procedures will
replace the current character with the new  one,  and  then  move  the
cursor one place to the right.

-veddocr- is disabled, therefore typing carriage return  has  no  effect
and  with  break  mode on, lines will not be broken when they grow too
long.

The behaviour  of  some of  the  delete procedures  is  affected.  Those
procedures that delete  text within  lines overwrite  with spaces.  This
affects  -vedchardelete-  -veddotdelete-  -vedclearhead-  -vedcleartail-
-vedwordleftdelete- and  -vedwordrightdelete-.  -vedlinedelete-  is  not
affected.

-vedwordleftdelete- and  -vedchardelete-  are additionally  affected  in
that they will have no effect at the beginning of a line.

Movement commands function normally in static mode.


13.0 CURSOR POSITIONING
-----------------------

The current location of the cursor is stored in the variables  -vedline-
and  -vedcolumn-.   When  the cursor is positioned at the beginning of a
file, -vedline- and -vedcolumn- both have the value 1.


13.1        Procedures For Changing The Cursor Position
-------------------------------------------------------

    vedjumpto(<line>,<column>)
        Moves the cursor to the specified line and column position

    vedcharup() and vedchardown()
        Move  current  position  a  single  line  vertically,  without
        changing the current column.

    vedcharleft()
        Move the cursor one character to the left, if necessary moving
        to  the  end  of  the  previous  line  or scrolling the screen
        horizontally.

    vedcharright()
        Move the cursor one character to right, scrolling  the  screen
        if necessary.

    vedcharupleft(), vedchardownright(), vedchardownleft() and
                    vedcharupright()
        Move one character diagonally, using VEDCHARUP/DOWN  and  then
        VEDCHARRIGHT/LEFT.

    vednextline()
        Move to the beginning  of  the  next  line,  as  indicated  by
        -vedleftmargin-.

    vedwordleft() and vedwordright()
        Move a word  to  the  left  or  right.   Word  boundaries  are
        determined by the full text itemising rules of Pop-11, see HELP
        ITEMISE for further details.

    vedcharleftlots() and vedcharrightlots()
        Move horizontally a quarter of -vedscreenwidth-.

    vedcharuplots() and vedchardownlots()
        Move vertically a third of a WINDOW.

    vedcharuprightlots(), vedcharupleftlots(),  vedchardownrightlots()
        and vedchardownleftlots()
        Move diagonally third of a  WINDOW  vertically  quarter  of  a
        SCREEN horizontally.

    vedscreenup() and vedscreendown()
        Move to top or bottom of screen.

    vedscreenleft(), vedscreenright() and  vedscreenmiddle():  Move  to
        left, right or middle of screen on current line.

    vedtextright(), vedtextleft() and vedcharmiddle()
        Move to right, left or middle of TEXT on current line.

    vedtopfile() and vedendfile()
        Move to top or bottom of file.

    vedmarkfind()
        Move to beginning of marked range.


13.2        Syntax Directed Moves
---------------------------------

    ved_mm
        Move to Matching end. Uses -vedopeners-  and  -vedclosers-  to
        recognise  opening  and closing brackets.  E.g.  If the cursor
        is just before "if", ENTER MM moves it to after  the  matching
        "endif".

    ved_mp
        Match parenthesis.  Moves right to next  '(',  or  ')'.   Then
        moves left or right to matching ')' or '('.

    vedmoveitem()  -> item
        Return next text item in file, move cursor past it,  see  also
        -vednextitem-


13.3        Testing The Edit Position
-------------------------------------

    vedatend()
        TRUE if at end of file (i.e.  after last line of text).
    vedatitemend(<line>,<col>)
        True if that location is legitimate Pop-11  item  boundary  for
        end if word, number, etc.
    vedatitemstart(<line>,<col>)
        True if that location is legitimate start for Pop-11 item.
    vedatstart()
        True if at the beginning of the first line of the file.


13.4        Position Stack Commands
-----------------------------------

The position stack,  -vedpositionstack-, allows cursor  positions to  be
stored and retrieved. -vedpositionstack- is a list of 3-element vectors,
each vector contains a line number,  a column number and the row  number
in the current window.

-vedpositionstack- is manipulated by the following procedures;

    vedpositionpush()
        Adds the current position i.e.  line, column and row number in
        the current window to the start of -vedpositionstack-

    vedpushkey()
        Adds the current position to the  start  of -vedpositionstack-
        If the stack contains more than five positions the last one is
        removed, ensuring that if -vedpositionstack-  has  more  than  5
        saved  positions,  it will be truncated.  Thus only the 5 most
        recently pushed and non-popped positions  will  be  available.
        -vedpositionpush-  should be used in procedures which don't want
        the stack truncated.

    vedpositionpop()
        Moves the cursor back to the position  at  the  front  of  the
        stack.   Does  not restore position of line in window.  If the
        stack contains less than five  saved  positions  the  restored
        position is then moved to the back of the stack.

    vedpopkey()
        Moves the cursor  to the  position at  the front  of the  stack,
        restoring the position of the line  in the window. If the  stack
        contains less than five saved positions the restored position is
        then moved to the back of the stack.

        -vedpopkey- is like -vedpositionpop- except that if the restored
        position is not in the current window, it restores the  position
        so that  it occupies  the same  row in  the window  as when  the
        position was  saved.  E.g.  if  you save  a  position  with  the
        procedure starting at  the top of  the screen, then  when it  is
        POPped the procedure will again start at the top.

    vedexchangeposition()
        Exchanges the current position with that at  the  top  of  the
        stack.   The  current  position  is  placed  at the top of the
        stack.  Does not truncate the stack when it contains more than
        five positions.

The saved positions are adjusted  appropriately  by  procedures  which
insert or delete lines.

A separate stack is saved for each file edited.  Thus  when  switching
from  one  edit  buffer  to  another,  the  locations  reachable using
-vedpositionpop- change.

The procedure -ved_cps- clears the positionstack by assigning  an  empty
list to -vedpositionstack-.


14.0  MARKED RANGES
-------------------

Sections of  the  file can  be  "marked" in  order  to select  text  for
deletion/movement or to restrict the  scope of certain editor  funtions.
The line  number of  the  first line  in the  marked  range is  held  in
-vvedmarklo- and that of the last line in -vvedmarkhi-. No marked  range
exists when -vvedmarkhi- is equal to zero.

The marked range will be denoted on the screen by a 'mark', usually  a
vertical  line,  placed  against  every line of the range in the first
column of the  screen.   The  character  for  this  mark  is  held  in
-vedscreenmark-.

The marking of the range on the screen may  be  supressed  by  setting
-vedediting- to be FALSE, or by setting -vedscreenmark- to be `\s`.
The procedures used to mark ranges are:-
    vedmarklo()
        Select the current  line as  the first of  "marked" range,  i.e.
        make -vedline- the value  of -vvedmarklo-. If  the new value  of
        -vvedmarklo- is greater than  the current value of  -vvedmarkhi-
        -vvedmarkhi- will be  made equal to  -vvedmarklo- The screen  is
        updated accordingly.

    vedmarkhi()
        Select the current line as the last of "marked" range. i.e. make
        -vedline- the  value  of  -vvedmarkhi-  and  update  the  screen
        accordingly. If the new value  of -vvedmarkhi- is less than  the
        current value of -vvedmarklo-,  -vvedmarklo- will be made  equal
        to -vvedmarkhi-. The screen is updated accordingly.

    ved_crm
        Unmarks the marked range,  leaving  no  portion  of  the  file
        marked.  The screen is updated accordingly.

Procedures for finding and checking marked ranges:-

    vedmarked(<line>)
        Returns TRUE if line is in marked range, otherwise FALSE.

    vedmarkfind()
        Make the beginning of marked range the current position.

The procedures  -vedmarkpush- and  -vedmarkpop-  manipulate a  stack  of
marked ranges. The  stack itself  is not accessible,  but consists  of a
list of three-element vectors. Each vector contains two line numbers and
a character code (-vvedmarkhi- -vvedmarklo- and -vvedsreenmark-).  These
procedures can be  used for  saving and restoring  marked ranges  within
user defined procedures. For an example of their use SHOWLIB * VED_JJP.

    vedmarkpush()
        Push the current marked range and screen mark onto the  stack.
        Does not reset the marked range.

    vedmarkpop()
        Pop  the  most  recently  stored   marked   range,   resetting
        -vvedmarkhi-  -vvedmarklo-  and  -vvedscreenmark- If part of the
        range is in the current window,  it  will  be  marked  on  the
        screen.

        There are several  procedures  for  marking  certain  specific
        portions of the buffer:-

    ved_mbe
        Mark file from beginning to end.

    ved_mbf
        Make first line of the file the beginning of marked range.

    ved_mef
        Make last line of file end of marked range.
    ved_mcp
        Mark current Pop-11 procedure from beginning to end.


15.0  DELETE COMMANDS
---------------------

Although VED doesn't  make  available  a  general  UNDO  facility  for
recovering  from  changes  made  to  the  buffer,  there  is a limited
capability for undoing the effects of deletions.

Three buffers  are maintained  for the  storage of  single instances  of
deleted text, -vveddump- -vvedwordump-  and -vvedlinedump-. Most of  the
delete procedures copy the deleted text  into one of these buffers,  the
contents of  which can  be  reinserted into  the  buffer with  the  YANK
commands(see below).

There is a fourth  buffer used by the  library procedures -ved_cut-  and
-ved_splice-, namely -vvedcut_dump-, a list of strings.

Finally LIB * VEDBLOCKS,  which can be used  for inserting and  deleting
arbitrary rectangular  blocks of  text  in VED,  uses  -vvedblockdump- a
vector of strings.

There is  only one  version of  each delete  buffer, so  they  provide a
mechanism whereby text may be copied  between files, as well as  between
different parts of a file.

The procedures for deleting portions of the buffer are:-

    vedchardelete()
        Delete character to left of cursor.

        When called at the start of a line, joins that line to the end
        of  the  preceding  line.   Unnecessary  spaces  and  tabs are
        removed, and if the preceding line  is  not  empty,  a  single
        space  is  inserted  between the two merged text portions.  If
        break-mode is set and the line is too long, it will be  broken
        at a suitable place.

    veddotdelete()
        Delete the character underneath the cursor.

    vedclearhead-()
        Delete everything to the left of the  cursor  on  the  current
        line and store the deleted text in -vvedworddump-

        When called at the start of a line, joins the line to the  end
        of the preceding line (see -vedchardelete- above).

    vedlinedelete()
        Delete the  current  line  and  copy  the  deleted  text  into
        -vvedlinedump-,  unless  the current line is empty in which case
        the contents of -vvedlinedump- will remain unchanged.

    vedcleartail()
        Delete everything to the right of and including the  character
        below the cursor and store the deleted text in -vvedworddump-

        Has no effect at the end of a line.

    vedwordleftdelete()
        Delete the word to the left of and not  including  the  cursor
        and place the deleted text in -vvedworddump-

        A "word" is determined by the  Pop-11  character  types.   Text
        will  be  deleted  until a character type boundary is reached.
        Roughly, a group of spaces or a sequence  of  characters  that
        would be recognised as a text item in Pop-11 will be deleted.

        When called at the start of a line, joins that line to the end
        of the preceding line(see -vedchardelete- above).

    vedwordrightdelete()
        Delete the word(see above) to the right of and  including  the
        cursor and store the deleted text in -vvedworddump-

        If called at the end of a line this procedure moves the cursor
        to the beginning of the next line.

    ved_d
        Delete marked range and store the deleted text in -vveddump-

    ved_da
        Delete marked range and append to -vveddump-


15.1        Yanking: retrieving deleted text
--------------------------------------------

VED (at present) maintains three temporary stores for text deleted from
the buffer.

    -vveddump-
        for text deleted by ved_d, or ved_da or copied by ved_copy
        (A list of strings)

    -vvedworddump-

    ved_y or ved_yank
        Insert the contents of -vveddump- into the  current  file  after
        the current line.

        Either procedure can be given a line number  as  an  argument.
        If  a  numeric  argument is supplied, the contents of -vveddump-
        will be inserted after that line, e.g.

            <ENTER> y 0

        to insert the contents of -vveddump- at  the  beginning  of  the
        file.

    ved_yankl
        Insert the contents of -vvedlinedump- before the current line.

    ved_yankw
        Insert the contents of -vvedworddump- at the current position.

All the yank commands can be used several times on the  same  buffers,
and for copying text between files.

There is one other YANK procedure  -ved_yankc-  which  behaves  somewhat
differently from the others...

    ved_yankc
        Insert the contents of  the  marked  range  into  the  command
        buffer.   The  cursor will be returned to the current location
        in the text.


15.2        Moving And Copying Text
-----------------------------------

The delete buffers can be used  for  copying  and  moving  text,  both
within  a  file  and  between files.  Some of the following procedures
alter the delete buffers locally, these do not  therefore  change  the
contents  of  the  buffers.   Unless  otherwise indicated it should be
assumed that the buffer contents will change.

    ved_copy
        Copy the marked range into -vveddump-

    ved_ca
        Append a copy of the marked range onto the end of -vveddump-

    ved_m
        Move the marked range to after the current line, uses -vveddump-
        locally.

    ved_t
        Insert a copy of marked range after  the  current  line,  uses
        -vveddump- locally.

The procedures -ved_ti- -ved_to- -ved_mi-  and -ved_mo- can be used  for
moving and copying text from buffer to buffer. (Compare the "append"
procedures listed below, ved_wapp, ved_wappr, etc.)

All these procedures assume that if -vedargument- is non-empty it  is  a
filename,  specifying  which  file  other  than  the  current  one  is
involved.  The default file is the most recently edited file i.e.  the
second  file  in  -vedbufferlist-.   None of these procedures alters the
value of -vveddump-.

T stands for Transcribe (or copy), M for Move (i.e.  delete and yank)
I stands for In (to the current file), O stands for Out (from  current
file)

    ved_ti <file>
        transcribe (copy) marked range from <file> IN to current file.

    ved_to <file>
        transcribe marked range OUT to other file.

    ved_mi <file>
        MOVE marked range from <file> IN to current file i.e.  (delete
        from other file).

    ved_mo <file>
        MOVE marked  range  OUT  to  <file>  from  current  file  i.e.
        (delete from current file).

In the case  of -ved_to- and  -ved_mo- if the  specified <file>  doesn't
exist it will be created.

In all cases the new text is inserted immediately after the  "current"
line  in  the target file.  The inserted text will not be 'marked', in
either case.


16.0  COMPILE FROM BUFFER COMMANDS
----------------------------------

Rapid switches may  be  made  between  the  Poplog  subsystems,  (i.e.
Pop-11,  PROLOG  and LISP) and VED.  Pop-11, PROLOG and LISP code may be
compiled directly from the buffer, and PASCAL programs (on VMS machines
only in the  buffer may be compiled and executed from the buffer.


16.1        Compiling From Disc Files
-------------------------------------

The compiler used by these procedures  will  depend  upon  the  Poplog
subsystem from which the editor was entered.

    ved_load <file>
        Assumes that -vedargument- holds the name of a file and attempts
        to load that file.

    ved_lib <file>
        An autoloadable extension to VED that assumes that -vedargument-
        holds  the name of a library file in one of the directories in
        POPUSESLIST and attempts to load it.  If no file extension  is
        specified  the  value of POP_DEFAULT_TYPE will be added to the
        name given e.g.  '.pl'.


16.2        Compilers
---------------------

The compiler used by those procedures that compile text from VED buffers
will depend upon the current value of -popcompiler-. This is set for the
current file when  it is  read into the  editor, according  to the  file
type:

    compile for Pop11 files

    lisp_compile for Lisp files.

    prolog_compile for Prolog files.
        (PROLOG text will be compiled in reconsult mode).

    ml_compile for ML files

The user procedure -vedveddefaults- can over-ride this setting, as can
the user defined list -vedfiletypes-. See HELP * VEDFILETYPES.

A single file/buffer may contain a mixture of Pop-11, PROLOG  and  LISP
text.   For  an explanation of the mechanism for switching between the
Poplog languages within a single file see HELP * LANGUAGES.


16.3        Compiling Buffers
-----------------------------

    ved_l
        Compile (load) all the compileable files, and continue editing
        the current file.

    ved_l1
        Load only the current file.

    vedcompilefiles()
        Compile all compileable and changed files.


16.4        Compiling Sections Of The Buffer
--------------------------------------------

The procedure  -ved_lmr- uses  -popcompiler- to  compile the  text  in a
marked range. If there is no marked range, the current line is compiled.

Some syntax errors are trapped, and a shortened message printed on the
command  line.   The  cursor  will then be positioned at the point the
compiler has read to.

Other output may be directed to editor buffers or not as the user sees
fit.


16.4.1      Output
------------------

Output that is  generated during  the compilation of  program text  with
-ved_lmr- can be directed into an editor buffer (either the current file
or a different file),  or be printed  out at the  bottom of the  screen.
These options  are controlled  by the  variable  -vedlmr_print_in_file-,
which may be FALSE, TRUE, or a STRING.

If -vedlmr_print_in_file- is  a string,  this string will  be used  as a
filename. Output will go into  the named file, at  the end of the  file.
The default  value of  -vedlmr_print_in_file- for  Pop-11 users  is  the
string, 'output', for prolog users 'prolog.pl', and so on.

If -vedlmr_print_in_file- is TRUE then output will go into  the  CURRENT
file.

If -vedlmr_print_in_file- is FALSE, output  is printed at the bottom  of
the screen,  and  VED will  request  the  user to  press  RETURN  before
refreshing the screen.

The procedure -ved_output- (i.e. ENTER output) can be used to alter  the
value of -vedlmr_print_in_file- as follows:

If -vedargument- is a string that is = '.' i.e.

    ENTER output .
        Then the current file (i.e. the one in which ved_lmr is invoked)
        will become the output file.

elseif -vedargument- is a string that is = '^' i.e.

    ENTER output ^
        Then output will go onto the screen without going into any file.

otherwise if -vedargument- is a string it is assumed to be a file-name.

    ENTER output foo.p
        Then will make the file called 'foo.p' the output file.

If  -vedargument-  is  an   empty   string,   the   current   value   of
-vedlmr_print_in_file- is displayed.


16.4.1.1.   Error Messages
--------------------------

Some syntax errors will be  trapped,  and  instead  of  a  full  error
message,  a  short message will be displayed on the command line.  The
cursor is left at the point that the compiler has read to.  This  will
not neccessarily be the source of the error.

Run-time errors or undeclared variables will cause a full  message  to
be printed, either
    in the output file (if -vedlmr_print_in_file- is a file name) or
    at the bottom of the screen, if -vedlmr_errs_in_file-  is  FALSE  or
        -vedlmr_print_in_file- is FALSE, or
    in  the  current  file,  if  -vedlmr_print_in_file-  is   TRUE   and
        -vedlmr_errs_in_file- is TRUE.

The default for -vedlmr_errs_in_file- is FALSE.

The   combination    of    both    -vedlmr_print_in_file-    TRUE    and
-vedlmr_errs_in_file- TRUE  is convenient  for preparing  a record  of a
full interactive session, including all error messages.

The procedure -ved_errs- sets -vedlmr_print_in_file- TRUE, switches  the
value of -vedlmr_errs_in_file-, and reports the current value.

If error messages are put into the current file they are automatically
marked,  so  that  they can be deleted with ENTER D.  Warning messages
about undeclared variables are inserted as comments, so  they  can  be
deleted or left in the file.

If error messages are inseerted into the current file the  symbol  '^'
should appear above the error message to show how far the compiler had
got before the error  occurred.   (The  mistake  will  not  always  be
exactly at that location.  Sometimes it may be several lines earlier.)

Undeclared variable messages may occur immediately before or after the
line where the variable is first used.


16.4.1.2    Interactive programs
--------------------------------

Interactive programs invoked by the  user can call standard  interactive
procedures like -rawcharin- -charin- and  -readline-. The last two  will
prompt for something  to be  typed in  the file  currently specified  by
-vedlmr_print_in_file-, and when RETURN is pressed the current line will
be handed over as input to the program. To represent -termin-, i.e.  the
"end of file" character  for interactive programs invoked  in VED it  is
necessary to  call  the  procedure  -ved_end_im-.  By  default  this  is
associated with the input key sequence ESC CTRL-z. However CTRL-z is not
available for some Unix users, as it is set as the "suspend"  character,
so in such cases it is necessary to use
        ENTER end_im

In earlier versions of Poplog a special procedure -vedreadline- was used
inside VED as an alternative value for value of -readline- to be used by
-ved_lmr-. This is now redundant, though LIB * VEDREADLINE remains  as a
demonstration library program.

When an interactive procedure is invoked  in VED it is not necessary  to
respond immediately. As long as the user moves to another VED file it is
possible to  invoke  any  Poplog  facilities,  including  calling  other
procedures or inspecting HELP files, before returning to the interactive
file to type in the answer. This is because the interaction makes use of
the Poplog "process" mechanism. Compilation  of a marked range  causes a
process to be started up that is suspended when interaction is required.
Pressing RETURN in the interaction file causes the process to  continue,
with the current line as input. Alternatively a range can be marked  and
and <ENTER> lmr used to provide more than one line of input.


16.5        PROLOG Compilation
------------------------------

As the prolog system is a sub-system of Pop-11, most of  the  preceding
section applies to the compilation of PROLOG text from the buffer e.g.
when VED is called from PROLOG, all the commands that  would  normally
cause an exit to Pop-11 return control to the PROLOG system.

In a similar way, HELP, TEACH and REF files  can  be  accessed.   File
names should not be enclosed in quotes.  An example line would be:

    ?- ved myfile.pl

To return to Prolog, any of the  normal ways of exiting from VED may  be
used.

After an exit from VED using -ved_x- any files that have  been  changed
and whose names end in .PL will be 'reconsult'ed.

Various other facilities of VED can be used if files  of  Prolog  code
have  the extension .PL e.g.  a marked range can be 'reconsulted' with
-ved_lmr-.

As the action of 'reconsult' is to supersede any  existing  definition
for  a  predicate  with  the  new clauses, it is important to mark the
WHOLE of the new definition of a predicate that has changed.

Prolog  goals  can  also  be  included  in  a  marked  range   to   be
'reconsult'ed,   just   as   in   any  file  that  is  'consult'ed  or
'reconsult'ed.  These goals will be tackled by Prolog when it  reaches
them.

If goals perform any input/output - output will be to the DOIT  buffer
and the input will be taken from the marked range.

All input will be taken from the marked range, EXCEPT in two important
cases.   When Prolog is prompting to see whether alternative solutions
are required, or when it is prompting for an option at  a  spy  point.
It  will then read from the terminal (and copy the input into the DOIT
buffer).

Syntax errors will be announced in the DOIT buffer,  and  Prolog  will
try  reading  again  from  it's  position  in the marked range.  Other
mishaps cause a message to be displayed and an immediate abort back to
VED.

When Prolog called from VED interacts via the terminal, it is convenient
to use the  POP procedure  -readline- A possible  definition for  such a
Prolog predicate would be;-

    readline(L) :- prolog_eval(apply(valof(readline)),L).

This gives prolog users all the advantages of interaction in the editor,
as described above.

16.6        Other Languages
---------------------------

On Unix systems, the easiest method for compiling programs written  on
non-Poplog  languages  is  to  use  the shell escape commands from the
command line.

On VMS systems commands could be provided to use DCL command files  to
enable  the compilation and running of non-Poplog programs from within
VED.  Examples of these commands (for compiling PASCAL  programs)  are
in the [POP.LIB.VED] directory, and documented in HELP * PASCAL/

    ved_pascomp
        Compile and link the current  file,  creating  .OBJ  and  .EXE
        files.

    ved_pasexec
        Execute a previously compiled image of the current file  (i.e.
        search  for  a .EXE file, in the same directory as the current
        file and, if successful, RUN it).

    ved_pasrun
        compile AND execute current file.

In each case an error will occur if the current file is not  a  '.PAS'
file.

The screen will be cleared at  the  start  of  execution  and  various
messages will be produced as compilation proceeds.

Each of the above commands may have optional assignments of the  input
and  output  streams  to files (or devices).  The assignments take the
form:

        in=foo.dat;  (get input from file foo.dat)
        out=results.lis;  (send output to results.lis)

Spaces are not permitted and the semicolon is always required.

These assignments may be in either order (if both are specified).  The
default    is    to   read   from   and   write   to   the   terminal.
Devices,directories etc.  may be specified  as  required  (the  string
between '=' and ';' is passed literally to DCL).

Examples:

    ENTER pasrun                          (input and output to terminal)
    ENTER pasrun in=mydat.;out=results.lis;
    ENTER pasrun in=mydat2.;             (output to terminal)
    ENTER pasrun out=bing.baz;

Note:  input and output specifications may be given with  any  of  the
above  commands,  but -ved_pascomp- doesn't use them for anything, since
they only apply when the program is run.

On Unix systems there are two demonstration packages for compiling C and
Fortran programs from VED. See HELP * CCOMP, HELP * FCOMP.


17.0  LEAVING VED
-----------------

17.1        To VED
------------------

This section attempts to explain what happens when a file is quit, but
control remains within the editor.

There is one basic procedure for quitting a file and retaining control
within VED, -ved_q-.  All the other procedures mentioned in this section
are based on this.

    ved_q
        Quits  the  current  file,  removing  the  file  record   from
        -vedbufferlist-.   If  both -vedwriteable- and -vedchanged- are TRUE
        then a check will be made as to whether  the  file  should  be
        saved, unlike -ved_rrq-, which quits regardless.

        The file at the head  of  -vedbufferlist-  becomes  the  current
        file, if this list is empty then the default file will be read
        into the buffer, see below.

        The default file name is changed according  to  the  following
        algorithm:-

   if there are no more files in the  editor  i.e.   -vedbufferlist-  is
   empty then

      if   the   current   file    is    a    TEACH    file,    assign
      vedteachdirectory:teach  to -vedteachname- i.e.  make -vedteachname-
      point to TEACH TEACH.

      else assign an empty string to the  default  name,  forcing  the
      choice  of  the relevant system default file e.g.  'temp.p' when
      quitting VED files or an index when quitting DOC and REF files.


The user-assignable procedure -vedvedquitfile- is run whenever a file is
quit in VED. It's default value is -identfn-.


17.2        Quitting to Poplog
------------------------------

It is possible to put Pop-11 instructions  on  the  VED  command  line.
When  the command line starts with a colon (the Pop-11 prompt) then the
rest of the command is treated as Pop-11  code  to  be  compiled.   Any
output  will  appear  on the status line if possible, otherwise at the
bottom of the screen.


17.2.1      Procedures For Returning Control To Poplog
------------------------------------------------------

These procedures all return control to the Poplog subsystem from which
VED was entered.

    ved_pop
        Returns control to the Poplog subsystem  from  which  VED  was
        called  e.g.   Pop-11.  Saves the state of the current file and
        executes exitfrom(vedprocess).

    ved_c
        returns control to Poplog, saving the  edit  state.   Compiles
        all files that need compiling i.e.  those files for which both
        -vedcompileable     and     -vedneedscompiling-     are     TRUE.
        -vedneedscompiling-  will  be  set TRUE for any compileable file
        when it is changed and will be set FALSE  after  the  file  is
        compiled.

        The compiler used for each file will depend upon the value  of
        -popcompiler-   for  that  file.   If  an  error  occurs  during
        compilation, control returns to VED with the file that  caused
        the error as the current file.

        If the compilation succeeds, -ved_pop-  is  executed,  returning
        control to Poplog.

    ved_c1
        Compiles  the   current  file,   if   necessary  i.e   if   both
        -vedneedscompiling- and -vedcompileable- are TRUE. The  compiler
        used will  depend  upon  the value  of  -popcompiler-.  Executes
        -ved_pop- if successful.

    ved_x
        Writes all the changed and writeable files, then compiles  all
        the  compileable  files  which  need compiling.  Equivalent to
        executing -ved_w- followed by -ved_c-

    ved_x1
        Compiles and writes only the current file as neccessary,  i.e.
        executes -ved_w1- followed by -vedc1-


17.3        To DCL (VMS) or SHELL (Unix)
----------------------------------------

On exit from the  Poplog system i.e. when  SETPOP reads TERMIN(^Z)  from
the standard  input,  the procedure  SYSEXIT  is called.  SYSEXIT  first
closes all the currently  open files and  then runs the  user-assignable
procedure POPEXIT(default -identfn-).  Unless the  procedure in  POPEXIT
prevents the system from exitting, e.g. by doing a SETPOP, the procedure
-vedpopexit- is  then executed.  -vedpopexit- checks  if there  are  any
changed but unwritten files and if -vedalwaysask- is FALSE writes all of
these files to  disc. If -vedalwaysask-  is TRUE and  there are  changed
files the user will be asked whether they should all be written.

If POPEXIT is re-defined, it may be wise for it to call vedpopexit().

N.B. -sysexit- is not called when the  Poplog  session  is terminated
with ^Y in VMS or the "kill" signal in Unix.

Commands for ending the editing session:

    ved_qq
        Quits the editor, requests confirmation if any files have been
        altered since they were last saved.

        Uses SYSEXIT.

    ved_xx
        Exits from VED, writing all the files that have been altered.

    ved_rqq
        Resets the terminal and exits from VED and Poplog.   Does  not
        call SYSEXIT.



18.0  SEARCH AND SUBSTITUTE COMMANDS
------------------------------------

This section describes the procedures for searching  VED  buffers  for
text  strings.   These  procedures  allow the search string to contain
special characters e.g.  to accept only successful matches that  begin
or end on text boundaries etc.
    See also REF * VEDVARS and HELP * VEDSEARCH

All the search procedures  are  case  specific  i.e.   if  the  search
argument  is  'AbCd' then matches will be made only against 'AbCd' and
not against 'abcd' or 'ABCD'.  There is no provision  for  a  non-case
specific  search,  though the user can implement this, if desired.  It
must be noted however that as  the  search  procedures,  as  presently
implemented,  utililse  VAX-VMS string matching instructions, a search
procedure written entirely in Pop-11 will probably be very slow.

18.1        vvedsrchstring
--------------------------

All the search procedures update the value  of  -vvedsrchstring-.   This
will  be either FALSE, before the first call of a search procedure, or
the most recently used search-string.


18.2        ved_search
----------------------

The  most  convenient  user-interface  with  the  search  procedures  is
provided by -ved_search-, a procedure that searches forwards through the
buffer for the target string.

-ved_search- is called  directly from the  command line interpreter  for
the most commonly used search commands;  ENTER / and ENTER "  by-passing
the command-line parser,  and without  splitting the  command line  into
command and argument strings. It assumes that -vedargument- contains the
complete command line and its  behaviour depends on the first  character
in -vedargument- (the delimiter) as follows:-

    If the string delimiter is '/' i.e.  ENTER /string/

        Search forward for the first occurrence of 'string'.


    If the string delimiter is '"' i.e.  ENTER "string"

        Search forward for  the  first  occurrence  of  'string'  that
        starts  and  ends on text item boundaries, using the full text
        itemising rules of Pop-11. I.e. it rejects embedded occurrences
        of the string.

The delimiting  character at  the  end of  these commands  is  optional,
unless  the  string  has  trailing  spaces,  in  which  case  the  final
occurrence of the delimiter is required to indicate how many spaces.

If -vedargument- contains only one character, this must be either `/` or
`"`  indicating  search  type,  and the most recent search string, the
value of -vvedsrchstring-, is searched for.

When the search is successful, -vedline- and -vedcolumn- are altered  so
that the cursor is positioned at the start of the found string.

When no matching string is found between the cursor position  and  the
end  of the file, -ved_search- will "wrap around" and start again at the
top of the file.

When a search is unsuccesful  -vederror-  is  called  and  the  original
cursor position is retained.

The procedure -ved_re_search- searches forward for the first  occurrence
of  most  recent  search  string  used. It is normally mapped onto the
key sequence <ESC> /

Similarly   -ved_re_backsearch-, described below, searches backwards. It
is normally mapped onto <ESC> \


18.3        ved_backsearch
--------------------------

This function is called in similar fashion  to  VEDSEARCH  by  ENTER \
or ENTER `, i.e.

    ENTER \string\
or
    ENTER `string`

As before the final occurrence of the search string delimiter is
optional, unless used to indicate spaces, e.g.
    ENTER `string `

These commands cause VED to search backward until it finds an occurrence
of 'string' and positions the cursor at the start of the occurrence.

The use of the second form is analogous to ENTER ", i.e. it prevents the
location of embedded strings.

-ved_backsearch- differs  from -ved_search-  in that  it does  not  wrap
around from the beginning to the end of the file. (Before version 14  it
could not  contain any  special  search characters,  e.g. @?,  but  that
restriction has been  lifted, though on  long files searching  backwards
can be slow if search patterns are used.)

The procedure -ved_re_backsearch- searches backwards for the most recent
search string using -ved_backsearch-


18.4        vedtestsearch
-------------------------

-vedtestsearch- requires two arguments, a string and a flag and  returns
TRUE or FALSE

    vedtestsearch(string, flag) -> boolean

The string, possibly including special characters is searched for,  in
a  forwards  direction.   If  a  successful  match  is  found, TRUE is
returned, otherwise FALSE.

If flag is FALSE, -vedtestsearch- will accept  only  those  matches  for
<string>  that  begin  and  end on text item boundaries, otherwise any
occurrence of <string> will be accepted.

This procedure does not test for 'wrapping', therefore

    while vedtestsearch('example') do
        ;;; DO NOTHING!
    endwhile;

will cycle indefinetely if there is a successful match.


18.4.1      vedlocate
---------------------

-vedlocate- is a library procedure that "packages" -vedtestsearch-

    vedlocate(<string>, <word> or <integer>)

-vedlocate- searches forwards  through the buffer  for an occurrence  of
the target item. If this item is  a word or integer it finds only  those
occurrences that begin and end on text item boundaries. If the item is a
string, -vedlocate- finds any occurrence, whether embedded or not.

-vedlocate- leaves the cursor positioned at start of the  matching  text
if it is successful and calls -vederror- if no match is found.

18.4.2      vedbacklocate
-------------------------

-vedbacklocate- searches backwards  for  the  first  occurrence  of  its
argument using -ved_backsearch-

    vedbacklocate(<item>)

If <item> is a word or integer it will match only occurrences that begin
and end  on  text item  boundaries.  If item  is  a string  matches  any
occurrence. Calls -vederror- if unsuccessful.


18.5        Search Strings
--------------------------

Search strings may be composed of  ordinary  characters,  and  special
pattern elements, with the following properties.

      @?              : matches any single character
      @@              : matches a '@'
      @<delimiter>    : matches the delimiter character
      @a              : matches beginning of line
      @z              : matches end of line
      \^A             : matches CTRL-A

(For more complete details of how to  insert  CONTROL-characters  into
search strings see HELP ASCII).


18.6        Examples
--------------------

These examples refer to the enter commands

    /fred/          : search forward for next occurrence of 'fred'.

    "fred@z         : search forward for next occurrence of "fred"
                      at the end of a line. Will not find alfred

    // or /         : search for the next occurrence of previous
                      search string.

    "" or "         : search for the next occurrence of previous
                      search string that begins and ends on text
                      boundaries

    /fred@z@ajoe    : search for 'fred' at the end of a line followed
                      by 'joe' at the beginning of the next line.

    /\^L            : search for CTRL-L i.e. form-feed


19.0  COMBINED SEARCH AND SUBSTITUTION COMMANDS
-----------------------------------------------

VED provides substitution procedures that  search  for  a  string  and
replace  it  with another one.  The substitution can be interactive or
not as required.

19.1        Interactive Substitution
------------------------------------


-ved_s- is the procedure that does the interactive substitution,  asking
the  user whether each successful match of the search string should be
replaced.  This is normally invoked from the command line, e.g.

    ENTER s/string1/string2/
        -ved_s- assumes that vedargument holds a string beginning with a
delimiter  character,  and  containing at least one other delimiter to
separate the search and replacement strings.  The acceptable delimiter
characters are / or ".  These signify whether embedded or non-embedded
instances of the search string are to be replaced.  The two  delimiter
characters must be of the same type e.g.

    ENTER s/string1"string2

will cause an error.

-ved_s- searches forward for the next occurence of the first string, and
if  found,  "wiggles"  the  cursor  and prompts for instructions.  The
acceptable responses are

    y or Y      : do the substitution and stop.
    RETURN      : do the substitution and search for the next
                  occurrence of string1.
    DEL         : leave this occurrence unchanged and continue search
    n or N      : stop without doing the substitution.

The search string must conform to the requirements detailed above,  in
the section on search.

The  matching  instance  of  the  search   string   is   assigned   to
-vvedfoundstring-


19.1.1      Replacement Strings
-------------------------------

The replacement strings may contain the following special sequences:

      @n      : insert a newline
      @<dlm>  : insert the character used as the delimiter
      @&      : insert a copy of the text matched by the search string
      @@      : insert @

If an empty search string is given, the most recent search  string  is
used.   If  both  search and replacement strings are omitted, the most
recent search and replacement strings are used.


19.1.2      Examples
--------------------

    s/fred/fried    : transform 'fred' into 'fried', interactively.

    s"fred"fried    : as above, but ignores occurrences of 'freddy'
    s"f@?@?d"fried  : transform both 'fred' and 'food' into 'fried'.
    s/@z@a@z@a//    : delete a blank line


19.2        Non-interactive Substition
--------------------------------------

The non-interactive substitution procedures detailed below all  expect
-vedargument- to be in the form described in the previous section.

    ved_gs
        Global Substitute: replaces ALL occurrences of the search string
        in the  current VED  file.  A running  count  of the  number  of
        substitutions is displayed on the status line.

    ved_sgs
        Silent Global Substitute: like ved_gs, but does not display the
        counter. This can make it much faster on large files.

    ved_gsr
        Substitute ALL occurrences of the search string in the  MARKED
        RANGE. (See HELP * MARK)

    ved_gsl
        Globally Substitute occurrences of the search string in the
        current Line.

    ved_gsp
        Globally Substitute occurrences of the search string in the
        current Procedure.

The number of substitutions  will  be  counted  and  a  running  total
displayed  on  the  status  line for all except ved_sgs.

        Examples

            ENTER gs/@af/F        : change all f's at the start of a
        line to F

            ENTER gs              : redo previous substitution,
        possibly on a different file.

If the delimiter " is used then only non-embedded strings will be
replaced.


20.0  MISCELLANEOUS PROCEDURES
------------------------------

20.1        Compilation
-----------------------

    ved_lcp
        load the current procedure.  This causes the current procedure
        to  be  marked,  and  then loaded.  The procedure heading must
        start at the beginning of a line.
    ved_pcmr
        Prolog Compile marked range.  For use with prolog when the
        current value of -popcompiler- is not suitable.
    ved_plx
        exit  from  VED  and  call  prolog  on  the  current  file  in
        re-consult mode.

    See also REF * VEDCOMMS, for a more complete list of VED commands.


20.2        Deletion
--------------------

    ved_dcp
        Delete current procedure and  copy  text  to  -vveddump-.   Uses
        VED_MCP and VED_D()

    ved_delout
        Delete all Pop-11 output lines i.e.  lines beginning with '**',
        from the current file.

    ved_deof
        Delete from and including the current line up to  the  end  of
        the file and copy text to -vveddump-

    ved_clear
        Delete everything from the current file.  Does NOT  copy  text
        to a safe location.

    See also REF * VEDCOMMS and REF * VEDPROCS


20.3    Interactive Definition Commands
---------------------------------------

With the procedure -ved_dm- it is possible to interactively define a new
edit macro, the name of which must be entered with the command from  the
command line  and,  if required,  store  the definition  in  the  user's
vedinit.p. file.  e.g. suppose  that  a frequently  made mistake  is  to
mistype 'define'  as 'dfine'.  a command  called FIX  could be  defined,
which will effect a global substitution.

    ENTER dm fix

The user will be asked whether the change is to be permanent,  and  if
so  the  user's  vedinit.p  file will be edited, otherwise a temporary
file will be used.  The procedure ved_fix will be defined and the user
will  be prompted to press keys and terminate with <ESC> pressed three
times.  At this point all the keys that would have to  be  pressed  to
give    the    command    directly    should    be    pressed.    I.e.
ENTERgs/dfine/defineRETURN, then, <ESC> three times.   The  definition
of  ved_fix  will  then  be  completed,  and  loaded,  and  the user's
vedinit.p file will be written, if necessary.

Mistakes made while defining the macro, can be deleted with  ESC  then
DEL.

When the definition is completed, typing
        ENTER fix

will be the same as typing
        ENTER gs/dfine/define


20.4        ved_dk
------------------

Vedsetkey has been packaged, for ease of use during editing sessions, in
the procedure -ved_dk-,  which allows the  user to interactively  define
new functions for  key sequences. This  will inquire as  to whether  the
change is to  be permanent  and if so,  edit the  user's vedinit.p  file
accordingly, otherwise a temporary file will be used.

Two strings of characters are read from the terminal, the key  or  key
sequence to be defined and the characters which are to be simulated.

Mistakes can be deleted with the sequence <ESC> DEL.


20.5        Writing To Disk
---------------------------

    ved_w
        write all files that have been altered.
    ved_w <filename>
        write the current file to the specified file name.
    ved_w1
        write only the current file.
    ved_wq
        write and then quit the current file.
    ved_wqved <filename>
        Like wq followed by a call of VED on a new file.
    ved_wr <filename>
        write marked range into file <filename>.
    ved_wved <filename>
        Like w1 followed by a call of VED on a new file.

The following can be used to APPEND to an existing file on the disk.

    ved_wapp <filename>
        Write and APPend whole current ved buffer to named FILE on disc,
        without reading it into VED like ved_to.

    ved_wappdr <filename>
        Write and APPend to FILE  then Delete marked Range (Much  faster
        than ved_mo and doesn't read FILE into VED).

    ved_wappr <filename>
        Write and  APPend  marked  Range  to  FILE.  (Much  faster  than
        -ved_to-. Uses -discappend-).

    See also REF * VEDCOMMS and REF * VEDPROCS


20.6        Text Formatting
---------------------------

    ved_centre
        Centres current line.  Uses -vedleftmargin-, and -vedlinemax-.
    ved_j
        Fills marked range.  Uses -vedleftmargin-, and -vedlinemax-.
    ved_lcw n
        Transforms next N words to lower case.  N defaults to 1.
    ved_ljmr
        Left Justify Marked range.  Uses -vedleftmargin-.
    ved_margin n
        Set -vedleftmargin-  to  be  N,  if  no  argument,  uses  cursor
        position.
    ved_right <string>
        Adds string to current line, right adjusted.  If  no  argument
        is   given,   right   adjusts  text  on  current  line.   Uses
        -vedlinemax-.
    ved_smr
        Alphabetically sort the marked range.
    ved_sw
        Swap the two characters to left of cursor.
    ved_swl
    ved_swr
        Swap the two words to the left or right of the  cursor.   Uses
        space as delimiter

    See also HELP * FORMAT, HELP * PAGE


20.7        Case transformation
-------------------------------

    vedchangecase()
        If the cursor is on an alphabetic character it changes its case
        from lower to upper or vice versa. This is often mapped onto CTRL-n
        or ESC-u
    vedcapword()
        Capitalises the initial letter of  the current word, making sure
        all other characters are in lower case, then  moves right to
        next word.
    ved_lcw n
        Transforms next N words to lower case.  N defaults to 1.
    ved_lcl n
        Transforms next N lines to lower case.  N defaults to 1.
    ved_ucw n
        Transforms next N words to upper case.  N defaults to 1.
    ved_ucl n
        Transforms next N lines to upper case.  N defaults to 1.



20.8        Further ENTER commands
----------------------------------

    ved_h <topic>
        Allows the user to choose from a list of help files on  topic.
        Copes with minor spelling errors and truncated topics.
    ved_help <file>
        Reads in a file from the help library, or if name is ommited a
        short introductory file.
    ved_hk
        Display information on a key, i.e.  the name of the associated
        function, if any.
    ved_qhelp <filename>
        Quits the current file and reads  in  a  file  from  the  help
        library.
    ved_vh <topic>
        Allows the user to search a file containing information  about
        command mode functions for help on topic.

    See also HELP * DOCUMENTATION, REF * VEDCOMMS


20.9        Text Input Functions
--------------------------------

    ved_ic n
        inserts ASCII character N into the buffer.


20.10       Pop-11 Format Insertion
-----------------------------------

There are several functions for inserting pop11 text  e.g.   VED_UNTIL
causes  an  'until'  construct  to  be input into the buffer after the
current line.

So ENTER until
inserts:

    until CONDITION do
        ACTION
    enduntil;

This uses -vedinsertstring- as follows;-

define ved_until();
    vedlinebelow();
    vedpositionpush();
    vedinsertstring(
        '\n\tuntil CONDITION do\n\t\tACTION\n\tenduntil;');
    vedpositionpop();
enddefine;

Other template insertion functions and the text inserted are

   ved_define

   define NAME (PARAMETERS) -> OUTPUT;
       vars VARIABLES;
   enddefine;

   ved_if
       if CONDITION
       then ACTION
       elseif CONDITION
       then ACTION
       else DEFAULT
       endif;

   ved_repeat

       repeat NUMBER times
           ACTION
       endrepeat;

   ved_unless

       unless CONDITION
       then ACTION
       endunless;

   ved_while

       while CONDITION do
           ACTION
       endwhile;

It is easy for users to define their own extensions to this  facility,
using the  techniques  illustrated  in the  definition  of  ved_until,
above.


21.0  APPENDIX 1: Some important VED variables
----------------------------------------------

This lists some of the main VED variables. See also REF * VEDVARS.

  NAME                  TYPE           DEFAULT          WHERE
vedautowrite         integer/false       1500
vedalwaysask            boolean         false
vedversions          integer/false      false
vedwriteable            boolean      file-dependent
vedbackers               list       [then times do else elseif
                                elseunless step till forever
                                quitif quitunless nextif nextunless
                                returnif returnunless and or case]
vedforwarders            list         [-> ->> --> ==> =>]
vedclosers               list   [) enddefine endfast_for endfor
                                endforeach endforevery endif
                                endlblock endprocedure endrepeat
                                endswitchon endunless enduntil
                                endwhile endfast_repeat end close]
vedopeners               list   [( define fast_for for foreach
                                forevery if lblock procedure repeat
                                fast_repeat switchon unless until while]
vedbreak                boolean      file-dependent
vednonbreakfiles         list        See HELP * VEDFILETYPES
veddelspaces            boolean          true
vedindentstep           integer           4
vedleftmargin       integer/procedure     0
vedlinemax              integer          78 (Depends on terminal)
vednotabs               boolean          Depends on file type
vedcompileable          boolean     file-dependent
vedlmr_errs_in_file     boolean         true
vedscreenlength         integer          24 (depends on terminal)
vedscreenwidth          integer          80 (depends on terminal)
vedwindowlength         integer        varies
vedscrollscreen         integer         false
vedstartwindow          integer          12
vedhelpdirectory        string      depends on operating system
veddocdirectory         string      depends on operating system
vedrefdirectory         string      depends on operating system
vedteachdirectory       string      depends on operating system
vvedampersand           integer         131
vvedquery               integer         129


22.0  APPENDIX 2: Variables associated with each buffer
-------------------------------------------------------

The variables saved by -vedsaveglobals-, i.e.  those variables that  are
buffer specific are as follows (this list may change);

    vedcurrent
    veddirectory
    vedbuffer
    vedline
    vedlineoffset
    vedcolumnoffset
    vedcolumn
    vedstatic
    vedbreak
    vedchanged
    vedwriteable
    vedneedscompiling
    vedcompileable
    popcompiler
    vedpositionstack
    vvedmarklo
    vvedmarkhi
    vvedmarkprops
    vedmarkstack
    vvedbuffersize
    vvedlinesize
    vednamestring
    vedleftmargin
    vedlinemax
    vednotabs
    vedindentstep
    vedwindowlength
    vedscreenoffset
    vedfileprops
    vedprocwait
    vedwasonstatus
    vedstatusline
    vedpwmwindow
    vedpathname


INDEX
-----

The page numbers are no longer  appropriate, and will be updated if  and
when this file is properly reformatted.

Autoloadable files, 14             Graphics characters, 28
Automatic terminal selection, 7
                                   Help, 4
Break mode, 32
                                   Identfn, 4
Charin, 22                         Init.p, 5
Charin_timeout, 23                 Initialisation procedures, 5
Charout, 22                        Interrupt, 15
Command buffer, 13
Command mechanism, 10              Lisp_compile, 42
Compilation, 42
Compile, 42                        Marked ranges, 37
Cursor positioning, 35               compilation, 43

Debugging ved procedures, 15       Newline characters, 16
Definining new commands, 14
Delete buffers, 39                 Pascal compilation
  insertion, 40                      vms command files, 46
Disk quotas, 29                    Pop11 format insertion, 57
Doc, 4                             Pop_file_write_error, 30
Dumps, 39                          Popcompiler, 42, 48, 61
                                   Popdevin, 22
Entering ved                       Popdevout, 22
  from lisp, 3                     Popdevraw, 22
  from monitor level, 3            Popexit, 49
  from pop11, 3                    Poplastchar, 31
  from prolog, 3                   Popautolist, 14
Error handling, 15                 Popready, 15
                                   Popuseslist, 42
File records, 17                   Position stack, 36
Filenames                          Prmishap, 15, 24
  length, 8                        Prolog compilation, 45
  truncation, 8                    Prolog_compile, 42
  unix, 9
    directories, 10                Rawcharin, 22, 24
    environment variables, 9       Rawcharout, 22, 24
    filename truncation, 9         Readline, 44
    metacharacters, 9              Ref, 4
    multiple versions, 9
  vms, 8                           Saved images, 6
    directories, 9                 Screen control procedures, 26
    file types, 8                  Search, 49
    filenames, 8                     case, 49
    underscore, 8                    delimiter, 50
    version numbers, 8               strings, 52
Files                                wrapping, 50
  unix                             Showlib, 4
    access mode, 10                Src, 4
  vms                              Static mode, 34
    access mode, 10                Strnumber, 12
                                   Substitution, 52
  delimiter, 53                    Ved_load, 42
  interactive, 53                  Ved_m, 41
    responses, 53                  Ved_margin, 56
  non-interactive, 54              Ved_mbe, 38
  replacement strings, 53          Ved_mbf, 38
Sysexit, 49                        Ved_mcp, 39
Sysopen, 29                        Ved_mef, 38
Sysread, 28                        Ved_mi, 41
                                   Ved_mm, 36
Tabs, 16                           Ved_mo, 41
Teach, 4                           Ved_mp, 36
Text                               Ved_output, 43
  deletion, 39                     Ved_pascomp, 46
    buffers, 39                    Ved_pasexec, 46
Text formatting, 56                Ved_pasrun, 46
                                   Ved_pcmr, 55
Ved, 4, 61                         Ved_plx, 55
Ved_autowrite, 31                  Ved_pop, 48
Ved_backsearch, 50                 Ved_q, 47
Ved_break, 32                      Ved_qhelp, 57
Ved_c, 48                          Ved_qq, 49
Ved_c1, 48                         Ved_r, 33
Ved_ca, 41                         Ved_re_backsearch, 51
Ved_centre, 56                     Ved_re_search, 50
Ved_char_in_stream, 23             Ved_repeat, 58
Ved_clear, 55                      Ved_right, 56
Ved_copy, 41                       Ved_rqq, 49
Ved_cps, 37                        Ved_s, 53
Ved_crm, 38                        Ved_search, 50
Ved_d, 40, 55                      Ved_smr, 56
Ved_da, 40                         Ved_sw, 56
Ved_dcp, 55                        Ved_swl, 56
Ved_define, 57                     Ved_swr, 56
Ved_delout, 55                     Ved_t, 41
Ved_deof, 55                       Ved_tabs, 17
Ved_dk, 56                         Ved_ti, 41
Ved_dm, 55                         Ved_to, 41
Ved_errs, 44                       Ved_ucw, 57
Ved_gs, 54                         Ved_unless, 58
Ved_gsl, 54                        Ved_ved, 19, 22
Ved_gsp, 54                        Ved_vh, 57
Ved_gsr, 54                        Ved_w, 30, 56
Ved_h, 57                          Ved_w1, 30, 48, 56
Ved_help, 57                       Ved_while, 58
Ved_hk, 57                         Ved_wq, 56
Ved_ic, 57                         Ved_wqved, 56
Ved_if, 58                         Ved_wr, 56
Ved_j, 56                          Ved_ws, 20
Ved_l, 42                          Ved_wtype, 16
Ved_l1, 42                         Ved_wved, 56
Ved_lcp, 54                        Ved_x, 48
Ved_lcw, 56                        Ved_x1, 48
Ved_lib, 42                        Ved_xx, 49
Ved_ljmr, 56                       Ved_y, 40
Ved_lmr, 43                        Ved_yank, 40
Ved_yankc, 13, 40                  Veddocdirectory, 59
Ved_yankl, 40                      Veddocr, 34
Ved_yankw, 40                      Veddointerrupt, 15
Vedalignscreen, 21                 Veddoitfile, 59
Vedalwaysask, 49, 59               Veddoitlimit, 43, 59
Vedappfiles, 19                    Veddotdelete, 34, 39
Vedargument, 12                    Vedediting, 25, 37
Vedatend, 36                       Vededitor, 19
Vedatitemend, 36                   Vedendfile, 36
Vedatitemstart, 36                 Vedenter, 12-13
Vedatstart, 36                     Vederror, 15
Vedautowrite, 31, 59               Vedescape, 60
Vedbackers, 59                     Vedescapetable, 10
Vedbacklocate, 52                  Vedexchangeposition, 37
Vedbreak, 4, 29, 32, 59, 61        Vedfileprops, 6, 61
Vedbuffer, 16-17, 61               Vedforwarders, 59
Vedbufferextend, 17, 34            Vedgetfile, 19
Vedbufferlist, 18, 41, 47          Vedgetlibfilename, 5
Vedchanged, 30-31, 61              Vedgraphicmode, 27
Vedchardelete, 34, 39              Vedhardtabs, 16-17
Vedchardown, 35                    Vedhelpdefaults, 5
Vedchardownleft, 35                Vedhelpdirectory, 59
Vedchardownleftlots, 35            Vedinascii, 23-24
Vedchardownlots, 35                Vedindentstep, 16, 29, 31-32,
Vedchardownright, 35                 59, 61
Vedchardownrightlots, 35           Vedinit, 6
Vedcharinsert, 32-33               Vedinit.p, 6, 55
Vedcharleft, 35                    Vedinitfile, 6
Vedcharleftlots, 35                Vedinput, 23
Vedcharmiddle, 36                  Vedinserting, 27
Vedcharright, 35                   Vedinsertstring, 33
Vedcharrightlots, 35               Vedinsertvedchar, 10, 32
Vedcharup, 35                      Vedinterrupt, 15
Vedcharupleft, 35                  Vedjumpto, 35
Vedcharupleftlots, 35              Vedleftmargin, 32-33, 35, 59, 61
Vedcharuplots, 35                  Vedline, 35, 61
Vedcharupright, 35                 Vedlineabove, 33
Vedcharuprightlots, 35             Vedlinebelow, 33
Vedcheck, 21, 25                   Vedlinedelete, 34, 39
Vedclearhead, 34, 39               Vedlinemax, 29, 32, 59, 61
Vedcleartail, 34, 39               Vedlineoffset, 21, 61
Vedclosers, 36, 59                 Vedlmr_errs_in_file, 44, 59
Vedcolumn, 35, 61                  Vedlmr_print_in_file, 43-44
Vedcolumneoffset, 61               Vedlocate, 51
Vedcolumnoffset, 21                Vedlowerfile, 18
Vedcompileable, 4, 48, 59, 61      Vedmarked, 38
Vedcompilefiles, 42                Vedmarkfind, 36, 38
Vedcurrent, 61                     Vedmarkhi, 38
Vedcurrentchar, 31                 Vedmarklo, 38
Vedcurrentfile, 18                 Vedmarkpop, 38
Vedcursorset, 21, 25               Vedmarkpush, 38
Veddebug, 15                       Vedmidscreen, 59
Veddecodetabs, 31                  Vedmoveitem, 32, 36
Veddelspaces, 59                   Vednamestring, 61
Veddirectory, 61                   Vedneedscompiling, 48, 61
Vednextitem, 32                    Vedscreengraphon, 27
Vednextline, 35                    Vedscreeninsertchar, 27
Vednonbreakfiles, 32, 59           Vedscreeninsertline, 27
Vednormaltable, 10                 Vedscreenleft, 35
Vednotabs, 16, 28-29, 31, 59, 61   Vedscreenlength, 20, 59
Vedobey, 19                        Vedscreenline, 26
Vedopen, 19                        Vedscreenlinemark, 28
Vedopeners, 36, 59                 Vedscreenmark, 28, 37
Vedout, 33                         Vedscreenmiddle, 35
Vedoutascii, 24                    Vedscreenoffset, 61
Vedpopexit, 49                     Vedscreenoutput, 24
Vedpopkey, 37                      Vedscreenpulldown, 27
Vedpopready, 15                    Vedscreenpullup, 27
Vedpositionpop, 37                 Vedscreenpushdown, 27
Vedpositionpush, 36                Vedscreenpushup, 27
Vedpositionstack, 36, 61           Vedscreenraw, 22
Vedpresent, 18                     Vedscreenreset, 22, 26
Vedprintingdone, 15, 25            Vedscreenright, 27, 35
Vedprmishap, 15, 24                Vedscreensetpad, 22
Vedprocess, 15, 25                 Vedscreenup, 35
Vedprocesschar, 10, 23             Vedscreenwidth, 35, 59
Vedpushkey, 36                     Vedscreenxy, 26
Vedputcommand, 13                  Vedscrollscreen, 59
Vedputmessage, 15, 25              Vedselect, 19, 22
Vedquery, 10                       Vedsetcursor, 21
Vedquerytable, 10                  Vedsetglobals, 18
Vedrangerepeater, 31               Vedsetkey, 11, 14, 56
Vedreadin, 29                        abbreviations, 12
Vedreadline, 44                    Vedsetlinesize, 17, 34
Vedredocommand, 13                 Vedsetonscreen, 21
Vedrefdirectory, 59                Vedsetscreen, 21
Vedrefname, 5                      Vedsetstatic, 34
Vedrefresh, 25                     Vedsetstatus, 27
Vedrefreshrange, 25                Vedsetwindow, 20
Vedrepeater, 31                    Vedsrcname, 5
Vedrestorescreen, 25               Vedstartwindow, 20, 25, 59
Vedsaveglobals, 18                 Vedstatic, 34, 61
Vedsaveglobals,, 61                Vedstatusline, 61
Vedscreenbell, 26                  Vedstatusswitch, 13
Vedscreenchardown, 26              Vedswapfiles, 22
Vedscreencharleft, 26              Vedsysfile, 4
Vedscreencharright, 26             Vedteachdirectory, 47, 59
Vedscreencharup, 26                Vedteachlist, 5
Vedscreenclear, 26                 Vedteachname, 5, 47
Vedscreencleartail, 26             Vedterminalselect, 7
Vedscreencolumn, 26                Vedtestsearch, 51
Vedscreencommandmark, 28           Vedtextleft, 36
Vedscreencontrolmark, 28           Vedtextright, 36
Vedscreencursor, 28                Vedthisline, 31
Vedscreencursormark, 28            Vedthisstring, 31
Vedscreendeletechar, 27            Vedtoperror, 15
Vedscreendeleteline, 27            Vedtopfile, 36
Vedscreendown, 35                  Vedtrimline, 17, 34
Vedscreenescape, 24, 26            Vedupperfile, 18
Vedscreengraphoff, 27              Vedusedsize, 17
Vedveddefaults, 4, 6, 42
Vedvedname, 4
Vedversions, 30, 59
Vedwasonstatus, 61
Vedwindowlength, 20, 59, 61
Vedwordleft, 35
Vedwordleftdelete, 34, 39
Vedwordright, 35
Vedwordrightdelete, 34, 40
Vedwriteable, 4, 30, 59, 61
Vedwritefiles, 30
Vedwriterange, 30
Vvedampersand, 59
Vvedbuffersize, 17, 61
Vveddump, 39-41
Vvedfoundstring, 53
Vvedlinedump, 39-40
Vvedlinesize, 17, 61
Vvedmarkhi, 37-38, 61
Vvedmarklo, 37-38, 61
Vvedquery, 59
Vvedscreenalpha, 60
Vvedscreencharleft, 60
Vvedscreencharright, 60
Vvedscreencharup, 60
Vvedscreenclear, 26, 60
Vvedscreencleartail, 60
Vvedscreencursorupscroll, 60
Vvedscreendeletechar, 60
Vvedscreendeleteline, 60
Vvedscreengraphic, 60
Vvedscreeninsertline, 60
Vvedscreeninsertmode, 60
Vvedscreenmark, 38
Vvedscreenovermode, 60
Vvedscreenpoint, 60
Vvedscreenresetpad, 60
Vvedscreensendidseq, 7
Vvedscreensetpad, 60
Vvedsrchstring, 50
Vvedworddump, 39-40
Vvedwordump, 39

Windows
  position, 21
  size, 19
Yanking, 40


--- C.all/doc/vedmanual
--- Copyright University of Sussex 1990. All rights reserved. ----------
