DOCs for FOREST2.PRG
The list of changes in FOREST2 vs FOREST are listed at the end of 
the document.  The first part is the original distribution DOCs 
for the original version.

                         -------------
FOREST is a program to produce a listing which is an automatically 
produced table of contents of a source file in Pascal and,  at the 
same  time,  a  listing  which shows the  structure  (or  lack  of 
structure) of the program.  You don't need to read this to use the 
program.   Go  ahead and click on it.  Use FOREST.PAS as a  sample 
input  file  when one is asked for.   You're not  going  to  break 
anything by running it. 

Still here? O.K., the file allows three different destinations for 
the output:  to the monitor, to a printer, or to a file.  The idea 
behind  putting  the output to a file is that you can then  use  a 
text  editor  and a block paste to paste the file  back  into  the 
original program.  Look at the last few lines of FOREST.PAS to see 
an example.   The line numbers may be a few lines off,  since  the 
paste was done as the program was nearing completion,  rather than 
the absolute last revision.  The pasting has to be near the end of 
the program since its' inclusion will change the line numbers.  

The  ouput  - regardless of the form - serves as  a  good  minimal 
effort  refresher if you have to come back to the  program  later.  
It  serves  as  a  sort of road map  so  you  can  quickly  locate 
PROCEDUREs and FUNCTIONs,  and it also shows the nesting and scope 
of  subprograms  with respect to each other.  This  is  especially 
helpful with a program written by someone else. 

There is a help screen built into the program, so there isn't much 
left to say here.   A few points, though.  The file write uses the 
Personal  Pascal WriteLn to a text file which doesn't allow me  to 
provide  any error handling.   Consequently,  the  error  messages 
aren't as informative as I would like.   Using a text file is also 
excrutiatingly slow but considering the nature of the  program,  I 
don't look on this as a problem. 

If the ouput is directed at the monitor,   you can stop  scrolling 
with <control><s> and resume scrolling with <control><q>. 

You  can choose  different printer line widths if you  believe  a 
line to be printed will have usefull information beyond column 80.  
If you request a change to the printer pitch,  the printer will be 
reset  at the end of the program.   I don't like that but  the  ST 
doesn't allow any proper alternatives.  The moral is, don't change 
the pitch just for fun.   

My practice is to repeat the name of a subprogram in a comment  on 
the BEGIN line if, and only if, it is separated from its' matching 
PROCEDURE  line  (for example) by other  subprogram  declarations. 
Such  BEGIN  lines will be printed out.   Printing of  lines  that 
start with BEGIN can be suppressed by the use of a '\' as in :
    BEGIN  {\ don't print this line}
I  also repeat the subprogram name in a comment  on the  END  line 
(always), but that has no impact on this program, per se.

The program should work with any valid ASCII file,  regardless  of 
the  Pascal  compiler being used.   It has been  tested  with  the 
editor  output  for both major levels of Personal  Pascal.  To  be 
recompiled,  level  2.XX must be used since lines greater than  80 
characters long are used and the external calls are for level 2.

There is a smattering of syntax in the program so that running the 
program  against  itself  as source will check  to  see  that  the 
anomolies are handled properly.  For example,  I don't  personally 
use  tabs;   but I put them in in a few places so I could be  sure 
that the program handles them properly.   For the .PAS file To  be 
printed properly, a tab setting of 2 must be used.

   **************** CHANGES in FOREST 2 *****************
After using FOREST for several months, I noticed several 
deficiencys which are corrected in this new release. 

The original version tested for first 3 or 4 characters on a line 
and based on this, decided whether the line contained a reserved 
word or not.  This allowed similar words to get to the output 
consisting of a 'noise pollution'. I tried this on several sample 
programs and didn't find any noise.

The program now prints the file name and the date on a header line 
if the output is directed to the printer.  

This version sets the printer to skip over perforations if the 
output is directed to the printer.  This is a sore point with me 
because I'm constantly turning the printer off and losing the set
up codes that have been sent to the printer.  If you don't like 
this change, you can defeat it easily.  At approximately address 
$0000A2 of the .PRG there is a constant, $AAAAAAAA.  Change any 
one of these characters and the printer will not be changed unless 
you specifically permitted a change by your answer to the question 
regarding changing the printer pitch.  The location above is near 
the beginning of the program so it's easy to find and change it 
with a sector editor. 

Th program has a kinder and gentler exit when output is directed 
to a file.  A message is shown reassuring you that all is well in 
the world. (If it _is_ well, of course.)                    

The program sets up the default path to the current drive and 
folder before showing the file selector box asking for an input 
file.