[PATCH 0/4] Fortran: Improve flow of intrinsics/library documentation [PR47928]

[Sandra Loosemore]

This series addresses PR 47928, a Fortran documentation issue filed back
in 2011.  Quoting from the issue:

"IMHO the order of paragraphs in the intrinsics chapter of the manual
is a bit illogical. For instance, the description comes before the
(strangely named) syntax paragraph, so when the description refers to
arguments it's a bit backwards. Similarly, is the version of the
standard where the intrinsic was introduced really the second most
important thing a user needs to know?"

I'd also thought that the ordering of the syntax/description
subheadings was confusing even before I found this issue, so I figured
this was a worthwhile documentation fix for me to tackle.

Only the first part involved manual editing; the other three patches
were purely mechanical: search-and-replace for part 2, Emacs keyboard
macros for parts 3 and 4 (it did take me a few attempts before I got
the latter right).  I did confirm that part 2 consisted of nothing but
whitespace changes and that parts 3 and 4 did not add or lose any
lines, only change their ordering.  I skimmed both the patches and the
final PDF output but I admit I didn't do a line-by-line review of the
entire patch series.

Both parts 3 and 4 are too big for the mailing list so I have attached
the whole set as a tarball instead of posting the pieces individually.
I'll hold off on pushing this patch series for a few days in case
anybody else does want to review it.

I can see that the documentation for the intrinsics and library
functions still needs a lot of cleanup in addition to this patch.
There are problems all over the place with inconsistent use of @var
markup to describe arguments, some instances of missing @code
markup on symbolic constants, poor formatting of the syntax/synopsis
in the library function documentation with line breaks in random
places, places where using a table for formatting would greatly
improve readability (e.g. _gfortran_set_options), etc.  But those are
separate from the issue addressed by this patch series and would need
to be addressed individually by hand.

-Sandra

Sandra Loosemore (4):
   Fortran: Tidy subheadings in Fortran documentation [PR47928]
   Fortran: Whitespace cleanup in documentation [PR47928]
   Fortran: Rename/move "Syntax" subheading in documentation [PR47928]
   Fortran: Move "Standard" subheading in documentation [PR47928]

  gcc/fortran/gfortran.texi  |  387 ++--
  gcc/fortran/intrinsic.texi | 3912 ++++++++++++++++++------------------
  2 files changed, 2147 insertions(+), 2152 deletions(-)

-- 
2.34.1
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pr47928.tgz
Type: application/x-compressed-tar
Size: 64577 bytes
Desc: not available
URL: <https://gcc.gnu.org/pipermail/fortran/attachments/20250225/052e243c/attachment-0001.bin>