.COMMENT
.COMMENT  THIS FILE IS A COMBINATION OF THE .HLP AND THE .DOC FILES FOR LIST.
.COMMENT  THE .HLP FILE IS MEANT TO BE READ AT A TERMINAL, USING LIST
.COMMENT  WITH THE SCREEN SIZE SET TO 24.
.COMMENT  IN ADDITION, IT IS READ BY LIST AS A HELP FILE WHEN THE "H"
.COMMENT  COMMAND IS GIVEN IN LIST.
.COMMENT  TO USE THIS FILE TO CREATE THE .HLP FILE, DELETE ALL OCCURRENCES
.COMMENT  OF ".COMMENT HLP " FROM THE FILE AND RUN IT OFF (SEE HLP.CMD).
.COMMENT  TO USE THIS FILE TO CREATE THE .DOC FILE, DELETE ALL OCCURRENCES
.COMMENT  OF ".COMMENT DOC " FROM THE FILE AND RUN IT OFF (SEE DOC.CMD).
.COMMENT
.COMMENT  TO CREATE THIS FILE FOR THE VAX, FIRST DELETE ALL OCCURRENCES OF
.COMMENT  ".COMMENT VAX ", THEN RUNOFF THE FILE. FOR THE PDP11, FIRST
.COMMENT  DELETE ALL OCCURRENCES OF ".COMMENT PDP11 ", THEN RUN IT OFF.
.COMMENT
.COMMENT HLP .PS 24,79
.COMMENT HLP .NHD
.COMMENT HLP .LM 0
.COMMENT HLP .RM 79
.COMMENT HLP .literal
.COMMENT HLP Examples of commonly used commands:
.COMMENT HLP .end literal
.COMMENT HLP .include EXAMPLES.RNO
.COMMENT HLP Help on advanced use of LIST follows (type _^Z to exit help).
.COMMENT HLP .NHD
.COMMENT HLP .LM 0
.COMMENT HLP .RM 79
.COMMENT DOC .PAGE SIZE 60,75
.COMMENT DOC .header mixed
.COMMENT DOC .LM +5
.COMMENT DOC .RM 75
.HY
.COMMENT DOC .skip 20
.COMMENT DOC .center
.COMMENT DOC LIST File Listing Utility
.COMMENT DOC .center
.COMMENT DOC =========================
.COMMENT DOC .skip 4
.COMMENT DOC .center
.COMMENT DOC Written by:
.COMMENT DOC .skip 1
.COMMENT DOC .center
.COMMENT DOC William P. Wood, Jr.
.COMMENT DOC .center
.COMMENT DOC The Institute For Cancer Research
.COMMENT DOC .center
.COMMENT DOC 7701 Burholme Ave.
.COMMENT DOC .center
.COMMENT DOC Philadelphia, Pa. 19111
.COMMENT DOC .center
.COMMENT DOC (215) 728 2760
.COMMENT DOC .skip 1
.COMMENT DOC .center
.COMMENT DOC Version 3
.COMMENT DOC .page
.COMMENT DOC .TITLE LIST File Listing Utility
.COMMENT HLP .page
.paragraph 5,0
LIST's simplest use is to display lines from a file at the terminal,
usually a screen at a time.
LIST can also search for character strings
and write portions of a file to disk.
Finally, LIST can be postioned to any line in a file using line (record)
numbers.
.skip 1
This manual explains how to use LIST.
.skip 1
.COMMENT HLP Running LIST:
.COMMENT DOC .header level 1 Running LIST
.paragraph 5,1
The LIST command line has the following syntax
(optional parts of the command line are enclosed in square brackets):
.skip 1
.indent +8
LIST[/switches]#fspec[,fspec...]#[commands][>[>]file]
.COMMENT HLP .skip 2
.COMMENT HLP Switches:
.COMMENT DOC .header level 1 Switches
.skip 1
.LM +20
.INDENT -12
/HD#########Write a header record containing each file's name and the date
to the standard output before listing the file.
.skip 1
.INDENT -12
/GO#########List all files selected by "fspec" without prompting
(see below: FSPEC).
.COMMENT HLP .SKIP 1
.COMMENT HLP .page
.LM -20
.COMMENT HLP Fspec:
.COMMENT DOC .header level 1 Fspec
.paragraph 5,1
"Fspec" may be a simple file  name,  an  indirect command file name
preceded by _@, or
.COMMENT PDP11 in some installations,
a file name containing
.COMMENT PDP11 SRD wild card characters and/or switches.
.COMMENT VAX standard RMS wild card characters.
If "fspec" is an indirect file name, LIST  will  list
the named files  in  the indirect file one at a time.
The default extension for indirect file names is
.COMMENT PDP11 ".CMD".
.COMMENT VAX ".COM".
If "fspec" contains wild card characters
.COMMENT PDP11 and/or switches,
LIST will list the files which match the wild
.COMMENT VAX cards.
.COMMENT PDP11 cards and/or switches.
When "fspec" contains wild cards
.COMMENT PDP11 and/or switches
or is an indirect file name,
LIST will prompt you with each of the
selected file names to see if you  want  it  listed,  unless  /GO  was
selected (see above:  Switches).  Responses to the prompt are:
.lm +8
.skip 1
Y###########List the file.
.BR
<cr>#or#N###Don't list the file.
.BR
G###########List this and remaining files with no prompting.
.BR
_^Z##########Don't list this file and remaining files.
.BR
.lm -8
.paragraph 5,1
If commands are given on LIST's command line, they will be executed  once
for each file selected by "fspec".  If the standard output is
redirected by the command line, it will  remain  redirected  for  each
file selected
(See below: Redirecting Output From LIST).
.SKIP 1
.lm +7
.rm -7
.indent -7
.COMMENT PDP11 Note:##
.COMMENT PDP11 Normal SRD wild card characters and switches may
.COMMENT PDP11 be used in an SRD-type
.COMMENT PDP11 file name;
.COMMENT PDP11 however, do not
.COMMENT PDP11 use the /SE: switch, as this is the default switch.
.COMMENT PDP11 Also, only the most recent versions will be selected unless
.COMMENT VAX Note:#
.COMMENT VAX The wild card character matching works identically to the
.COMMENT VAX way it works in the DIRECTORY command, except that only
.COMMENT VAX the most recent version of the file is selected unless
;* is specified.
.lm -7
.rm +7
.COMMENT HLP .page
.COMMENT HLP Default fields in file names:
.COMMENT DOC .header level 2 Default Fields in File Names
.paragraph 5,1
More than one file may be listed during the same LIST session
by typing LIST and then a carriage-return.
LIST will prompt for a file name.
After each file has been listed, LIST will prompt for a new file name.
.paragraph 5,1
Whenever LIST attempts to open a file,
the device, uic, name, and extension
are remembered and become the defaults.
The defaults are used to replace missing fields
of subsequent file names entered for listing.
For example:
.skip 1
.lm +8
.literal
PDS> LIST
FILE? LB:[22,2]LIST.DOC
.end literal
.skip 1
.lm -8
When you are finished listing LB:[22,2]LIST.DOC,
if you wanted to see LB:[22,2]VG3.DOC, you would only have to type:
.skip 1
.lm +8
FILE?#VG3
.lm -8
.skip 1
and LIST would supply the missing fields of the file name.
.paragraph 5,1
If LIST can't open a file after supplying the defaults, it tries
the file name as entered.
Initially, the defaults are
.COMMENT VAX "SYS$DISK:" for the device and ".LIS" for the extension.
.COMMENT PDP11 "SY:" for the device and ".LST" for the extension.
.COMMENT HLP .page
.COMMENT HLP Numbers:
.COMMENT DOC .header level 1 Numbers
.paragraph 5,1
Numbers are used to position LIST in the file and as arguments to commands.
Numbers always precede the command they affect.
A number may be a simple number, one of several
special line number variables,
or a search pattern.
The value of a search pattern is the number of the line that matches
the pattern.
Some commands optionally take two numbers as arguments;
when specifying more than one number, separate the two
numbers by a comma, e.g. 1,45 .
In addition, numbers
may be added and subtracted from one another, e.g. $-9 is the 10th line
from the end of the file.
.paragraph 5,1
LIST scans the input on a command line from left to right.
Whenever it encounters a number,
dot (the current line number) is set to that number.
Multiple line numbers may appear next to each other;
LIST positions to each in turn, e.g. 1/SUBR/ searches for SUBR
after line 1.
.COMMENT HLP .skip 8
.COMMENT HLP .page
.COMMENT HLP Line number variables:
.COMMENT DOC .header level 2 Line Number Variables
.skip 1
.lm +16
.indent -8
_.#######Dot is the current line number.
Whenever LIST encounters a line number, the value of dot is reset
to that line number.
.skip 1
.indent -8
_%#######Percent sign is the first line of the file.
.skip 1
.indent -8
_$#######Dollar is the last line of the file.
.skip 1
.indent -8
_########Sharp is the line number displayed by the most recent prompt.
.skip 1
.indent -8
_@#######At-sign is the line number of the
top of the last screen displayed by LIST.
.skip 1
.indent -8
_*#######Star is set by the = command and is equal to the value of
dot when the = command was last issued.
* serves to mark a line of interest for future reference.
.lm -16
.COMMENT HLP .skip 6
.COMMENT HLP .page
.COMMENT HLP Search patterns:
.COMMENT DOC .header level 2 Search Patterns
.paragraph 5,1
A search pattern is a string of characters bracketed by
slashes (/) or backwards slashes (_\):
.skip 1
.LM +20
.indent -12
/string/####causes LIST to search forward from dot for a line
which matches "string".
.indent -12
_\string_\####causes LIST to search backwards from dot-1 for
a line which matches "string".
.skip 1
.LM -20
Case is not significant in search patterns, eg. /X/ and /x/ will
match the same lines.
There are several characters which have a special meaning when they appear
inside a search pattern:
.SKIP 1
.lm +12
.indent -6
"#####causes all following characters until the next "
to be treated as themselves, not as special characters.
Case is significant when the characters appear within double quotes.
Two double quote characters in a row are interpreted as one literal
double quote.
.COMMENT DOC .SKIP 1
.indent -6
%#####specifies that the match must occur at the beginning
of the line only. % itself must appear at the beginning of the pattern,
otherwise it has no special meaning.
.COMMENT DOC .SKIP 1
.indent -6
$#####specifies that the match must occur at the end
of the line only. $ itself must appear at the end of the pattern,
otherwise it has no special meaning.
Thus /%$/ searches for a line with nothing in it.
.COMMENT DOC .SKIP 1
.indent -6
*#####is a wild card character that matches any sequence of characters.
.COMMENT DOC .SKIP 1
.indent -6
?#####is a wild card character that matches any single character.
.COMMENT DOC .SKIP 1
.indent -6
_^#####causes the next character to be interpreted
as a control character.
Thus /_^Z/ matches the end-of-file character.
.COMMENT DOC .SKIP 1
.indent -6
_|#####logical OR. Causes a match if the sub-pattern before it or the
sub-pattern after it match the line.
For instance, /x|y/ matches lines containing an x or a y.
.COMMENT DOC .SKIP 1
.indent -6
_&#####logical AND. Causes a match if the sub-pattern before it and the
sub-pattern after it match the line.
.COMMENT DOC .SKIP 1
.indent -6
_~#####negation. Causes a match if the sub-pattern does not match the line.
_~ must appear at the beginning of a sub-pattern, otherwise it
has no special meaning.
Thus /x_&~y/ matches lines which contain an x but no y.
.COMMENT DOC .SKIP 1
.indent -6
_`#####accent matches a break character. Break characters are:
beginning of line, end of line, and any non-alphanumeric character.
To search for all occurrences of the variable "i" you could use the
following pattern
with the ? command:
/_`i_`/?
.skip 1
.lm -12
Once specified, a pattern becomes the default pattern and may be
invoked by // or _\_\.
Patterns may be used anywhere a number may appear; the value of
a pattern is the line number of the matched line.
.COMMENT HLP .skip 1
.COMMENT HLP .page
.COMMENT HLP Examples of line numbers:
.COMMENT DOC .header level 2 Examples of Line Numbers
.SKIP 1
.lm +20
.indent -12
_.-10########10 lines before the current line.
.COMMENT DOC .SKIP 1
.indent -12
1,$#########Line 1 through the last line of the file.
.COMMENT DOC .SKIP 1
.indent -12
/SUBR/######Next line which has the string SUBR in it.
.COMMENT DOC .SKIP 1
.indent -12
/%SUBR/#####Next line which has SUBR at the beginning of the line.
.COMMENT DOC .SKIP 1
.indent -12
_\_\##########Next line which matches the default
pattern while scanning backwards.
.COMMENT DOC .SKIP 1
.indent -12
/_`I_`_&_`J_`/###Next line on which the characters I and J both appear
each surrounded by break characters.
.COMMENT DOC .SKIP 1
.indent -12
/"""/He"""/#Next line which contains##"/He"
.COMMENT DOC .SKIP 1
.indent -12
1/SUBR/-1###The line before the first occurrence of SUBR after line 1.
.LM -20
.paragraph 5,2
It is possible to specify fairly complex line numbers;
the value of a line number is always the last number evaluated.
For instance,
.skip 1
.indent +8
1/SUBR/+1//,.+3/END/+1//
.skip 1
specifies two line numbers; the first is the second occurrence of SUBR
at or after line one; the second is the second occurrence of END at or after
3 after the first line number.
.COMMENT HLP .SKIP 2
.COMMENT HLP .page
.COMMENT HLP Commands:
.COMMENT DOC .header level 1 Commands
.paragraph 5,1
LIST accepts commands on it's command line
or when it prompts with the current line number
and a ">" character.
Commands are single characters and are preceded
by zero, one, or two numbers which are arguments to the command.
More than one command may be entered on a command line;
LIST scans the command line from left to right,
positioning to line numbers and executing commands.
.paragraph 5,1
There are two types of commands;
those that print
and those that affect LIST's state without printing.
Commands that print usually print from dot (the current line number)
unless two line numbers were specified, in which case printing
occurs from the first line number.
Other commands "eat up" the number(s) that are their arguments;
in other words, dot is reset to the value it had before the command,
with it's argument(s), was executed.
.paragraph 5,1
If a line number appears at the end of the command line with no
command after it, the default command (P) is executed.
Thus###/SUBR/###is equivalent to###/SUBR/P##;
both cause printing to begin at the next occurrence of SUBR.
.COMMENT HLP .skip 5
.COMMENT HLP .page
.COMMENT HLP Commands that print:
.COMMENT DOC .header level 2 Commands That Print
.skip 1
.lm +8
.indent -4
P###Displays
lines from the file.
Dot is always left at the last line printed plus 1.
P is the default command, and is optional at the end of the command line.
.lm +12
.indent -8
P#######Print
as many lines as will fit
within the current screen size (initially 23), starting at the current line (dot).
.indent -8
nP######Print as many lines as will fit within the current screen size
starting at line n.
.indent -8
n1,n2P##Print lines n1-n2.
.lm -12
.skip 1
.indent -4
G###Like
"P", "G" displays lines from the file,
however with zero or one arguments G only prints one line, and
the value of dot is not changed.
.lm +12
.indent -8
G#######Print the current line.
.indent -8
nG######Print line n.
.indent -8
n1,n2G##Print lines n1-n2.
.lm -20
.COMMENT HLP .skip 7
.COMMENT HLP .page
.COMMENT HLP Commands that print (continued):
.skip 1
.lm +8
.indent -4
?###Displays
only lines matching the current search pattern.
.lm +12
.indent -8
?#######Display
a screen-full of lines matching the current pattern.
If the end of the file is reached, dot is left at line 1, else dot is
left at the next line matching the current pattern.
.indent -8
n?######Display
a screen-full of lines matching the current pattern, starting at line n.
If the end of the file is reached, dot is left at line 1, else dot is
left at the next line matching the current pattern.
.indent -8
n1,n2?##Display
all lines matching the current pattern between lines n1 and n2.
Dot is left at n1.
.skip 2
.lm -20
.lm +7
.rm -7
.indent -7
Note:##LIST
usually changes most control characters to nulls before
writing out a line, however
when two line numbers are specified or when the G command
is executed, (eg. the commands "1,$P" or "100G")
all characters are written out unchanged.
Thus it is possible to write out portions of a file without losing
any characters.
.lm -7
.rm +7
.COMMENT HLP .skip 3
.COMMENT HLP .page
.COMMENT HLP Other commands:
.COMMENT DOC .header level 2 Other Commands
.skip 1
.lm +8
.indent -4
L###The
L command causes the last command line to be reexecuted.
.skip 1
.indent -4
=###The
= command sets the line number variable, *, to dot.
* serves to mark a line for later reference.
.lm +12
.indent -8
=#######Set * to dot.
.indent -8
n=######Set * to n.
.lm -12
.skip 1
.indent -4
S###Sets
the screen size.
.lm +12
.indent -8
S#######Reset the screen size to 23.
.indent -8
nS######Set the screen size to n.
.indent -8
n1,n2S##Set the screen size to (n2-n1)+1.
.lm -12
.skip 1
.indent -4
C###Sets
the column range which will be read from the input file.
.lm +12
.indent -8
C#######Reset the column range to 1-512.
.indent -8
nC######Set the column range to 1-n.
.indent -8
n1,n2C##Set the column range to n1-n2.
.lm -20
.COMMENT HLP .skip 5
.COMMENT HLP .page
.COMMENT HLP Other commands (continued):
.skip 1
.lm +8
.indent -4
F###Create a "virtual file" by restricting LIST to a contiguous subset
of the lines in
the file.
.lm +12
.indent -8
F#######Reset the virtual file to correspond to the actual file.
.indent -8
nF######Make a virtual file between dot and dot+n-1.
Dot becomes the new line 1 of the virtual file.
.indent -8
n1,n2F##Make a virtual file between n1 and n2.
N1 becomes the new line 1 of the virtual file.
.lm -12
.skip 1
.indent -4
N###Turn prompt mode on/off.
When prompt mode is off, LIST will not prompt with the current
line number, but will leave the cursor after the last line printed.
If the screen size is set to one and prompt mode is set off
(1SN accomplishes this)
then LIST will be in line-by-line mode, in which one
line is printed for each carriage-return.
.skip 1
.indent -4
R###Resets the screen size to 23,
the screen width to it's original value,
the column range to 1-512,
the virtual file to the full, actual file,
and prompt mode to on.
.skip 1
.indent -4
X###Finish listing the file.
X is identical to _^Z (EOF).
.skip 1
.indent -4
" "#Space (blank) is the null command, and does nothing.
.lm -8
.COMMENT HLP .page
.COMMENT HLP Installation specific commands:
.COMMENT DOC .header level 2 Installation Specific Commands
.skip 1
Not all installations have the following commands.
.lm +8
.skip 1
.indent -4
W###Sets
the screen width.
.lm +12
.indent -8
W#######Reset
the screen width to it's original value.
.indent -8
nW######Set the screen width to n.
.lm -12
.skip 1
.indent -4
H###Invokes LIST as a subtask to print a help file.
.skip 1
.indent -4
V###Routes all the following output from the command line to the printer port
of the DT80 (a VT100 look-alike).
.lm -8
.COMMENT HLP .skip 11
.COMMENT HLP .page
.COMMENT HLP Defining and using the macro:
.COMMENT DOC .header level 1 Defining and Using the Macro
.paragraph 5,1
LIST has a simple text replacement macro facility.
A macro is a remembered set of commands.
The macro is defined by enclosing the commands in
square brackets ([]).
When M is specified on the command line,
the M is replaced by the macro text.
.skip 1
For example:
.skip 1
.indent +8
[_@+1//P]
.skip 1
defines a macro to search for the current pattern starting
from the top of the last screen + 1, and print from there.
To invoke the macro, type M on the command line.
.paragraph 5,1
The text of the macro is not executed when it is defined.
It is not executed until an M is typed.
M may appear with other commands and line numbers on the command line;
first the macro text replaces the M, then the command line is executed.
The macro, M, may be used more than once on a command line.
.COMMENT HLP .skip 3
.COMMENT HLP .page
.COMMENT HLP Redirecting output from LIST:
.COMMENT DOC .header level 1 Redirecting Output From LIST
.paragraph 5,1
The output from a line of LIST commands,
which normally goes to the terminal,
may be redirected to a file.
To write a new file, put
>FILE
at the end of the commands, where FILE is a standard file name.
To append to an existing file, put
>>FILE
at the end of the command line.
If FILE doesn't exist, it will be created.
The default extension for FILE is
.COMMENT PDP11 ".LST".
.COMMENT VAX ".LIS".
The carriagecontrol type of newly created files is identical
to the carriagecontrol type of the file being listed,
while that of appended files is the same as that of the file being appended to.
.paragraph 5,1
Once a file name has been
specified using >FILE or >>FILE,
that file name becomes the default file name for
file redirection only,
and need not be specified again,
i.e. > or >> alone is all that is needed to
redirect output to that file.
.paragraph 5,1
When output is redirected by the initial command line which
selected the file(s) to be listed, it remains redirected
as long as the file(s) are being listed.
.COMMENT HLP .skip 4
.COMMENT DOC .page
.COMMENT DOC .header level 1 Examples of Commonly Used Commands
.COMMENT DOC .lm 0
.COMMENT DOC .rm 79
.COMMENT DOC .literal
.COMMENT DOC 
.COMMENT DOC     <cr>            Hitting return prints the next screen.
.COMMENT DOC     45              Start printing at line 45.
.COMMENT DOC     -5              Print from 5 lines back.
.COMMENT DOC     -               Print starting half a screen back.
.COMMENT DOC     ---             Start printing one and one-half screens back.
.COMMENT DOC     <esc>           Hitting escape prints from 2 screens back.
.COMMENT DOC     $-9             Print the last 10 lines in the file.
.COMMENT DOC     /SUBR/          Locate the string SUBR and print from there.
.COMMENT DOC     //              Locate the default pattern and print from there.
.COMMENT DOC     1/SUBR/         Locate SUBR at or after line 1 and print from there.
.COMMENT DOC     /ERR/-5         Print starting 5 lines before the next occurrence of ERR.
.COMMENT DOC     1,10            Print lines 1-10.
.COMMENT DOC     /SUBR/,/END/    Print the next subroutine.
.COMMENT DOC     /SUBR/?         Display lines containing SUBR.
.COMMENT DOC     ?               Display lines containing the current pattern.
.COMMENT DOC     1/`I`/,$?       Print all occurences of the variable "I".
.COMMENT DOC     10,$>T.TMP      Write lines 10 through the end of the file to T.TMP.
.COMMENT DOC  
.COMMENT DOC .end literal
.COMMENT PDP11 .COMMENT DOC LIST *.FTN /`N`/,$?X  would print all occurrences of the variable N in *.FTN
.COMMENT VAX .COMMENT DOC LIST *.FOR /`N`/,$?X  would print all occurrences of the variable N in *.FOR