HELP EDITOR_OVERVIEW                            Robert Duncan, July 1996

An introduction to XVed: the Poplog editor and help viewer. To see more
of this file, use the scrollbar or press the PageDown key.


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

  1   Introduction

  2   XVed Windows

  3   Some Common XVed Operations
      3.1   File Operations: How To
            ... open a new file
            ... quit from a file
            ... save the contents of a file
            ... save all changed files
            ... change the name of a file
            ... make a file writeable
      3.2   Window Operations: How To
            ... change the size of a window
            ... change the colour of a window
            ... change the window font
            ... iconify a window
            ... iconify all XVed windows
      3.3   Moving Around in a File: How To
            ... position the cursor
            ... view the next page
            ... view the previous page
            ... go to the start of the file
            ... go to the end of the file
            ... go to a specific line
            ... use the CONTENTS section
      3.4   Editing: How To
            ... select text
            ... delete selected text
            ... paste selected text
            ... copy selected text to the clipboard
            ... set the XVed AutoCut resource
      3.5   Getting Help: How To
            ... search for help on a topic
            ... get help on a selected item
            ... find a cross-reference
            ... follow a cross-reference
            ... view a known help file

  4   Customisation

  5   Further Reading


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

XVed is an enhanced version of the Poplog editor Ved designed for use
with X. It is a superset of Ved, inheriting all of Ved's functionality
as an editor, so anything you read in this file or elsewhere about Ved
is equally true of XVed. The principal features added by XVed include:

    #   multiple windows

    #   menus, scrollbars and dialogs

    #   customisable fonts and colours

    #   use of the mouse

Poplog uses plain Ved on terminals and in XTerm or other terminal
emulator windows, and XVed when started under X. If you came to this
file through the control panel Help menu, then you will be viewing it in
XVed.

XVed serves both for editing files and as a documentation viewer. There
is no distinction between documentation files and other files except
that documentation files are not writeable; this means that you can edit
documentation in the same way as you would any other file -- to add your
own notes, or to expand programming examples, etc. -- but you can't save
your changes back to the original file. You can, of course, write the
modified file under a new name.


-----------------------------------------------------------------------
2  XVed Windows
-----------------------------------------------------------------------

XVed will normally create a new window for each file you open; the name
of the file is displayed in the window title bar and on the icon label.
Using the window manager to delete an XVed window will close the
associated file.

There is no practical limit on the number of files -- and hence the
number of windows -- that you can have open at any one time. If you find
the number of windows becomes excessive, you can restrict it to a
maximum by selecting Ved from the control panel Options menu and setting
the XVed Max Windows resource. If the number of files you open exceeds
this maximum, the available windows are used to display the most
recently accessed files.

Each XVed window contains a text area for editing and a status line. The
status line displays information about the current file and has an input
area for Ved commands. The status line is normally placed at the top of
the window, above the text area, but you can choose to have it at the
bottom of the window by setting the XVed StatusAtTop resource to false.

Much of the more sophisticated functionality of XVed can only be
accessed through commands typed on the status line. In this file and
elsewhere, status-line commands are written as

    <ENTER> command arguments...

To execute such a command, use the ENTER logical key to move the cursor
onto the status line and clear the input area. If your keyboard has a
keypad, the ENTER logical key will normally be bound to the keypad
<ENTER> key; if you don't have a keypad and can't find an <ENTER> key
elsewhere, typing <CTRL>-G (^G) will work instead. Once on the status
line, type the command as given followed by <RETURN>.

XVed keeps a history of your most recent commands. You can use the
CHARUP and CHARDOWN keys on the status line to navigate the history list
and <RETURN> to re-enter a command; you can also edit previous commands
using the normal editing functions. The size of the history list can be
customised from General page of the control panel Ved Options dialog.
The STATUSSWITCH logical key will swap the cursor between the status
line and the text area: this is normally bound to the keypad key above
the <ENTER> key, and always to the two-key sequence <ESC> <CTRL>-G. You
can also move the cursor onto the status line with the mouse by
positioning the pointer in the status-line area of the window and
pressing Button1.

As well as the text area and status line, each XVed window can have a
scrollbar and menu bar which provide short-cuts to the most common XVed
operations. You can choose which if these decorations to include on your
XVed windows by setting combinations of the XVed Vanilla, MenuBarOn and
ScrollBarOn resources.

For a full description of the XVed application and window resources see
REF * XVED or choose Editor|XVed Reference from the control panel Help
menu. You can set some of these resources interactively from the XVed
and XVed Window pages of the control panel Ved Options dialog.


-----------------------------------------------------------------------
3  Some Common XVed Operations
-----------------------------------------------------------------------

This section provides only a brief overview of some of the more common
XVed functions sufficient to get you started with the editor. For a full
listing of the core command set see REF * VEDCOMMS or choose
Editor|Command Reference from the control panel Help menu. For details
of the standard key bindings see HELP * VEDKEYS and for bindings
specific to your keyboard do

    <ENTER> hkeys

or choose Editor|Keyboard from the control panel Help menu.


3.1  File Operations: How To
----------------------------

...  open a new file
--------------------

From the control panel:

    Choose Open from the File menu

From the XVed menu bar:

    Choose Open from the File menu

From the status line:

    <ENTER> ved filename


...  quit from a file
---------------------

From the window manager:

    Choose the Close (mwm) or Quit (olwm) option from the file window
    menu

From the XVed menu bar:

    Choose the Quit option from the File menu

From the status line:

    <ENTER> q

From the keyboard:

    <ESC> q


...  save the contents of a file
--------------------------------

From the XVed menu bar:

    Choose Save from the File menu

From the status line:

    <ENTER> w1

NB: you can only save a file that is writeable.


...  save all changed files
---------------------------

From the control panel:

    Choose Save All from the File menu

From the status line:

    <ENTER> w

NB: these will save all writeable files which have been modified.


...  change the name of a file
------------------------------

From the XVed menu bar:

    Choose Save As from the File menu

From the status line:

    <ENTER> name newname


...  make a file writeable
--------------------------

From the status line:

    <ENTER> set vedwriteable

NB: this toggles the writeable flag, so will also make a writeable file
non-writeable.


3.2  Window Operations: How To
------------------------------

...  change the size of a window
--------------------------------

From the window manager:

    Use any of the resize controls

From the control panel:

    Choose Ved from the Options menu, select the XVed Window page and
    set the number of rows and columns, then press Apply.

From the status line:

    <ENTER> window nrows
    <ENTER> xved window numRows nrows numColumns ncolumns

From the keyboard:

    <ESC> w will toggle the window between half- and full-size


...  change the colour of a window
----------------------------------

From the control panel:

    Choose Ved from the Options menu, select the XVed Window page and
    fill in the Foreground and Background colour fields, then press
    Apply. Status-line colours are set separately in the
    Status Foreground and Status Background fields.

From the status line:

    <ENTER> xved window foreground colour background colour
    <ENTER> xved window statusForeground colour statusBackground colour


...  change the window font
---------------------------

From the control panel:

    Choose Ved from the Options menu, select the XVed Window page and
    fill in the Font field, then press Apply. You can select different
    fonts for characters with italic and bold attributes.

From the status line:

    <ENTER> xved window font font altFont font...


...  iconify a window
---------------------

From the window manager:

    Choose the Minimize (mwm) or Close (olwm) option from the window
    file menu

From the status line:

    <ENTER> xved window iconic true


...  iconify all XVed windows
-----------------------------

From the status line:

    <ENTER> closeall


3.3  Moving Around in a File: How To
------------------------------------

...  position the cursor
------------------------

Using the mouse:

    Position the pointer and press Button1

From the keyboard:

    ^P to move up a line
    ^N to move down a line
    ^B to move left one character
    ^F to move right one character

    <ESC> v to move up one screenful
    ^V to move down one screenful
    ^A to move to the start of the current line
    ^E to move to the end of the current line

The numeric keypad keys will move the cursor by one character position
in the corresponding direction from the keypad centre (5), e.g. 8 to
move up, 6 to move right, 9 to move up and right, etc.

The arrow keys may move the cursor in the obvious way, i.e. the same as
the ^P, ^N, ^B and ^F keys, but on some keyboards will behave as the
<ESC> v, ^V, ^A and ^E keys.


...  view the next page
-----------------------

Using the scrollbar:

    Press Button1 below the slider

From the keyboard:

    PageDown or Next


...  view the previous page
---------------------------

Using the scrollbar:

    Press Button1 above the slider

From the keyboard:

    PageUp or Previous


...  go to the start of the file
--------------------------------

From the XVed menu bar:

    Choose Start of File from the View menu

From the status line:

    <ENTER> @a

From the keyboard:

    <ESC> <


...  go to the end of the file
------------------------------

From the XVed menu bar:

    Choose End of File from the View menu

From the status line:

    <ENTER> @z

From the keyboard:

    <ESC> >


...  go to a specific line
--------------------------

From the status line:

    <ENTER> line-number


...  use the CONTENTS section
-----------------------------

Using the mouse:

    Position the pointer over the topic of interest and press Button1.
    This works only if you are using the new button bindings and the
    index is active: you'll see the pointer change shape if so.

Using the mouse or keyboard, position the cursor on the topic of
interest and then from the status line:

    <ENTER> g


3.4  Editing: How To
--------------------

...  select text
----------------

Using the mouse:

    Press and drag Button1 to select an arbitrary range of text
    Double-click Button1 to select a word
    Triple-click Button1 to select a whole line

    Press Button2 to extend an existing selection

NB: selecting text does not change the cursor position.


...  delete selected text
-------------------------

From the XVed menu bar:

    Choose Cut from the Edit menu

From the keyboard:

    Meta-X

NB: if the XVed resource AutoCut is true, then pressing the DELETE key
or inserting any character will automatically delete (cut) the selected
text.


...  paste selected text
------------------------

Using the mouse:

    Press Button3

From the XVed menu bar:

    Choose Paste from the Edit menu

From the keyboard:

    Meta-V

NB: pasting inserts the selected text at the current cursor position,
not at the pointer position, even when using the mouse. Pasting will
insert text selected from other applications, not just from XVed.


...  copy selected text to the clipboard
----------------------------------------

From the XVed menu bar:

    Choose Copy from the Edit menu

From the keyboard:

    Meta-C


...  set the XVed AutoCut resource
----------------------------------

From the control panel:

    Choose the Ved option from the Options menu, select the XVed page
    and check the Auto Cut box, then press Apply.

From the status line:

    <ENTER> xved AutoCut true


3.5  Getting Help: How To
-------------------------

...  search for help on a topic
-------------------------------

From the control panel:

    Choose Search from the Help menu

From the XVed menu bar:

    Choose Other Help from the Help menu

From the status line:

    <ENTER> helpfor pattern


...  get help on a selected item
--------------------------------

From the XVed menu bar:

    Choose For Selected Item from the Help menu

From the keyboard:

    Meta-H


...  find a cross-reference
---------------------------

From the XVed menu bar:

    Choose Next Cross Reference or Previous Cross Reference from the
    Help menu

From the keyboard:

    <ESC> n to find the next cross-reference
    <ESC> N to find the previous cross-reference


...  follow a cross-reference
-----------------------------

Using the mouse:

    Position the pointer over the reference and press Button1.
    This works only if you are using the new button bindings and the
    reference is active: you'll see the pointer change shape if so.

From the XVed menu bar:

    Choose For Current Item from the Help menu

From the keyboard:

    <ESC> h


...  view a known help file
---------------------------

From the status line:

    <ENTER> help topic


-----------------------------------------------------------------------
4  Customisation
-----------------------------------------------------------------------

Both Ved and XVed are highly customisable. There are two ways in which
you can apply your preferences to each invocation of the editor:

#   The appearance and behaviour of XVed can be controlled through a
    number of X resources set by the standard X defaults mechanism.
    For example, the specification:

        XVed.Vanilla: true

    placed in your .Xdefaults file or similar would turn off all window
    decorations and dialogs. For a full description of all the XVed
    resources, see REF * XVED.

#   Each time Ved starts up, it compiles a Pop-11 program file called
    "vedinit.p" in your *poplib directory. All aspects of Ved and XVed
    can be controlled from here; even the XVed resources can be changed,
    so that the previous example could be equally well expressed as

        true -> xved_value("application", "Vanilla");

    (see REF * xved_value; resource assignments in the "vedinit.p" file
    are processed after those set via the X defaults mechanism and so
    take precedence). Other uses of this file include: setting Ved
    global variables, changing key bindings, defining new commands, etc.
    For suggestions on what to put in this file, see

        HELP * VEDSET
            Defining new key bindings and button bindings

        HELP * VEDFILETYPES
            How to change Ved's behaviour based on the type -- i.e. the
            file extension -- of the file being edited

        REF * VEDVARS
            Descriptions of Ved global variables which you may wish to
            change

        REF * VEDPROCS
            Descriptions of Ved procedures which can be bound to keys or
            used to define new commands

Once Ved is running, you can still change things interactively. From the
control panel Options menu, select the Ved preferences dialog and try
adjusting the various settings to see their effect on your editing
session (you must press the Apply button to make your changes
effective). If you like the changes you have made, select Save Options
from the Options menu to have them written to your "vedinit.p" file so
that they will be applied each time you run Ved in the future.

There are various status-line commands you can use too. For example,
doing

    <ENTER> xved StatusAtTop false

will move the status line below the text area in each new window opened
(see HELP * VED_XVED; other examples are given above) while

    <ENTER> set vedbreak

will toggle automatic line-breaks at the right margin within the current
file (see REF * ved_set, * vedbreak).


-----------------------------------------------------------------------
5  Further Reading
-----------------------------------------------------------------------

You can find out more about using Ved from the files:

TEACH * TEACH, * VED, * XVED
    Very simple tutorials

TEACH * VEDPOP
    Pop-11 programming in Ved

HELP * PLOGVED, * LISPVED, * PMLVED
    Using Ved with other subsystems

HELP * IM
    Creating an interactive Ved window

REF * VEDCOMMS
    Command reference


--- C.x/x/pop/help/pop_ui_editor_overview
--- Copyright University of Sussex 1996. All rights reserved.
