[Bug fortran/47928] New: Gfortran intrinsics documentation paragraph ordering illogical

[Bug fortran/47928] New: Gfortran intrinsics documentation paragraph ordering illogical

[jb at gcc dot gnu.org]

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: unassigned@gcc.gnu.org
        ReportedBy: jb@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

[Bug fortran/47928] Gfortran intrinsics documentation paragraph ordering illogical

[dominiq at lps dot ens.fr]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=47928

Dominique d'Humieres <dominiq at lps dot ens.fr> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Priority|P3                          |P5
             Status|UNCONFIRMED                 |WAITING
   Last reconfirmed|                            |2014-01-07
     Ever confirmed|0                           |1
           Severity|normal                      |enhancement

--- Comment #1 from Dominique d'Humieres <dominiq at lps dot ens.fr> ---
Is it really worth the work? I am voting for no.