Merge pull request #2986 from edwardhartnett/ejh_d3

added documentation about reading an unknown netCDF/HDF5 file in tutorial, and some other documentation fixes

CMakeLists.txt

@@ -13,7 +13,7 @@ project(netCDF
   LANGUAGES C CXX
   HOMEPAGE_URL "https://www.unidata.ucar.edu/software/netcdf/"
   DESCRIPTION "NetCDF is a set of software libraries and machine-independent data formats that support the creation, access, and sharing of array-oriented scientific data."
-  VERSION 4.9.3
+  VERSION 4.9.4
 )
 
 #####
@@ -27,7 +27,7 @@ project(netCDF
 # http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning
 #####
 
-set(NC_VERSION_NOTE "-rc1")
+set(NC_VERSION_NOTE "-development")
 set(netCDF_VERSION ${PROJECT_VERSION}${NC_VERSION_NOTE})
 set(VERSION ${netCDF_VERSION})
 set(NC_VERSION ${netCDF_VERSION})

RELEASE_NOTES.md

@@ -10,7 +10,7 @@ This file contains a high-level description of this package's evolution. Release
 * Provide better documentation for the .rc file mechanism and API. See [Github #2956](https://github.com/Unidata/netcdf-c/pull/2956) for more information.
 * Convert NCZarr V2 to store all netcdf-4 specific info as attributes. This improves interoperability with other Zarr implementations by no longer using non-standard keys. The price to be paid is that lazy attribute reading cannot be supported. See [Github #2836](https://github.com/Unidata/netcdf-c/pull/2936) for more information.
 * Cleanup the option code for NETCDF_ENABLE_SET_LOG_LEVEL\[_FUNC\] See [Github #2931](https://github.com/Unidata/netcdf-c/pull/2931) for more information.
-* 
+
 ### Release Candidate 1 - July 26, 2024
 
 * Convert NCZarr V2 to store all netcdf-4 specific info as attributes. This improves interoperability with other Zarr implementations by no longer using non-standard keys. The price to be paid is that lazy attribute reading cannot be supported. See [Github #2836](https://github.com/Unidata/netcdf-c/issues/2936) for more information.
@@ -661,12 +661,10 @@ Example Work Flow from netcdf-c source directory:
 * $ `make build-netcdf-fortran`
 * $ `make install-netcdf-fortran`
 
-> These make targets are **only** valid after `make install` has been invoked.  This cannot be enforced rigidly in the makefile for reasons we will expand on in the documentation, but in short: `make install` may require sudo, but using sudo will discard environmental variables required when attempting to build netcdf-fortran in this manner.<br><br>
+> These make targets are **only** valid after `make install` has been invoked.  This cannot be enforced rigidly in the makefile for reasons we will expand on in the documentation, but in short: `make install` may require sudo, but using sudo will discard environmental variables required when attempting to build netcdf-fortran in this manner.
 
 > It is important to note that this is functionality is for *convenience only*. It will remain possible to build `netcdf-c` and `netcdf-fortran` manually.  These make targets should hopefully suffice for the majority of our users, but for corner cases it may still be required of the user to perform a manual build.  [NCF-323](https://bugtracking.unidata.ucar.edu/browse/NCF-323)
 
-----
-
 * Added a failure state if the `m4` utility is not found on non-Windows systems; previously, the build would fail when it reached the point of invoking m4.
 
 * Added an explicit check in the build systems (autotools, cmake) for the CURL-related option `CURLOPT_CHUNK_BGN_FUNCTION`.  This option was introduced in libcurl version `7.21.0`.  On installations which require libcurl and have this version, `CURLOPT_CHUNK_BGN_FUNCTION` will be available. Otherwise, it will not.

docs/FAQ.md

@@ -49,7 +49,7 @@ utility programs, is available from [the NetCDF Downloads
 page](https://downloads.unidata.ucar.edu/netcdf-c). Separate source distributions for
 the Java library, Fortran libraries, and C++ libraries are also
 available there. Installation instructions are available with the
-distribution or [online](https://docs.unidata.ucar.edu/netcdf-c/current/building.html).
+distribution or [online](https://docs.unidata.ucar.edu/netcdf-c/current/netCDF-CMake.html).
 
 Binary distributions of netCDF are available for various platforms from
 package management systems such as dpkg, RPM, fink, MacPorts, Homebrew,

docs/install-fortran.md

@@ -15,7 +15,7 @@ More recently, building netcdf-fortran as an automated step in the
 netcdf-c build is now possible (for non-MSVC builds) by using new
 options at configure time, so if you haven't built and installed the
 netCDF-C library yet, you may want to try the new netCDF-C <a
-href="https://docs.unidata.ucar.edu/netcdf-c/current/getting_and_building_netcdf.html#getting"
+href="https://docs.unidata.ucar.edu/netcdf-c/current/netCDF-CMake.html"
 >Fortran-bootstrap procedure</a>.
 
 In the example commands below, we assume use of a

docs/tutorial.dox

@@ -15,7 +15,8 @@ This page contains references to various other NetCDF background and tutorial pa
 - \subpage tutorial_ncids
 - \subpage creating
 - \subpage reading_known
-- \subpage reading_unknown
+- \subpage reading_unknown_classic
+- \subpage reading_unknown_nc4
 - \subpage accessing_subsets
 
 \subsection background_further_reading Background and Further Reading
@@ -894,7 +895,7 @@ interest.
 
 Use ncdump to learn the structure of a file (use the -h option).
 
-\page reading_unknown Reading NetCDF Files of Unknown Structure
+\page reading_unknown_classic Reading Classic Format NetCDF Files of Unknown Structure
 
 Perhaps you would like to write your software to handle more general
 cases, so that you don't have to adjust your source every time the
@@ -946,6 +947,42 @@ num attributes.
 - nc_inq_format() Find file format: classic CDF-1, 64-bit offset CDF-2, or 64-bit data CDF-5
 - nc_inq_libvers() Find the netCDF library version.
 
+\page reading_unknown_nc4 Reading NetCDF/HDF5 Format NetCDF Files of Unknown Structure
+
+When using netCDF/HDF5 files (i.e. NC_NETCDF4 without
+NC_CLASSIC_MODEL), reading an unknown file is more complex, because
+groups and multiple unilimited dimensions are permitted. User defined
+types may also be present.
+
+To read an unknown netCDF/HDF5 file, start at the root group and then
+read each group recursively. Within each group, start by scanning for
+user-defined types.
+
+The follow additional inquiry functions support netCDF/HDF5 files.
+
+Files and Groups:
+- nc_inq_ncid()
+- nc_inq_grps()
+- nc_inq_grpname()
+- nc_inq_grpname_full()
+- nc_inq_grpname_len()
+- nc_inq_grp_parent()
+- nc_inq_grp_ncid()
+- nc_inq_grp_full_ncid()
+- nc_inq_unlimdims()
+
+User Defined Types:
+- nc_inq_type_equal()
+- nc_inq_type()
+- nc_inq_user_type()
+- nc_inq_typeid()
+- nc_inq_compound()
+- nc_inq_compound_field()
+- nc_inq_vlen()
+- nc_inq_enum()
+- nc_inq_enum_member()
+- nc_inq_opaque()
+
 \page accessing_subsets Reading and Writing Subsets of Data
 
 Usually users are interested in reading or writing subsets of