docs

DennisHeimbigner · Sep 29, 2024 · bb6869b · bb6869b
1 parent 618518c
commit bb6869b
Show file tree

Hide file tree

Showing 10 changed files with 106 additions and 72 deletions.
diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in
@@ -964,8 +964,8 @@ INPUT                  = @abs_top_srcdir@/docs/mainpage.dox \
                          @abs_top_srcdir@/docs/file_format_specifications.md \
                          @abs_top_srcdir@/docs/all-error-codes.md \
                          @abs_top_srcdir@/docs/filters.md \
-                         @abs_top_srcdir@/docs/pluginpath.md \
                          @abs_top_srcdir@/docs/quickstart_filters.md \
+                         @abs_top_srcdir@/docs/pluginpath.md \
                          @abs_top_srcdir@/docs/quickstart_paths.md \
                          @abs_top_srcdir@/docs/quickstart_env.md \
                          @abs_top_srcdir@/include/netcdf.h \

diff --git a/docs/filters.md b/docs/filters.md
@@ -1207,7 +1207,7 @@ A user may encounter an incompatibility if any of the following appears in user
 
 For additional information, see [Appendix B](#filters_appendixb).
 
-## Point of Contact {#filters_poc}
+## History {#filters_history}
 
 *Author*: Dennis Heimbigner<br>
 *Email*: [email protected]<br>

diff --git a/docs/footer.html b/docs/footer.html
@@ -1,4 +1,4 @@
-<!-- HTML footer for doxygen 1.9.1-->
+<!-- HTML footer for doxygen 1.10.0-->
 <!-- start footer part -->
 <!--BEGIN GENERATE_TREEVIEW-->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->

diff --git a/docs/header.html b/docs/header.html
@@ -1,54 +1,78 @@
-<!-- HTML header for doxygen 1.9.1-->
+<!-- HTML header for doxygen 1.10.0-->
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
 <head>
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
-<meta http-equiv="X-UA-Compatible" content="IE=9"/>
+<meta http-equiv="X-UA-Compatible" content="IE=11"/>
 <meta name="generator" content="Doxygen $doxygenversion"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
 <!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+<!--BEGIN PROJECT_ICON-->
+<link rel="icon" href="$relpath^$projecticon" type="image/x-icon" />
+<!--END PROJECT_ICON-->
 <link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
+<!--BEGIN DISABLE_INDEX-->
+  <!--BEGIN FULL_SIDEBAR-->
+<script type="text/javascript">var page_layout=1;</script>
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
 <script type="text/javascript" src="$relpath^jquery.js"></script>
 <script type="text/javascript" src="$relpath^dynsections.js"></script>
+<!--BEGIN COPY_CLIPBOARD-->
+<script type="text/javascript" src="$relpath^clipboard.js"></script>
+<!--END COPY_CLIPBOARD-->
 $treeview
 $search
 $mathjax
+$darkmode
 <link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
 $extrastylesheet
 </head>
 <body>
+<!--BEGIN DISABLE_INDEX-->
+  <!--BEGIN FULL_SIDEBAR-->
+<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+
 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
 
 <!--BEGIN TITLEAREA-->
 <div id="titlearea">
 <table cellspacing="0" cellpadding="0">
  <tbody>
- <tr style="height: 56px;">
+ <tr id="projectrow">
   <!--BEGIN PROJECT_LOGO-->
-  <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
+  <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"$logosize/></td>
   <!--END PROJECT_LOGO-->
   <!--BEGIN PROJECT_NAME-->
-  <td id="projectalign" style="padding-left: 0.5em;">
-   <div id="projectname">$projectname
-   <!--BEGIN PROJECT_NUMBER-->&#160;<span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER-->
+  <td id="projectalign">
+   <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
    </div>
    <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
   </td>
   <!--END PROJECT_NAME-->
   <!--BEGIN !PROJECT_NAME-->
    <!--BEGIN PROJECT_BRIEF-->
-    <td style="padding-left: 0.5em;">
+    <td>
     <div id="projectbrief">$projectbrief</div>
     </td>
    <!--END PROJECT_BRIEF-->
   <!--END !PROJECT_NAME-->
   <!--BEGIN DISABLE_INDEX-->
    <!--BEGIN SEARCHENGINE-->
-   <td>$searchbox</td>
+     <!--BEGIN !FULL_SIDEBAR-->
+    <td>$searchbox</td>
+     <!--END !FULL_SIDEBAR-->
    <!--END SEARCHENGINE-->
   <!--END DISABLE_INDEX-->
  </tr>
+  <!--BEGIN SEARCHENGINE-->
+   <!--BEGIN FULL_SIDEBAR-->
+   <tr><td colspan="2">$searchbox</td></tr>
+   <!--END FULL_SIDEBAR-->
+  <!--END SEARCHENGINE-->
  </tbody>
 </table>
 </div>

diff --git a/docs/indexing.dox b/docs/indexing.dox
@@ -2,7 +2,7 @@
 
 \internal
 
-\page Hashed + Indexed Access to Metadata Objects
+\page Indexed Access to Metadata Objects
 
 \tableofcontents
 

diff --git a/docs/pluginpath.md b/docs/pluginpath.md
@@ -49,7 +49,7 @@ to set the global plugin path to control plugin discovery.
 Since the global path and the HDF5 and NCZarr paths are kept in
 sync, this means that both HDF5 and NCZarr will look in the same
 directories in order to locate specified plugins.
-[Appendix A](#pluginpath_appendixa) defines the current API for
+[Appendix E.1](#pluginpath_appendixe1) defines the current API for
 managing the global plugin path.
 
 Note that it is best practice for a client program to use the API
@@ -70,53 +70,6 @@ initial plugin path is either:
 
 This initial global plugin path will be propagated to HDF5 and NCZarr.
 
-### A Note About HDF5\_PLUGIN\_PATH
-
-## Appendix A. Programmatic Plugin Pathh API{#pluginpath_appendixa}
-
-The API makes use of a counted vector of strings representing the sequence of directories in the path. The relevant type definition is as follows.
-````
-typedef struct NCPluginList {size_t ndirs; char** dirs;} NCPluginList;
-````
-
-The API proposed in this PR looks like this (from netcdf-c/include/netcdf_filter.h).
-
-* ````int nc_plugin_path_ndirs(size_t* ndirsp);````
-
-    This function returns the number of directories in the sequence if internal directories of the internal plugin path list.
-
-    The argument is as follows:
-    - *ndirsp* store the number of directories in this memory.
-
-* ````int nc_plugin_path_get(NCPluginList* dirs);````
-
-    This function returns the current sequence of directories from the internal plugin path list. Since this function does not modify the plugin path, it does not need to be locked; it is only when used to get the path to be modified that locking is required.
-
-    The argument is as follows:
-    - *dirs* counted vector for storing the sequence of directies in the internal path list.
-
-    If the value of *dirs.dirs is NULL (the normal case), then memory is allocated to hold the vector of directories. Otherwise, use the memory of *dirs.dirs* to hold the vector of directories.
-
-* ````int nc_plugin_path_set(const NCPluginList* dirs);````
-
-    This function empties the current internal path sequence and replaces it with the sequence of directories argument. Using an *ndirs* argument of 0 will clear the set of plugin paths.
-
-    The argument are as follows:
-    - *dirs* counted vector for storing the sequence of directies in the internal path list.
-
-*HDF5\_PLUGIN\_PATH* is a typical Windows or Unix style
-path-list.  That is it is a sequence of absolute directory paths
-separated by a specific separator character. For Windows, the
-separator character is a semicolon (';') and for Unix, it is a
-colon (':').
-
-At the moment, NetCDF optionally (i.e. not overridden) uses the
-existing HDF5 environment variable *HDF5\_PLUGIN\_PATH* to
-locate the directories in which plugin libraries are located. It
-also optionally uses the last directory in the path as the
-installation directory. This is used both for the HDF5 filter
-wrappers but also the NCZarr codec wrappers.
-
 ## Installing Plugins at Build-Time
 
 At build-time, the target location directory into which libraries implementing plugins are installed is specified using a special *./configure* option
@@ -147,7 +100,7 @@ or (cmake)
 -DNETCDF_PLUGIN_INSTALL_DIR=NO
 ````
 
-### Multi-Threaded Access to the Plugin Path.
+## Multi-Threaded Access to the Plugin Path.
 Specifically, note that modifying the plugin path must be done "atomically".
 That is, in a multi-threaded environment, it is important that the sequence of actions involved in setting up the plugin path must be done by a single processor or in some other way as to guarantee that two or more processors are not simultaneously accessing the plugin path get/set operations.
 
@@ -180,7 +133,52 @@ There is a complication with respect to the *nc_plugin_path_get* function.
 It is possible for users to bypass the netcdf API and modify the HDF5 plugin paths directly. This can result in an inconsistent plugin path between the value
 used by HDF5 and the global value used by netcdf-c. Since there is no obvious fix for this, we warn the user of this possibility and otherwise ignore it.
 
-## Point of Contact {#pluginpath_poc}
+## Appendix E.1. Programmatic Plugin Path API{#pluginpath_appendixe1}
+
+The API makes use of a counted vector of strings representing the sequence of directories in the path. The relevant type definition is as follows.
+````
+typedef struct NCPluginList {size_t ndirs; char** dirs;} NCPluginList;
+````
+
+The API proposed in this PR looks like this (from netcdf-c/include/netcdf_filter.h).
+
+* ````int nc_plugin_path_ndirs(size_t* ndirsp);````
+
+    This function returns the number of directories in the sequence if internal directories of the internal plugin path list.
+
+    The argument is as follows:
+    - *ndirsp* store the number of directories in this memory.
+
+* ````int nc_plugin_path_get(NCPluginList* dirs);````
+
+    This function returns the current sequence of directories from the internal plugin path list. Since this function does not modify the plugin path, it does not need to be locked; it is only when used to get the path to be modified that locking is required.
+
+    The argument is as follows:
+    - *dirs* counted vector for storing the sequence of directies in the internal path list.
+
+    If the value of *dirs.dirs is NULL (the normal case), then memory is allocated to hold the vector of directories. Otherwise, use the memory of *dirs.dirs* to hold the vector of directories.
+
+* ````int nc_plugin_path_set(const NCPluginList* dirs);````
+
+    This function empties the current internal path sequence and replaces it with the sequence of directories argument. Using an *ndirs* argument of 0 will clear the set of plugin paths.
+
+    The argument are as follows:
+    - *dirs* counted vector for storing the sequence of directies in the internal path list.
+
+*HDF5\_PLUGIN\_PATH* is a typical Windows or Unix style
+path-list.  That is it is a sequence of absolute directory paths
+separated by a specific separator character. For Windows, the
+separator character is a semicolon (';') and for Unix, it is a
+colon (':').
+
+At the moment, NetCDF optionally (i.e. not overridden) uses the
+existing HDF5 environment variable *HDF5\_PLUGIN\_PATH* to
+locate the directories in which plugin libraries are located. It
+also optionally uses the last directory in the path as the
+installation directory. This is used both for the HDF5 filter
+wrappers but also the NCZarr codec wrappers.
+
+## History {#pluginpath_history}
 
 *Author*: Dennis Heimbigner<br>
 *Email*: [email protected]<br>

diff --git a/docs/quickstart_env.md b/docs/quickstart_env.md
@@ -1,6 +1,8 @@
-Appendix D.3. Environment Variables and .RC files {#nc_env_quickstart}
+Appendix G. Environment Variables and .RC files QuickStart {#nc_env_quickstart}
 ==============================
 
+[TOC]
+
 The netCDF-c library provides several parameterization mechanisms to
 control its behavior at run-time. The term _run-time_ means that the
 library's behavior can be changed every time the library is initialized
@@ -147,7 +149,7 @@ Other keys are as follows:
 * oc2/occurlfunctions.c
     - HTTP.NETRC -- alternate way to specify the path of the .netrc file
 
-## Point of Contact {#nc_env_poc}
+## History {#nc_env_history}
 
 __Author__: Dennis Heimbigner<br>
 __Email__: dmh at ucar dot edu<br>

diff --git a/docs/quickstart_paths.md b/docs/quickstart_paths.md
@@ -1,6 +1,8 @@
-Appendix D.2. Specifying Paths for NetCDF-C {#nc_paths_quickstart}
+Appendix F. Specifying Paths for NetCDF-C QuickStart {#nc_paths_quickstart}
 ==============================
 
+[TOC]
+
 A key concept in netcdf-c is the notion of a "path".
 A path specifies some dataset that is of interest to a user.
 It is the primary argument to the *nc_open* and *nc_create*
@@ -13,10 +15,10 @@ for using the NetCDF-C library.
 ## Classification of Paths {#nc_paths_kinds}
 
 Basically, there are two kinds of paths:
-1. File system paths, and
-2. Uniform Resource Locator (URL) paths.
+1. <a href="#qpaths_filesystem">File system paths</a>, and
+2. <a href="#qpaths_url">Uniform Resource Locator (URL) paths</a>.
 
-### File System Paths
+### File System Paths {#qpaths_filesystem}
 
 The most common form of path accepted by the NetCDF-C library is a file system path.
 Every user of some computer operating system is familiar with the idea of a file system path.
@@ -37,7 +39,7 @@ Windows has a notion of a drive ("d:") and each drive serves as the root
 of its own file system. Windows uses "\\" as its file separator, although
 many programs also accept "/".
 
-## Uniform Resource Locator (URL) Paths
+## Uniform Resource Locator (URL) Paths {#qpaths_url}
 
 The NetCDF-C library can access datasets that reside on remote computers,
 Hence NetCDF-C now also accepts URLs to specify those remote datasets.

diff --git a/libdispatch/ddispatch.c b/libdispatch/ddispatch.c
@@ -154,7 +154,7 @@ static int NC_createglobalstate(void);
 /** \defgroup global_state Global state functions. */
 /** \{
 
-\ingroup global state
+\ingroup global_state
 */
 
 /* NCglobal state management */

diff --git a/libdispatch/dfile.c b/libdispatch/dfile.c
@@ -1748,6 +1748,13 @@ nc_inq_type(int ncid, nc_type xtype, char *name, size_t *size)
     return ncp->dispatch->inq_type(ncid,xtype,name,size);
 }
 
+/** \defgroup dispatch dispatch functions. */
+/** \{
+
+\ingroup dispatch
+*/
+
+
 /**
    Check the create mode parameter for sanity.
 
@@ -2214,3 +2221,4 @@ nc__pseudofd(void)
     }
     return pseudofd++;
 }
+/** \} */