HELP PAGE                             Chris Slymon, David Roberts and
                                           Roger Evans, January 1983.

    This file describes commands that are adequate for simple
text-formatting within VED. For more elaborate (but non-interactive)
text-formatting, the RUNOFF program is probably more appropriate.

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

 -- Loading the commands
 -- Altering line length and margin size
 -- Text justification
 -- Text alignment
 -- Moving blocks of text
 -- Manipulating case
 -- LIB PAGE
 -- PAGE - a definition
 -- Specifying headers and footers
 -- Page length
 -- the PAGE and AUTOPAGE commands
 -- Removing pages - the UNPAGE command
 -- Runoff-style commands
 -- LIB RNO
 -- Defining new runoff-style commands

-- Loading the commands ---------------------------------------

Some of the commands described in this file are not part of the basic
POPLOG system, but are contained in library files which will be loaded
on the first occasion that the command is used.

You will need to load two library files to use the facilities in this
file, to do this do;

    <ENTER> lib rno <RETURN>
    <ENTER> lib page <RETURN>

-- Altering line length and margin size -------------------------------

    VED uses the global variables to control the starting position of
text on a line and the maximum number of characters per line. These are
VEDLEFTMARGIN and VEDLINEMAX.

    The values of these variables may be altered or examined with the
ENTER LCOL and RCOL commands, which provide convenient ways of setting
the 'leftmost' and 'rightmost' columns: these are the screen columns
which are, respectively, as far left and as far right as text is
ordinarily able to stand.

LCOL - Leftmost COLumn

The command takes an optional argument which must be either an integer
or '?'. If the argument is '?' the margin setting is unchanged but the
current setting for the the leftmost column is dispalayed on the command
line. If the argument is a number, that column becomes the leftmost
column. When no argument is given, the current cursor position becomes
the leftmost column.

MARGIN

This is similar to LCOL, except that numerical arguments are taken to be
the size of the margin, i.e. the number of column positions BEFORE the
leftmost column.

RCOL - Rightmost COLumn

As for LCOL, but sets or displays the rightmost column.

RULER

This inserts a 'ruler' above the current line. This numbers the screen
columns, indicates the limits of left and right margins and displays the
tab settings. On this HELP file it would look like this:

         1         2         3         4         5         6         7
123456789012345678901234567890123456789012345678901234567890123456789012
<   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |  >

- the leftmost column is indicated by '<', the rightmost by '>' and the
tab positions by '|'.

The 'ruler' will appear within a marked range and can easily
be removed with ENTER D or with the delete line key. (Warning: a
previous marked range will be lost).

-- Text justification -------------------------------------------------

There are various commands that can be used for justifying text,
depending upon whether "full justification" is required, the body of
text to be justified and whether the file is a program file.

"Full justification" produces text with both the first and last
characters on each line aligned with the respective margin, otherwise
VED attempts to place as many words as possible on each line, but will
not insert extra spaces to align the last text character with the right
margin. Uses VEDLEFTMARGIN, and VEDLINEMAX.

The Text to be justified can be either a marked range or the current
paragraph. The current paragraph is defined as that body of text
containing the cursor that is bounded by empty lines or lines beginning
with a full stop. If the current file is a program file VED will assume
that the text is a program listing unless otherwise informed.

J    - 'Justify' marked range.

JJ   - Full justification of a marked range.

FILL - Justify marked range as if in text file, even if current file is
        a program file.

JP   - Justify current pararaph.

JJP  - Fully justify the current paragraph.

FP   - FILL current paragraph.

GOBBLE - The antidote to full justification; GOBBLE removes redundant
        spaces from a marked range. Only one space is allowed between
        any two non-space characters. Spaces at the beginnings of lines
        are left intact, hence paragraph indentations will not be
        altered.

NOTE: GOBBLEing may not return the text to exactly the same state as
before full justification. E.g. if you are in the habit of double
spacing after a full stop, one of these spaces will be deleted by
GOBBLEing. One more reason for abandoning double spacing.

-- Text alignment -----------------------------------------------------

    There are three commands that step through a marked range, aligning
each line in turn, either with one of the margins or the centre of the
text.

AC  - Centres each line in the marked range between the left and right
    margins, as defined by VEDLEFTMARGIN and VEDLINEMAX.
AL  - Aligns first character of the text on each line in the marked
    range with the left margin.
AR  - Aligns last text character of each line in marked range with
    the right margin.
CENTRE  - Takes an optional argument: if no argument is given, the
    text on the current line is centred. Otherwise the argument (a text
    string) is inserted at the centre of the current line.
RIGHT   - Takes an optional argument: if no argument is given, the
    text on the current line is right adjusted. Otherwise the
    argument (a text string) is inserted at the right of the
    current line.

-- Moving blocks of text ----------------------------------------------

    These commands align, as a unit, the block of text in a marked range
(unlike the commands described in the previous section, which move the
individual lines).

BC - Moves the marked range left or right so that the first line
    of the range is centred between the two margins.
BL - Takes an optional argument: if no argument is given, the text in
    the marked range is moved one space to the left. A numeric argument
    specifies the number of spaces the text is to be moved e.g. ENTER BL 5
    would move the text 5 spaces to the left.

This command allows text to be moved beyond the leftmost column, if
there is room on the screen; if there is not enough room text is moved
as far as possible (hence ENTER BL 999 is allowable).

BR - As for BL above, but moves the text to the right.

Overlaying text

OVER - overlays one block of text upon another. E.g. if the text that is
overlaid, the 'undertext', is:

                Mary had a little lamb,
                Its fleece was white as snow

and the text that does the overlaying, the 'overtext', is:

               |JOHN                        |
               |               BLACK    COAL|

the result will be:

               |JOHN had a little lamb,     |
               |Its fleece was BLACK as COAL|

That is, each non-blank character in the overtext replaces the character
in the equivalent position in the undertext.

Put the required overtext in a marked range and indicate the first line
of the undertext by the position of the cursor. Note: The command won't
allow text to be overlaid upon itself.

The new text will appear in place of the undertext, the old undertext is
stored in VVEDDUMP and can be restored by ENTER Y, if there has been any
miscalculation.

-- Manipulating case --------------------------------------------------

    The procedure VEDCHANGECASE alters the case of the current character, if
that character is an alphabetic, and moves the cursor one place to the right.
VEDCHANGECASE is normally associated with CTRL-N.

    The following ENTER commands change ALL the alphabetic characters in their
scope to upper or lower case.

LCL - Lower Case Line. Takes an optional argument: if no argument is
given, forces all alphabetic characters in the current line to lower
case. A numeric argument specifies the number of lines to be converted
into lower case, starting with the current line.

LCR - Lower Case Range. Forces all alphabetic characters in the marked
range into lower case.

LCW - Lower Case Word. Takes an optional argument: if no argument is
given, forces all alphabetic characters up to the end of the current
word into lower case. A numeric argument specifies the number of words
to be converted into lower case.

The commands UCL, UCR and UCW behave in exactly the same manner, but
force the alphabetic characters within their scope into UPPER case.


-- LIB PAGE -----------------------------------------------------------

    The ENTER commands in this package allows the user to divide a file into
pages in a way that enables bad page breaks to be avoided. Headers and
footers may be inserted, if desired, and pages are numbered automatically. The
package also includes a capability for dealing with runoff-style commands.

    To make these commands available, do LIB PAGE or, in VED, ENTER LIB PAGE.

-- PAGE - a definition ------------------------------------------------

    For the purposes of this package, a 'page' consists of:

        a) a number of blank lines (default 0) that make up the top margin;

        b) a header line (if one has been specified), followed by a number of
            blank lines (default 2);

        c) the body of the text;

        d) a footer line (if one has been specified), preceded by a
             number of blank lines (default 2);

        e) a form feed character.

-- Specifying headers and footers -------------------------------------

    The HEADER command is used for changing the header line that is
inserted at the top of each page by the PAGE command (see above/below).
If an argument is given any future PAGEs will insert that string as a
header line. If there is no argument, future PAGEs will have no header.
The FOOTER command works in the same way as HEADER, except that it
refers to the footer line.

    The argument (and the header/footer line) can be divided into three
fields; that will be left justified, centred and right justified.

        Text that appears before a "<" character will be left justified;

        Text that appears after a ">" character will be right justified;

        Text that appears between "<" and ">" will be centred.

    Hence the general form of the argument is

                left < middle > right

    Any "#" characters that are included in the argument will be
converted into the current page number.

    Any "%" characters that are included in the argument will be
converted into the filename.

    E.g. header FILE: %< Example Header > PAGE: #

would put

FILE: FORMAT                    Example Header                         PAGE: 1

at the head of each page, with appropriate page numbers after the first
page.

-- Page length --------------------------------------------------------

    The PAGESIZE command controls the number of lines per page and
requires a numeric argument: If the argument is negative, the text will
be (vertically) centred on the page; if positive, it will start printing
from the top line. If no argument is given, the default value of 60
lines is assigned.

    Note: when using headers or footers, they each require 3 lines.

-- the PAGE and AUTOPAGE commands -------------------------------------

    PAGE and AUTOPAGE divide a file into pages, PAGE interacts with the
user to check that the page breaks are acceptable, AUTOPAGE doesn't. The
first new page will begin directly after the last form feed, if the file
has previously been PAGEd; otherwise, it will begin at the top of the
file.

    Responses to PAGE:

    If the PAGE command is used, the bottom of each new page will appear
at the middle of the screen, so that the page break can be checked.

    One of the following responses must then be typed:

'Y' or 'y' - accepts the page and exits from the paging routine.

'N' or 'n' - rejects the page and exits from the paging routine.
The header and footer lines, blank lines and form feed character
that have been inserted are removed, and the bottom of the
previous page appears on the middle of the screen.

RETURN - accepts the page and continues paging with the next new page.

an integer - If one of the integer keys <n> is struck, the last
<n> lines will be transferred to the next page, and the prompt
will be repeated. I.e. the page break is moved up <n> lines and
you have a further chance to type Y, N or an integer.
Negative numbers can be used to add lines to the current page.

    PAGE and AUTOPAGE may be given a numerical argument in order to
specify the number of the next page. Otherwise it is assumed that the
first page in a file is page 1 and numbering carries on from there.

-- Removing pages - the UNPAGE command --------------------------------

    The UNPAGE command removes pages, form-feeds, headers and footers,
and adjusts page numbering accordingly.

    UNPAGE removes the last page.
    UNPAGE <number> removes <number> pages.
    UNPAGE * removes all pages from the file.

    *** WARNING ***

    This command is somewhat simple-minded and must be used with care.

    The paging mechanism doesn't keep a record of what it has done on
previous pages. If headers and footers are being used or lines have been
transferred over page breaks, extra blank lines  may be left in the file
by UNPAGE. More seriously, if PAGEing began without headers and footers,
and headers and/or footers were later used, the command will assume that
all pages have headers and/or footers and will delete lines accordingly,
which could mean that text is lost! For this reason, the user is advised
to SAVE a file (e.g. use ENTER W1, or ENTER W <file name> before running
PAGE or unpage.

    *** END OF WARNING ***

-- Runoff-style commands ----------------------------------------------

    PAGE and AUTOPAGE will treat any line with a full stop in column 1
as a runoff-style command, i.e. a command that controls the formatting
process.

E.g. the following commands to control paging are included in LIB PAGE:

    .bp begin a new page with the next "text" line.
    .bp <number> begin a new page, calling it page <number>.

    .tp <number> test to see if the next <number> lines can be fitted
    on the current page; if not, begin a new page.

    If the command is unknown or inapplicable at the current location
the user will be asked whether they wish to continue paging. If so, the
line will be treated as a line of text.

    One command only may appear on a line.

-- LIB RNO ------------------------------------------------------------

    LIB RNO contains some additional "runoff" commands for use with LIB
PAGE, which is loaded automatically if necessary. These commands are:

   .header      sets the header. The format of the header is the same as
                described above e.g.

                    .header F.Bloggs < -- Page # -- > Candidate No. 2

   .footer      like .header but sets footer.

   .sp          leave a blank line. May be followed by an integer to leave
                several blank lines e.g.

                    .sp 5

                to leave 5 blank lines etc.

   .tidy        commence justification of the text (using ENTER J). For full
                justification i.e. the right margin too, see .FILL below.

   .endtidy     marks the end-point for justification.

   .title       the remaining text on the line is inserted into the file and
                underlined. Note: underlining is 'true' underlining using
                '_',not hyphens on the line below. The underline string
                appears in the file ON THE SAME LINE as the title, but when
                printed on the printer it will come out as underlining. e.g.

                    .title SECTION 1

                would produce (in the file):

                    SECTION 1_______ _

                (the character after the 1 is a carriage return that tells the
                printer to go back to the beginning of the line and start
                again).
                A long title may produce underlining that goes off the end of
                the screen - don't worry about that, it will still work!

    .fill       fill/endfill brackets are just like tidy/endtidy brackets (see
    .endfill    above), but they use ENTER JJ for tidying, and so do right
                margin justification too.

    .ctitle     similar to title (see above) except that the title is centred
                on the page.

    .ul         brackets like tidy/endtidy for using ved_ul (see
    .endul      SHOWLIB ved_ul) to underline the text.

-- Defining new runoff-style commands ---------------------------------

    Users may define their own commands for use with LIB PAGE. This section
describes the conventions that should be followed.

    PAGE behaves in a similar way to VED, in that for ENTER commands VED
attaches the prefix 'ved_' to the command and runs the procedure of that
name. E.g. if the command is XYZ, the procedure VED_XYZ is called. An
RNO command in a file to be PAGEd causes PAGE to attache the prefix
'rno_' to the command word and execute the procedure of that name. E.g.
if the command line is

.foo

    then the procedure "rno_foo" will be executed.

    Thus to write a new RNO command, write a procedure called rno_<name>
which does what is required. (This may well require a fair understanding
of how VED and LIB PAGE work. For gory details see SHOWLIB PAGE and
SHOWLIB RNO.)

    Arguments may be passed to the command procedure using the rest of
the command line, which is given to the procedure as a string.

    If the command procedure wishes to cause an error, the procedure
RNO_ERROR, which is provided by LIB PAGE, should be used. RNO_ERROR
prints a message on the command line, displaying the line that caused
the problem and asks whether paging should continue. If the response is
'Y' or 'y', the RNO command will be ignored, if 'N' or 'n', page
processing will stop.

    N.B. the line with the command on it is deleted after the procedure
has been located but before it is run. Thus if the error is caused by
the procedure not being found, the command line remains, but if it is
caused by processing in the command itself, it will have been deleted.

    E.g. the rno command '.bp' might look something like this:

    define rno_bp(n);
        if n == vednullstring then
        ;;; if n = vednullstring there were no arguments - just start next
        ;;; page
            pagenum + 1 -> pagenum;
        else
            ;;; try to convert string to number
            strnumber(n) -> n;
            if n then
                n -> pagenum;
            else
                ;;; argument is not a number - exit via error routine
                rno_error();
            endif;
        endunless
        startpage();
    enddefine;

    *** THIS WON'T WORK AS IT STANDS as it is incomplete ***

    The variable POPFORMFEED has as its default value a string
containing the form-feed character. This is used to mark page
boundaries, e.g. for use with a printer. Any other string may be
assigned to POPFORMFEED, e.g. '.pg' to insert a runoff command instead
of the form feed.

    The procedure CHECKBOTTOM() is called on every page, just before the
footer and form feed are inserted. It can be defined by the user to make
the page boundary change.

--- C.all/help/page ----------------------------------------------------
--- Copyright University of Sussex 1987. All rights reserved. ----------
