[Bug fortran/37605] New: Remarks on user manual for Gfortran

["arjen dot markus at wldelft dot nl" <gcc-bugzilla at gcc dot gnu dot org>]

Remarks on manual Gfortran
--------------------------
(Page numbers and such refer to the PDF-file available online
at 19 september 2008)

General remarks
---------------
1. Section on distributing programs is missing:
   What is needed if you have created a product to distribute it to
   customers? (Either with or without sources)
2. Section on floating-point issues is missing:
   How do the compile options influence the floating-point behaviour?
   What is the treatment of special values such as Inf and Nan?
   What happens with atan2(0,0)?
3. POSIX-type extensions in the language reference:
   No particular information is given how the various functions
   (SYMLNK for instance or STAT) work (or do not work) on a non-POSIX
   system like MS Windows.

Specific remarks
----------------

Missing words indicated as _words_
Superfluous words indicated as /words/

Page 1.
(bullet 2) because _it_ is easy to make ...

(bullet 3) The Fortran 90 _standard_ requires

Sentence: "When writing Fortran, it is easy to make big mistakes
That is not a very encouraging statement, it is also not inherent to
Fortran (but rather to programming in general) and it adds no
information. Just remove it.

Page 7.
-Wall:
I have seen at least one version of Gfortran that said (with
--help) "This option lacks documentation" or similar words. Version
"4.3.2-tdm-1 for MinGW" does not list it at all

Page 8.
-fall-intrinsics:
The explanation is not very clear, in my opinion: it accepts all intrinsic
procedures without regard to -std, but it is very useful with -std=f95?
The next sentence I had to read it two or three times.

Perhaps something like:
This option causes all intrinsic procedures (including the GNU-specific
extensions) to be accepted. Any user-defined procedures with the same
name are ignored.

-fd-lines-as-*
What is the default? (-fd-lines-as-comments, I suppose)

-fdefault-double-8 etc:
Does this have any influence on selected_real_kind() or kind(1.0), etc.?

Page 15.
-Wextra:
This flag does not appear in the documentation, other than under
-Wunused-parameter

Page 16.
are likely to /to/ trigger

Page 17.
-static-libgfortran:
When would you use this flag? Would it make distribution easier?

Page 20.
-founds-check:
_Note:_ In the future

Page 23.
3.5 GFORTRAN_TMPDIR
On Windows I have had severe problems with temporary files opened
from a C program (tmpfile()): Files were opened on the root directory
of a network disk - which was prohibited, of course.

How is that taken care of in Gfortran?

Page 29.
-fshort-enums should not be "hyphenated".

Page 31.
TYPESPEC(k):

Please replace the sentence explaining k by something like the
following, to stress that the _numerical_ value of k is platform-dependent:

"where k is the kind parameter suitable for the intended precision. As
kind parameters are implementation-dependent, use the kind(),
selected_int_kind() and selected_real_kind() functions to retrieve the
correct value, for instance:

REAL*8 x can be replaced by:

integer, parameter :: dbl = kind(1.0d0)
real(dbl)          :: x"

Page 38.
"to the existence of an important number of extensions:"
Shouldn't that be:
"to the existence of a number of important extensions"

Page 39.
(comment) manipulates -> manipulate

Page 41.
ABORT: produces a coredump even if -fno-dump-core is in effect?

ABS: COMPLEX(8) return type - shouldn't that be REAL(8)?

ACCESS: how is the executable flag determined on MS Windows?

ACOS: that is less than _or equal to_ one

ADJUSTL: the standard that introduced it is Fortran 90, but perhaps this
is too detailed.

ALLOCATED: if (allocated(x) .eqv. .false.) ...
This is an ugly style and actually a misuse of .eqv., use instead:
           if (.not. allocated(x)) ...

ASIN: see ACOS

ASSOCIATED: Is it still possible that association status of a pointer is
undefined? I thought Fortran 95 solved that monstrum?

If I understand it correctly, the return value of associated(p,a) is
always false if a is a zero-sized array?

BIT_SIZE: ... by the type of I. _The result bit_size() is independent of
the actual value of I._

BTEST: ... I is set. The counting of the bits starts at 0.

CHDIR: does it change the disk drive on Windows automatically? So that
    CALL CHDIR( "C:/" )
succeeds?

COSH: for real argument x, cosh(x) >= 1

COUNT: scaler -> scalar. The range formatting is wrong: 1/leqDIM/leqn

Note: scaler occurs more often, and the range formatting too

CSHIFT: range formatting wrong, "scaler"

DIGITS: significant _binary_ digits

DOT_PRODUCT: "scaler"

EOSHIFT: "scaler" (2x) and range formatting

EPSILON: replace by: EPSILON(X) returns the smallest number E of the
same kind as X such that 1+E is not equal to 1.

GET_COMMAND_ARGUMENT:
Is LENGTH independent of the buffer used (so that you can use it to
check that all of the argument was retrieved)?
retrival -> retrieval
positiv -> positive

GMTIME:
This is missing a reference to the standard routine DATE_AND_TIME
(I think it would be good to mention the standard routines for all
date and time related GNU-specific intrinsics).

IDATE:
"Does not return"? This text appears more often with subroutines, but is
only correct for ABORT and EXIT. As subroutines have no return values,
perhaps leave out that part?

LOG:
What is the imaginary part for complex arguments?

LOG_GAMMA:
Allows negative values like -0.5?

MAXLOC:
MAXLOC does _not_ return a scalar if the array is of rank 1:

This program fails to compile: Incompatible ranks 0 and 1 in assignment

! maxlocp.f90 --
!     Check the return value of maxloc for a one-dimensional array
!
program maxlocp
    integer             :: pos
    real, dimension(10) :: x

    call random_number( x )

    pos = maxloc(x)

    write(*,*) pos
end program maxlocp

MAXVAL:
Replace "...the result is the most negative number" by "... the result
is -HUGE(ARRAY)"

MINLOC: see MAXLOC

PRODUCT: formatting error - RESULT = ... ]) RESULT = ...

RANDOM_NUMBER:
Does each run of the program produce the _same_ or a different sequence?
(Perhaps a clue as to how to guarantee the same sequence is used?)

SELECTED_REAL_KIND:
return -> returns
"greater" is superfluous

SIGNAL:
There is no information on the interface for the signal handler. Does it
take any parameters?

STAT:
Function form missing

Page 169.
Vertical spacing between C_FUNLOC and C_LOC

Page 170.
(CHARACTER(KIND=C_CHAR) lacks a closing paren.


-- 
           Summary: Remarks on user manual for Gfortran
           Product: gcc
           Version: 4.4.0
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: fortran
        AssignedTo: unassigned at gcc dot gnu dot org
        ReportedBy: arjen dot markus at wldelft dot nl


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37605