Re: [PATCH 11/11] gdb/doc: add section about fortran intrinsic functions and types

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed,  9 Mar 2022 11:39:22 +0100
> From: Nils-Christian Kempke via Gdb-patches <gdb-patches@sourceware.org>
> 
> The earlier version of this document had no sections about the
> available Fortran intrinsic functions or the Fortran builtin types.
> 
> I added two sections 'Fortran intrinsics' and 'Fortran types' to
> document the available Fortran language features.

Thanks, see some comments below, mostly about markup.

> +In Fortran the primitive data-types have an associated KIND type parameter,
> +written as 'TYPE*KINDPARAM', 'TYPE(KIND=KINDPARAM)', or in the
> +@value{GDBN}-only dialect 'TYPE_KINDPARAM'.  A concrete example would be
> +'REAL*4', 'REAL(KIND=4)', and 'REAL_4'.  The kind of a type can be retrieved by
> +using the intrinsic function KIND(), see @ref{Fortran Intrinsics}.

Some of the words you wrote in CAPS are actually meta-syntactic
variables, i.e. they aren't literal symbols, but rather stand for some
symbol.  Those should have the @var markup in Texinfo, and should be
spelled in lower-case letter.  In this case, I think the correct
markup will be this:

  In Fortran the primitive data-types have an associated @code{KIND}
  type parameter, written as @samp{@var{type}*@var{kindparam}},
  @samp{@var{type}(KIND=@var{kindparam})}, or in the @value{GDBN}-only
  dialect @samp{@var{type}_@var{kindparam}}.  A concrete example would
  be @samp{REAL*4}, @samp{REAL(KIND=4)}, and @samp{REAL_4}.  The kind
  of a type can be retrieved by using the intrinsic function @code{KIND},
  see @ref{Fortran Intrinsics}.

The above also fixes other issues with markup:

  . use @samp instead of manual quoting 'like this'
  . use @code{funcname} instead of funcname() to reference to a
    function (the latter looks like a call to the function with no
    arguments, which is not what you meant)

Please make such fixes elsewhere in the patch, there are other such
places.

> +Generally, the actual implementation of the KIND type parameter is compiler
> +specific.  In @value{GDBN} the kind parameter is implemented in accordance to
> +its use in the @sc{gnu} gfortran compiler.  Here, the kind parameter for a
> +given TYPE specifies its size in memory - a Fortran Integer*4 or
> +Integer(kind=4) would be an integer type occupying 4 bytes of
> memory.

Since "Integer*4" and Integer(kind=4) are literal pieces of code
(AFAIU), they should be in @code.

>                                                        An
> +exception to this rule is the COMPLEX type for which the kind of the type
> +does not specify its entire size, but the size of each of the two REAL's it is
> +composed of.  A COMPLEX*4 would thus consist of two REAL*4s and occupy 8 bytes
> +of memory.

Same here with the other data types.

> +note, that the @sc{gnu} default types can actually be changed by compiler flags
> +such as '-fdefault-integer-8' and '-fdefault-real-8'.

Instead of quoting command-line options by hand, please use the
@option markup.

> +Computes the absolut value of its operand A.  Currently not supported for
                ^^^^^^^
Typo: should be "absolute".  Also, I thing "argument" is better than
"operand" here.

"A" should be @var{a}, according to the same methodology as explained
above.

> +@item ALLOCATE(ARRAY)
> +Returns whether ARRAY is allocated or not.

@var{array}

> +@item ASSOCIATED(POINTER [, TARGET])
> +Returns the association status of the pointer POINTER or if TARGET is present
> +whether POINTER is associated with the target TARGET.

POINTER and TARGET should b @var{pointer} and @var{target}.

Same in other similar situations in your patch.

> +@item CMPLX(X [, Y [, KIND]])
> +Returns a complex number where X is converted to the real component.  If Y is
> +present it is converted to the imaginary component.  If Y is not present then
> +the imaginary component is set to 0.0 except if X itself is of COMPLEX type.
> +The optional parameter KIND specifies the kind of the return type
> +COMPLEX(KIND).

"0.0" should be in @code.