[Patch,Fortran] Update gfortran.texi for mixed-language programming

[Craig Powers]

Tobias Burnus wrote:
> 
> PS: Please proof read. I did a couple of times, found
> several typos, but I think there are more language and
> maybe also content bugs hidden.

Also see my comments on Ralf's suggestions, which I concur with except 
where I explicitly disagreed.  I've tried to avoid duplicating his comments.

> @@ -787,9 +807,9 @@
>  @node Fortran 2003 status
>  @section Fortran 2003 status
>  
> -Although GNU Fortran focuses on implementing the Fortran 95
> -standard for the time being, a few Fortran 2003 features are currently
> -available.
> +GNU Fortran supports the several Fortran 2003 features; an incomplete
> +list can be found below.
> +The following, i

Did this get cut off?

> +In order to ensure that one uses exactly the same variable type and kind
> +in C and Fortran, one should use as kind parameter the named constants
> +defined in the @code{ISO_C_BINDING} intrinsic module. The module contains
> +additionally character named constants for character literals which are
> +available via escape sequences in C. The kind and character named constants
> +can be found in @ref{ISO_C_BINDING}.

s/contains additionally/also contains/

> +As there exists no direct Fortran equivalent, structs with bit field
> +and variable-length array members, and unions are not interoperable.

I think I would change this paragraph to:
As there exist no direct Fortran equivalents, neither unions nor structs 
with bit field or variable length array members are interoperable.

(Should there be a hyphen in 'variable length'?)

> +Variables can be made accessible from C using the C binding attribute,
> +optionally together with specifying a binding name. Those variables
> +have to be declared in the declaration part of a @code{MODULE} and
> +shall be of interoperable type and neither pointers nor allocatable.

I think I would change the second sentence here to,
...part of a @code{MODULE}, be of interoperable type, and be neither 
pointer nor allocatable.

(should 'pointer' and 'allocatable' also be @code?)

I also pondered making the last clause, 'and have neither the pointer 
nor the allocatable attribute.'

> +Here, @code{_MyProject_flags} is the case-sensitive name of the variable
> +as seen from C programs while @code{global_flag} is the case-insensitive
> +name as seen from Fortran. If no binding name is specified, as for
> +@var{tp}, the C binding name is the (lowercase) Fortran binding name.
> +If a binding name is specified, only a single variable may be after the
> +double colon. Note of warning: You can not use a global variable to
> +access @var{errno} of the C library as the C standard allows it to be
> +a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead.

s/can not/cannot/

> +@node Interoperable Subroutines and Functions
> +@subsection Interoperable Subroutines and Functions
> +
> +Subroutines and functions have to have the @code{BIND(C)} attribute to
> +be compatible with C. The dummy-argument declaration is relatively
> +streight forward. However, one needs to be careful because C uses by
> +default call-by-value while Fortran uses call-by-reference. Additionally,
> +strings and pointers are handled different. Note that only explicit
> +size and assumed-size arrays are supported but not assumed-shape or
> +allocatable arrays.

s/dummy-argument/dummy argument/ (unless it appears with the hyphen in 
the standard, which I don't think it does)

I would move 'by default' to after 'call-by-value'.  My instincts are 
opposed to calling Fortran's default 'call-by-reference' (probably 
because of numerous corrections in clf to anyone who calls the Fortran 
default that), but I can't think of a short way to state it more accurately.

I would prefer 'Furthermore' in place of additionally.

s/different/&ly/

> +As the example shows, one needs to take care oneself that the
> +string is NULL terminated. Additionally, the dummy argument
> +@var{string} of @code{print_C} is a length-one assumed-size
> +array; using @code{character(len=*)} is not allowed. The example
> +above uses @code{c_char_"Hello World"} to ensure the string
> +literal has the right type; typically the default character
> +kind and @code{c_char} are the same and thus @code{"Hello World"}
> +is equivalent. However, the standard does not guarantee this.

I would prefer 'ensure' in place of 'take care oneself'.

> +The technical report 29113 will presumably also include support for
> +@code{OPTIONAL}, assumed-rank and assumed-type variables. However, the TR
> +has neither been approved nor implemented in GNU Fortran; therefore
> +theses features are not yet available.

Assumed rank?

Add a comma after 'therefore'.

> +When you compile a @code{PROGRAM} with GNU Fortran, a function
> +with the name @code{main} (in the symbol table of the object file)
> +is generated, which initializes the libgfortran library and then
> +calls the actual program which has due to historic reasons the
> +name @code{MAIN__}. If you link GNU Fortran compiled procedures
> +to, e.g., a C or C++ program or to a Fortran program compiled by
> +a different compiler, the libgfortran library is not initialize
> +and thus a few intrinsic procedures do not work properly, e.g.
> +those for obtaining the command-line arguments.

Doesn't I/O fail too?

> +@table @asis
> +@item @emph{Description}:
> +@code{_gfortran_set_options} sets several flags related to the Fortran
> +standard to be used, whether backtracing or coredumping should be enabled
> +or whether range-checks should be performed.

I would use 'and' instead of 'or' here.

> +@item @var{option}[4] @tab If non zero, enable backtracing on run-time
> +errors. Default: off.
> +Note: Installs a signal handler and requires that command-line
> +initialization using @code{_gfortran_set_args}.

Cut out 'that', or add something after @code{_gfortran_set_args} to go 
with it.

> +@table @asis
> +@item @emph{Description}:
> +@code{_gfortran_set_max_subrecord_length} set the maximum length
> +for a subrecord. This option only makes sense for testing and
> +debugging of the unformatted I/O.

Cut out 'the' before 'unformatted'.