HELP MARK                                   Updated A. Sloman Mar 1990

                FACILITIES INVOLVING MARKED RANGES IN VED
                =========================================

VED allows you to mark a consecutive sequence of lines in a file and
then perform a variety of operations on the range, including, copying,
moving, transferring to another file, deleting, formatting, or creating
a character repeater function for the characters in the range.

The file TEACH * MARK provides an introduction for relatively
inexperienced users.

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

 -- Introduction
 -- <ENTER> m  (move marked range)
 -- <ENTER> t (transcribe/copy marked range)
 -- <ENTER> d (delete marked range)
 -- <ENTER> crm (Clear Range Mark)
 -- <ENTER> y (Yank back previously stored range)
 -- <ENTER> copy (Saving marked range in vveddump)
 -- Copying or moving text between files
 -- <ENTER> ti (Transcribe/copy range In - from other file)
 -- <ENTER> mi (Move range In - from other file)
 -- <ENTER> to (Transcribe/copy range Out - to other file)
 -- <ENTER> mo (Move range Out - to other file)
 -- <ENTER> da (Delete range and Append to vveddump)
 -- <ENTER> lmr (Load (compile) a marked range
 -- <ENTER> mcp (Mark Current Procedure
 -- <ENTER> lcp (Load Current Procedure
 -- <ENTER> tidy (Tidy marked range in program file)
 -- <ENTER> jcp (Justify Current Procedure)
 -- <ENTER> fill (Fill marked range in text file)
 -- <ENTER> j (Justify range in program or text file)
 -- Additional useful <ENTER> commands
 -- Marked ranges manipulated by user programs
 -- Further information

-- Introduction -------------------------------------------------------

VED provides two procedures for marking a "range" in the current file,
VEDMARKLO and VEDMARKHI. These set two global variables vvedmarklo, the
beginning of the marked range (the lowest marked line number) and
vvedmarkhi the end of the range (the highest marked line number).

Various operations may be applied to the marked range - deleting it,
moving it, copying it, compiling it, producing a character repeater for
it, sorting the lines alphabetically, 'pretty-printing' it, etc.

The two marking procedures are usually mapped onto function keys on the
keyboard, called MARKLO and MARKHI. When they are pressed, the range
marked is indicated by a vertical line on the left of the screen.

The default key mappings are described in HELP * VEDKEYS. For the
particular terminal or keyboard you are using it may be different.
If you do not have a keyboard map giving VED's key mappings, look
for a relevant help file in for the section on terminals in the
overview file: HELP * VED/Terminal

The best way to learn what these keys do is to play with them. Move the
cursor to various places and press one or other of the mark range keys.
You will see a vertical bar appear on the left of the screen to indicate
the range which has been marked. This bar is not part of the file and
will not be included in the file if it is written to disk.

-- <ENTER> m  (move marked range) -------------------------------------

To MOVE the marked range to after the current cursor line use the
command

    <ENTER> m

or use the MOVE_RANGE key associated with the function ved_m if there
is one set up for your terminal.

Attempting to move the range to a location already in the range will
produce an error message.

The moved portion of the file will remain marked. So you can move it
again if you wish, or perform some other operation.


-- <ENTER> t (transcribe/copy marked range) ---------------------------

To transcribe (copy) the marked range to after the current cursor line,
use the command:
    <ENTER> t

or the COPY_RANGE or ved_t function key if it has been set up for your
terminal.

A range can be copied to a location inside itself, if required!


-- <ENTER> d (delete marked range) ------------------------------------

You can delete a marked range with the <ENTER>d command. The last
deleted (or copied) range can be retrieved using the <ENTER> y command.

-- <ENTER> crm (Clear Range Mark) -------------------------------------

This removes the mark but leaves the text unchanged.

-- <ENTER> y (Yank back previously stored range) ----------------------

The last text deleted is stored in the variable VVEDDUMP in the form of
a list of strings, and the <ENTER> y command will retrieve it ("yank" it
back), immediately after the current line.

The sequence

    <ENTER> d
    <ENTER> y

is equivalent to
    <ENTER> m

with the difference that after the MOVE command, the variable VVEDDUMP
has not changed. I.e. <ENTER> y will not insert the text last moved.

You can use <ENTER> y even after switching to another file. So the
sequence <ENTER> d, change files, <ENTER> y will move text from one file
to another. (See <ENTER> mi (or mo) described below for a simpler
procedure)

See HELP * YANK for more information on retrieving deleted portions of
text.

-- <ENTER> copy (Saving marked range in vveddump) ---------------------

The <ENTER> copy command leaves the marked range and the current file
unchanged, but overwrites the contents of VVEDDUMP with the text in
the current marked range.

You can then move to another place in the same file or a different file
and use <ENTER> y to yank a copy of the previous text into the file,
after the line containing the cursor. So the command <ENTER> t is
equivalent to <ENTER> copy then <ENTER> y.

-- Copying or moving text between files -------------------------------
The following commands can also have an optional file name argument,
as described in HELP * INOROUT.

-- <ENTER> ti (Transcribe/copy range In - from other file) ------------

There is a quicker way of copying part of a file to another file, which
is sometimes more convenient. Mark the range you want copied. Then use
VED to get to the file you want to copy into. Put the cursor at the
location after which you want the text inserted. Then do
    <ENTER> ti

-- <ENTER> mi (Move range In - from other file) -----------------------

This will copy the marked range in from the previous file to the current
file and delete it from the original file.

-- <ENTER> to (Transcribe/copy range Out - to other file) ------------

This is like <ENTER> to, but copies the marked range from the current
file to after the cursor position in the next file in VEDBUFFERLIST,
i.e. the last file edited. It can be given an optional file name.

-- <ENTER> mo (Move range Out - to other file) ------------------------

This is like ved_to except that the text is deleted from the current
file.

-- <ENTER> da (Delete range and Append to vveddump) -------------------
This command is useful for merging a number of portions of a fi.

    <ENTER> da

does Delete marked range and Append to VVEDDUMP. Thus if there was
previously a record of a marked range in VVEDDUMP it will be extended by
the new marked range. Thus a succession of ranges can be marked then
deleted with DA, then retrieved with <ENTER>y, into the same or a
different file, whereupon they will appear in the order in which they
were appended using <ENTER> da

-- <ENTER> lmr (Load (compile) a marked range -------------------------

If the marked range contains program code for one of the Poplog
languages, and the file name ends with the appropriate suffix, or
the variable -subsystem- has been set up appropriately for the file,
then the marked range can be compiled with the command

    <ENTER> lmr

or possibly CTRL-d (if you are not using LIB VEDEMACS).

For more information on interactively compiling marked ranges in VED see
TEACH * LMR and HELP * LMR and HELP * IM ("immediate mode").

If the file name ends in '.pl' it is assumed to be a Prolog file, and
the marked range will be compiled by Prolog rather than POP. If it ends
in '.lsp' it will be treated as Lisp. The compiler used with a VED file
is controlled by the variable -subsystem- set up when the file is
created or read in from disk. The user can change this if necessary.
 (See HELP * VEDFILETYPES)


-- <ENTER> mcp (Mark Current Procedure --------------------------------

If VED has been set up for the language you are currently using this
will mark the current procedure or the current Prolog predicate. You can
then follow this with a command to format the range or compile it, etc.

-- <ENTER> lcp (Load Current Procedure --------------------------------

The command <ENTER> lcp will cause the current procedure to be marked
and compiled. It is equivalent to <ENTER> mcp followed by <ENTER> lmr,
except that it does not leave the current procedure marked.

-- <ENTER> tidy (Tidy marked range in program file) -------------------

If a portion of a program file is marked, the command
    <ENTER> tidy

will tidy the marked range by inserting indentation to show the
structure of the program, using a "pretty printer" for programs. The
indentation is controlled by the variable * VEDINDENTSTEP (default 4)

A collection of user assignable global variables controls the behaviour
of tidy. The variables, with their default values for Pop-11 users are:

vedopeners      = [ if define (  repeat while  until for unless procedure
                    lambda forevery foreach function switchon ],

vedclosers      = [ enddefine  end ) endif endwhile enduntil endunless
                    endfor endforevery endforeach enddo  endrepeat
                    endprocedure exit enddo close endswitchon ],

vedbackers      = [ then times do else elseif elseunless step till do
                    forever quitif quitunless nextif nextunless and or
                    case ],

vedforwarders   = [-> ->> --> ],

vedvarskeywords = [lvars dlvars vars lconstant constant global]

Users who extend the syntax of POP-11 by defining macros or new syntax
procedures may alter these lists to ensure that their programs are
formatted appropriately.

The style of formatting produced by <ENTER> tidy is illustrated by the
library programs
    $usepop/pop/lib/*/*.p       (UNIX)

    $USEPOP:[POP.LIB.*]*.P      (VMS)

-- <ENTER> jcp (Justify Current Procedure) ----------------------------

This is equivalent to <ENTER> mcp followed by <ENTER> tidy, except that
it does not leave the current procedure marked.


-- <ENTER> fill (Fill marked range in text file) ----------------------

This command is for use in text files, or for non-program text in
program files (e.g. in formatting comments).

It will format the marked range by rearranging text to fill the width of
the screen, i.e. the text is 'right justified', though with a 'ragged'
right hand margin. See jj below.

In a text file the right hand margin is controlled by VEDLINEMAX and the
left hand margin by VEDLEFTMARGIN. For more on text formatting commands
see HELP * FORMAT.

-- <ENTER> j (Justify range in program or text file) ------------------

The command <ENTER> j (for "justify") can be used on either a text file
or a program file. If used on a program file (e.g. name ending in '.p')
behaves like <ENTER> tidy, whereas on a text file it is like
<ENTER> fill

More more on formatting text see HELP * FORMAT

-- Additional useful <ENTER> commands ---------------------------------
The following <ENTER> commands operate on marked ranges or other
portions of a file:
    JJ  Right justify and insert extra spaces if necessary to line
        up right hand margin

    JP  Like JCP in a program file, otherwise justify current paragraph
        in a text file.

    JJP like JJ but for current paragraph

    SMR Sort marked range - treating each line in the range as a text
        string, sort them alphabetically.

    MEF mark end of file as end of range
    MBF mark beginning of file as beginning of range

    CRM clear range mark - i.e. get rid of mark, without
        altering text.

-- Marked ranges manipulated by user programs -------------------------

The procedures vedmarklo, vedmarkhi, and the variables vvedmarklo
vvedmarkhi may be used by user programs extending VED. Usually it is
helpful to ensure that after any manipulation by a program the marked
range is reset and that during manipulations temporary changes to the
marked range are not shown on the screen. The following facilities can
be used to achieve this:

vvedmarkprops
    - variable which if set FALSE prevents screen being altered by
vedmarklo() or vedmarkhi(). Default is TRUE.

vedmarkpush()
    - stack current marked range and value of vvedmarkprops

vedmarkpop()
    - restore last previously stacked marked range and value of
vvedmarkprops. If the latter is true, show the marked range on the
screen.

vedmarkfind()
    - move to line starting the marked range. If there isn't one, cause
an error.

The absence of a marked range is represented by vvedmarkhi being
negative. Usually in that situation vvedmarklo is assigned a very large
number.

For examples of the use of these facilities see the following library
files: SHOWLIB * VED_GSP, * VED_WCMR, * VED_GSL

-- Further information ------------------------------------------------

TEACH * MARK
TEACH * LMR

See REF * VEDPROCS, *VEDVARS, * VEDCOMMS

HELP * VED

HELP * VEDBLOCKS
    Operations on arbitrary rectangular blocks of next

HELP * FORMAT

--- C.all/help/mark
--- Copyright University of Sussex 1990. All rights reserved. ----------
