		 README file for ftnchek version 2.12

Author: Robert Moniot
	Fordham University
	New York, NY  10023  USA
	Telephone: (212) 636-6311
	E-mail:  moniot@fordham.edu

Date:	March 15, 2000

Ftnchek is written in C.  You must have a C compiler for the machine
on which you wish to build it.  The URL for ftnchek's home page is
http://www.dsm.fordham.edu/~ftnchek.  Source code and other
information is available there.

If the file you received is a UNIX compressed tar file, suffix .Z, you
should first unzip it using the UNIX ``uncompress'' command, and then
give it as input to ``tar'' to unpack the files.  For example, assuming
the file has been placed in the desired directory, and is named
ftnchek.tar.Z, you would give the two UNIX commands
	uncompress ftnchek.tar.Z
	tar -xf ftnchek.tar
If the suffix is .gz instead of .Z, use the program ``gunzip'' in
place of ``uncompress''.  The gunzip program is publicly available
from the GNU project.

The tar command creates a directory named ftnchek-2.12.0 containing the
files of the distribution.  These files are described briefly below.
You should change directory to this directory and follow the
installation instructions.


		  INSTALLING FTNCHEK
		  ------------------

See the file INSTALL for detailed instructions on how to install
ftnchek on your system.


		   NEW FEATURES
		   ------------

Here are the new features in version 2.12, aside from bug fixes:

	o  New format of warnings produced at end of each subprogram
	   (local warnings) and after all files have been processed
	   (global warnings).  The warnings now include line numbers
	   for the location in the source code where the problem
	   arises.  The change is most noticeable in -nonovice mode:
	   these warnings now have a format compatible with smart text
	   editors that can automatically jump to the point indicated
	   by a warning.  If you find the new format of the local
	   warnings too verbose, a format closer to the more compact
	   previous form can be specified using the new -brief flag.

	o New option -identifier-chars allows you to specify
	   non-alphanumeric characters to be permitted in identifier
	   names.

	o New sub-option of -usage setting: -usage=arg-unused
	   separately controls some warnings, formerly controlled by
	   -usage=var-unused, about unused dummy arguments.

	o New check for attempt to READ or ACCEPT a non-lvalue.

	o The source code has been re-organized into a larger number
	   of smaller files.  Some mixed signed/unsigned operations
	   have been cleaned up.

	o The VMS version can now run the test suite, using the
	   CHECK.COM script provided by Bob Wells.

	o The MS-DOS/Win version can now run the test suite, using
	  the CHECK.BAT script provided by Gunnar Duus.



			     SOURCE FILES
			     ------------

The minimum set of source files needed to compile ftnchek is:

Header files:
	config.h ftnchek.h intrins.h iokeywds.h keywords.h loccheck.h
	options.h pgsymtab.h plsymtab.h symtab.h tokdefs.h

C source:
	argcheck.c calltree.c comcheck.c exprtype.c forlex.c fortran.c
	fortran.y ftnchek.c intrins.c loccheck.c makedcls.c message.c
	options.c pgsymtab.c plsymtab.c prlocsym.c project.c symtab.c


An associated file, not needed to compile ftnchek, is the Yacc grammar:
	fortran.y
The file fortran.c is generated from fortran.y by yacc or bison.  The
file tokdefs.h is a copy of the y.tab.h file also generated from fortran.y.

For VMS, it is recommendend to obtain the file shell_mung.c.  This
file is not necessary to build ftnchek, but without it wildcards in
file names on the command line will not be expanded.  This file is no
longer bundled with ftnchek, but is obtainable at the ftnchek home
site and elsewhere.


		   AUXILIARY FILES
		   ---------------

This section describes the auxiliary and documentation files included
with the distribution.

The example program used in the documentation, the result of running
Ftnchek on it, and the example program, corrected:
	average.f average.out correct.f

NOTE: VAX/VMS users should rename "AVERAGE.F" to "AVERAGE.FOR".

DCL command files for building ftnchek on DEC VAX and Alpha under VMS:
	build.com build-vax.com cc.com link.com

DCL command file for testing ftnchek under VMS:
	check.com

An awk script which converts declarations files into include files,
and a file used to create a shell script (to be installed as dcl2inc):
	dcl2inc.awk dcl2inc.sh.in

Files used to create Makefile:
	configure configure.in Makefile.in

Specialized makefiles for specific systems:
	makefile.bcc32 for Borland C (MS-DOS/Windows)
	makefile.mpw for Macintosh Programmer's Workbench
	makefile.generic for any system having the "make" utility
	ftnchek2_12.dsp ftnchek2_12.dsw for Microsoft MSVC (MS-DOS/Windows)

There is a module definition file and a configure script that creates a
makefile for IBM PC under OS/2:
	ftnchek.def configure_os2.cmd
The file configure_os2.cmd mimics configure in an OS/2 environment.
Use it to create a Makefile from Makefile.in, substituting appropriate
values for options and command paths for your system.

The file makefile.generic is created from Makefile.in by the shell
script configure.generic.  It uses vanilla configuration options.  The
purpose of makefile.generic is to provide a starting point for editing
to suit a non-Unix system.

Documentation files:
	ftnchek.doc	ftnchek user's manual in flat text format.
	ftnchek.ps	PostScript version of the same.
	ftnchek.hlp	Source for a HELP library for VMS systems.
	ftnchek.man	The file from which these files are derived.
	html/*.html	Hyptertext versions of the user's manual.
	dcl2inc.doc	dcl2inc user's manual in flat text format.
	dcl2inc.ps	same in PostScript.
	man2ps		script for converting man pages to PostScript.
	project-doc.tex description of project-file format for people
			interested in developing applications that
			make use of the information these contain.
	macro-doc.txt   description of macro names used in ftnchek
			source, for those interested in serious
			customization or development of ftnchek. (Out-of-date.)
	FAQ		answers to frequently asked questions about ftnchek.

The Unix manual page, ftnchek.1, is generated from ftnchek.man during the
installation process.  The VMS help library, ftnchek.hlb, is generated
from ftnchek.hlp by the build.com script.

A list of changes made since the original release of this version:
	PATCHES

There is also a small file, project.magic, which can be added to your
system's magic file, so that the ``file'' program will recognize
project files for what they are.

The UNIX Makefile employs a private script, man2ps, for converting
manual pages to PostScript (linked to names me2ps, mm2ps, and ms2ps,
it will support the -me, -mm, and -ms formats as well).  The script
currently knows about GNU groff, Sun Solaris 2.x troff + dpost and
psroff; it will use any of these, with groff preferred.  For troff +
dpost, if you get errors like this

troff: Can't open /usr/lib/font/devpost/C.out; line 818, file <standard input>

you can repair them if you have appropriate privileges:

% cd /usr/lib/font/devpost
% ln CO C
% ln CO.name C.name
% ln CO.out C.out

These commands simply create links between a Courier font that Sun
named CO, and the one named C that is expected by ftnchek.man.  If
some troff expert knows a better way to handle this, please tell us.
Additional alternatives in the man2ps script to support ditroff and
other vendors' troff-to-PostScript solutions will also be welcome.



		     CUSTOMIZING
		     -----------

Ftnchek has many options that affect what features it supports, the
sizes of various internal tables, and so forth.  These options are
controlled by various macros.  The important ones are either set
automatically by the configure script, or are described above.  Users
who are interested in tinkering with these macro settings can read the
file macro-doc.txt, which describes many of the macros.  However, the
description in this file is out of date, and you should consult the
source code for the current status of these and other macros.
