http://gcc.gnu.org/bugzilla/show_bug.cgi?id=47928
Summary: Gfortran intrinsics documentation paragraph ordering
illogical
Product: gcc
Version: unknown
Status: UNCONFIRMED
Severity: normal
Priority: P3
Component: fortran
AssignedTo: unassig...@gcc.gnu.org
ReportedBy: j...@gcc.gnu.org
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?
Looking at other documents (which are not 100% internally consistent, but
still), based on some googling and looking at man pages we have:
POSIX 2008: name, synopsis, description, return value, errors,
examples, application usage, rationale, future direction, see also,
changelog.
Linux manpages: name, synopsis, description, return value, (notes),
errors, files, conforming to, (notes), bugs, see also, (notes), (bugs)
FreeBSD manpages: name, library, synopsis, description, tuning,
environment, return values, debugging malloc problems, diagnostic
messages, errors, security considerations, notes, see also, standards,
history, authors, bugs
Fortran 2008: synopsis (title), description (short 1-line), class, arguments,
result characteristics (only functions), result value (only functions),
example.
Gfortran currently: title, description, standard, class, syntax,
arguments, example, specific names, see also
While F2008 is perhaps the one most relevant to gfortran, that description is
very terse and often lacks a description at all, so IMHO we shouldn't slavishly
follow that one either.
I'd suggest something like:
Title: name and a-few-words description. No change needed.
Synopsis: The current "Syntax" paragraph.
Description: Longer description.
Class.
Arguments.
Description, alternate placement? Comments?
Return value.
Example.
Notes
Standard
See also
