[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: 20040629: netCDF doc suggestion

>To: address@hidden
>From: der Mouse <address@hidden>
>Subject: doc suggestion
>Organization: ?
>Keywords: 200406292108.i5TL8mWb012708 netCDF web page documentation

Hi,

> http://my.unidata.ucar.edu/content/software/netcdf/guidec.txt has a
> minor problem.  When describing an argument to a routine, the formal
> parameter name in the description is placed to the left of the
> description - but it is centred vertically.  In many cases, this is not
> much of a problem, but in some it is a significant issue.  For example,
> in nc_open's description,
> 
> int nc_open (const char *path, int omode, int *ncidp);
> 
>   path    File name for netCDF dataset to be opened.
> 
>           A zero value (or NC_NOWRITE) specifies the default behavior:
>           open the dataset with read-only access, buffering and caching
>           accesses for efficiency
> 
>           Otherwise, the creation mode is NC_WRITE, NC_SHARE, or
>           NC_WRITE|NC_SHARE. Setting the NC_WRITE flag opens the dataset
>           with read-write access. ("Writing" means any kind of change to
>   omode   the dataset, including appending or changing data, adding or
>           renaming dimensions, variables, and attributes, or deleting
>           attributes.) The NC_SHARE flag is appropriate when one process
>           may be writing the dataset and one or more other processes
>           reading the dataset concurrently; it means that dataset accesses
>           are not buffered and caching is limited. Since the buffering
>           scheme is optimised for sequential access, programs that do not
>           access data sequentially may see some performance improvement by
>           setting the NC_SHARE flag.
> 
> it looks as though the first paragraph of omode's description is
> actually the second paragraph of path's.
> 
> I don't know how easy it would be to do, but I'd recommend moving the
> formal parameter names up to the first line of their descriptions, at
> least for the text version.  (I haven't looked at the other versions,
> so I'm not competent to comment on them in this regard.)  If this is
> difficult, maybe the blank line between each parameter and the next
> could be replaced with a line of dashes or something, to provide a
> clear boundary?

Thanks for the suggestion.  For version 3.6.0, we have converted all
the documentation from FrameMaker to texinfo, and it fixes the problem
you noted, among other things.  The texinfo to html conversion, for
example, produces this for the nc_open description:

  
http://my.unidata.ucar.edu/content/software/netcdf/netcdf-4/newdocs/netcdf-c/nc_open.html#nc_open

--Russ