[patch] intrinsic.texi

[Daniel Franke]

Brooks,

thanks for your review. Please find a revised patch attached. 
Can you please commit it when it's acceptable?

Regards
	Daniel


Annotated comments follow:

> > +* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, 
> > Retrieve the number of command line arguments
>
> I've been trying to keep these short, and avoid near-zero-information
> phrases like "retrieve the".  The change to "Number of command line
> arguments" is probably a good thing, though.

Changed to "Get number of command line arguments".


> > -* @code{GETARG}:  GETARG,    Get command line arguments
> > +* @code{GETARG}:  GETARG,    Retrive command line arguments
> Though, actually, "get" rather than "retrieve" is what most of
> the rest say, so maybe being consistent is better....

Done. 


> > +@cindex getopt
> "getopt" should probably be @code{GETOPT}?

Since there is no getopt function or subroutine, @code{getopt} would be 
misleading. I added this index entry to help programmers who know about 
getopt (C, bash, ...) to find the corresponding Fortran functions and 
subroutines more easily. 


> [in FSTAT]
> > +@item @var{UNIT}   @tab The type shall be @code{INTEGER}, an open I/O
> > unit number.
>
> Maybe "An open I/O unit number of type @code{INTEGER}"

Done.


> [In GETARG]
>
> >  @item @emph{Return value}:
> > +After @code{GETARG} returns, the @var{ARG} argument holds the @var{N}th
> > +command line argument. If @var{ARG} can not hold the argument, it is
> > +truncated to fit the length of @var{ARG}. If there are less than @var{N}
> > +arguments specified at the command line, @var{ARG} will be filled with
> > +blanks. If @math{@var{N} = 0}, @var{ARG} is set to the name of the
> > +program (on systems that support this feature).
>
> What is it set to on systems that don't support this?  All blanks, or is
> there an error?

I assume that it should be all blanks. The docs of g77 remain silent in this 
matter (http://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/GetArg-Intrinsic.html).

Out of couriosity: can someone name a system where this might be an issue?


> > +@smallexample
> > +PROGRAM test_getarg
> > +  INTEGER :: i
> > +  CHARACTER(len=32) :: arg
> >
> > +  DO i = 1, iargc()
>
> I think that as a matter of general policy we've been using the
> most-standard version of codes in the examples.  I can certainly see
> where there's a case for using IARGC with GETARG, but I think it would
> still be better to use COMMAND_ARGUMENT_COUNT here.

I disagree. If someone decides to use getarg, it is likely that one has a 
reason to use iargc instead of COMMAND_ARGUMENT_COUNT, otherwise one could 
use GET_COMMAND_ARGUMENT in the first place. In a manner of speaking, in this 
example I tried to be consistent within one standard (or the lack thereof). 



> >  @item @emph{See also}:
> > -@ref{IARGC}, @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
> > +GNU Fortran 77 compability function: @ref{IARGC}
> > +
> > +F2003 functions and subroutines: @ref{GET_COMMAND},
> > @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
>
> This long line ought be broken.  I like the division of the "See also"
> list up into categories, though!

There are a couple of long reference lines. Agreed, the info and dvi outputs 
could be formatted more nicely, but the length of the line still looks 
reasonable to me. Maybe multiple references [cs]hould be itemized?



> [In GET_COMMAND]
>
> >  @item @emph{Return value}:
> > +Stores the entire command line that was used to invoke the program in
> > @var{ARG}. +If @var{ARG} is not large enough, the command will be
> > truncated.
>
> What happens on systems where retrieving the command name isn't supported?

42? See above.


> [In GET_COMMAND_ARGUMENT]
>
> >  @item @emph{Example}:
> > -@item @emph{Specific names}:
> > +@smallexample
> > +PROGRAM test_get_command_argument
> > +  INTEGER :: i
> > +  CHARACTER(len=32) :: arg
> > +
> > +  i = 0
> > +  DO
> > +    CALL get_command_argument(i, arg)
> > +    IF (LEN_TRIM(arg) == 0) EXIT
>
> Why does this use this version of the loop, rather than the
> I=0,COMMAND_ARGUMENT_COUNT() loop that the GETARG example uses?  That
> seems cleaner, and introduces the appropriate companion intrinsic.

To show that, if i > COMMAND_ARGUMENT_COUNT, arg is really blanked and as an 
example within the example, there is more than one way to achieve a goal.



> > +@node LSTAT
> > +@section @code{LSTAT} --- Get file status
> > +@findex @code{LSTAT} intrinsic
> > +@cindex file system operations
> >
> > +@table @asis
> > +@item @emph{Description}:
> > +@code{LSTAT} is identical to @ref{STAT}, except that if path is a
> > symbolic link, +then the link itself is stat-ed, not the file that it
> > refers to.
>
> "Statted" is the correct form, I think.  :)

Done.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: intrinsic.texi.diff
Type: text/x-diff
Size: 20981 bytes
Desc: not available
URL: <http://gcc.gnu.org/pipermail/fortran/attachments/20061009/6353c654/attachment.bin>