REF REFFORM_OLD                               Diarmuid McIntyre Jun 1993
                                           Based on work by John Gibson,
                                        A.Sloman, and A.Howard 1987-1990

        COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<     THE OLD STYLE FORMAT    >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<        FOR REF FILES        >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

From Version 14.22 of Poplog onwards, the system REF files have taken on
a new look.  However it is  recognised that people  write their own  REF
files and  might not  wish to  change  the format  of these.  This  file
therefore specifies the old style format with tightened up standards for
use with the REFORMAT program (which  works with both old and new  style
REF files), listing various procedures to help you
    REF * REFFORM specifies the new  style format that system REF  files
MUST take.

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

 --  Introduction
 --  The REFORMAT program
 --  Previewing your file
 --  Format of REF files
 --  Template for REF files
 --  The Overview
 --  The Title
 --  Section (sub)headings format
 --  ... Heading types
 --  Tables
 --  Paragraphs
 --  Program example code
 --  Lists
 --  ... Enumerated
 --  ... Bullet
 --  ... Descriptive
 --  Dstrings and Cross-references
 --  Quoting things
 --  Identifier Entries
 --  Example identifier entries
 --  Standard Type Names for Arguments/Results
 --  Basic Types (Excluding Numbers)
 --  Numbers
 --  Other types
 --  Prolog types
 --  Useful utility procedures
 --  ... <ENTER> ulheading: underline heading with hyphens
 --  ... <ENTER> idprops <type>: insert or update identprops on right
 --  ... <ENTER> ved_jrefmr: justify in REF format, marked range
 --  ... <ENTER> ved_slrhs: Swap Left and Right Sides of an assignment
 --  ... vedrefdefaults: tailoring VED for REF files
 --  See also


Introduction
------------
This file sets out the standard format for Poplog REF files. This format
is used by the library program  LIB * MKREFINDEX (which builds an  index
of the identifiers documented by a set of REF files).

For more general  information on formatting  online documentation,  HELP
and TEACH files, libraries, etc. see HELP * STANDARDS.



The REFORMAT program
--------------------
After Poplog 14.22 there  will a program  in existence called  REFORMAT.
The purpose  of this  program is  to enable  the user  to  automatically
create a hard copy manual from  the REF files. This is done  dynamically
using the most  current edition  of a REF  file. The  programs uses  the
various standards laid out in this file to divide a given REF file  into
text blocks  which it  then wraps  in LATEX  code. More  details of  the
workings of the program are given in REF * REFORMAT and HELP * REFORMAT.
    It is crucial to the workings of this program that each REF file  be
acceptable input  to the  program.  There has  been  no changes  in  the
standards but there has been a tightening up. It is now imperative  that
this standards are rigorously adhered too.
    Most REF  files  will all  ready  have  been prepared  to  be  input
(inconsistences taken out, etc).  However if you change  a REF file  you
should make sure  that  the  changes are  compatible  with  the REFORMAT
program. A special previewer has been written to enable you to see a REF
file as a potential chapter in a manual. If this previewer does not work
on your newly changed REF file, then you have either discovered a bug in
the program  or  your changes have  slipped  up in  their  adherence  to
standards.

REMEMBER: Small errors which you can get away with on-line become really
obvious when nicely printed out.



Previewing your file
--------------------
Do:

     lib reformat;

then

     <ENTER> filepreview

Depending on the length of the file, after 2-10 minutes a dvi version of
the file will appear on your screen using xdvi. See HELP * REFORMAT  for
more details.



Format of REF files
-------------------
The overall format (exemplified by this file) is

        <header>
        <contents>
        <section 1>
        <section 2>
        ...
        <footer>

where no lines extend  over 72 characters, and  all descriptive text  is
right-justified using jj or jjp.




Template for REF files
----------------------
NB in  the template  given  here, the  numbers  of blank  lines  between
different kinds  of  entries  are  important -  they  will  be  used  by
programs.

REF XXXX                                                     Author Date

       COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<          TITLE              >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxx overview xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

 --  Introduction

 ...



Section 1
---------
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxx text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxx more text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxx more text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

                     table/program code/list

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxx more text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


<identifier entry 1>


<identifier entry 2>


<identifier entry 3>


<identifier entry 4>



Section 2
---------
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxx text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxx more text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


<identifier entry 1>


<identifier entry 2>


<identifier entry 3>


<identifier entry 4>



--- C.all/ref/example
--- Copyright University of Sussex 1993. All rights reserved. ----------



The Overview
------------
This should act as a very brief sysnopis.

See the template  for its  format. Note that  there should  be no  empty
lines between any paragraphs.



The Title
---------
Since the REFORMAT program uses the title  of the REF file as a  chapter
heading, please ensure the following:

    # It is meaningful

    # It is all upper case

Do please also ensure that the box surrounding the title is of the  same
dimensions as the one at the top of this file.



Section (sub)headings format
----------------------------
One rule:

     # There must be  THREE or more empty lines between the end of the
       previous section and the section heading. This applies to all
       types of heading including subheadings.

You should have NO space after the heading at all.

Please do ensure that any under or overlining matches the wording of the
heading in terms of length.

For details of the new style of heading please see REF * REFFORM.



... Heading types
-----------------
Two types


    Section             (Main Heading)
    -------

    ... Subsection      (Sub Heading)
    --------------

All these are left justified with a continuous row of hyphens underneath.


Tables
------
Tables are recognised by each  column having an underlined heading.  The
underlining is the SAME  LENGTH as the heading.  The underlining can  be
made up of ordinary hyphens or `G-` characters.

Each entry  should be  to the  same left-justification  i.e. aligned  in
columns to the left.

If there are  going to be  columns where entries  will be omitted,  make
sure a row containing an entry for each column is the first row. This is
VERY important. If  this is  impossible place  a '-'  in the  non-filled
columns to indicate this.



Paragraphs
----------
These follow the form of the template. Only two things are crucial:

    # Do not have double spaces in one line paragraphs which do not
      reach the right margin.

    # Make sure that all regular paragraphs are right justified.



Program example code
--------------------
This should have  the Ved  special space  character Sf  or Sp  character
placed at  the  beginning  of  every  line  which  you  wish  reproduced
verbatim. i.e.

           blah
             blah

           more blah
           last line of blah

(You will need to have done <ENTER> dssp to see these characters.)

As with all other  text groups there  should be a  blank line on  either
side.

Sp should only be  used for program code  that is ACTUALLY  compileable,
i.e. not just 'outline' or 'meta' examples. If in doubt, use Sf.

<ENTER> ifsp  can  be used  to  insert  (or remove)  the  special  space
characters -- see REF * ved_ifsp.

NOTE: The  reformat  program has  to  use  some character  to  mark  the
beginning and end of  program code. The `?`  character was selected  for
this purpose. Therefore, try not to use the `?` character in code or  if
you have to, please try and put it on the end of a line.


Lists
-----
There are three types of lists.

     # Enumerated

     # Descriptive

     # Itemized (bullet)

Lists can be embedded in each other. If this is the case then it is best
to indent the sublist.

Although you are able to  have non-indented lists, The REFORMAT  program
is on safer ground if they are indented.



... Enumerated
--------------
These take the form:

     N  text text text text text text text
        text text text text text text

     N  text text text text text text text


where N is a number bullet in the form of one of: 1. (1) (a) a) a.



... Bullet
----------
These take the form

     B  text text text text text text text
        text text text text text text

     B  text text text text text text text


where b is one of # (G-), o, or  *. The `*` is not as good as the  other
two as it can lead to confusion with cross references.



... Descriptive
---------------
These take the form

     ITEM  text text text text text text text

     ITEM  text text text text text text text

for short snappy lists or:


     ITEM
         text text text text text text text
         text text text text text text text

              example of code/table

         text text text text text text text
         text text text text text text text
         text text text text text text text

     ITEM
         text text text text text text text
         text text text text text text text
         text text text text text text text
         text text text text text text text

     ITEM
         text text text text text text text
         text text text text text text text

              example of code/table

         text text text text text text text
         text text text text text text text

for longer ones.

Sometimes when you are making a list, it can look better as a table.  If
this is the  case then  please convert it.  The hard  copy version  will
definitely look better.



Dstrings and Cross-references
-----------------------------
The use of dstrings is fine. You should use them to emphasise pieces  of
the text.
    References to identifiers  can either  having a hyphen  on each  end
(i.e. -ident-) or be bolded (ident).
    Text variables can  either be  capitalised (NUM) or  lower case  and
italicised  (num).  The  italicisation  will  be  represented  on   some
terminals  as   underlining.   Cross   references   to   other   on-line
documentation can be italicised too i.e. REF * REFFORM.
    Finally list items can also be italicised.

You can use ved_chat to chat the attributes of a word. The rest of  this
REF file will be without attributes.


Quoting things
--------------
Just some simple rules which should be observed as a matter of course.

    #  Use the (") character to quote words. Do NOT use a character
       quote to begin the word and a string quote to end it.

    #  Use the character quote (`) to quote characters

    #  Use the string character (') to quote strings.

    #  If you are refering to a named section, enclose the reference in
       double quotes (").

    #  Make sure that if you open a double quote on a word then you end
       it. i.e do not write "ref'. It is okay to have single " in
       verbatim code however or enclosed in character quotes or
       brackets.



Identifier Entries
------------------
The important things are:

    1.  No entry should contain MORE than 1 consecutive blank line,  and
        each entry must have ONLY 2 blank lines before and after it.
        Use ONLY 3 blank lines  after the last entry  in each section
        to separate sections.

    2.  An entry  begins  with  one (or  more)  'synopsis'  lines,  each
        starting at  column 1,  and  the first  of  which for  each  new
        identifier has that identifier's  identprops enclosed in  square
        brackets at the end  of the line. To  save space, "constant"  is
        omitted in combination  with anything  else, and  the only  type
        that should be given is  "procedure" for a procedure  identifier
        (Poplog  doesn't   have   any   typed   variables   other   than
        procedure-type,  so  this   part  shouldn't  imply   otherwise).
        Examples are

                               [procedure]     (= procedure constant)
                      [procedure variable]
                                [constant]
                                [variable]
                              [operator N]
                                  [syntax]
                                [syntax N]
                                   [macro]
                          [macro variable]

        For a variable, it should also say if protected, e.g.

            [protected procedure variable]

        I've also used [library] to flag the name of a library that must
        be explicitly loaded.

    3.  Synopsis lines represent the following items:

          # An outline use for syntax words,
          # An outline call for procedures with arguments and results
          # Example assignments to and from items for ordinary variables
          # Example assignments to items for protected variables and
            constants
          # or just the name for anything else

        If this extends over  more than 1  line, the continuation  lines
        must be indented by any number of columns (OTHER THAN 8  columns
        to distinguish them from  the body of the  text). Note that  the
        [identprops] part  must  still be  on  the first  line  of  that
        synopsis). See examples below.

    4.  As implied  above,  each  entry can  contain  multiple  synopsis
        lines, either for different call  forms of the same  identifier,
        or for several identifiers, but  [identprops] at the end of  the
        line must mark the first one for each new identifier introduced.

    5.  Formal  parameter  names  in  synopsis  lines  should  use  only
        upper case alphanumeric characters and underscore.

    6.  The first line of the following text for the entry must start at
        column 8;  the rest  of  lines must  be  idented by  at  least 8
        columns (and mustn't contain 2 or more consecutive blank lines).



Example identifier entries
--------------------------
(In the examples  that follow,  the entries  have been  indented by  one
character to prevent confusion with actual entries in ref files.)

     col 8                                                         col 72
        |                                                              |


 newanyproperty(ASSOC_LIST, TAB_SIZE, EXPAND_POW, THRESH,    [procedure]
                           HASH_P, EQUAL_P, GC_TYPE,
                           DEFAULT, ACTIVE_DEFAULT) -> PROP
        This is for constructing  more complex properties. It  returns a
        new property PROP, where the arguments are:


 subscrs(N, STRING) -> CHAR                                  [procedure]
 CHAR -> subscrs(N, STRING)
        Returns or updates the N-th character CHAR of the string STRING.


 NUM_1  +  NUM_2  ->  NUM_3                                 [operator 5]
 NUM_1  -  NUM_2  ->  NUM_3                                 [operator 5]
 NUM_1  *  NUM_2  ->  NUM_3                                 [operator 4]
 NUM_1  /  NUM_2  ->  NUM_3                                 [operator 4]
        These operators respectively add, subtract, multiply and  divide
        their arguments,  which may  be  any numbers.  The type  of  the
        result depends  on  the  rules  of  floating-point  and  complex
        contagion (etc, etc).


 popradians -> BOOL                                           [variable]
 BOOL -> popradians
        This  boolean-valued  variable   specifies  whether  the   angle
        arguments or results for trigonometric procedures are in radians
        (true) or  degrees  (false). Note  that  the default  is  false,
        implying angles in degrees.


 pi -> FLOAT                                                  [constant]
        This constant is the best ddecimal approximation to "pi".


 popexecute -> BOOL                                 [protected variable]
        This boolean variable is <true>  when the current invocation  of
        the VM through  -sysCOMPILE- is  at execute  level, and  <false>
        when code is being planted inside a procedure or a non-executing
        lblock.



Standard Type Names for Arguments/Results
-----------------------------------------
The following  names  can be  used  for  arguments and  results  of  the
appropriate type: they are  not meant to be  compulsory, only for  cases
where the use of more descriptive 'semantic' names isn't warranted  (or,
they can be used in combination with the latter).

    They are also not  meant to be  rigorous in the  sense that a  given
argument or result can ONLY take  the implied value, but show that  this
is its 'principal' value (any exceptions being clearly described in  the
text).

    Where more than one is used, add integer subscripts at the end, i.e.
ITEM_1, ITEM_2, etc.

    Alternatively if  there  are different  type  characterisations  add
prefixes separated by underscores, e.g. S_VED and D_VEC for start vector
and destination vector in REF * DATA/move_subvector

See REF* DATA for information on the data types built in to Poplog.



Basic Types (Excluding Numbers)
-------------------------------
ARRAY                                                         [datatype]
        An array. See REF * ARRAYS


BOOL                                                          [datatype]
        Boolean: -true- or -false-
        Note that any non-false value is treated as being -true- in most
        circumstances.


CHAR                                                          [datatype]
        Character: an integer between 0 and 255.
        Note that Poplog uses the ASCII standard.


CLOS                                                          [datatype]
        Closure: procedure built by partial application.
        See REF * PROCEDURE/Overview


DEV                                                           [datatype]
        Device: structure used for file and terminal I/O.
        See REF * SYSIO


EXTERNAL_P                                                    [datatype]
        External procedure: created by -external_load-.


FVEC                                                          [datatype]
        Standard full vector.


IDENT                                                         [datatype]
        Identifier. See REF * IDENT


INTVEC                                                        [datatype]
        A vector of 32-bit signed integers.


ITEM                                                          [datatype]
        Any Poplog object at all.


KEY                                                           [datatype]
        Class-descriptor. See REF * KEYS


LIST                                                          [datatype]
        A list of items (or the empty list, -nil-). See REF * LISTS


P                                                             [datatype]
        Procedure.


PAIR                                                          [datatype]
        A pair:  two-element record structure used,  among other things,
        for building lists.


PROC                                                          [datatype]
        A  process:  a  data  structure  created  (e.g.)  by  -consproc-
        recording the state of execution of a procedure.
            See REF * PROCESS


PROP                                                          [datatype]
        Property: a hashed data structure associating item/value pairs.


PROPENT                                                       [datatype]
        Property entry: records a single item/value association.


REF                                                           [datatype]
        Reference: a one-element record type object.
        See REF * RECORDS/References


SECT                                                          [datatype]
        Section: a mapping between WORD's and IDENT's.
        See REF * SECTIONS


STRING                                                        [datatype]
        A vector of characters. See REF * STRINGS


STRUCT                                                        [datatype]
        Compound object (anything except integers & decimals).
        See REF * DATA


UNDEF                                                         [datatype]
        An  undef  record:  the  value  of  an  uninitialised  permanent
        identifier. See REF * IDENT/Undef


VEC                                                           [datatype]
        Vector: any vector type object.


WORD                                                          [datatype]
        Word. See REF * WORDS



Numbers
-------
See REF * NUMBERS for full information on types of numbers available.

N                                                             [datatype]
        A simple integer.


M                                                             [datatype]
        A simple integer.


INT                                                           [datatype]
        Integral: simple or big integer.


FLOAT                                                         [datatype]
        A floating point number (decimal or ddecimal).


RAT                                                           [datatype]
        Rational: ratio or integral.


RATIO                                                         [datatype]
        A ratio (fraction).


REAL                                                          [datatype]
        A non-complex number  (integer,  biginteger,  ratio,  decimal or
        ddecimal)


COMPLEX                                                       [datatype]
        A complex number.


NUM                                                           [datatype]
        Any number at all.



Other types
-----------
BYTESTRUCT                                                    [datatype]
        A 'byte accessible' data structure. See REF * DATA/Byte.


CHAR_CONS                                                     [datatype]
        A character consumer procedure. See REF * CHARIO


CHAR_REP                                                      [datatype]
        A character repeater procedure. See REF * CHARIO


DIR                                                           [datatype]
        Directory: a string naming a disk directory.


FIELD_SPEC                                                    [datatype]
        A record or vector field type descriptor (as used by -conskey-).
        See REF * KEYS


FILE                                                          [datatype]
        A string  or  word  naming  a disc  file,  or  a  device  record
        corresponding to a disc  file or pipe  or mailbox, suitable  for
        reading or writing.


FILENAME                                                      [datatype]
        String or word naming a disc file.


IDPROPS                                                       [datatype]
        An identifier status descriptor (as used by -sysSYNTAX-).


ITEM_REP                                                      [datatype]
        An item repeater procedure, producing a Pop11 item each time  it
        is called, and -termin- when there are no more items.
        See  REF * ITEMISE


LIB_NAME                                                      [datatype]
        Name of a library file. Normally a string, but can sometimes  be
        a word. See REF * LIBRARY.


SEARCH_LIST                                                   [datatype]
        List of directories in which to search for library programs  and
        documentation. See REF * LIBRARY and HELP * SEARCH_LISTS.


SPEC                                                          [datatype]
        Field specification as used for -conskey-   See REF * KEYS/SPEC


SPEC_LIST                                                     [datatype]
        List of field specifications as required for record classes.
        See REF * KEYS/SPEC_LIST


STRING_REP                                                    [datatype]
        An string repeater procedure, producing a string each time it is
        called, or -termin- when finished.


STRWORD                                                       [datatype]
        WORD or STRING.


VEDFILE                                                       [datatype]
        A string that  is a  filename suitable for  ved, or  a VED  file
        structure such as is found in -vedbufferlist-  (i.e. a vector of
        strings).


WIDENT                                                        [datatype]
        WORD or IDENT.



Prolog types
------------
PROLOGTERM                                                    [datatype]
        A complex Prolog term.  See REF * PROLOG


PROLOGVAR                                                     [datatype]
        A Prolog variable.  See REF * PROLOG



Useful utility procedures
-------------------------
The following procedures  may be  found useful when  editing REF  files.
Note that  <ENTER>  dssp  can  be used  to  display  Ved  special  space
characters (in the current file only), and that <ENTER> ifsp can be used
to insert special spaces at the beginnings of lines where necessary, See
REF * ved_dssp, ved_ifsp.



... <ENTER> ulheading: underline heading with hyphens
-----------------------------------------------------

define ved_ulheading();
    ;;; underline side heading with hyphens
    lvars size = vvedlinesize;
    vedlinebelow();
    fast_repeat size times
        vedcharinsert(`-`)
    endrepeat
enddefine;




... <ENTER> idprops <type>: insert or update identprops on right
----------------------------------------------------------------

    compile_mode:pop11 +strict;
    section;

    include vedscreendefs;

    lvars Last_idprops_string='[\{bi}procedure\{-bi}]';

    /*
     * <ENTER> idprops [type]
     * Insert/Update REF file idprops entry on right of line
    */
    define global ved_idprops();
        lvars col = locchar_back(`[`, vvedlinesize, vedthisline());
        dlocal vedlinemax = 72;

        ;;; GET HOLD OF PREVIOUS IDPROPS
        if col then col -> vedcolumn; vedcleartail(); endif;

        if (vedargument=nullstring) then
            Last_idprops_string
        else
            consdstring(#|
                `[`;
                lvars char;
                ;;; PUT STRING IN BOLD ITALICS
                for char in_string vedargument do;
                    char || VEDCMODE_BOLD || VEDCMODE_ALTFONT
                endfor;
                `]`;
            |#) ->> Last_idprops_string;
        endif -> vedargument;
        ved_right()
    enddefine;

    endsection;



... <ENTER> ved_jrefmr: justify in REF format, marked range
-----------------------------------------------------------

Warning: this can screw up program examples if used indiscriminately.

define ved_jrefmr;
    ;;; Indent and right justify description of procedure or variable in
    ;;; marked range

    lvars arg = strnumber(vedargument);
    dlocal vedleftmargin, vedlinemax = 72;

    if arg then strnumber(vedargument) else 8 endif -> vedleftmargin;

    ved_jj()
enddefine;

In some cases it is necessary to use ved_ljmr to prepare for the use  of
ved_jrefmr, i.e.  if  the  existing indentation  is  greater  than  that
ved_jrefmr is to produce.



... <ENTER> ved_slrhs: Swap Left and Right Sides of an assignment
-----------------------------------------------------------------

This takes a line with  an assignment arrow and  produces a copy of  the
line with the arguments on  the left and right  hand sides of the  arrow
reversed (without any identprops on the original line).

define ved_slrhs();
    lvars arrow_pos, bracket_pos, this_line=vedthisline();

    ;;; If there is an assignment arrow, record its position
    if (issubstring(' -> ', this_line) ->> arrow_pos) then

        ;;; Copy the line it occurs on
        vedlinebelow();
        this_line -> vedthisline();

        ;;; Find and remove any idprops at the end of the line
        if (locchar_back(`[`, vvedlinesize, this_line) ->> bracket_pos)
        then
            bracket_pos -> vedcolumn;
            vedcleartail();
            vedtrimline();
            vedsetlinesize();
        endif;

        ;;; And swap left and right hand sides
        vedthisline() -> this_line;
        (substring(arrow_pos+4, vvedlinesize-arrow_pos-3, this_line) ><
         ' -> ' ><
         substring(1, arrow_pos-1, this_line)
        ) -> vedthisline();

        ;;; Not forgetting to refresh the line so we can see the change
        vedrefreshrange(vedline, vedline, false);
    else
        vederror('No assignment arrow on line');
    endif;

enddefine;



... vedrefdefaults: tailoring VED for REF files
-----------------------------------------------
REF files  should contain  no tab  characters or  other special  control
characters.

They should also be limited to 72 columns, for convenient printing  in a
readable format.

The following can be called from inside vedinitfile

    define vedrefdefaults();
        72 -> vedlinemax;
        true -> vednotabs;
    enddefine;

e.g.

    define vedinitfile();
               .....
        if isstartstring('REF', vedbuffer(1)) then vedrefdefaults endif;
    enddefine;

Alternatively use -vedfiletypes-. See HELP VEDFILETYPES



See also
--------
HELP * MKREFINDEX

HELP * STANDARDS

HELP * FORMAT

HELP * VEDCOMMS/ved_fill
HELP * VEDCOMMS/ved_gobble
HELP * VEDCOMMS/ved_jj
HELP * VEDCOMMS/ved_jp
HELP * VEDCOMMS/ved_jjp
HELP * VEDCOMMS/ved_ljmr
HELP * VEDCOMMS/ved_tidy

HELP * VEDBLOCKS
    - moving blocks of text around

HELP * VEDFILETYPES
    - setting defaults for different types of files.


--- C.all/ref/refform_old
--- Copyright University of Sussex 1993. All rights reserved. ----------
