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

[Ralf Wildenhues]

Hello Tobias,

* Tobias Burnus wrote on Sun, May 31, 2009 at 11:39:01PM CEST:
> 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.

Style and language-proof only:

> 2009-05-31  Tobias Burnus  <burnus@net-b.de>
> 
> 	* gfortran.texi: Add mixed-language programming, mention
> 	varying string lengths, some clean up of introduction parts.
> 	* intrinsic.texi (instrinsic modules): Create @menu for
> 	subsections.
> 	(ISO_C_BINDING): Support ISOCBINDING_INT_FAST128_T.
> 	* libgfortran.h: Comment to rember to keep gfortran.texi
> 	in sync.
> 	* iso-c-binding.def: Support ISOCBINDING_INT_FAST128_T.

> --- gfortran.texi	(Revision 148016)
> +++ gfortran.texi	(Arbeitskopie)
> @@ -182,6 +182,7 @@
>  Part II: Language Reference
>  * Fortran 2003 and 2008 status::  Fortran 2003 and 2008 features supported by GNU Fortran.
>  * Compiler Characteristics::      KIND type parameters supported.
> +* Mixed-language programming::    Interoperability with C

I think it is common to uppercase like this in headings and node names:
  Mixed-Language Programming::     Interoperability with C


>  * Extensions::           Language extensions implemented by GNU Fortran.
>  * Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran.
>  * Intrinsic Modules::    Intrinsic modules supported by GNU Fortran.


> @@ -515,6 +514,10 @@
>  @section Standards
>  @cindex Standards
>  
> +@menu
> +* Varying length character strings::

Likewise.

> +@end menu
> +

> +@node Varying length character strings
> +@subsection Varying length character strings
> +@cindex Varying length character strings
> +@cindex Varying length strings
> +@cindex strings, varying length
> +
> +The Fortran 95 standard specifies in Part 2 (ISO/IEC 1539-2:2000)
> +varying length character strings. While GNU Fortran currently does not
> +support such strings directly, there exist two Fortran implementation

s/implementation/&s/

> +for them, which work with GNU Fortran. They can be found at
> +@uref{http://www.fortran.com/iso_varying_string.f95} and at
> +@uref{ftp://ftp.nag.co.uk/sc22wg5/ISO_VARYING_STRING/}.

Maybe throw in some @/ after single slashes in the URLs to allow
optional line wrapping?

> +@node Mixed-language programming
> +@chapter Mixed-language programming

see above

> +@cindex Interoperability
> +@cindex Mixed-language programming

> -@c ---------------------------------------------------------------------
> +@menu
> +* Interoperability with C::
> +* Non-Fortran main program::

see above

> +@end menu

> +@menu
> +* Intrinsic Types::
> +* Further Interoperability of Fortran with C::
> +* Derived Types and struct::
> +* Interoperable Global variables::

I'd upcase 'variables', too.

> +* Interoperable Subroutines and Functions::
> +@end menu

> +Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a
> +standardized way to generate procedure and derived-type
> +declarations and global variables which are interoperable with C
> +(ISO/IEC 9899:1999). The the bind(C) attribute has been added

s/The the/The/
@code{bind(C)}  ?

> +to inform the compiler that a symbol shall be interoperable with C;
> +additionally some constrains are added. Note, however, that not

s/additionally/also,/  to add both a comma and avoid duplicate use of
the "add" word.

> +all C features have a Fortran equivalent or vice versa. For instance,
> +neither C's signed integers nor C's functions with variable number
> +of arguments have an equivalent in Fortran.

s/have/possess/  ?

> +@node Intrinsic Types
> +@subsection Intrinsic Types
> +
> +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

@samp{kind}  ?

> +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}.

This paragraph sounds a bit confusing.

> +Derived types with the C binding attribute cannot have the sequence
> +attribute, type parameters, the extends attribute, type-bound procedures,
> +and every component must be of interoperable type and kind and may not

s/, and every/.  Every/

@samp or @code for all the attributes?

> +have the pointer or allocatable attribute. The name of the variables is

s/name/&s/  s/is/are/

> +irrelevant for the interoperability.

s/the//

> +As there exists no direct Fortran equivalent, structs with bit field

structures

> +and variable-length array members, and unions are not interoperable.

> +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

@emph ?

> +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.

> +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

straightforward

> +default call-by-value while Fortran uses call-by-reference. Additionally,

because by default, C uses

> +strings and pointers are handled different. Note that only explicit

differently

> +size and assumed-size arrays are supported but not assumed-shape or
> +allocatable arrays.
> +
> +To pass a variable by value, one uses the @code{VALUE} attribute.

s/one uses/use/

> +Strings are handled quite differently in C and Fortran. In C a string
> +is a NULL terminated arrays of characters while in Fortran each string

s/arrays/array/

> +has a length associated and is thus not terminated (by e.g. NULL).

s/associated/& with it/
s/NULL/@code{NUL}/  or  @code{\0}  or  zero?

> +to print "Hello World" from Fortran, one can call it using

``Hello World''

> +As the example shows, one needs to take care oneself that the
> +string is NULL terminated. Additionally, the dummy argument

see above
I'd write zero-terminated

> +The function @code{strncpy} copies maximally @var{n} characters from

s/maximally/at most/

> +string @var{s2} to @var{s1} and returns @var{s1}. In the following
> +example, we ignore the return value:

> +C pointers are represented in Fortran via the special derived type
> +@code{type(c_ptr)}, with private components. Thus one needs to
> +use intrinsic conversion procedures to convert from/to C pointers.

s,/, or ,

> +Assumed-shape and allocatable arrays are passed using an array descriptor
> +(dope vector). The internal structure of the array descriptor used
> +by gfortran is not yet documented and will change. There will also be

@command{gfortran}  ?

> +a Technical Report (TR 29113) which standardizes an interoperable
> +array descriptor. Until then, you can use the

the what?

> +@url{http://chasm-interop.sourceforge.net/} which provides an interface to
> +GNU Fortran's array descriptor.

> +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.

s/theses/these/

> +Even if you are doing mixed-language programming, it is very
> +likely that you do not need to know or use the information in this
> +section. Since it is about the internal structure of gfortran,

see above

> +it may also change in GCC minor releases.

> +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__}.

which uses the name @code{MAIN__}, for historic reasons.

> 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

s/initialize/&d/

> +and thus a few intrinsic procedures do not work properly, e.g.

e.g.,

> +those for obtaining the command-line arguments.
> +
> +Therefore, if your @code{PROGRAM} is not compiled with
> +GNU Fortran and the GNU Fortran compiled procedures require
> +intrinsics relying on the library initialization, you need to
> +initialize the library yourselve. Using the default options,

yourself

> +gfortran calls @code{_gfortran_set_args} and

see above

> +@code{_gfortran_set_options}. The initialization of the former
> +is needed if the called procedures access the command line
> +(and for backtracing); the latter sets some flags based on the
> +standard choosen or to enable backtracing. In typical programs,

chosen

> +it is not necessary to call any initialization function.

> +@node _gfortran_set_args
> +@subsection @code{_gfortran_set_args} --- Save command-line arguments
> +@fnindex _gfortran_set_args
> +@cindex libgfortran initialization, set_args

Maybe use @deffn here somewhere?

> +@table @asis
> +@item @emph{Description}:
> +@code{_gfortran_set_args} saves the command-line arguments; this
> +initialization is required if any of the command-line intrinsics
> +is called. Additionally, it shall be called if backtracing is
> +enabled (see @code{_gfortran_set_options}).

> +@node _gfortran_set_options
> +@subsection @code{_gfortran_set_options} --- Set library option flags
> +@fnindex _gfortran_set_options
> +@cindex libgfortran initialization, set_options
> +
> +@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

core dumps  ?

> +or whether range-checks should be performed. The syntax allows for

range checks

> +upward compatibility since the number of passed flags is specified; for
> +non-passed flags, the default value is used. More about the options
> +can be found in the compiler-option section of this manual. Please

Please use a suitable cross reference (@ref, @xref, or @pxref) here.

> +note that not all flags are actually used.

> +@item @var{option}[3] @tab If non zero, enable coredumping on run-time
> +errors. Default: off.

see above

> +@node _gfortran_set_convert
> +@subsection @code{_gfortran_set_convert} --- Set endian conversion
> +@fnindex _gfortran_set_convert
> +@cindex libgfortran initialization, set_convert
> +
> +@table @asis
> +@item @emph{Description}:
> +@code{_gfortran_set_convert} set the used the representation

s/used the/used/

> +of data for unformatted files.

> +@node _gfortran_set_record_marker
> +@subsection @code{_gfortran_set_record_marker} --- Set length of record markers
> +@fnindex _gfortran_set_record_marker
> +@cindex libgfortran initialization, set_record_marker
> +
> +@table @asis
> +@item @emph{Description}:
> +@code{_gfortran_set_record_marker} the length of record markers

set

> +for unformatted files.

> +@node _gfortran_set_max_subrecord_length
> +@subsection @code{_gfortran_set_max_subrecord_length} --- Set length of record markers

copy paste error?

> +@fnindex _gfortran_set_max_subrecord_length
> +@cindex libgfortran initialization, set_record_marker

likewise

Cheers,
Ralf