950221

*IMPORTANT GENERAL INFORMATION*

1. Local variables are not necessarily initialized to zero, even if they
   are saved.

2. g77 currently is implemented as a replacement for the f2c+gcc
   combination, and its implementation is designed so it can, in
   most cases, generate object files that are link-compatible with
   those generated by f2c+gcc using the identical combination (which
   includes a similar/identical copy of f2c.h).  Therefore, the
   g77-gcc C-Fortran interface ought to work in a way that is
   consistent with f2c.  For instance, a Fortran string subroutine
   argument will become two arguments on the C side: a char* and an int
   length.  Much of this compatibility results from the fact that
   g77 uses the same run-time library, libf2c, used by f2c+gcc.

   However, it is expected that a future version of g77 will not
   by default generate object files compatible with f2c+gcc and not
   use libf2c.  If you expect to depend on this compatibility in the
   long term, use the options "-ff2c -ff2c-library" when compiling
   all of the applicable code (which should at the very least trigger
   compiler warning messages, if not enable f2c compatibility compilation,
   in future versions of g77).

3. Due to #2 above, object files compiled by g77 are not guaranteed to work
   well with objects compiled by the native compiler.  Libraries compiled
   with the native compiler will probably have to be recompiled with
   g77 to be used with g77.  There are two reasons for this: (1) there
   may be subtle type mismatches which cause subroutine arguments
   and function return values to get corrupted. (2) native compilers
   use libraries of private I/O routines which will not be available
   at link time unless you have the native compiler - and you would
   have to explicitly ask for them.  For instance, on the Sun you
   would have to add "-L/usr/lang/SCx.x -lF77 -lV77" to the link
   command.

*PORTING INFORMATION*

During the private alpha test phase, which lasted about 2.5 years,
g77 was tested by a small number of people worldwide on a fairly
wide variety of machines.

Currently, all of these configurations were self-hosted, i.e. it
is not likely that g77 can itself be cross-compiled or that it can
be configured as a cross-compiler.  There is only one known bug
(a design bug to be fixed in 0.6) that prevents configuration of
g77 as a cross-compiler, though there are assumptions made during
configuration that probably make doing non-self-hosting builds
a hassle, requiring manual intervention.

*CHANGES DURING 0.5.x*

In 0.5.9:

-  Carriage returns ('\r') in source lines are ignored.  This is somewhat
   different from f2c, which seems to treat them as spaces outside
   character/hollerith constants, and encodes them as '\r' inside such
   constants.

-  A source line with a TAB character anywhere in it is treated as
   entirely significant -- however long it is -- instead of ending
   in column 72 (for fixed-form source) or 132 (for free-form source).
   This also is different from f2c, which encodes tabs as '\t' inside
   character and hollerith constants, but nevertheless seems to treat
   the column position as if it had been affected by any tab.

   NOTE: this default behavior probably will change for 0.6, when
   it will presumably be available via a command-line option.  The
   default as of 0.6 is expected to be a "pure visual" model, where
   tabs are immediately converted to spaces and otherwise have no
   effect, so the way a typical user sees source lines produces a
   consistent result no matter how the spacing in those source lines
   is actually implemented via tabs, spaces, and trailing tabs/spaces
   before newline.  Command-line options are likely to be added to
   specify whether all or just-tabbed lines are to be extended to
   132 or full input-line length, and perhaps even an option will be
   added to specify the truncated-line behavior to which Digital compilers
   default.

In 0.5.5:

-  A warning message now is issued when g77 sees code that provides
   initial values (e.g. via DATA) to an aggregate area (COMMON or
   EQUIVALENCE, or even a large enough array or CHARACTER variable)
   that is large enough to increase g77's compile time by roughly
   a factor of 10.  This size is currently quite small, since g77
   currently has a known bug (see f/BUGS) requiring too much memory
   and time to handle such cases.  See f/data.c macro
   FFEDATA_sizeTOO_BIG_INIT_ for the minimum size (in storage units,
   which can be bytes, words, or whatever, on a case-by-case basis).

In 0.5.4:

-  Entities in local EQUIVALENCE no longer are emitted for debug support
   when specifying -g, because this triggered the same bug found when
   trying to support emitting COMMON members.

In 0.5.3:

-  The "gcc" command driver no longer automatically links the Fortran
   run-time library (libf2c, or libF77 and libI77 on some systems).
   Since that library is required for just about any g77-produced code
   to link and run successfully, the "g77" command driver should be
   used instead (at least to link the executable), or "-lf2c -lm" should
   be specified on the "gcc" command line.

-  The "g77" command driver recognizes "none" as a non-language, just as
   does the "gcc" command driver, as per documentation.  Previously, "g77"
   treated the option "-xnone" as it would any other "-xlanguage" option.
   This probably has no actual effect on the behavior of the command.

-  The "g77" command driver now recognizes both the "-xlanguage" and
   "-x language" forms of the -x option.

-  The "g77" command driver now handles much larger command lines --
   specifically, lines containing lots of .f or .F source file names --
   in the sense that it passes smaller command lines on to the gcc
   driver

-  g77 has a new, more consistent way to map Fortran types to their sizes.
   These rules are based on the configuration that is in force for the
   version of gcc built in the same release as g77:

     REAL: same size as whatever gcc calls a "float"
     DOUBLE PRECISION: same size as whatever floating-point type gcc provides
       that is twice the size of a "float" (usually a "double")
     INTEGER: a gcc integral type that is the same storage size as "float"
     LOGICAL: same size as INTEGER
     COMPLEX: two REALs
     DOUBLE COMPLEX: two DOUBLE PRECISIONs

     numeric-type*N (any type other than CHARACTER, such as INTEGER*2):
       is N times the size of whatever gcc calls a "char"

     numeric-type(KIND=N): N=1 for REAL, INTEGER, LOGICAL, COMPLEX;
       N=2 for DOUBLE PRECISION, DOUBLE COMPLEX [this is proposed for now;
       it might change in the future]

   Some of the above might seem unexpected, but is based on the requirements
   of the Fortran standards (77 and 90).  g77 is going to provide a
   consistent interpretation across all machines by following the above
   rules, rather than conforming to the expectations of the users of
   particular machines when they reflect inconsistent type-sizing rules.
   This consistency also should improve the interoperability and portability
   of applications combining Fortran and C-family code.

   For now, g77 does not support numeric types other than the ones listed
   above.  So, on a typical 32-bit machine, only INTEGER*4, REAL*4,
   LOGICAL*4, COMPLEX*8, etc., will work.  When g77 does support other
   types, they will be derived from gcc types such as "char", "short",
   "int", "long", "long long", "long double", and so on.  That is, whatever
   types gcc already supports, g77 will someday support.  The rules for
   the "numeric-type*N" notation will be applied to the new types, and
   new values for "numeric-type(KIND=N)" will be assigned on a clear,
   consistent basis, which we will invent when the time is right.

   Note that g77 strictly assigns types to all constants not documented
   as "typeless" (the typeless constants include things like "Z'1'").
   Context is never a determining factor for the type, and hence the
   interpretation, of a typed constant.  Examples: "1" is always type
   INTEGER, "3.141592653545256234" is always type REAL (even if the
   additional precision specified is lost, and even when used in a
   DOUBLE PRECISION context), "1E0" is always type REAL, and "1D0" is
   always type DOUBLE PRECISION.

   Many other Fortran compilers attempt to assign types to typed constants
   based on their context.  This results in hard-to-find bugs, nonportable
   code, and is not in the spirit (though it strictly follows the letter)
   of the 77 and 90 standards.  g77 will not support these dangerous
   semantics, but might offer, in a future release, explicit constructs
   by which a wider variety of typeless constants may be specified.

-  g77 now, on most machines, puts more variables and arrays on the stack
   where possible, and can be configured (by changing FFECOM_sizeMAXSTACKITEM
   in com.c) to force smaller-sized entities into static storage (saving
   on stack space) or permit larger-sized entities to be put on the
   stack (which can improve run-time performance).

-  Entities in EQUIVALENCE but not in COMMON now are emitted via -g so
   they can be easily debugged.  COMMON blocks themselves still are emitted,
   but their members are not emitted due to what appears to be a back-end
   bug in at least one output module for a debugging format.  (THIS IS
   REVERTED IN 0.5.4.)

-  All debuggable entities in a program unit, not just the referenced ones,
   are output when -g is specified.

-  g77 build will crash if an attempt is made to build it as a cross-compiler
   for a target when g77 cannot reliably determine the bit pattern of
   floating-point constants for the target.  Planned improvements for g77-0.6
   will give it the capabilities it needs to not have to crash the build
   but rather generate correct code for the target.  (Currently, g77
   would generate bad code under such circumstances if it didn't crash
   during the build, e.g. when compiling a source file that does
   something like EQUIVALENCE (I,R) and DATA R/3.1415926535/.)

In 0.5.2:

-  Dollar signs ('$') allowed in identifiers (other than as the first
   character) when the command-line option -fdollar-ok is specified

*CHANGES DURING 0.4.x*

In 0.4.14:

-  Default options are now -fno-f90, -ff90-intrinsics-delete,
   -ff2c-intrinsics-enable, so g77 now, by default, behaves much
   more like a traditional Unix f77 compiler

-  '_' now valid after first character of a symbol name even for
   -ff90

-  '_' as first character of symbol name (valid if -fno-f90) is
   treated as if IMPLICIT REAL(_) were present -- this makes g77
   compatible with f2c, though f2c does not allow IMPLICIT specification
   for '_' (except via IMPLICIT NONE) unlike g77, which treats
   '_' just as any other first character

In 0.4.12:

-  Symbol names can no longer contain the '$' character at all --
   previously, they could contain '$' as any character except the
   first character (THIS IS CHANGED IN 0.5.2)

-  Symbol names can contain the '_' only if -fno-f90, else they
   cannot contain '_' -- previously, they could contain '_' as
   any character except the first character, independent of -ff90
   (THIS IS CHANGED IN 0.4.14)

*CHANGES SINCE 0.3.12*

Among the user-visible changes in 0.4:

-  g77 crashes immediately in ffecom_init_0 if the size/alignment info
   the front end has for the user-visible types (INTEGER, REAL,
   CHARACTER, and so on) disagrees with what the back end uses -- the
   g77 installer must fix this by patching target.h or the appropriate
   file(s) in the config/ directory (and please email the patches,
   along with your config.status file, to the maintainers).  (THIS IS
   CHANGED IN 0.5.x.)

-  Handling of floating-point constants has been radically changed for
   systems where gcc emulates floating-point computations during
   compilation (systems where real.h #define's REAL_ARITHMETIC) -- this
   not only fixes some bugs involving mixed-type EQUIVALENCE and
   COMMON areas with initial floating-point values, but it changes
   the values produced by some cases such as where single-precision
   constants (using the "E" exponent letter, if any) are used in a
   double-precision context such that they no longer are interpreted
   as if they were specified as double-precision constants (i.e.
   precision is now apparently lost in these cases; use the "D" exponent
   letter in these cases to force the constants to be interpreted as
   double-precision, as you generally should anyplace a floating-point
   constant is used in a double-precision context).

-  Some options like -w and -Werror now work.

-  gcc now refuses to continue compiling when errors are detected in
   a .f file -- in other words, the f771 program gcc invokes to
   compile the Fortran source file into assembler output now should
   return an indication that errors were detected, which should prevent
   gcc from trying to assemble (and then maybe link) the assembler output
   into an object/executable file.

-  New: -fxxx-intrinsics-hide, a way to "hide" intrinsics that aren't normally
   used and whose names should normally be available as names of external
   procedures -- like -fxxx-intrinsics-delete, but allows INTRINSIC FOO
   as a way of saying "I really want the FOO intrinsic available in this
   program unit".

-  Some convenient new options to specify common combinations of source-
   file casing, such as -fcase-upper and -fcase-lower.

-  Handling of implied-DO control variables in DATA statements has been
   redone so some useful (and valid) constructs now work, and so some
   useless and weird constructs no longer are accepted (and are made
   invalid by the Fortran 90 standard, even though they were valid
   according to the FORTRAN 77 standard) -- note that it is very
   unlikely that any existing Fortran code uses the constructs that
   g77 no longer supports and F90 makes invalid.

-  Error reporting is fixed for source files using INCLUDE more than
   once -- the proper line numbers are given now.

-  Passing a hollerith constant as an actual argument to an external
   procedure now works (with no diagnostic when -fugly is specified),
   though the meaning of this might not be what is expected by users
   of various other Fortran systems -- I copied what the DEC VAX/VMS
   FORTRAN documentation says that system does, which is basically to
   pass the hollerith string "3HFOO" as if it read "%VAL('FOO')";
   note that use of hollerith constants in such contexts is usually
   nonportable.

-  Passing a typeless constant as an actual argument to an external
   procedure now works (with no diagnostic when -fugly is specified) --
   it is converted to INTEGER and passed by reference; note that use of
   typeless constants in such contexts is usually nonportable.

*WHAT IS AND ISN'T SUPPORTED*

This release supports ANSI FORTRAN 77 with the following caveats:

-  No passing of an external procedure as an actual argument if the procedure's
   type is declared CHARACTER*(*) (because it isn't clear the standard
   really considers this standard-conforming, but it should be fairly easy
   to support if someone gets an RFI showing it is standard-conforming).

-  No passing of a dummy procedure as an actual argument if the procedure's
   type is declared CHARACTER*(*) (again, because it isn't clear the
   standard considers this conformant).

-  The DO variable for an implied-DO construct in a DATA statement may
   not be used as the DO variable for an outer implied-DO construct (this
   is also disallowed by Fortran 90, as it offers no additional capabilities).
   Note that it is very unlikely that any existing Fortran code
   tries to use this unsupported construct.

-  An array element initializer in an implied-DO construct in a DATA
   statement must contain at least one reference to the DO variables of
   each outer implied-DO construct (this is also required by Fortran 90,
   as FORTRAN 77's more permissive requirements offer no additional
   capabilities).  However, g77 doesn't necessarily diagnose all cases
   where this requirement is not met.  Note that in any case it is
   very unlikely that any existing Fortran code tries to use this
   unsupported construct.

This release supports ANSI FORTRAN 77 plus:

-  -g for local variables and external names; COMMON variables, local
   EQUIVALENCE variables, labels, and so on aren't support yet.

-  LOC(), if -fvxt-intrinsics-enable is in force.

-  %LOC, %VAL, %REF, and %DESCR -- where %DESCR currently means the same thing
   as passing the argument the normal way.

-  MIL-STD 1753 features (IAND, IOR, MVBITS, DO WHILE, END DO, etc).

-  NAMELIST.

-  Most f2c/f77 intrinsics (AND, OR, LSHIFT, RSHIFT, and so on).

-  DOUBLE COMPLEX and related intrinsics (standard and f2c varieties).

-  Various Fortran 90 features.

-  Various DEC VAX/VMS FORTRAN v4.0 features.

-  Source files that are uppercase-only (enforced), lowercase-only
   (enforced), caseless, and various other combinations as chosen via
   command-line options.

-  Arbitrary (limited only by available memory) number of continuation
   lines.

-  Dollar signs ('$') in identifiers (other than as the first character)
   when the command-line option -fdollar-ok is specified.

*BLOCK DATA AND LIBRARIES*

To ensure that BLOCK DATA program units are linked, especially a concern
when they are put into libraries, give each one a name (as in
BLOCK DATA FOO) and make sure there is an EXTERNAL FOO statement
in every program unit that uses any COMMON area initialized by the
corresponding BLOCK DATA.  g77 currently compiles a BLOCK DATA as
if it were a SUBROUTINE, that is, it generates an actual procedure
having the appropriate name.  The procedure does nothing but return
immediately if it happens to be called.  For EXTERNAL FOO, where FOO
is not otherwise referenced in the same program unit, g77 assumes
it is a BLOCK DATA and generates a reference to it so the linker will
make sure it is present.  (Specifically, g77 outputs in the data
section a static pointer to the external name FOO.)

The implementation g77 currently uses to make this work is
one of the few things not compatible with f2c as currently
shipped.  f2c currently does nothing with EXTERNAL FOO except
issue a warning that FOO is not otherwise referenced, and for
BLOCK DATA FOO, f2c doesn't generate a dummy procedure with the
name FOO.  The upshot is that you shouldn't mix f2c and g77 in
this particular case.  If you use f2c to compile BLOCK DATA FOO,
then any g77-compiled program unit that says EXTERNAL FOO will
result in an unresolved reference when linked.  If you do the
opposite, then FOO might not be linked in under various
circumstances (such as when FOO is in a library, or you're
using a "clever" linker).

The changes you make to your code to make g77 handle this
situation, however, appear to be a widely portable way to handle
it.  That is, many systems permit it (as they should, since the
FORTRAN 77 standard permits EXTERNAL FOO when FOO is a BLOCK DATA
program unit), and of the ones that might not link BLOCK DATA FOO
under some circumstances, most of them appear to do so once
EXTERNAL FOO is present in the appropriate program units.

*FORTRAN 90*

The -ff90 and -fno-f90 command-line options control whether certain
Fortran 90 constructs are recognized.  (Other Fortran 90 constructs
might or might not be recognized depending on other options such as
-fvxt-not-f90, -ff90-intrinsics-enable, and the current level of support
for Fortran 90.)

When -ff90 is specified, the following constructs are accepted:

  -  Zero-length CHARACTER entities (not supported by run-time code,
     so diagnostics are produced for g77 nevertheless).
  -  Zero-size array dimensions (as in INTEGER I(10,20,4:2)) (not supported
     by run-time code, so diagnostics are produced for g77 nevertheless).
  -  DOUBLE COMPLEX (explicit or implicit) even when -fpedantic specified.
  -  Substrings of constants (as in "'hello'(3:5)") even when -fpedantic
     specified.
  -  DATA statements allowed to precede executable statements even when
     -fpedantic specified (note that this is not the same as whether
     "DATA I/1/" is permitted before other specifications for I, such as
     "INTEGER I" -- it does allow, however, "DATA I/1/" before "INTEGER J").
  -  Semicolon as statement separator even when -fpedantic specified
     (so "CALL FOO; CALL BAR" works).
  -  Underscores are not accepted as the first character of a
     symbol name, since F90 provides a different interpretation
     for certain cases where that would occur (though g77 does not
     yet support that interpretation).

*VAX FORTRAN VERSUS FORTRAN 90*

The -fvxt-not-f90 and -ff90-not-vxt command-line options control how
g77 interprets certain tokens and constructs that are have different
meanings in VAX FORTRAN and Fortran 90.

When -ff90-not-vxt is specified, the following interpretations are
made:

  -  "TYPE <symbol-name>" and "TYPE (<symbol-name>), <...>"
     statements recognized as the Fortran 90 variety, not I/O statements.
  -  Double-quote character (") delimits character constant just as does
     apostrophe ('), rather than beginning an octal constant of INTEGER type.
  -  Exclamation point in column 5 of fixed-form source file treated as
     a continuation character rather than the beginning of a comment (as it
     does in any other column).

*LIBRARY AND PROCEDURE-CALLING INTERFACE*

Currently, -ff2c and -ff2c-library are defaults and must be specified
for g77 to work properly.  In particular, how COMPLEX FUNCTIONs are
called is governed by these command-line options.  Also, diagnostics
are issued for some features unsupported by the f2c library, such as
NAMELIST in combination with source case preservation.

*SOURCE FORM*

The -ffree-form (aka -fno-fixed-form) and -ffixed-form (aka -fno-free-form)
command-line options govern how the source file is interpreted.  Fixed form
corresponds to classic ANSI FORTRAN 77 (plus popular extensions, such as
allowing tabs) and Fortran 90's fixed form.  Free form corresponds to
Fortran 90's free form (though possibly not entirely up-to-date, and
without complaining about some things that for which Fortran 90 requires
diagnostics, such as "R = 3 . 1").

*OPTIONS FOR POTENTIALLY BUGGY PROGRAMS*

The -fno-automatic command-line option tells g77 to assume, in essence, that
a SAVE statement is present in every program unit.  The effect of this
is that all variables and arrays are made static, i.e. not placed on
the stack or in heap storage.  This might cause a buggy program to appear
to work better -- if so, rather than relying on this command-line
option (and hoping all compilers provide the equivalent one), add SAVE
statements to some or all program unit sources, as appropriate.  The
default is -fautomatic, which tells g77 to try and put variables and
arrays on the stack where possible and reasonable.

*PEDANTIC COMPILATION*

The -fpedantic and -fno-pedantic command-line options control whether
certain non-standard constructs elicit diagnostics (usually in the form
of warnings) from g77.  The -fpedantic option is useful for finding
some extensions g77 accepts that other compilers might not accept.

With -ff90 in force along with -fpedantic, some constructs are
accepted that result in diagnostics when -fno-f90 and -fpedantic are
both in force.  See *FORTRAN 90* for information on those constructs.

The constructs for which g77 issues diagnostics when -fpedantic is
specified (and -fno-f90 is in force) are:

  -  "READ (<cilist>), <iolist>" -- the standard disallows the comma
     here, while allowing it in "READ <f>[, <iolist>]", but many
     compilers (including f2c) support the superfluous comma.
  -  DOUBLE COMPLEX, either explicitly (via explicit or IMPLICIT statement)
     or implicitly (as in "C*D", where C is COMPLEX and D is DOUBLE
     PRECISION, which is prohibited by the standard because it should
     produce a non-standard DOUBLE COMPLEX result).
  -  Automatic conversion of LOGICAL, REAL, DOUBLE PRECISION, and COMPLEX
     expressions to INTEGER in contexts such as: array-reference indexes;
     alternate-RETURN values; computed GOTO; FORMAT run-time expressions
     (not yet supported); dimension lists in specification statements;
     numbers for I/O statements (such as "READ (UNIT=3.2, <...>)"); sizes
     of CHARACTER entities in specification statements; kind types in
     specification entities (a Fortran 90 feature); initial, terminal,
     and incrementation parameters for implied-DO constructs in DATA
     statements.
  -  Automatic conversion of LOGICAL expressions to INTEGER in context
     such as: arithmetic IF (where COMPLEX expressions are completely
     disallowed).
  -  Substring operators applied to character constants and named
     constants (such as "PRINT *,'hello'(3:5)", which would print "llo").
  -  Null argument passed to statement function (as in "PRINT *,FOO(,3)").
  -  Differences between program units regarding whether a given COMMON
     area is SAVEd (for targets where program units in a single source
     file are "glued" together as they typically are for UNIX development
     environments).
  -  Differences between named-COMMON-block sizes between program units.
  -  Specification statements following first DATA statement (normally
     "DATA I/1/" may be followed by "INTEGER J", though not "INTEGER I",
     but -fpedantic complains about both cases).
  -  Semicolon as statement separator (as in "CALL FOO; CALL BAR").
  -  Comma before list of I/O items in WRITE, ENCODE, DECODE, REWRITE
     statements (kind of strange, since ENCODE/DECODE/REWRITE should yield
     diagnostics with -fpedantic???), as with READ (as explained above).

And these constructs actually are _enabled_ via -fpedantic, because they
are considered too dangerous to allow under normal circumstances even
though they are permitted by the standard:

  -  DO loops with REAL or DOUBLE PRECISION DO variables (including
     implied-DO loops in I/O and DATA statements), since the implementation
     required by the standard, combined with the vagaries of floating-point
     arithmetic on most machines, will likely result in terminating
     conditions not meeting the programmer's expectations (with regard
     to the terminal value for the loop).

*UGLY FEATURES*

The -fugly and -fno-ugly command-line options determine whether certain
features supported by VAX FORTRAN and other such compilers, but considered
too ugly to be in code that can be changed to use safer and/or more
portable constructs, are accepted.

The constructs enabled via -fugly include:

  -  Automatic conversion between INTEGER and LOGICAL as dictated by
     context (typically implies nonportable dependencies on how a
     particular implementation encodes .TRUE. and .FALSE.).
  -  Use of typeless and hollerith constants in non-standard places
     (the "standard" here being the appendix in ANSI FORTRAN 77 and
     the descriptions in MIL-STD 1753).
  -  Use of LOGICAL variable in ASSIGN and assigned-GOTO statements.
  -  Single trailing comma meaning "pass extra trailing null argument" in
     list of actual arguments to procedure other than statement function
     (e.g. "CALL FOO(,)" meaning "pass two null arguments" rather than
     "pass one null argument").
  -  DO loops with REAL or DOUBLE PRECISION DO variables (including
     implied-DO loops in I/O and DATA statements).

*CASE SENSITIVITY IN SOURCE CODE*

There are 66 useful settings that affect case sensitivity, plus 10
settings that are nearly useless, with the remaining 116 settings
being either redundant or useless.

None of these settings have any effect on the contents of comments
(the text after a "c" or "C" in Column 1, for example) or of character
or Hollerith constants.  Note that things like the "E" in the statement
"CALL FOO(3.2E10)" and the "TO" in "ASSIGN 10 TO LAB" are considered
built-in keywords.

Low-level switches are identified in this discussion thusly:

A: Source Case Conversion:
   0: Preserve (see Note 1)
   1: Convert to Upper Case
   2: Convert to Lower Case

B: Built-in Keyword Matching:
   0: Match Any Case (per-character basis)
   1: Match Upper Case Only
   2: Match Lower Case Only
   3: Match InitialCaps Only (see tables for spellings)

C: Built-in Intrinsic Matching:
   0: Match Any Case (per-character basis)
   1: Match Upper Case Only
   2: Match Lower Case Only
   3: Match InitialCaps Only (see tables for spellings)

D: User-defined Symbol Possibilities (warnings only)
   0: Allow Any Case (per-character basis)
   1: Allow Upper Case Only
   2: Allow Lower Case Only
   3: Allow InitialCaps Only (see Note 2)

Note 1: g77 will eventually support NAMELIST in a manner that is
coordinate with these source switches, in that input will be
expected to meet the same requirements as source code in terms
of matching symbol names and keywords (for the exponent letters).
Currently, however, NAMELIST is supported via the f2c library,
which uppercases NAMELIST input and symbol names for matching.
This means not only that NAMELIST output currently shows symbol
(and keyword) names in uppercase even if lower-case source
conversion (option A2) is selected, but that NAMELIST cannot be
adequately supported when source case preservation (option A0)
is selected.  If A0 is selected, a warning message will be
output for each NAMELIST statement to this effect.  The behavior
of the program is undefined at run time if two or more symbol names
appear in a given NAMELIST such that the names are identical
when converted to upper case (e.g. "NAMELIST /X/ VAR, Var, var").
For complete and total elegance, perhaps there should be a warning
when option A2 is selected, since the output of NAMELIST is currently
in uppercase but will someday be lowercase (when a g77lib is written),
but that seems to be overkill for a product in alpha (or even beta)
test.

Note 2: Rules for InitialCaps names are:
   -  Must be a single uppercase letter OR
   -  Must start with an uppercase letter and contain at least one
      lowercase letter
So A, Ab, ABc, AbC, and Abc are valid InitialCaps names, but AB, A2, and
ABC are not.  Note that most, but not all, built-in names meet these
requirements -- the exceptions are some of the two-letter FORMAT
specifiers, such as BN and BZ.

Here are the names of the corresponding command-line options for
the stand-alone front end (ffe):

A0: -fsource-case-preserve
A1: -fsource-case-upper
A2: -fsource-case-lower

B0: -fmatch-case-any
B1: -fmatch-case-upper
B2: -fmatch-case-lower
B3: -fmatch-case-initcap

C0: -fintrin-case-any
C1: -fintrin-case-upper
C2: -fintrin-case-lower
C3: -fintrin-case-initcap

D0: -fsymbol-case-any
D1: -fsymbol-case-upper
D2: -fsymbol-case-lower
D3: -fsymbol-case-initcap


Useful combinations of the above settings, along with abbreviated
option names that set some of these combinations all at once:

 1: A0--  B0---  C0---  D0---    -fcase-preserve
 2: A0--  B0---  C0---  D-1--
 3: A0--  B0---  C0---  D--2-
 4: A0--  B0---  C0---  D---3
 5: A0--  B0---  C-1--  D0---
 6: A0--  B0---  C-1--  D-1--
 7: A0--  B0---  C-1--  D--2-
 8: A0--  B0---  C-1--  D---3
 9: A0--  B0---  C--2-  D0---
10: A0--  B0---  C--2-  D-1--
11: A0--  B0---  C--2-  D--2-
12: A0--  B0---  C--2-  D---3
13: A0--  B0---  C---3  D0---
14: A0--  B0---  C---3  D-1--
15: A0--  B0---  C---3  D--2-
16: A0--  B0---  C---3  D---3
17: A0--  B-1--  C0---  D0---
18: A0--  B-1--  C0---  D-1--
19: A0--  B-1--  C0---  D--2-
20: A0--  B-1--  C0---  D---3
21: A0--  B-1--  C-1--  D0---
22: A0--  B-1--  C-1--  D-1--    -fcase-strict-upper
23: A0--  B-1--  C-1--  D--2-
24: A0--  B-1--  C-1--  D---3
25: A0--  B-1--  C--2-  D0---
26: A0--  B-1--  C--2-  D-1--
27: A0--  B-1--  C--2-  D--2-
28: A0--  B-1--  C--2-  D---3
29: A0--  B-1--  C---3  D0---
30: A0--  B-1--  C---3  D-1--
31: A0--  B-1--  C---3  D--2-
32: A0--  B-1--  C---3  D---3
33: A0--  B--2-  C0---  D0---
34: A0--  B--2-  C0---  D-1--
35: A0--  B--2-  C0---  D--2-
36: A0--  B--2-  C0---  D---3
37: A0--  B--2-  C-1--  D0---
38: A0--  B--2-  C-1--  D-1--
39: A0--  B--2-  C-1--  D--2-
40: A0--  B--2-  C-1--  D---3
41: A0--  B--2-  C--2-  D0---
42: A0--  B--2-  C--2-  D-1--
43: A0--  B--2-  C--2-  D--2-    -fcase-strict-lower
44: A0--  B--2-  C--2-  D---3
45: A0--  B--2-  C---3  D0---
46: A0--  B--2-  C---3  D-1--
47: A0--  B--2-  C---3  D--2-
48: A0--  B--2-  C---3  D---3
49: A0--  B---3  C0---  D0---
50: A0--  B---3  C0---  D-1--
51: A0--  B---3  C0---  D--2-
52: A0--  B---3  C0---  D---3
53: A0--  B---3  C-1--  D0---
54: A0--  B---3  C-1--  D-1--
55: A0--  B---3  C-1--  D--2-
56: A0--  B---3  C-1--  D---3
57: A0--  B---3  C--2-  D0---
58: A0--  B---3  C--2-  D-1--
59: A0--  B---3  C--2-  D--2-
60: A0--  B---3  C--2-  D---3
61: A0--  B---3  C---3  D0---
62: A0--  B---3  C---3  D-1--
63: A0--  B---3  C---3  D--2-
64: A0--  B---3  C---3  D---3    -fcase-initcap
65: A-1-  B01--  C01--  D01--    -fcase-upper
66: A--2  B0-2-  C0-2-  D0-2-    -fcase-lower

Number 22 is the "strict" ANSI FORTRAN 77 model whereas all input
(except comments, character constants, and hollerith strings) must
be entered in uppercase.  Use -fcase-strict-upper to specify this
combination.

Number 43 is like Number 22 except all input must be lowercase.  Use
-fcase-strict-lower to specify this combination.

Number 65 is the "classic" ANSI FORTRAN 77 model as implemented on many
non-UNIX machines whereby all the source is translated to uppercase.
Use -fcase-upper to specify this combination.

Number 66 is the "canonical" UNIX model whereby all the source is
translated to lowercase.  Use -fcase-lower to specify this
combination.

There are a few nearly useless combinations:

67: A-1-  B01--  C01--  D--2-
68: A-1-  B01--  C01--  D---3
69: A-1-  B01--  C--23  D01--
70: A-1-  B01--  C--23  D--2-
71: A-1-  B01--  C--23  D---3
72: A--2  B01--  C0-2-  D-1--
73: A--2  B01--  C0-2-  D---3
74: A--2  B01--  C-1-3  D0-2-
75: A--2  B01--  C-1-3  D-1--
76: A--2  B01--  C-1-3  D---3

The above allow some programs to be compiled but with restrictions that
make most useful programs impossible: Numbers 67 and 72 warn about
_any_ user-defined symbol names (such as "SUBROUTINE FOO"); Numbers
68 and 73 warn about any user-defined symbol names longer than one
character that don't have at least one non-alphabetic character after
the first; Numbers 69 and 74 disallow any references to intrinsics; and
Numbers 70, 71, 75, and 76 are combinations of the restrictions in
67+69, 68+69, 72+74, and 73+74, respectively.

All redundant combinations are shown in the above tables anyplace
where more than one setting is shown for a low-level switch.  For
example, "B0-2-" means either setting 0 or 2 is valid for switch B.
The "proper" setting in such a case is the one that copies the setting
of switch A -- any other setting might slightly reduce the speed of
the compiler, though possibly to an unmeasurable extent.

All remaining combinations are useless in that they prevent successful
compilation of non-null source files (source files with something other
than comments).

*INTRINSIC GROUPS*

A given specific intrinsic belongs in one or more groups.  Each group
is deleted, disabled, hidden, or enabled by default or a command-line
option.  If a group is deleted, no intrinsics will be recognized as
belonging to that group; if it is disabled, intrinsics will be recognized
as belonging to the group but cannot be referenced (other than via
the INTRINSIC statement) through that group; if hidden, intrinsics
in that group are recognized and enabled (if implemented) only if
the first mention of the actual name of an intrinsic is in an INTRINSIC
statement; if enabled, intrinsics in that group are recognized and
enabled (if implemented).

The distinction between deleting and disabling a group is illustrated
by the following example.  Assume intrinsic FOO belongs only to group
FGR.  If group FGR is deleted, the following program unit will successfully
compile, because FOO() will be seen as a reference to an external
function named FOO:

      PRINT *, FOO()
      END

If group FGR is disabled, the above program unit will be compiled with
errors, either because the FOO intrinsic is improperly invoked or, if
properly invoked, it is not enabled.  To change the above program so it
references an external function FOO instead of the disabled FOO intrinsic,
add the following line to the top:

      EXTERNAL FOO

So, deleting a group tells g77 to pretend as though the intrinsics in
that group do not exist at all, whereas disabling it tells g77 to
recognize them as (disabled) intrinsics in intrinsic-like contexts.

Hiding a group is like enabling it, but the intrinsic must be first
named in an INTRINSIC statement to be considered a reference to the
intrinsic rather than to an external procedure.  This might be the
"safest" way to treat a new group of intrinsics when compiling old
code, because it allows the old code to be generally written as if
those new intrinsics never existed, but to be changed to use them
by inserting INTRINSIC statements in the appropriate places.  However,
it should be the goal of development to use EXTERNAL for all names
of external procedures that might be intrinsic names.

If an intrinsic is in more than one group, it is enabled if any of its
containing groups are enabled; if not so enabled, it is hidden if
any of its containing groups are hidden; if not so hidden, it is disabled
if any of its containing groups are disabled; if not so disabled, it is
deleted.  This extra complication is necessary because some intrinsics,
such as IBITS, belong to more than one group, and hence should be
enabled if any of the groups to which they belong are enabled, etc.

The groups are:

DCP -- DOUBLE COMPLEX intrinsics from the standards (F77, F90)
F2C -- Intrinsics supported by AT&T's f2c converter
F90 -- Fortran 90 intrinsics
MIL -- MIL-STD 1753 intrinsics
VXT -- VAX/VMS FORTRAN (as of V4) intrinsics

The command-line options are:

-fdcp-intrinsics-delete  -- Delete DCP intrinsics
-fdcp-intrinsics-hide    -- Hide DCP intrinsics
-fdcp-intrinsics-disable -- Disable DCP intrinsics
-fdcp-intrinsics-enable  -- Enable DCP intrinsics
-ff2c-intrinsics-delete  -- Delete F2C intrinsics
-ff2c-intrinsics-hide    -- Hide F2C intrinsics
-ff2c-intrinsics-disable -- Disable F2C intrinsics
-ff2c-intrinsics-enable  -- Enable F2C intrinsics
-ff90-intrinsics-delete  -- Delete F90 intrinsics
-ff90-intrinsics-hide    -- Hide F90 intrinsics
-ff90-intrinsics-disable -- Disable F90 intrinsics
-ff90-intrinsics-enable  -- Enable F90 intrinsics
-fmil-intrinsics-delete  -- Delete MIL intrinsics
-fmil-intrinsics-hide    -- Hide MIL intrinsics
-fmil-intrinsics-disable -- Disable MIL intrinsics
-fmil-intrinsics-enable  -- Enable MIL intrinsics
-fvxt-intrinsics-delete  -- Delete VXT intrinsics
-fvxt-intrinsics-hide    -- Hide VXT intrinsics
-fvxt-intrinsics-disable -- Disable VXT intrinsics
-fvxt-intrinsics-enable  -- Enable VXT intrinsics

*SUMMARY OF OVERLY CONVENIENT COMMAND-LINE OPTIONS*

These options should only be used as a quick-and-dirty way to determine
how well your program will run under different compilation models
without having to change the source.  Some are more problematic
than others, depending on how portable and maintainable you want the
program to be (and, of course, whether you are allowed to change it
at all is crucial).

You should not continue to use these command-line options to compile
a given program, but rather should make changes to the source code:

-fno-automatic
    Use SAVE statements in the appropriate places instead.
-fugly
    Fix the source code so that -fno-ugly (the default) will work.
-fxxx-intrinsics-hide
    Change the source code to use EXTERNAL for any external procedure
    that might be the name of an intrinsic.  It is easy to find these
    using -fxxx-intrinsics-disable.
