THE OLD STYLE FORMAT FOR REF FILES
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.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
Select headings to return to index
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.
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.
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.
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.
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)
...
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>
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. ----------
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.
Since the REFORMAT program uses the title of the REF file as a chapter heading, please ensure the following:
Do please also ensure that the box surrounding the title is of the same dimensions as the one at the top of this file.
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.
Two types
Section (Main Heading) -------
... Subsection (Sub Heading) --------------
All these are left justified with a continuous row of hyphens underneath.
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.
These follow the form of the template. Only two things are crucial:
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.
There are three types of lists.
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.
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.
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.
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.
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.
Just some simple rules which should be observed as a matter of course.
The important things 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:
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.
(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.
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.
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
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.
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.
PROLOGTERM [datatype]
A complex Prolog term. See REF * PROLOG
PROLOGVAR [datatype]
A Prolog variable. See REF * PROLOG
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.
define ved_ulheading();
;;; underline side heading with hyphens
lvars size = vvedlinesize;
vedlinebelow();
fast_repeat size times
vedcharinsert(`-`)
endrepeat
enddefine;
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;
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.
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;
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
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. ----------