[patch] intrinsic.texi

[Brooks Moses]

Daniel Franke wrote:
> I realized, I can not continue to work on the docs for another 
> two weeks, so I send out for review what is available now.

Some comments follow; these are mostly small nitpicks, and the bulk of 
the documentation looks good to me.  Nice work!

- Brooks


---------------------

>  * @code{CMPLX}:         CMPLX,     Complex conversion function
> -* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT,  Command line argument count
> +* @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.

>  * @code{FTELL}:         FTELL,     Current stream position
> -* @code{GETARG}:        GETARG,    Get command line arguments
> -* @code{GET_COMMAND}:   GET_COMMAND, Subroutine to retrieve the entire command line
> -* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Subroutine to retrieve a command argument
> +* @code{GETARG}:        GETARG,    Retrive command line arguments
> +* @code{GET_COMMAND}:   GET_COMMAND, Retrieve the entire command line
> +* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Retrieve command line arguments

Here, though, there's not really a shorter way to write this, so it 
should probably stay.  (And the "subroutine to" stuff is right out; good 
catch!)  Though, actually, "get" rather than "retrieve" is what most of 
the rest say, so maybe being consistent is better....

Note that you misspelled "retrieve" on GETARG, though.

>  @node COMMAND_ARGUMENT_COUNT
> -@section @code{COMMAND_ARGUMENT_COUNT} --- Argument count function 
> +@section @code{COMMAND_ARGUMENT_COUNT} --- Retrieve the number of command line arguments

If you change the menu list from my comments there, this should be changed.

>  @findex @code{COMMAND_ARGUMENT_COUNT} intrinsic
> -@cindex command argument count
> +@cindex command line arguments
> +@cindex getopt

"getopt" should probably be @code{GETOPT}?

[in FSTAT]
>  @item @emph{Arguments}:
> -@item @emph{Return value}:
> +@multitable @columnfractions .15 .80
> +@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}"

[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?

> +@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.

>  @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!

[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?

[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.

[In IARGC]
>  @item @emph{See also}:
> -@ref{GETARG}, @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}, @ref{GET_COMMAND_ARGUMENT}
> +GNU Fortran 77 compability subroutine: @ref{GETARG}
>  
> +F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}

Again, overlong lines.
> +@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.  :)

Or, perhaps, "the status of the link itself is returned, rather than 
that of the file...."

Other than that, it all looks good!