               LIST - BASIC Listing Program
               ============================


by:	Nigel Bevan & Graham Clemow
	National Physical Laboratory
	Teddington, Middx

	01-977 3222 x4013/4011


LIST lists BASIC programs in an attractive easy-to-read form,
together with columns of cross-referenced line numbers (if
option specified). Listing features include: Blanking or
exdenting of unreferenced line numbers (optional), FOR-NEXT loop
indentation, Variable page width, Spacing of subroutines,
Highlighting of frequently referenced line numbers (optional),
and Character and line count at the end of the listing. The
names of the BASIC programs to be listed can be entered at run
time or read from a command file. MLIST is the same as LIST
except that it lists programs written in micro-computer BASIC.
FLIST is the same as LIST except that it lists programs written
in BASIC-11 which are in a free format (not in SAVEd file format).


While the numbering of each line of a BASIC program allows easy
editing it has the disadvantage that the structure of the
program, especially if it is a lengthy one, is hard to follow.

The program supplied overcomes this problem by listing BASIC
programs in a format which yields at a glance which lines are
referenced by other parts of the program and where these
referencing lines appear. Other structuring features include the
indentation of each level of a FOR-NEXT loop and the spacing out
of subroutines.

One or other of the following two listing formats may be
selected:

i) Any line number which is not referred to in another statement
(ie after a GOTO, GOSUB or THEN) is blanked out. Statement
numbers which are referred to are printed as usual. For example
a simple program listing might be:

    REM PRINTS SQUARES
200 INPUT I
    PRINT I*I
    GO TO 200
    END

ii) Any statement number which is not referred to by another in
the program is exdented to the edge of the page. The listing
produces two columns of line numbers the inner ones pointing to
those lines to which jumps are made and the outer ones belonging
to unreferenced lines. The advantage this format has over the
blanking format is that if a correction involves referencing a
previously unreferenced line then the appropriate line number
can be found from the listing. With this exdented format the
program above would be listed as:

100    REM PRINTS SQUARES
   200 INPUT I
300    PRINT I*I
400    GO TO 200
500    END


Cross-referencing is possible for either of these formats. With
this option, columns to the left or right of the page contain a
list of the lines in which a reference is made to the current
line. In the exdented format therefore only the line numbers in
the inner column will have numbers in the cross-reference
columns. The example program could be listed as:

    | 100    REM PRINTS SQUARES
400 |    200 INPUT I
    | 300    PRINT I*I
    | 400    GO TO 200
    | 500    END


At the start of the program parameters can be entered to make
the cross-reference columns appear to the left or right of the
listing. In addition the number of columns of cross-reference
line numbers can also be selected. (The example above only had 1
column.) If a line needs more columns than specified then the
program will insert extra rows of line numbers before it. This
helps to give the listing structure since frequently referenced
lines will be preceded by a gap.

The program has other structuring features. i) All subroutines
start and end with two blank lines. ii) Each listing starts and
ends with a form feed. iii) The number of lines and the number
of characters in the source are printed at the end of the list.
iv) Each level of a FOR-NEXT loop is indented by two spaces. If
more NEXT statements than FOR statements are encoutered then
"??" is printed. v) The page width of the output device is set
at line 200 to 85. It is only necessary to alter this one
statement to set a different width. A line too long to fit
across the page (together with the extra line number columns
which may have been requested) will be continued to the next
line and indented by 5 spaces (as well as any FOR-NEXT
indentation etc).

There is a facility in the options section to run a list using
these options without any highlighting or cross-referencing.
This list is much faster than the other types since no line
number tables have to be made up.


                        Input of Options
                        ================

When run the program will prompt:

COMMAND FILE ( <CR>=NONE )?

The use of command files will be explained later so assume for
the moment that a carriage return has been entered. The next
prompt will be:

PROGRAM ( ,FILENAME )?

If the listing is to appear at the terminal simply give the name
of the program to be listed. If the listing is to be stored in a
file then reply with the program name, followed by a comma,
followed by the name of the file. If no file type is specified
in the name of the program to be listed then the default file
type .BAS is assumed. The default file type for the listing file
is .LST .

The next prompt will be:

HIGHLIGHT OR CROSS-REFERENCE LINE NUMBERS ( <CR>=NO )?

A reply of <CR> or of anything not beginning with Y will produce
a fast list incorporating the formatting features described
above but without any cross-referencing or highlighting (ie
blanking or exdenting). If a positive reply is given then two
further questions will appear:

BLANK NON-REFERENCED LINE NUMBERS ( <CR>=NO )?
NUMBER OF CROSS-REFERENCE COLUMNS (-VE TO RIGHT , 0=NONE )?

The first question determines whether blanking or exdenting is
required and the second determines the number of cross-reference
columns (if any), and which side of the page they appear. For
example, if the replies are Y and -3, the program will list in
the blanking format with 3 columns of cross-reference line
numbers to the right of the page.


                         Command Files
                         =============

Essentially a command file consists of a list of program names.
These program names appear in the command file in the same form
as they would if they were entered in reply to the prompt for
the program name - for instance it is possible to list a program
to a file as above.

It is also possible to select and change the various listing
options. This is done by starting a line with an asterisk
followed by the replies to the prompts which the program
normally gives. For example,

*YN-2

will change the options to exdenting with 2 cross-reference
columns to the right of the page. If the reply to the first
question is N then the other two questions need not be answered:

*N

The first two characters after the asterisk must (if anything)
be the letters Y or N. The number from column 4 onwards can take
any form which BASIC usually recognizes. The default options at
the start of the program are for no highlighting or
cross-referencing (equivalent to *N). Whenever the program finds
a line in the command file starting with an asterisk it changes
the current options to the new ones specified. For example
suppose the command file BASLIS.COM is created with the
following entries:

PROG1
*YY0
PROG2.XYZ,PROG2

If "BASLIS" is entered after the initial prompt for a command
file (the default file type for a command file is .COM) then the
program PROG1.BAS will be listed with no highlighting or
cross-referencing columns followed by a listing to the file
PROG2.LST of PROG2.XYZ with blanking of unreferenced line
numbers but no cross-referencing.

                             MLIST
                             =====

This program is very similar to LIST, its essential difference
being that it caters for less strict language formats than LIST.
It is primarily intended for listing programs written in
microcomputer BASIC. Its main features are:

i) Spacing in statements is not critical. For instance the
program will be able to extract the line number from GOT O9 00
whereas for the program LIST the format must be the same as the
SAVEd file format GO TO 900.

ii)Instead of the "\" statement terminator the ":" statement
terminator is used.

iii)The program will ignore blank lines.


                             FLIST
                             =====

This program is identical to MLIST except that the "\" statement
terminator is used instead of ":". (That is ignore (ii) above to
get the differences between LIST and FLIST). FLIST is intended
to be used to list programs written in BASIC-11 which have
been edited or created without using BASIC so that the spacing
of statements is not in the standard SAVEd file form.


                    Notes on source program
                    =======================

i)Very large programs may need more array space. The function of
each array is:
W5% Stores program numbers which are referenced.
W6% Stores subroutine entry points (Subset of W5%).
T6% Stores cross-reference numbers.
T5% Stores number of cross-reference numbers for a particular
    line. When re-dimensioning also change line 610.

ii)The margin between the body of the listing and the
cross-reference columns can be removed by replacing the two
occurences of the margin character by spaces.

iii)The subroutine at line 4000 will cater for all exotic
combinations of statements which do not involve true line number
references eg:

100 REM GO TO 50 \ PRINT " GO TO ' 50 REM " \ GO TO 200

will produce only one referenced line number ie 200.

iv)The whole program including array storage space requires
about 4700 words of memory.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                            