public inbox for gcc-bugs@sourceware.org
help / color / mirror / Atom feed
* [Bug fortran/47928] New: Gfortran intrinsics documentation paragraph ordering illogical
@ 2011-02-28 18:39 jb at gcc dot gnu.org
2014-01-07 10:06 ` [Bug fortran/47928] " dominiq at lps dot ens.fr
0 siblings, 1 reply; 2+ messages in thread
From: jb at gcc dot gnu.org @ 2011-02-28 18:39 UTC (permalink / raw)
To: gcc-bugs
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
^ permalink raw reply [flat|nested] 2+ messages in thread
* [Bug fortran/47928] Gfortran intrinsics documentation paragraph ordering illogical
2011-02-28 18:39 [Bug fortran/47928] New: Gfortran intrinsics documentation paragraph ordering illogical jb at gcc dot gnu.org
@ 2014-01-07 10:06 ` dominiq at lps dot ens.fr
0 siblings, 0 replies; 2+ messages in thread
From: dominiq at lps dot ens.fr @ 2014-01-07 10:06 UTC (permalink / raw)
To: gcc-bugs
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.
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2014-01-07 10:06 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-02-28 18:39 [Bug fortran/47928] New: Gfortran intrinsics documentation paragraph ordering illogical jb at gcc dot gnu.org
2014-01-07 10:06 ` [Bug fortran/47928] " dominiq at lps dot ens.fr
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).