https://gcc.gnu.org/g:d8f5e1b0ba01ac65dbae98daa065109f18b87751
commit r15-7781-gd8f5e1b0ba01ac65dbae98daa065109f18b87751
Author: Sandra Loosemore <sloosem...@baylibre.com>
Date: Tue Feb 25 01:03:52 2025 +0000
Fortran: Tidy subheadings in Fortran documentation [PR47928]
This is a preparatory patch for the main documentation changes requested
in the issue.
gcc/fortran/ChangeLog
PR fortran/47928
* gfortran.texi: Consistently use "@emph{Notes}:" instead of
other spellings.
* intrinsic.texi: Likewise. Also fix an inconsistent capitalization
and remove a redundant "Standard" entry.
Diff:
---
gcc/fortran/gfortran.texi | 57 +++++++++++++++++++++++-----------------------
gcc/fortran/intrinsic.texi | 40 ++++++++++++++++----------------
2 files changed, 48 insertions(+), 49 deletions(-)
diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi
index ba3c3771c43c..b45ea484f457 100644
--- a/gcc/fortran/gfortran.texi
+++ b/gcc/fortran/gfortran.texi
@@ -4173,7 +4173,7 @@ The references make up a single linked list of reference
operations. The
the chain. Component and array refs can be arbitrarily mixed as long as they
comply to the Fortran standard.
-@emph{NOTES}
+@emph{Notes}:
The member @code{STATIC_ARRAY_TYPE} is used only when the @code{TYPE} is
@code{CAF_REF_STATIC_ARRAY}. The member gives the type of the data referenced.
Because no array descriptor is available for a descriptorless array and
@@ -4256,7 +4256,7 @@ arguments passed to the program or @code{NULL}.
command-line arguments or @code{NULL}.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
The function is modelled after the initialization function of the Message
Passing Interface (MPI) specification. Due to the way coarray registration
works, it might not be the first call to the library. If the main program is
@@ -4278,7 +4278,7 @@ been compiled with the @option{-fcoarray=lib} option.
@item @emph{Syntax}:
@code{void _gfortran_caf_finish (void)}
-@item @emph{NOTES}
+@item @emph{Notes}:
For non-Fortran programs, it is recommended to call the function at the end
of the main program. To ensure that the shutdown is also performed for
programs where this function is not explicitly invoked, for instance
@@ -4305,7 +4305,7 @@ This function returns the current image number, which is
a positive number.
in TS18508. Shall be a nonnegative number.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
If the Fortran intrinsic @code{this_image} is invoked without an argument,
which
is the only permitted form in Fortran 2008, GCC passes @code{0} as
first argument.
@@ -4334,7 +4334,7 @@ Shall be positive.
@item @var{failed} @tab shall be -1, 0, or 1
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
This function follows TS18508. If the num_image intrinsic has no arguments,
then the compiler passes @code{distance=0} and @code{failed=-1} to the
function.
@end table
@@ -4362,7 +4362,7 @@ has executed a @code{FAIL IMAGE} statement.
performed.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
This function follows TS18508. Because team-functionality is not yet
implemented a null pointer is passed for the @var{team} argument at the moment.
@end table
@@ -4390,7 +4390,7 @@ performed.
@item @var{image} @tab optional; the kind of the resulting integer array.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
This function follows TS18508. Because team-functionality is not yet
implemented a null pointer is passed for the @var{team} argument at the moment.
@end table
@@ -4418,7 +4418,7 @@ performed.
@item @var{image} @tab optional; the kind of the resulting integer array.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
This function follows TS18508. Because team-functionality is not yet
implemented a null pointer is passed for the @var{team} argument at the moment.
@end table
@@ -4478,7 +4478,7 @@ an error message; may be @code{NULL}
@item @var{errmsg_len} @tab the buffer size of errmsg.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
Nonallocatable coarrays have to be registered prior use from remote images.
In order to guarantee this, they have to be registered before the main
program. This can be achieved by creating constructor functions. That is what
@@ -4529,7 +4529,7 @@ to an error message; may be NULL
@item @var{errmsg_len} @tab the buffer size of errmsg.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
For nonallocatable coarrays this function is never called. If a cleanup is
required, it has to be handled via the finish, stop and error stop functions,
and via destructors.
@@ -4564,7 +4564,7 @@ size_t *opt_dst_charlen)}. GFortran ensures that
functions provided to
@code{_gfortran_caf_register_accessor} adhere to this interface.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
This function is required to have a nearly constant runtime complexity, because
it will be called to register multiple accessor in a sequence. GFortran
ensures
that before the first remote accesses commences
@@ -4594,7 +4594,7 @@ indexing operations.
@item @emph{Arguments}:
No arguments.
-@item @emph{NOTES}
+@item @emph{Notes}:
This function may be called multiple times with and without new hash-accessors-
pairs being added. The post-condition after each call has to be that hashes
can be looked up quickly and indexing on the lookup table of
hash-accessor-pairs
@@ -4634,7 +4634,7 @@ lookups.
The zero based index to access the accessor funtion in a lookup table.
On error, @code{-1} can be returned.
-@item @emph{NOTES}
+@item @emph{Notes}:
The function's complexity is expected to be significantly smaller than N,
where N is the number of all accessors registered. Although returning
@code{-1}
is valid, will this most likely crash the Fortran program when accessing the
@@ -4710,7 +4710,7 @@ error occurs, then an error message is printed and the
program is terminated.
to be part of. Unused at the moment.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
It is permitted to have @code{image_index} equal the current image; the memory
to get and the memory to store the data may (partially) overlap. The
implementation has to take care that it handles this case, e.g. using
@@ -4811,7 +4811,7 @@ error occurs, then an error message is printed and the
program is terminated.
to be part of. Unused at the moment.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
It is permitted to have @code{image_index} equal the current image; the memory
to send the data to and the memory to read for the data may (partially)
overlap.
The implementation has to take care that it handles this case, e.g. using
@@ -4915,7 +4915,7 @@ is to be part of. Unused at the moment.
is to be part of. Unused at the moment.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
It is permitted to have both @code{dst_image_index} and @code{src_image_index}
equal the current image; the memory to send the data to and the memory to read
for the data may (partially) overlap. The implementation has to take care that
@@ -4978,7 +4978,7 @@ source is not an array, than the precise type, e.g. of a
component in a
derived type, is not known, but provided here.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
It is permitted to have the same image index for both @var{src_image_index} and
@var{dst_image_index}; the memory of the send-to and the send-from might
(partially) overlap in that case. The implementation has to take care that it
@@ -5030,7 +5030,7 @@ an error message; may be NULL.
@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
This function is also called for critical blocks; for those, the array index
is always zero and the image index is one. Libraries are permitted to use
other
images for critical-block locking variables.
@@ -5064,7 +5064,7 @@ an error message; may be NULL.
@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
This function is also called for critical block; for those, the array index
is always zero and the image index is one. Libraries are permitted to use
other
images for critical-block locking variables.
@@ -5095,7 +5095,7 @@ an error message; may be NULL.
@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
This acts like an atomic add of one to the remote image's event variable.
The statement is an image-control statement but does not imply sync memory.
Still, all preceding push communications of this image to the specified
@@ -5132,7 +5132,7 @@ an error message; may be NULL.
@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
This function only operates on a local coarray. It acts like a loop checking
atomically the value of the event variable, breaking if the value is greater
or equal the requested number of counts. Before the function returns, the
@@ -5174,7 +5174,7 @@ the event variable.
@item @var{stat} @tab intent(out) Stores the STAT=; may be NULL.
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
The typical use is to check the local event variable to only call
@code{event_wait} when the data is available. However, a coindexed variable
is permitted; there is no ordering or synchronization implied. It acts like
@@ -5261,7 +5261,8 @@ an error message; may be NULL.
@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
@end multitable
-@item @emph{NOTE} A simple implementation could be
+@item @emph{Notes}:
+A simple implementation could be
@code{__asm__ __volatile__ ("":::"memory")} to prevent code movements.
@end table
@@ -5321,7 +5322,7 @@ current image.
@item @emph{Syntax}:
@code{void _gfortran_caf_fail_image ()}
-@item @emph{NOTES}
+@item @emph{Notes}:
This function follows TS18508.
@end table
@@ -5522,7 +5523,7 @@ an error message; may be NULL.
@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
all images except of the specified one become undefined; hence, the library may
make use of this.
@@ -5559,7 +5560,7 @@ an error message; may be NULL.
@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
all images except of the specified one become undefined; hence, the library may
make use of this.
@@ -5594,7 +5595,7 @@ an error message; may be NULL.
@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
all images except of the specified one become undefined; hence, the library may
make use of this.
@@ -5642,7 +5643,7 @@ an error message; may be NULL.
@item @var{errmsg_len} @tab intent(in) the buffer size of errmsg
@end multitable
-@item @emph{NOTES}
+@item @emph{Notes}:
If @var{result_image} is nonzero, the data in the array descriptor @var{a} on
all images except of the specified one become undefined; hence, the library may
make use of this.
diff --git a/gcc/fortran/intrinsic.texi b/gcc/fortran/intrinsic.texi
index 6117771f2873..21da3ff34fa1 100644
--- a/gcc/fortran/intrinsic.texi
+++ b/gcc/fortran/intrinsic.texi
@@ -576,7 +576,7 @@ program test_achar
end program test_achar
@end smallexample
-@item @emph{Note}:
+@item @emph{Notes}:
See @ref{ICHAR} for a discussion of converting between numerical values
and formatted string representations.
@@ -2623,7 +2623,7 @@ for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
The return value is a scalar of type @code{REAL}. It has the same
kind as @var{X}.
-@item @emph{Note}:
+@item @emph{Notes}:
The transformational function uses a recurrence algorithm which might,
for some values of @var{X}, lead to different results than calls to
the elemental function.
@@ -2783,7 +2783,7 @@ for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
The return value is a scalar of type @code{REAL}. It has the same
kind as @var{X}.
-@item @emph{Note}:
+@item @emph{Notes}:
The transformational function uses a recurrence algorithm which might,
for some values of @var{X}, lead to different results than calls to
the elemental function.
@@ -2835,7 +2835,7 @@ Elemental function
@item @emph{Return value}:
The return value is of type @code{LOGICAL} and of the default kind.
-@item @emph{Note}:
+@item @emph{Notes}:
For @code{UNSIGNED} arguments, this function is identical to the
@code{.GE.} and @code{>=} operators.
@@ -2875,7 +2875,7 @@ Elemental function
@item @emph{Return value}:
The return value is of type @code{LOGICAL} and of the default kind.
-@item @emph{Note}:
+@item @emph{Notes}:
For @code{UNSIGNED} arguments, this function is identical to the
@code{.GT.} and @code{>} operators.
@@ -2959,7 +2959,7 @@ Elemental function
@item @emph{Return value}:
The return value is of type @code{LOGICAL} and of the default kind.
-@item @emph{Note}:
+@item @emph{Notes}:
For @code{UNSIGNED} arguments, this function is identical to the
@code{.LE.} and @code{<=} operators.
@@ -2999,7 +2999,7 @@ Elemental function
@item @emph{Return value}:
The return value is of type @code{LOGICAL} and of the default kind.
-@item @emph{Note}:
+@item @emph{Notes}:
For @code{UNSIGNED} arguments, this function is identical to the
@code{.LT.} and @code{<} operators.
@@ -3480,7 +3480,7 @@ end program test_char
@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab
Fortran 77 and later
@end multitable
-@item @emph{Note}:
+@item @emph{Notes}:
See @ref{ICHAR} for a discussion of converting between numerical values
and formatted string representations.
@@ -3907,7 +3907,7 @@ contains
end program test
@end smallexample
-@item @emph{Note}:
+@item @emph{Notes}:
While the rules permit in principle an intrinsic function, none of the
intrinsics in the standard fulfill the criteria of having a specific
function, which takes two arguments of the same type and returning that
@@ -4658,7 +4658,7 @@ Transformational function
@item @var{DIM} @tab The type shall be @code{INTEGER}.
@end multitable
-@item @emph{Note}:
+@item @emph{Notes}:
@var{ARRAY} can also be @code{UNSIGNED}.
@item @emph{Return value}:
@@ -4736,7 +4736,7 @@ program test_ctime
end program test_ctime
@end smallexample
-@item @emph{See Also}:
+@item @emph{See also}:
@ref{DATE_AND_TIME}, @*
@ref{GMTIME}, @*
@ref{LTIME}, @*
@@ -5395,7 +5395,7 @@ Transformational function
@item @var{DIM} @tab The type shall be @code{INTEGER}.
@end multitable
-@item @emph{Note}:
+@item @emph{Notes}:
@var{ARRAY} can also be @code{UNSIGNED}.
@item @emph{Return value}:
@@ -5782,7 +5782,7 @@ end program test_exec
@end smallexample
-@item @emph{Note}:
+@item @emph{Notes}:
Because this intrinsic is implemented in terms of the @code{system}
function call, its behavior with respect to signaling is processor
@@ -6218,7 +6218,7 @@ expression indicating the kind parameter of the result.
@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
@end multitable
-@item @emph{Note}:
+@item @emph{Notes}:
@var{ARRAY} can also be @code{UNSIGNED}.
@item @emph{Return value}:
@@ -6308,7 +6308,7 @@ Subroutine
@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
@end multitable
-@item @emph{Note}:
+@item @emph{Notes}:
Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
statement that should be preferred over the @code{FLUSH} intrinsic.
@@ -7598,7 +7598,7 @@ program test_iachar
end program test_iachar
@end smallexample
-@item @emph{Note}:
+@item @emph{Notes}:
See @ref{ICHAR} for a discussion of converting between numerical values
and formatted string representations.
@@ -8067,7 +8067,7 @@ end program test_ichar
@item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)}
@tab Fortran 77 and later
@end multitable
-@item @emph{Note}:
+@item @emph{Notes}:
No intrinsic exists to convert between a numeric value and a formatted
character string representation -- for instance, given the
@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
@@ -9063,8 +9063,6 @@ See @code{kill(2)}.
This intrinsic is provided in both subroutine and function forms;
however, only one form can be used in any given program unit.
-@item @emph{Standard}:
-GNU extension
@item @emph{Standard}:
GNU extension
@@ -10866,7 +10864,7 @@ returned value has the same sign as A and a magnitude
less than the
magnitude of P. (As a GNU extension, kind is the largest kind of the actual
arguments.)
-@item @emph{Note}:
+@item @emph{Notes}:
@code{MOD} and @code{MODULO} yield identical results if their arguments
are @code{UNSIGNED}.
@@ -10951,7 +10949,7 @@ extension, kind is the largest kind of the actual
arguments.)
The returned value has the same sign as P and a magnitude less than
the magnitude of P.
-@item @emph{Note}:
+@item @emph{Notes}:
@code{MOD} and @code{MODULO} yield identical results if their arguments
are @code{UNSIGNED}.
