REF REFFORM                                        John Gibson, Jun 1987
                                             Revised: A.Sloman, Jan 1990
                                             Revised: A.Howard, Jul 1990
                                           Revised: D.McIntyre, May 1993

        COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<   THE FORMAT OF REF FILES   >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This file  specifies the  format for  REF files  which Sussex  uses  and
recommends,  listing  various  procedures   to  help  adhere  to   these
standards. Note that from  Version 14.22 of  Poplog onwards, the  system
REF files have taken on a new look. This file details the new  standards
that accompany that look.
    When it comes to writing your own REF files, you can of course stick
to the old style. Details of the old style are now in REF * REFFORM_OLD.


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

  1   Introduction

  2   The REFORMAT Program

  3   Format of REF Files
      3.1   Example Template REF File
      3.2   The Header
      3.3   The Title
      3.4   The Overview
      3.5   The Contents
      3.6   Sections and Section-Header Formats

  4   Table Format

  5   Paragraph Format

  6   Verbatim Text

  7   Program Code

  8   Lists
      8.1   Enumerated Lists
      8.2   Bullet Lists
      8.3   Descriptive Lists

  9   The Use of VED Character Attributes

 10   Quoting Things

 11   Identifier Entries
      11.1  Example identifier entries
      11.2  Standard Type Names for Arguments/Results
            ... Basic Types (Excluding Numbers)
            ... Numbers
            ... Other types
            ... Prolog types

 12   Useful utility procedures

 13   Further Documentation



---------------
1  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.




-----------------------
2  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. For LIB * REFORMAT to work
then the standards  specified in  this file must  be rigorously  adhered
too.
    The  Sussex  REF   files  will  already   have  been  prepared   for
LIB * REFORMAT. However  if you  locally change  a Sussex  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.  To  preview a  file  using
LIB * REFORMAT do

     <ENTER> 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.
    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 set out in this file.
    REMEMBER: Small errors which you can get away with on-line become
really obvious when nicely printed out.




----------------------
3  Format of REF Files
----------------------

The overall format (exemplified by this file) is:

        <header>
        <title>
        <overview>
        <contents>
        <section 1>
            <identifier entry>
            <identifier entry>
            ...
        <section 2>
            <identifier entry>
            <identifier entry>
            ...
        ...
        <footer>

Where no lines extend  over 72 characters, and  all descriptive text  is
right-justified using * ved_jrefmr, * ved_jj or * ved_jjp.



3.1  Example Template REF File
------------------------------
NOTE: the numbers of blank lines between different kinds of entries  are
important --- they will be used by libraries like LIB * MKREFINDEX.


REF EXAMPLE                                        John Sloman, Jan 1990
                                             Revised: Joan Doe, Feb 1993

        COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<       AN EXAMPLE TITLE      >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxx overview xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

  1   First Section

  ...


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

    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxx more text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

                     table/program code/list

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>



-----------------
2  Second section
-----------------
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.



3.2  The Header
---------------
The header should specify the name  of the REF file, and it's  author(s)
as shown in the template given in the previous section.



3.3  The Title
--------------
The title should be enclosed in a  box made from `>` and `<`  characters
as shown in the template. Please make sure that the title is:

    # Meaningful

    # All in upper case

Please ensure that the width of the box used to enclose the title is the
same as that used in the template (this is used by LIB * REFORMAT.) More
than three lines can be used for long titles.



3.4  The Overview
-----------------
This should act  as a very  brief synopsis  of the contents  of the  REF
file. There  should  be  no  blank lines  between  paragraphs.  See  the
template for an example.



3.5  The Contents
-----------------
The contents are  an (optional)  index of the  REF file  as produced  by
* ved_newindex. Sussex REF files  are produced using  the "sp" style  of
index. See * ved_newindex for details.



3.6  Sections and Section-Header Formats
----------------------------------------
The main  text of  the REF  file  should be  divided into  sections  and
sub-sections to aid comprehension.

 #  Each (sub)section should have a heading.

 #  There should be 2 or more empty lines preceding a sub-sub-heading, 3
    preceding a sub-heading, and 4 preceding a main heading.

 #  There should be  one blank line  after main headings,  and no  blank
    lines after other headings.

Headings should  be produced  with * ved_newheading  to conform  to  the
format used by * ved_newindex. The three heading types used are:

    -------
    1  Bold                (Main Heading)
    -------

    1.1  Non-Bold          (Sub Heading)
    -------------

    ...  Non-Bold          (Sub Sub Heading)
    -------------

Note that:

 #  Underlining and overlining is the same length as the heading text
 #  Headings should start at column 1
 #  Underlining is made of `\G-` characters
 #  There are two spaces after the section number (or '...')

See REF * REFFORM_OLD  for  details  of  the  old  heading  and  section
formats.




---------------
4  Table Format
---------------

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

There should be a blank line before and after the table.

Each column should be left justified (ie. aligned with the first  column
of the heading.)

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. Without
this LIB * REFORMAT will not work properly. If this is impossible  place
a hyphen (`-`) in the non-filled columns to indicate a blank entry.




-------------------
5  Paragraph Format
-------------------

These follow  the form  of  the template.  Two  rules should  always  be
followed:

 #  Make sure that all regular paragraphs are right justified.

 #  Single line  paragraphs  should not  have  more than  two contiguous
    spaces to prevent  them being interpreted  by LIB *  REFORMAT as  an
    itemised list."




----------------
6  Verbatim Text
----------------

Text that should be  reproduced verbatim by  * REFORMAT should have  the
VED format-control  space character  `\Sf` placed  at the  beginning  of
every line. For example:

    Col:1   4   8   12
        |   |   |   |
        X   This text
        X   should be
        X   reproduced
        X   verbatim

(where `X` represents `\Sf`.)

There should be a blank line before and after the verbatim section.  The
command * ved_ifsp can be used to insert format spaces, and the  command
* ved_dssp can be used to view them.




---------------
7  Program Code
---------------

For compilable sections of code the ved prompt-marker space `\Sp` should
be placed at the start of every line. For example:

    Col:1   4   8   12  16  20  24  28
        |   |   |   |   |   |   |   |
        X   vedcurrent.sys_fname_nam=>

(where `X` represents `\Sp`.)

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  compilable,
i.e. not  just  'outline' or  'meta'  examples.  If in  doubt  treat  as
verbatim text and use `\Sf`.

As for verbatim text,  * ved_ifsp and * ved_dssp can  be used to  insert
and view prompt-marker spaces.

NOTE: The LIB * 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 to put it on the end of a line.




--------
8  Lists
--------

There are three types of lists.

     # Enumerated

     # Descriptive

     # Itemised (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  LIB *  REFORMAT
program performs better if they are indented.



8.1  Enumerated Lists
---------------------
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.



8.2  Bullet Lists
-----------------
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


B is one of `#` (`\G#`), `o`, or `*`. The use of `*` is not  recommended
as it can lead to confusion with cross references.



8.3  Descriptive Lists
----------------------
These take two forms. For short snappy lists do::

     ITEM  text text text text text text text

     ITEM  text text text text text text text

For longer, more informative lists do:

     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

(ITEM can be in lower or upper case.)

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  produced
by LIB * REFORMAT will definitely look better.




--------------------------------------
9  The Use of VED Character Attributes
--------------------------------------

The use  of the  VED  character attributes  in  REF files  is  perfectly
acceptable. You can use them to emphasize pieces of the text. The
following general rules are used in Sussex REF files:

 #  Identifier names are placed in bold text (eg popmemlim.)

 #  Variables are  placed in  italics  and are  usually lower  case  (eg
    item.)

 #  Descriptive list items are placed in italics.

 #  Cross references to other on-line documentation should be italicised
    too i.e. REF * REFFORM, except when they are to identifiers (eg  REF
    * ved_chat)  when the  identifier should  be bold.  The `*`  is  not
    attributed.

You can use ved_chat to change the attributes of a word. See  * ved_chat
for more information on VED character attributes.




------------------
10  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 referring  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.




----------------------
11  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.

    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 (right justified to column  72.)
        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.) These  lines can  be inserted  with
        * ved_idprops. The  main  text  of  the  idprops  should  be  in
        bold-italics, with the square brackets in normal text.  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]

        [library] is also used 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 (and  their updaters)  with
            arguments and results.

         #  Example  assignments  to   and  from   items  for   ordinary
            variables.

         #  Example assignments  to items  for protected  variables  and
            constants.

         #  Just the name for anything else

        If  a  synopsis  lines  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 only be made
        up  of  italicised  lower  case   alphanumeric   characters  and
        underscores.

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

    7.  As a  general room  everything on  the synopsis  line should  be
        bold, with two exceptions:

         #  Variables which should be in italics.

         #  Text which is  not typed used  to indicate option  arguments
            (which should be in normal text.)

        See the example identifier entries in the next section.



11.1  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.



11.2  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_vec and  d_vec for  start vector  and
destination vector in REF * 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/Closures.


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.
        See REF * PROPS.


propent                                                       [datatype]
        Property entry:  records a  single item/value  association.  See
        REF * PROPS


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


sect                                                          [datatype]
        Section: a mapping between words and idents. 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]
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 Poplog 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 * conskey.


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.




-----------------------------
12  Useful utility procedures
-----------------------------

The following procedures may be found useful when editing REF files:

 #  * ved_jrefmr is used for formatting REF file identifier entries.

 #  * ved_slrhs can be used to automatically create the updater  entries
    for REF file synopsis lines.

 #  * ved_idprops is used  to insert  [identprops] entries  in REF  file
    synopsis lines.

 #  * ved_dssp is used to see the special formatting spaces used by VED.

 #  * ved_ifsp is  used  to insert  and  remove the  special  formatting
    spaces used by VED.

 #  * ved_newheading is used to create REF file section headings.

 #  * ved_newindex is used to create a contents page for a REF file.

The normal  VED formatting  procedures can  also be  of great  use.  See
"Formatting Commands" in REF * VEDCOMMS for more information.

Also see:

    HELP * VEDBLOCKS
        Information on moving blocks of text in VED.

    HELP * FORMAT
        Commands to aid on-screen formatting of text in VED.




-------------------------
13  Further Documentation
-------------------------

HELP * VEDFILETYPES
    Setting the defaults for different types of files.

HELP * MKREFINDEX
    Creating an index of REF files that  can be used by the * ved_?  and
    * ved_?? commands

HELP * STANDARDS
    Other documentation and library standards for Poplog.

REF * DOCUMENTATION
    Implementation of the Poplog on-line documentation system.



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