Re: 970509: Suggestion re netCDF

> From: address@hidden (Roberta Young)
> To: address@hidden
> Subject: feed back on netcdf documentation, can you pass this along ?

Hi Roberta,

> i am starting to use a new numerical ocean model that does
> all it's i/o in the form of netcdf files. i have built
> netcdf for our system several times so i know where the
> man pages are and how to make sure i can read them.
> 
> it would be a very great help if there were a man page
> for each of the functions and subroutine calls to help
> the new user sort out that is happening with the netcdf
> calls. reading the netcdf user's guid gives far too
> much information at once to absorb reding it front
> to end.  and finding what ech funtion and call means
> feels like a random walk through the table of contents.
> a more direct access form via man pages would be
> easier to use for the novice netcdf user....
> 
> i know that for ncargks graphics, i tend to use the man
> pages released with that package heavily when i am following
> someone else's code.

The current netCDF distribution includes four man page files:

  man1/ncgen.1          the ncgen program
  man1/ncdump.1         the ncdump program
  man3/netcdf.3         the C library
  man3/netcdf.3f        the Fortran library

The latter two man pages provide reference documentation for all 34
functions in the C interface and 40 routines in the Fortran interface.
We did not provide man page documentation for the C++ interface, because
the -man troff macros are not well-suited to documenting C++ classes and
methods, but we do provide a C++ document in two other forms with the
distribution.

I think providing a separate man page for each function in the C and
Fortran interfaces would be inconsistent with conventions for other
Unix library packages, e.g. the 19 string operation functions are all
documented in one man page: string.3.

The netCDF-3 version we are about to announce and release supports all
the old netCDF-2 interfaces for backwards compatibility, but also
documents new netCDF interfaces for C and Fortran, with 134 new C
functions and 113 new Fortran functions.  We still document these in the
same four man page files as we did with netCDF-2.  I think you'll agree
that with netCDF-3, one man page per function would be impractical.

But thanks for the feedback.  Perhaps the appendices summarizing the
interfaces in the new User's Guides for C and Fortran available from

    ftp://ftp.unidata.ucar.edu/pub/netcdf/guidec-3.ps.Z
    ftp://ftp.unidata.ucar.edu/pub/netcdf/guidef-3.ps.Z

will suffice for providing short summaries of the available functions.

--Russ

_____________________________________________________________________

Russ Rew                                         UCAR Unidata Program
address@hidden                     http://www.unidata.ucar.edu