Possible Typos/Inconsistencies in the User's Guide

[Lenostatos]

Hello,

I originally created this issue in the netcdf-c repo: Unidata/netcdf-c#1860

The text below is a copy of the first post in that issue.

---

Hello,

I'm am currently reading the User's Guide at https://www.unidata.ucar.edu/software/netcdf/docs/user_guide.html and I believe that I am noticing a few typos/inconsistencies. I hope this is the right place to report these, but if not please point me to where I should go instead.

Also, while I feel confident in my English language skills, it is not my mother tongue so if there are any wrongly identified typos please ignore them (Of course if you tell me about them, I would learn something which would be very nice :)).

I've formatted additions italic and deletions with strike troughs.

Chapter "An Introduction to NetCDF":

• The second part of the first sentence in the paragraph about the CDF-5 format sounds weird. Maybe it should go like this?:
  ..., a 64-bit data format is being develop_ed_ to support such I/O requests. or like this?:
  ..., a 64-bit data format has been develop_ed_ to support such I/O requests.
• same place, second sentence: Files with the 64-bit data are identified with...
• same place third sentence: Since the CDF-5 format was introduced in version 4.4.0,...
• The last sentence in the "Creating Self-Describing Data..." section maybe should be extend like this?:
  These should be contributed to the above mentioned netCDF conventions site...
• The first sentence of the fourth paragraph in the "Limitations of netCDF" section sounds weird:
  "With the classic CDF-1 file format, there are constraints that limit how a dataset is structured to store more than 2 GiBytes[...]."
  From the rest of the text I understand that CDF-1 files can't store more than 2GiBytes of data and that that sentence is supposed to state that. However, it sounds a bit confusing to me with the "that limit how a dataset is structured" part. To me the phrasing "..., the structure of the dataset limits the amount of storable data to 2 GiBytes..." sounds more clear. What's your opinion on this?
• Could the second sentence of the seventh paragraph in the same section
  "CDF-5 files are not unreadable to the netCDF library before version 4.4.0." actually be intended to go like this instead?:
  CDF-5 files are not unreadable to with the netCDF library before version 4.4.0.

Chapter "File Structure and Performance"

• The third paragraph in the NetCDF-4 HDF5 section should probably be "Variables in netCDF coor_r_espond with identically..."

Chapter "The Components of a NetCDF Data Set"

• In the third and fourth paragraph of the "Variables" section the first sentence should probably go
  "In the CDL notation, classic data type_s_ can be used.". Other than that the fourth sentence
  "For the exact meaning of each of the types see External Types." looks as if it was missing a link at the end.
  Overall these two paragraphs sound as if they were continuing an explanation of CDL which was never properly started.

• Second sentence of the paragraph about name length in netCDF: This should probably be
  "Names longer than NC_MAX_NAME will not be accepted by any netCDF define function."

• The shorthand CDL is mentioned in multiple places but not explained anywhere.

  • The fourth to last paragraph in the "Dimensions" section seems to have nothing to do with the rest of the surrounding text. Am I missing something here?
  • The third and fourth paragraph of the "Variables" section already mentioned above.
  • There are more mentions on that page but I will stop listing them here since they don't all seem misplaced. Only an introduction to what they are about would help with understanding their meaning.

• In multiple places the text talks about an example which I cannot find anywhere.

  • The third to last paragraph in the "Dimensions" section mentions said example and gives a link to the topmost section on the same page ("The Data Model") but I can't see that example there.
  • The last paragraph of the "Variables" section talks about a "CDL example" which should be above it somewhere, but which I can't find on that page.
  • The "Coordinate Variables" section also mentions such an example and shows some coordinate variable definitions in what is probably CDL(?). At this point it became a bit more clear to me what this example should be about but I was still missing a proper description of it.
  • The last section also mentions that example in the beginning.
  • Hmm, I found a short description of maybe that exmaple in the netCDF-C tutorial. Is that it?

• When clicking on "The NetCDF User's Guide -> Writing NetCDF Files: Best Practices" in menu on the left I am apparently redirected to a development version of the documentation. Is that intentional?

Edit:

• In the "Limitations of netCDF" section the first sentence of the fifth paragraph has two repeated words:
  The CDF-2 format allows large files, and makes it easy to create to create fixed variables of about 4 GiB,...

Thank you for your consideration,
Leon

[WardF]

Thanks! I'm integrating some other updates into the users guide and will take a look to roll these in as well. Your contribution is very much appreciated!