[Fortran/gfortran][NFC] Update README.md (#108)

* [Fortran/gfortran][NFC] Update README.md

Remove references to the "old" way of doing things which has now been removed.
Add text describing the correct handling of directives. Add notes describing
some other limitations that would be good to remove.

Author: tarunprabhu

Fortran/gfortran/README.md

@@ -16,7 +16,9 @@ behavior of the binary produced by the compiler.
 Currently, only the _execute_ tests are supported in `regression`. Both
 `compile` and `execute` tests have been enabled in `torture`.
 
-Of the supported tests, a number of tests have been disabled. There are four
+Of the supported tests, a number of tests have been disabled. These are listed 
+in the `DisabledFiles.cmake` files that can be found in the various
+subdirectories of `Fortran/gfortran`. There are four
 categories of such tests:
 
 - *Unsupported*: These are tests that use non-standard extensions/intrinsics
@@ -129,19 +131,13 @@ implemented at a steady pace. The relevant tests in this directory should be
 enabled. This would involve building the test suite with one of the
 `TEST_SUITE_FORTRAN_*` flags described above.
 
-_*NOTE*: We are currently in the process of migrating to the static test 
-configuration described below. During that time, the configuration files and 
-associated scripts will be present in the repository but will not be used. When
-the migration is completed, this note will be removed._
-
 The build system uses static test configuration files named `tests.cmake` to be 
 found in the various subdirectories of the test suite. These are generated by 
 `utils/update-test-config.py`. The configuration files are the result of parsing
 the relevant DejaGNU annotations from the test files and are used by the various
-`CMakeLists.txt` files to set up the tests. This was a lot easier --- and 
-cleaner --- than parsing the annotations from `cmake`. These configuration files
-are not intended to be edited by hand - any edits will be overwritten when
-`update-test-config.py` is run.
+`CMakeLists.txt` files to set up the tests. These configuration files *must not*
+be edited by hand - any edits will be overwritten when `update-test-config.py`
+is run.
 
 The test configuration files consist of comment and non-comment lines. Comment
 lines start with a `#`. Each non-comment line represents a single test. The line
@@ -182,7 +178,9 @@ The test files in `regression` and `torture` *must not* be modified.
 If some of the items listed here are implemented, even in part, it should
 allows us to make better use of the test-suite.
 
-Several DejaGNU directives from the test files are currently ignored. In some
+Several DejaGNU directives from the test files are either ignored or only
+partially supported - i.e. only a subset of the options specified by the 
+directive are handled correctly. In some
 cases, those directives check that the language feature/optimization being
 exercised by the tests is actually handled correctly. By ignoring them, we are
 simply checking that `flang` (or the code produced by it) does not crash at
@@ -196,7 +194,7 @@ vectorized the code.
 It is not clear how much effort would be involved in correctly handling all the
 DejaGNU  directives.
 
-### `dg-error` directive ###
+#### `dg-error` directive ####
 
 The `dg-error` directive indicates that the test should fail to compile with a
 particular error. Obviously, this is a `gfortran`-specific error. `flang` may
@@ -210,7 +208,7 @@ are currently not implemented which results in a parse error (as opposed to the
 triggering of a "not-yet-implemented" assertion) which is also deemed an "error",
 thereby causing the test to pass.
 
-### `dg-warning` directive ###
+#### `dg-warning` directive ####
 
 Currently, the `dg-warning` directive is ignored. It ought to be possible to 
 treat in a manner similar to `dg-error`.
@@ -227,15 +225,27 @@ the file for the presence or absence of certain text. To capture the same
 behavior here, we would need to parse and translate the internal representation
 of GCC to an equivalent representation in LLVM IR.
 
-### `target` directive ###
+#### `target` directive ####
+
+The `target` directive is used to restrict tests to run on certain platforms
+and/or systems. The directive can be fairly complex. While in most cases the 
+directive simply consists of a triple specifying the platform on which the 
+test is enabled (or disabled), negations, logical `and` and `or` operations are 
+also permitted. The directives can appear in several places within 
+a test file. In addition to "top-level" directives which control whether or 
+not the entire test is enabled, a `target` directive can also be used to 
+conditionally emit or suppress an error or a warning on certain platforms. 
+Currently, there is limited support for these directives.
+
+- Logical operators on `target` directives are not supported. Directives 
+containing these operators are ignored entirely.
+
+- Only "top-level" directives are handled. `target` directives that appear 
+inside other directives such as `dg-error` or `dg-warning` are ignored. 
 
-_*NOTE*: With the static test configuration, the "top-level" `target` directives 
-are correctly handled. This section will be updated when the switch to the
-static test configurations is completed._
+#### Platform-specific disabling of tests ####
 
-The `target` directive is used to restrict tests to run on certain
-platforms/systems. Currently, the target directive is ignored entirely and the
-tests are always run. Currently, the gfortran tests are only enabled on *nix on
-x86-64 and aarch64 and ignoring the directive seems to be ok. As support for
-more systems and architectures are added, these directives will need to be
-handled correctly.
+Some tests fail on certain platforms but not on others. There is, currently, no
+way to disable these tests on a specific platform and these are disabled 
+everywhere. This is obviously not ideal since the extra coverage that the tests
+provide — even if on a limited set of platforms — is desirable.