Re: some g77 doc'toring

[Craig Burley <burley at gnu dot org>]

Thanks for doing this!  A couple of the changes look familiar -- perhaps
you sent them before, and I already put them in 0.5.24?  Anyway,
here are a few comments.

Generally it is considered "proper" to hyphenate adjective strings,
e.g. "floating-point unit" instead of "floating point unit".  I used
to resist that editorial advice mightily, but came to recognize that,
used consistently, it does avoid serious ambiguities often enough to
be worthwhile, and ends up making reading somewhat easier (though
extra hyphens, like slashes or whatever, can risk distracting
the reader, so it's a tradeoff).

>+@smallexample
>+      a = b + c
>+      d = a * e
>+@end smallexample

In the above example, and in other similar examples, I'm not sure
I see the reason to indent the text if all of the lines contain the
same indentation.  I used to be pedantic about always indenting,
e.g. Fortran, precisely the correct amount.  After writing several
manuals with this sort of format, though, I came to feel that
such examples usually need not highlight the 6-space indentation
as anywhere near as important as the text and, besides, the spaces
just aren't countable by readers who might actually need to be
reminded of the requirement!  Haven't changed my mind since, but
it's not a big deal.  At least with Info format, the cursor can
be used to count the spaces....

>+Typically improves performance on code using indexed @code{DO} loops by

"Indexed DO" is not a phrase I'm familiar with offhand -- I thought
the standard (F90, if not F77) called them "iterative DO" loops.
(This occurs at least one other time in the patch.)

>+Also, no loop discovery is done, so only loops written with @code{DO}

"Loop discovery" is likely to be a term that is unfamiliar to some
readers in this context.  Maybe quoting it is enough, to assure the
reader that he isn't expected to know its meaning in the context
of being a Fortran coder, but a definition (somewhere) might help,
e.g.:

@dfn{loop discovery} refers to the process by which a compiler,
or indeed any reader of a program,
determines which portions of the program are more likely
to be executed repeatedly
as it is being run.
Such discovery typically is done early
when compiling using optimization techniques,
so the ``discovered'' loops
get more attention---and more run-time resources, such as
registers---from the compiler.
It is easy to ``discover'' loops that are
constructed out of looping constructs in the language
(such as Fortran's @code{DO}).
For some programs, ``discovering'' loops
constructed out of lower-level constructs
(such as @code{IF} and @code{GOTO})
can lead to generation of more optimal code
than otherwise.

Or some such thing.

>+A dollar at the end of an output format specification suppresses the
>+newline at the end of the output.

"A dollar *sign*..." is probably better, though perhaps we should
not sniff at bribery of the run-time library.  :)

>+The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if
>+@code{STATUS='SCRATCH'} is supplied and the @code{STATUS='REPLACE'}
>+specifier is supported.

Is the "and the..." phrase to "if" as ".AND." is to "IF"?  Or should
there be a comma, semicolon, or period before "and the"?

>+@code{.NE.}, @code{.GT.} and @code{.GE.} repectively.

"respectively".

>+@code{KIND} is of limited usefulness in the absence of the
>+@code{KIND}-related intrinsics.  An example is:
>+@smallexample
>+      INTEGER (KIND=1) :: FOO=1, BAR=2
>+      CHARACTER (LEN=3) FOO
>+@end smallexample

Although not a run-on sentence, the "limited usefulness" might
seem to some readers to apply to "An example".  Perhaps finishing
the former sentence with ", since these intrinsics permit writing
more widely portable code" might help, as might either eliminating
the example, or replacing it with "So @samp{REAL(KIND=2)} is
supported, but @samp{REAL(KIND=KIND(0D0))} is not".

>+However, it might be better simply to put the FPU into double precision
>+mode and not take the performance hit of @code{-ffloat-store}.  On x86
>+and m68k GNU systems you can do this with a similar technique to that
>+for turning on floating point exceptions @xref{Floating-point Exception
>+Handling}.

Instead of "similar technique to that", perhaps "technique similar to
that".

>+@uref{http://http.cs.berkeley.edu/%7Ewkahan/ieee754status }; see also

Does "%7E" really work?  Is it "~"?

>+I think both programs can either be used in a pipeline or with files.

I think this should be "We believe", but am not really sure.

>+facilities at least for doing byte-swapping during unformatted i/o.

I usually capitalize "I/O".

Finally, I note several uses of "`foo'", which I *thought* texinfo
format "wanted" as "``foo''".  Maybe not, and/or maybe some of them
should really be @something{foo}.  I haven't refreshed my awareness
of texinfo format lately, though.

All in all, excellent work!

        tq vm, (burley)