summaryrefslogtreecommitdiffstats
path: root/doxygen/dox
diff options
context:
space:
mode:
Diffstat (limited to 'doxygen/dox')
-rw-r--r--doxygen/dox/APIVersions.dox173
-rw-r--r--doxygen/dox/About.dox114
-rw-r--r--doxygen/dox/Cookbook.dox14
-rw-r--r--doxygen/dox/FTS.dox8
-rw-r--r--doxygen/dox/Glossary.dox565
-rw-r--r--doxygen/dox/H5AC_cache_config_t.dox6
-rw-r--r--doxygen/dox/H5Acreate.dox9
-rw-r--r--doxygen/dox/H5Aiterate.dox9
-rw-r--r--doxygen/dox/MetadataCachingInHDF5.dox2
-rw-r--r--doxygen/dox/OtherSpecs.dox11
-rw-r--r--doxygen/dox/Overview.dox38
-rw-r--r--doxygen/dox/RFC.dox91
-rw-r--r--doxygen/dox/ReferenceManual.dox104
-rw-r--r--doxygen/dox/Specifications.dox38
-rw-r--r--doxygen/dox/TechnicalNotes.dox28
-rw-r--r--doxygen/dox/cookbook/Accessibility.c46
-rw-r--r--doxygen/dox/cookbook/Accessibility.dox39
-rw-r--r--doxygen/dox/cookbook/Attributes.c59
-rw-r--r--doxygen/dox/cookbook/Attributes.dox38
-rw-r--r--doxygen/dox/cookbook/Files.c71
-rw-r--r--doxygen/dox/cookbook/Files.dox31
-rw-r--r--doxygen/dox/cookbook/Performance.dox21
-rw-r--r--doxygen/dox/maybe_metadata_reads.dox50
23 files changed, 1491 insertions, 74 deletions
diff --git a/doxygen/dox/APIVersions.dox b/doxygen/dox/APIVersions.dox
new file mode 100644
index 0000000..3658f06
--- /dev/null
+++ b/doxygen/dox/APIVersions.dox
@@ -0,0 +1,173 @@
+/**
+ * \ingroup H5A
+ * \def H5Acreate
+ * \api_vers_2{H5Acreate,H5Acreate1,H5Acreate2}
+ */
+
+/**
+ * \ingroup H5A
+ * \def H5Aiterate
+ * \api_vers_2{H5Aiterate,H5Aiterate1,H5Aiterate2}
+ */
+
+/**
+ * \ingroup H5D
+ * \def H5Dcreate
+ * \api_vers_2{H5Dcreate,H5Dcreate1,H5Dcreate2}
+ */
+
+/**
+ * \ingroup H5E
+ * \def H5Eget_auto
+ * \api_vers_2{H5Eget_auto,H5Eget_auto1,H5Eget_auto2}
+ */
+
+/**
+ * \ingroup H5E
+ * \def H5Eprint
+ * \api_vers_2{H5Eprint,H5Eprint1,H5Eprint2}
+ */
+
+/**
+ * \ingroup H5E
+ * \def H5Epush
+ * \api_vers_2{H5Epush,H5Epush1,H5Epush2}
+ */
+
+/**
+ * \ingroup H5E
+ * \def H5Eset_auto
+ * \api_vers_2{H5Eset_auto,H5Eset_auto1,H5Eset_auto2}
+ */
+
+/**
+ * \ingroup H5E
+ * \def H5Ewalk
+ * \api_vers_2{H5Ewalk,H5Ewalk1,H5Ewalk2}
+ */
+
+/**
+ * \ingroup H5F
+ * \def H5Fget_info
+ * \api_vers_2{H5Fget_info,H5Fget_info1,H5Fget_info2}
+ */
+
+/**
+ * \ingroup H5G
+ * \def H5Gcreate
+ * \api_vers_2{H5Gcreate,H5Gcreate1,H5Gcreate2}
+ */
+
+/**
+ * \ingroup H5G
+ * \def H5Gopen
+ * \api_vers_2{H5Gopen,H5Gopen1,H5Gopen2}
+ */
+
+/**
+ * \ingroup H5L
+ * \def H5Lget_info
+ * \api_vers_2{H5Lget_info,H5Lget_info1,H5Lget_info2}
+ */
+
+/**
+ * \ingroup H5L
+ * \def H5Lget_info_by_idx
+ * \api_vers_2{H5Lget_info_by_idx,H5Lget_info_by_idx1,H5Lget_info_by_idx2}
+ */
+
+/**
+ * \ingroup TRAV
+ * \def H5Literate
+ * \api_vers_2{H5Literate,H5Literate1,H5Literate2}
+ */
+
+/**
+ * \ingroup TRAV
+ * \def H5Literate_by_name
+ * \api_vers_2{H5Literate_by_name,H5Literate_by_name1,H5Literate_by_name2}
+ */
+
+/**
+ * \ingroup TRAV
+ * \def H5Lvisit
+ * \api_vers_2{H5Lvisit,H5Lvisit1,H5Lvisit2}
+ */
+
+/**
+ * \ingroup TRAV
+ * \def H5Lvisit_by_name
+ * \api_vers_2{H5Lvisit_by_name,H5Lvisit_by_name1,H5Lvisit_by_name2}
+ */
+
+/**
+ * \ingroup H5O
+ * \def H5Oget_info
+ * \api_vers_3{H5Oget_info,H5Oget_info1,H5Oget_info2,H5Oget_info3}
+ */
+
+/**
+ * \ingroup H5O
+ * \def H5Oget_info_by_idx
+ * \api_vers_3{H5Oget_info_by_idx,H5Oget_info_by_idx1,H5Oget_info_by_idx2,H5Oget_info_by_idx3}
+ */
+
+/**
+ * \ingroup H5O
+ * \def H5Oget_info_by_name
+ * \api_vers_3{H5Oget_info_by_name,H5Oget_info_by_name1,H5Oget_info_by_name2,H5Oget_info_by_name3}
+ */
+
+/**
+ * \ingroup H5O
+ * \def H5Ovisit
+ * \api_vers_3{H5Ovisit,H5Ovisit1,H5Ovisit2,H5Ovisit3}
+ */
+
+/**
+ * \ingroup H5O
+ * \def H5Ovisit_by_name
+ * \api_vers_3{H5Ovisit_by_name,H5Ovisit_by_name1,H5Ovisit_by_name2,H5Ovisit_by_name3}
+ */
+
+/**
+ * \ingroup H5R
+ * \def H5Rdereference
+ * \api_vers_2{H5Rdereference,H5Rdereference1,H5Rdereference2}
+ */
+
+/**
+ * \ingroup H5R
+ * \def H5Rget_obj_type
+ * \api_vers_3{H5Rget_obj_type,H5Rget_obj_type1,H5Rget_obj_type2,H5R_get_obj_type3}
+ */
+
+/**
+ * \ingroup H5S
+ * \def H5Sencode
+ * \api_vers_2{H5Sencode,H5Sencode1,H5Sencode2}
+ */
+
+/**
+ * \ingroup H5T
+ * \def H5Tcommit
+ * \api_vers_2{H5Tcommit,H5Tcommit1,H5Tcommit2}
+ */
+
+/**
+ * \ingroup H5T
+ * \def H5Topen
+ * \api_vers_2{H5Topen,H5Topen1,H5Topen2}
+ */
+
+/**
+ * \ingroup ARRAY
+ * \def H5Tarray_create
+ * \api_vers_2{H5Tarray_create,H5Tarray_create1,H5Tarray_create2}
+ */
+
+/**
+ * \ingroup ARRAY
+ * \def H5Tget_array_dims
+ * \api_vers_2{H5Tget_array_dims,H5Tget_array_dims1,H5Tget_array_dims2}
+ */
diff --git a/doxygen/dox/About.dox b/doxygen/dox/About.dox
index 777b2a6..a8b31d7 100644
--- a/doxygen/dox/About.dox
+++ b/doxygen/dox/About.dox
@@ -10,4 +10,118 @@ and the online version of their
Not only does Eigen set a standard as a piece of software, but also as an example
of <em>documentation done right</em>.
+\section about_documentation Documentation about Documentation
+
+In this section, we describe common documentation maintenance tasks.
+
+\subsection plain_html Including Plain HTML Pages
+
+The most common use case for this is the inclusion of older documentation.
+New documentation should, whenever possible, be created using Doxygen markdown!
+
+Use Doxygen's <a href="https://www.doxygen.nl/manual/commands.html#cmdhtmlinclude"><code>htmlinclude</code></a>
+special command to include existing plain HTML pages.
+
+An example from this documentation set can be seen
+<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/dox/FileFormatSpec.dox">here</a>.
+
+\subsection new_rm_entry Creating a New Reference Manual Entry
+
+Please refer to the \ref RMT for guidance on how to create a new reference manual entry.
+
+\subsubsection new_example Adding and Referencing API Examples
+
+For each HDF5 module, such as \Code{H5F}, there is an examples source file called
+\Code{H5*_examples.c}. For example, the \Code{H5F} API examples are located in
+<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/examples/H5F_examples.c">
+<code>H5F_examples.c</code></a>. Examples are code blocks marked as Doxygen
+<a href="https://www.doxygen.nl/manual/commands.html#cmdsnippet">snippets</a>.
+For example, the source code for the H5Fcreate() API sample is located between
+the
+\verbatim
+//! <!-- [create] -->
+...
+//! <!-- [create] -->
+\endverbatim
+comments in
+<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/examples/H5F_examples.c">
+<code>H5F_examples.c</code></a>.
+
+Add a new API example by adding a new code block enclosed between matching
+snippet tags. The name of the tag is usually the function name stripped of
+the module prefix.
+
+The inclusion of such a block of code can then be triggered via Doxygen's
+<a href="https://www.doxygen.nl/manual/commands.html#cmdsnippet"><code>snippet</code></a>
+special command. For example, the following markup
+\verbatim
+* \snippet H5F_examples.c create
+\endverbatim
+yields
+\snippet H5F_examples.c create
+
+\subsubsection api_macro Adding an API Macro
+
+API macros are handled by the <code>api_vers_2, api_vers_3, api_vers_4</code>
+custom commands. The numbers indicate the number of potential API function
+mappings. For example, H5Acreate() has two potential mappings, H5Acreate1() and
+H5Acreate2(). To trigger the creation of a reference manual entry for H5Acreate()
+use the following markup:
+\verbatim
+\api_vers_2{H5Acreate,H5Acreate1,H5Acreate2}
+\endverbatim
+This yields:
+
+\api_vers_2{H5Acreate,H5Acreate1,H5Acreate2}
+
+\subsection custom_commands Creating Custom Commands
+
+See Doxygen's <a href="https://www.doxygen.nl/manual/custcmd.html">Custom Commands documentation</a>
+as a general reference.
+
+All custom commands for this project are located in the
+<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a>
+file in the <a href="https://github.com/HDFGroup/hdf5/tree/develop/doxygen"><tt>doxygen</tt></a>
+subdirectory of the <a href="https://github.com/HDFGroup/hdf5">main HDF5 repo</a>.
+
+The custom commands are grouped in sections. Find a suitable section for your command or
+ask for help if unsure!
+
+\subsection new_rfc Adding a New RFC or Referencing an Existing RFC
+
+For ease of reference, we define custom commands for each RFC in the <tt>RFCs</tt> section
+of the
+<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a>
+file. For example the custom command \Code{ref_rfc20141210} can be used to insert a
+reference to "RFC: Virtual Object Layer". In other words, the markup
+\verbatim
+\ref_rfc20141210
+\endverbatim
+yields a clickable link:
+
+\ref_rfc20141210
+
+To add a new RFC, add a custom command for the RFC to the
+<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a>
+file. The naming convention for the custom command is \Code{ref_rfcYYYYMMDD},
+where \Code{YYYYMMDD} is the ID of the RFC. The URL is composed of the prefix
+\verbatim
+https://docs.hdfgroup.org/hdf5/rfc/
+\endverbatim
+and the name of your RFC file, typically, a PDF file, i.e., the full URL would
+be
+\verbatim
+https://docs.hdfgroup.org/hdf5/rfc/my_great_rfc_name.pdf
+\endverbatim
+
+\subsection hosting How Do Updates and Changes Get Published?
+
+Currently, the files underlying this documentation website are stored in an
+bucket on AWS S3. The top-level bucket is <pre>s3://docs.hdfgroup.org/hdf5/</pre>
+There are folders for the <tt>development</tt> branch and all supported release
+version.
+
+Talk to your friendly IT-team if you need write access, or you need someone to
+push an updated version for you!
+
*/ \ No newline at end of file
diff --git a/doxygen/dox/Cookbook.dox b/doxygen/dox/Cookbook.dox
index 4abc896..56523e2 100644
--- a/doxygen/dox/Cookbook.dox
+++ b/doxygen/dox/Cookbook.dox
@@ -2,4 +2,18 @@
Healthy, everyday recipes for every taste and budget...
+\ref Files
+\li \ref CB_FreeSpace
+\li \ref CB_RemoveUnusedSpace
+\li \ref CB_UserBlock
+
+\ref Attributes
+\li \ref CB_LargeAttributes
+
+\ref Accessibility
+\li \ref CB_MaintainCompat
+
+\ref Performance
+\li \ref CB_MDCPerf
+
*/ \ No newline at end of file
diff --git a/doxygen/dox/FTS.dox b/doxygen/dox/FTS.dox
new file mode 100644
index 0000000..9dae7c1
--- /dev/null
+++ b/doxygen/dox/FTS.dox
@@ -0,0 +1,8 @@
+/** \page FTS Full-Text Search
+
+\htmlonly
+<script async src="https://cse.google.com/cse.js?cx=75c754173f9b90804"></script>
+<div class="gcse-search"></div>
+\endhtmlonly
+
+*/ \ No newline at end of file
diff --git a/doxygen/dox/Glossary.dox b/doxygen/dox/Glossary.dox
new file mode 100644
index 0000000..9ccd27d
--- /dev/null
+++ b/doxygen/dox/Glossary.dox
@@ -0,0 +1,565 @@
+/** \page GLS Glossary
+
+\section GLS_A A
+
+<DL>
+ <DT>Array datatype</DT>
+ <DD>A family of HDF5 datatypes whose elements are arrays of a fixed rank (≤
+ 32) and fixed finite extent. All array elements must be of the same HDF5
+ datatype.</DD>
+</DL>
+
+<DL>
+ <DT>Array variable</DT>
+ <DD><P>A variable that can store (logically) dense, rectilinear, multidimensional
+ arrays of elements of a given HDF5 datatype.</P>
+ <P>The combination of array rank (dimensionality) and extent is called an
+ array variable's shape. This includes the degenerate array shapes of a
+ singleton (scalar) and the empty array (null).</P>
+ <P>The array element datatype is sometimes referred to as the array
+ variable's type, which is not entirely accurate because the array variable's
+ type is 'array of element type' rather than 'element type'.</P>
+ <P>In HDF5, there are two kinds of array variables, attributes and datasets,
+ and the distinction is functional (i.e., how they can be used) rather than
+ conceptual. Attributes are commonly used for descriptive "light-weight"
+ HDF5 object metadata while datasets are HDF5 objects used to store
+ "heavy-weight" problem-sized data.</P>
+ </DD>
+</DL>
+
+<DL>
+ <DT>Attribute</DT>
+ <DD><P>A named array variable that is associated with an HDF5 object, its
+ owner or attributee, and used to represent application domain-specific
+ metadata of the object. Intuitively, the set of an object's attributes can
+ be thought of as its key-value pair collection. Attribute names (keys) can
+ be arbitrary Unicode strings, but must be unique per object, i.e., an
+ object can have at most one attribute with a given name.</P>
+ <P>A scalar attribute is an attribute backed by a singleton array
+ variable. A null attribute is attribute backed by an empty array
+ variable.</P>
+</DD>
+</DL>
+
+\section GLS_B B
+
+<DL>
+ <DT>Bitfield datatype</DT>
+ <DD>A family of HDF5 datatypes whose elements are fixed-width bit fields.</DD>
+</DL>
+
+\section GLS_C C
+
+<DL>
+ <DT>Chunked layout</DT>
+ <DD>
+ <P>A dataset storage layout where the dataset elements are partitioned into
+ fixed-size multidimensional chunks or tiles. Chunked layout is mandatory
+ for datasets with one or more dimensions of indefinite (infinite) extent
+ or where compression or other filters are applied to the dataset elements.</P>
+ <P>Chunked layout may improve I/O performance for certain access patterns.</P>
+</DD>
+</DL>
+
+<DL>
+ <DT>Committed datatype</DT>
+ <DD>An immutable kind of HDF5 object that is used to store an HDF5 datatype
+ definition, which can be referenced by multiple array variables. When linked
+ to an HDF5 group, a committed datatype can be located by an HDF5 path name,
+ and is sometimes called a named datatype.</DD>
+</DL>
+
+<DL>
+ <DT>Compact layout</DT>
+ <DD></DD>
+</DL>
+
+<DL>
+ <DT>Compound datatype</DT>
+ <DD>
+ <P>A family of HDF5 datatypes whose elements are records with named fields
+ of other HDF5 datatypes. Currently, on ASCII field names are supported.</P>
+ <P>Similar to a <CODE>struct</CODE> in C or a <CODE>COMMON</CODE> block in
+ Fortran.</P>
+</DD>
+</DL>
+
+<DL>
+ <DT>Contiguous layout</DT>
+ <DD>A dataset storage layout where the dataset elements are physically stored
+ in an HDF5 file as a contiguous block of bytes.</DD>
+</DL>
+
+\section GLS_D D
+
+<DL>
+ <DT>Dataset</DT>
+ <DD>
+ <P>A kind of HDF5 object, a linked array variable. which can be located in
+ an HDF5 file through a path name. Datasets are commonly used to store
+ "heavy-weight" problem-sized data.</P>
+ <P>The HDF5 library offers a lot of features aimed at optimized dataset
+ access and storage, including compression and partial I/O.</P>
+</DD>
+</DL>
+
+<DL>
+ <DT>Dataspace</DT>
+ <DD>The shape of an array variable. With the exception of degenerate cases
+ (empty set, singleton), this is a rectilinear lattice or grid of a certain
+ rank (dimensionality) and extent.</DD>
+</DL>
+
+<DL>
+ <DT>Datatype</DT>
+ <DD>
+ <P>An HDF5 datatype consists of an abstract data type (a set of elements)
+ and a bit-level representation of these elements in storage such as an HDF5
+ file or memory.</P>
+ <P>The HDF5 library comes with a large set of predefined datatypes and
+ offers mechanisms for creating user-defined datatypes.</P>
+ <P>The ten major families or classes of HDF5 datatypes are:</P>
+ <UL>
+ <LI>Integer datatypes</LI>
+ <LI>Floating-point number datatypes</LI>
+ <LI>String datatypes</LI>
+ <LI>Bitfield datatypes</LI>
+ <LI>Opaque datatypes</LI>
+ <LI>Compound datatypes</LI>
+ <LI>Reference datatypes</LI>
+ <LI>Enumerated datatypes</LI>
+ <LI>Variable-length sequence datatypes</LI>
+ <LI>Array datatypes</LI>
+ </UL>
+</DD>
+</DL>
+
+\section GLS_E E
+
+<DL>
+ <DT>Enumeration datatype</DT>
+ <DD>A family of HDF5 datatypes whose elements represent named integer values
+ called members or enumerators. Currently, only ASCII names are supported.</DD>
+</DL>
+
+<DL>
+ <DT>External layout</DT>
+ <DD>A form of contiguous layout where a dataset's elements are physically
+ stored in unformatted binary files outside the HDF5 file.</DD>
+</DL>
+
+<DL>
+ <DT>External link</DT>
+ <DD>An HDF5 link whose destination is specified as a pair of an HDF5 file name
+and an HDF5 path name in that file.</DD>
+</DL>
+
+\section GLS_F F
+
+<DL>
+ <DT>Field</DT>
+ <DD>See compound datatype.</DD>
+</DL>
+
+<DL>
+ <DT>File</DT>
+ <DD>
+ <OL>
+ <LI>A byte stream (in a storage context such as a file system or in
+ memory) formatted according to the HDF5 File Format Specification.</LI>
+ <LI>A (logical) container for HDF5 objects.</LI>
+ </OL>
+ </DD>
+</DL>
+
+<DL>
+ <DT>File format</DT>
+ <DD></DD>
+</DL>
+
+<DL>
+ <DT>Fill value</DT>
+ <DD></DD>
+</DL>
+
+<DL>
+ <DT>Filter</DT>
+ <DD></DD>
+</DL>
+
+\section GLS_G G
+
+<DL>
+ <DT>Group</DT>
+ <DD>
+ <P>A kind of HDF5 object that stores a collection of HDF5 links. Each HDF5
+ file contains at least one group, it's root group.</P>
+ <P>Among the destinations of an HDF5 group's links may be other HDF5 groups
+ (including the group itself!). This ability is sometimes referred to as the
+ closure property of groups. It is the basis for creating hierarchical or
+ more general graph-like structures.</P>
+</DD>
+</DL>
+
+\section GLS_H H
+
+<DL>
+ <DT>Hard link</DT>
+ <DD>An HDF5 link whose destination is specified (internally) as the address of
+ an HDF5 object in the same HDF5 file.</DD>
+</DL>
+
+<DL>
+ <DT>Hierarchy</DT>
+ <DD>See group.</DD>
+</DL>
+
+<DL>
+ <DT>Hyperslab</DT>
+ <DD>
+ <P>A regular multidimensional pattern described by four vectors whose length
+ equals the rank of the pattern.</P>
+ <OL>
+ <LI><CODE>start</CODE> - the offset where the first block of the hyperslab begins</LI>
+ <LI><CODE>stride</CODE> - the offset between pattern blocks</LI>
+ <LI><CODE>count</CODE> - the number of blocks</LI>
+ <LI><CODE>block</CODE> - the extent of an individual pattern block</LI>
+ </OL>
+ <P>For example, the black squares on a (two-dimensional) chessboard with
+ origin at <CODE>(0,0)</CODE> can be represented as the union of two
+ hyperslabs representing the even <CODE>(0,2,4,6)</CODE> and
+ odd <CODE>(1,3,5,7)</CODE> rows, respectively.</P>
+ <IMG SRC="https://upload.wikimedia.org/wikipedia/commons/thumb/d/d7/Chessboard480.svg/176px-Chessboard480.svg.png"/>
+ <P>The hyperslab parameters for the even rows are: <CODE>start (0,0)</CODE>,
+ <CODE>stride (2,2)</CODE>, <CODE>count (4,4)</CODE>, <CODE>block
+ (1,1)</CODE>. Likewise the parameters for the odd rows are: <CODE>start
+ (1,1)</CODE>, <CODE>stride (2,2)</CODE>, <CODE>count
+ (4,4)</CODE>, <CODE>block (1,1)</CODE>.</P>
+</DD>
+</DL>
+
+\section GLS_I I
+
+<DL>
+ <DT>Identifier</DT>
+ <DD>An opaque, transient handle used by the HDF5 library to manipulate
+ in-memory representations of HDF5 items.</DD>
+</DL>
+
+\section GLS_L L
+
+<DL>
+ <DT>Library</DT>
+ <DD></DD>
+</DL>
+
+<DL>
+ <DT>Link</DT>
+ <DD>
+ <P>A named, uni-directional association between a source and a
+ destination. In HDF5, the source is always the HDF5 group that hosts the
+ link in its link collection.</P>
+ <P>There are several ways to specify a link's destination:</P>
+ <UL>
+ <LI>The address of an HDF5 object in the same HDF5 file; so-called hard
+ link.</LI>
+ <LI>A path name in the same or a different file; so-called soft or
+ external link.</LI>
+ <LI>User-defined</LI>
+ </UL>
+ <P>A link name can be any Unicode string that does not contain slashes
+ (<CODE>"/"</CODE>) or consists of a single dot character
+ (<CODE>"."</CODE>). A link name must be unique in a group's link
+ collection.</P>
+ </DD>
+</DL>
+
+\section GLS_M M
+
+<DL>
+ <DT>Metadata</DT>
+ <DD>Data that in a given context has a descriptive or documentation function
+ for other data. Typically, the metadata is small compared to the data it
+ describes.</DD>
+</DL>
+
+<DL>
+ <DT>Member</DT>
+ <DD>
+ <P>A link destination is sometimes referred to as a member of the link's
+ source (group). This way of speaking invites confusion: A destination (e.g.,
+ object) can be the destination of multiple links in the same (!) or
+ different groups. It would then be a "member" of a given group with
+ multiplicity greater than one and be a member of multiple groups.</P>
+ <P> It is the link that is a member of the group's link collection and not
+ the link destination.</P>
+ </DD>
+</DL>
+
+\section GLS_N N
+
+<DL>
+ <DT>Name</DT>
+ <DD>
+ <P>A Unicode string that depending on the item it names might be subject to
+ certain character restrictions, such as ASCII-encoded only. In HDF5, the
+ user might encounter the following names:</P>
+ <UL>
+ <LI>A link name</LI>
+ <LI>A path name</LI>
+ <LI>An attribute name</LI>
+ <LI>A field name (compound datatypes)</LI>
+ <LI>A constant name (enumeration datatypes)</LI>
+ <LI>A tag name (opaque datatypes)</LI>
+ <LI>A file name</LI>
+ </UL>
+ </DD>
+</DL>
+
+
+<DL>
+ <DT>Named datatype</DT>
+ <DD>See committed datatype.</DD>
+</DL>
+
+<DL>
+ <DT>Null dataspace</DT>
+ <DD>A shape which represents the empty set. Array variables with this shape
+ cannot store any values.</DD>
+</DL>
+
+\section GLS_O O
+
+<DL>
+ <DT>Object</DT>
+ <DD>An HDF5 group, dataset or named datatype; an HDF5 item that can be linked
+ to zero or more groups and decorated with zero or more HDF5 attributes.</DD>
+</DL>
+
+<DL>
+ <DT>Object reference</DT>
+ <DD>
+ <OL>
+ <LI>A datatype for representing references to objects in a file.</LI>
+ <LI>A value of the object reference datatype.</LI>
+ </OL>
+ </DD>
+</DL>
+
+<DL>
+ <DT>Opaque datatype</DT>
+ <DD>A family of HDF5 datatypes whose elements are byte sequences of a given
+ fixed length. An opaque datatype can be tagged with a sequence of up to 256
+ ASCII characters, e.g., MIME code.</DD>
+</DL>
+
+\section GLS_P P
+
+<DL>
+ <DT>Path name</DT>
+ <DD>A Unicode string that is the concatenation of link names separated by
+ slashes (<CODE>'/'</CODE>). In HDF5, path names are used to locate and refer
+ to HDF5 objects.</DD>
+</DL>
+
+<DL>
+ <DT>Plugin</DT>
+ <DD>An HDF5 library feature or capability that can be added dynamically at
+ application run time rather than library compilation time. Plugins are
+ usually implemented as shared libraries, and their discovery and loading
+ behavior can be controlled programmatically or through environment
+ variables.
+ </DD>
+</DL>
+
+<DL>
+ <DT>Point selection</DT>
+ <DD>A dataspace selection that consists of a set of points (coordinates) in
+ the same dataspace.</DD>
+</DL>
+
+<DL>
+ <DT>Property list</DT>
+ <DD>
+ <P>An HDF5 API construct, a means of customizing the behavior of the HDF5
+ library when creating, accessing or modifying HDF5 items.</P>
+ <P>While the default property settings are sufficient in many cases, certain
+ HDF5 features, such as compression, can be reasonably controlled only by the
+ user who has to provide the desired settings via property lists.</P>
+</DD>
+</DL>
+
+\section GLS_R R
+
+<DL>
+ <DT>Rank</DT>
+ <DD>The number of dimensions of a non-null dataspace.</DD>
+</DL>
+
+<DL>
+ <DT>Reference</DT>
+ <DD>
+ <OL>
+ <LI>An HDF5 object reference</LI>
+ <LI>An HDF5 dataset region reference</LI>
+ </OL>
+ </DD>
+</DL>
+
+<DL>
+ <DT>Reference datatype</DT>
+ <DD>
+ <OL>
+ <LI>An HDF5 datatype whose elements represent references to HDF5
+ objects.</LI>
+ <LI>An HDF5 datatype whose elements represent references to regions of an
+ HDF5 dataset.</LI>
+ </OL>
+ </DD>
+</DL>
+
+<DL>
+ <DT>Region reference</DT>
+ <DD>See dataset region reference.</DD>
+</DL>
+
+<DL>
+ <DT>Root group</DT>
+ <DD>
+ <P>An HDF5 group that is present in all HDF5 files and that acts as the
+ entry or base point for all other data stored in an HDF5 file.</P>
+ <P>The root group is "the mother of all objects" in an HDF5 file in the
+ sense that all objects (and their attributes) can be discovered,
+ beginning at the root group, by combinations of the following
+ operations:</P>
+ <UL>
+ <LI>Link traversal</LI>
+ <LI>De-referencing of object references</LI>
+ </UL>
+ <P>This discovery is portable and robust with respect to file-internal
+ storage reorganization.</P>
+</DD>
+</DL>
+
+\section GLS_S S
+
+<DL>
+ <DT>Scalar dataspace</DT>
+ <DD>A kind of HDF5 dataspace that has the shape of a singleton, i.e., a set
+ containing a single element. Array variables with this shape store exactly one
+ element.</DD>
+</DL>
+
+<DL>
+ <DT>Selection</DT>
+ <DD>
+ <OL>
+ <LI>A subset of points of an HDF5 dataspace. The subset might be a point
+ selection or a combination (union, intersection, etc.) of hyperslabs.</LI>
+ <LI>A subset of dataset elements associated with a dataspace selection as
+ described under 1.</LI>
+ </OL>
+ </DD>
+</DL>
+
+<DL>
+ <DT>Serialization</DT>
+ <DD>
+ <OL>
+ <LI>The flattening of an N-dimensional array into a 1-dimensional
+ array.</LI>
+ <LI>The encoding of a complex data item as a linear byte stream.</LI>
+ </OL>
+ </DD>
+</DL>
+
+<DL>
+ <DT>Soft link</DT>
+ <DD>A kind of HDF5 link in which the link destination is specified as an HDF5
+ path name. The path name may or may not refer to an actual object.</DD>
+</DL>
+
+<DL>
+ <DT>Storage layout</DT>
+ <DD>The storage arrangement for dataset elements, links in a group's link
+ collection, or attributes in an object's attribute collection.</DD>
+</DL>
+
+<DL>
+ <DT>String datatype</DT>
+ <DD></DD>
+</DL>
+
+<DL>
+ <DT>Super block</DT>
+ <DD>An HDF5 file format primitive; a block of data which contains information
+ required to access HDF5 files in a portable manner on multiple platforms. The
+ super block contains information such as version numbers, the size of offsets
+ and lengths, and the location of the root group.</DD>
+</DL>
+
+<DL>
+ <DT>SWMR</DT>
+ <DD>Single Writer Multiple Reader, a file access mode in which a single
+ process is permitted to write data to an HDF5 file while other processes are
+ permitted to read data from the same file without the need of inter-process
+ communication or synchronization.</DD>
+</DL>
+
+<DL>
+ <DT>Symbolic link</DT>
+ <DD>An external link or a soft link.</DD>
+</DL>
+
+\section GLS_U U
+
+<DL>
+ <DT>User block</DT>
+ <DD>An HDF5 file format primitive that allows one to set aside a fixed-size
+ (at least 512 bytes or any power of 2 thereafter) contiguous range of bytes at
+ the beginning of an HDF5 file for application purposes which will be
+ skipped/ignored by the HDF5 library.</DD>
+</DL>
+
+<DL>
+ <DT>UTF-8</DT>
+ <DD>
+ <P>A variable-length (1-4 bytes per code point) encoding of the Unicode set
+ of code points. This is the encoding supported by HDF5 to represent Unicode
+ strings.</P>
+ <P>The ASCII encoding is a proper subset of UTF-8.</P>
+</DD>
+</DL>
+
+\section GLS_V V
+
+<DL>
+ <DT>Variable-length (sequence) datatype</DT>
+ <DD>A family of HDF5 datatypes whose elements are variable-length sequences of
+ a given datatype.</DD>
+</DL>
+
+<DL>
+ <DT>Virtual Dataset (VDS)</DT>
+ <DD>An HDF5 dataset with virtual storage layout. A dataset whose elements are
+ partially or entirely stored physically in other datasets.</DD>
+</DL>
+
+<DL>
+ <DT>Virtual File Driver (VFD)</DT>
+ <DD></DD>
+</DL>
+
+
+<DL>
+ <DT>Virtual layout</DT>
+ <DD></DD>
+</DL>
+
+
+<DL>
+ <DT>Virtual Object Layer (VOL)</DT>
+ <DD></DD>
+</DL>
+
+*/
diff --git a/doxygen/dox/H5AC_cache_config_t.dox b/doxygen/dox/H5AC_cache_config_t.dox
index 9b9862b..3faecd5 100644
--- a/doxygen/dox/H5AC_cache_config_t.dox
+++ b/doxygen/dox/H5AC_cache_config_t.dox
@@ -26,7 +26,7 @@
*
* \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead
*
- * The trace file is a debuging feature that allow the capture of
+ * The trace file is a debugging feature that allow the capture of
* top level metadata cache requests for purposes of debugging and/or
* optimization. This field should normally be set to \c FALSE, as
* trace file collection imposes considerable overhead.
@@ -82,7 +82,7 @@
* H5C_incr__off ) && ( decr_mode == H5C_decr__off )}). There
* is no logical reason why this should be so, but it simplifies
* implementation and testing, and I can't think of any reason
- * why it would be desireable. If you can think of one, I'll
+ * why it would be desirable. If you can think of one, I'll
* revisit the issue. (JM)
* \endparblock
*
@@ -383,7 +383,7 @@
* to disk.\n
* When the sync point is reached (or when there is a user generated
* flush), process zero flushes sufficient entries to bring it into
- * complience with its min clean size (or flushes all dirty entries in
+ * compliance with its min clean size (or flushes all dirty entries in
* the case of a user generated flush), broad casts the list of
* entries just cleaned to all the other processes, and then exits
* the sync point.\n
diff --git a/doxygen/dox/H5Acreate.dox b/doxygen/dox/H5Acreate.dox
deleted file mode 100644
index 18d648f..0000000
--- a/doxygen/dox/H5Acreate.dox
+++ /dev/null
@@ -1,9 +0,0 @@
-/**
- * \ingroup H5A
- * \def H5Acreate()
- * H5Acreate() is a macro that is mapped to either H5Acreate1() or
- * H5Acreate2().
- *
- *
- * \todo Standardize the way we describe these macros!
- */
diff --git a/doxygen/dox/H5Aiterate.dox b/doxygen/dox/H5Aiterate.dox
deleted file mode 100644
index 46b9bb4..0000000
--- a/doxygen/dox/H5Aiterate.dox
+++ /dev/null
@@ -1,9 +0,0 @@
-/**
- * \ingroup H5A
- * \def H5Aiterate()
- * H5Aiterate() is a macro that is mapped to either H5Aiterate1() or
- * H5Aiterate2().
- *
- *
- * \todo Standardize the way we describe these macros!
- */
diff --git a/doxygen/dox/MetadataCachingInHDF5.dox b/doxygen/dox/MetadataCachingInHDF5.dox
index adaf110..b84ddea 100644
--- a/doxygen/dox/MetadataCachingInHDF5.dox
+++ b/doxygen/dox/MetadataCachingInHDF5.dox
@@ -668,7 +668,7 @@ reduction.
With the hit rate threshold cache size decrement algorithm, the remaining fields
in the section are ignored.
-\subsubsection acsr Ageout Cache Size Reduction
+\subsubsection dacsr Ageout Cache Size Reduction
If \ref H5AC_cache_config_t.decr_mode "decr_mode" is #H5C_decr__age_out the
cache size is decreased by the ageout algorithm, and the remaining fields of the
diff --git a/doxygen/dox/OtherSpecs.dox b/doxygen/dox/OtherSpecs.dox
deleted file mode 100644
index e53f26e..0000000
--- a/doxygen/dox/OtherSpecs.dox
+++ /dev/null
@@ -1,11 +0,0 @@
-/** \page IMG HDF5 Image and Palette Specification Version 1.2
-
-\htmlinclude ImageSpec.html
-
-*/
-
-/** \page TBL HDF5 Table Specification Version 1.0
-
-\htmlinclude TableSpec.html
-
-*/
diff --git a/doxygen/dox/Overview.dox b/doxygen/dox/Overview.dox
index 754722e..040769c 100644
--- a/doxygen/dox/Overview.dox
+++ b/doxygen/dox/Overview.dox
@@ -1,14 +1,12 @@
/** \mainpage notitle
-This is the documentation set for HDF5. You can
-<a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading.
-
-This is the documention set for HDF5 in terms of specifications and software
-developed and maintained by <a href="https://www.hdfgroup.org/">The HDF
-Group</a>. It is impractical to document the entire HDF5 ecosystem in one place,
-and you should also consult the documentation sets of the many outstanding
-community projects.
+This is the documentation set for HDF5.
+It includes specifications and documentation
+of software and tools developed and maintained by
+<a href="https://www.hdfgroup.org/">The HDF Group</a>. It is impractical to document
+the entire HDF5 ecosystem in one place, and you should also consult the documentation
+sets of the many outstanding community projects.
For a first contact with HDF5, the best place is to have a look at the \link
GettingStarted getting started \endlink page that shows you how to write and
@@ -19,12 +17,28 @@ technical documentation consists to varying degrees of information related to
<em>tasks</em>, <em>concepts</em>, or <em>reference</em> material. As its title
suggests, the \link RM Reference Manual \endlink is 100% reference material,
while the \link Cookbook \endlink is focused on tasks. The different guide-type
-documents cover a mix of tasks, concepts, and reference, to help a certain
+documents cover a mix of tasks, concepts, and reference, to help a specific
<em>audience</em> succeed.
-Finally, do not miss the search engine (top right-hand corner)! If you are
-looking for a specific function, it'll take you there directly. If unsure, it'll
-give you an idea of what's on offer and a few promising leads.
+\par Versions
+ Version-specific documentation (see the version in the title area) can be found
+ here:
+ - HDF5 <code>develop</code> branch (this site)
+ - <a href="https://docs.hdfgroup.org/hdf5/v1_12/index.html">HDF5 1.12.x</a>
+ - <a href="https://docs.hdfgroup.org/hdf5/v1_10/index.html">HDF5 1.10.x</a>
+ - <a href="https://docs.hdfgroup.org/hdf5/v1_8/index.html">HDF5 1.8.x</a>
+
+\par Search
+ If you are looking for a specific function, constant, type, etc., use the
+ search box in the top right-hand corner!\n Otherwise, check out the
+ \link FTS full-text search\endlink.
+
+\par Offline reading
+ You can <a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading.
+
+\par History
+ A snapshot (~April 2017) of the pre-Doxygen HDF5 documentation can be found
+ <a href="https://docs.hdfgroup.org/archive/support/HDF5/doc/index.html">here</a>.
\par ToDo List
There is plenty of <a href="./todo.html">unfinished business</a>.
diff --git a/doxygen/dox/RFC.dox b/doxygen/dox/RFC.dox
new file mode 100644
index 0000000..c16dcea
--- /dev/null
+++ b/doxygen/dox/RFC.dox
@@ -0,0 +1,91 @@
+/** \page RFC RFCs
+
+<table>
+<tr><th>RFC ID</th><th>Title</th><th>Comments</th></tr>
+<tr> <td>2021-05-28</td> <td>\ref_rfc20210528</td> <td></td></tr>
+<tr> <td>2019-09-23</td> <td>\ref_rfc20190923</td> <td></td></tr>
+<tr> <td>2019-04-10</td> <td>\ref_rfc20190410</td> <td></td> </tr>
+<tr> <td>2018-12-31</td> <td>\ref_rfc20181231</td> <td></td> </tr>
+<tr> <td>2018-12-20</td> <td>\ref_rfc20181220</td> <td></td> </tr>
+<tr> <td>2018-06-20</td> <td>\ref_rfc20180620</td> <td></td> </tr>
+<tr> <td>2018-06-10</td> <td>\ref_rfc20180610</td> <td></td> </tr>
+<tr> <td>2018-03-21</td> <td>\ref_rfc20180321</td> <td></td> </tr>
+<tr> <td>2018-01-25</td> <td>\ref_rfc20180125</td> <td></td> </tr>
+<tr> <td>2017-07-07</td> <td>\ref_rfc20170707</td> <td></td> </tr>
+<tr> <td>2016-01-05</td> <td>\ref_rfc20160105</td> <td></td> </tr>
+<tr> <td>2015-09-15</td> <td>\ref_rfc20150915</td> <td></td> </tr>
+<tr> <td>2015-07-09</td> <td>\ref_rfc20150709</td> <td></td> </tr>
+<tr> <td>2015-06-15</td> <td>\ref_rfc20150615</td> <td></td> </tr>
+<tr> <td>2015-04-29</td> <td>\ref_rfc20150429</td> <td></td> </tr>
+<tr> <td>2015-04-24</td> <td>\ref_rfc20150424</td> <td></td> </tr>
+<tr> <td>2015-04-23</td> <td>\ref_rfc20150423</td> <td></td> </tr>
+<tr> <td>2015-03-01</td> <td>\ref_rfc20150301</td> <td></td> </tr>
+<tr> <td>2015-02-12</td> <td>\ref_rfc20150212</td> <td></td> </tr>
+<tr> <td>2015-02-05</td> <td>\ref_rfc20150205</td> <td></td> </tr>
+<tr> <td>2015-02-02</td> <td>\ref_rfc20150202</td> <td></td> </tr>
+<tr> <td>2014-12-10</td> <td>\ref_rfc20141210</td> <td></td> </tr>
+<tr> <td>2014-12-01</td> <td>\ref_rfc20141201</td> <td></td> </tr>
+<tr> <td>2014-09-16</td> <td>\ref_rfc20140916</td> <td></td> </tr>
+<tr> <td>2014-08-27</td> <td>\ref_rfc20140827</td> <td></td> </tr>
+<tr> <td>2014-07-29</td> <td>\ref_rfc20140729</td> <td></td> </tr>
+<tr> <td>2014-07-22</td> <td>\ref_rfc20140722</td> <td></td> </tr>
+<tr> <td>2014-07-17</td> <td>\ref_rfc20140717</td> <td></td> </tr>
+<tr> <td>2014-07-07</td> <td>\ref_rfc20140707</td> <td></td> </tr>
+<tr> <td>2014-05-24</td> <td>\ref_rfc20140524</td> <td></td> </tr>
+<tr> <td>2014-03-18</td> <td>\ref_rfc20140318</td> <td></td> </tr>
+<tr> <td>2014-03-13</td> <td>\ref_rfc20140313</td> <td></td> </tr>
+<tr> <td>2014-02-24</td> <td>\ref_rfc20140224</td> <td></td> </tr>
+<tr> <td>2013-12-11</td> <td>\ref_rfc20131211</td> <td></td> </tr>
+<tr> <td>2013-09-30</td> <td>\ref_rfc20130930</td> <td></td> </tr>
+<tr> <td>2013-09-19</td> <td>\ref_rfc20130919</td> <td></td> </tr>
+<tr> <td>2013-06-30</td> <td>\ref_rfc20130630</td> <td></td> </tr>
+<tr> <td>2013-03-16</td> <td>\ref_rfc20130316</td> <td></td> </tr>
+<tr> <td>2012-11-14</td> <td>\ref_rfc20121114</td> <td></td> </tr>
+<tr> <td>2012-10-24</td> <td>\ref_rfc20121024</td> <td></td> </tr>
+<tr> <td>2012-08-28</td> <td>\ref_rfc20120828</td> <td></td> </tr>
+<tr> <td>2012-05-23</td> <td>\ref_rfc20120523</td> <td></td> </tr>
+<tr> <td>2012-05-01</td> <td>\ref_rfc20120501</td> <td></td> </tr>
+<tr> <td>2012-03-05</td> <td>\ref_rfc20120305</td> <td></td> </tr>
+<tr> <td>2012-02-20</td> <td>\ref_rfc20120220</td> <td></td> </tr>
+<tr> <td>2012-01-20</td> <td>\ref_rfc20120120</td> <td></td> </tr>
+<tr> <td>2012-01-04</td> <td>\ref_rfc20120104</td> <td></td> </tr>
+<tr> <td>2011-11-19</td> <td>\ref_rfc20111119</td> <td></td> </tr>
+<tr> <td>2011-08-25</td> <td>\ref_rfc20110825</td> <td></td> </tr>
+<tr> <td>2011-08-11</td> <td>\ref_rfc20110811</td> <td></td> </tr>
+<tr> <td>2011-07-26</td> <td>\ref_rfc20110726</td> <td></td> </tr>
+<tr> <td>2011-06-14</td> <td>\ref_rfc20110614</td> <td></td> </tr>
+<tr> <td>2011-03-29</td> <td>\ref_rfc20110329</td> <td></td> </tr>
+<tr> <td>2011-01-18</td> <td>\ref_rfc20110118</td> <td></td> </tr>
+<tr> <td>2010-11-22</td> <td>\ref_rfc20101122</td> <td></td> </tr>
+<tr> <td>2010-11-04</td> <td>\ref_rfc20101104</td> <td></td> </tr>
+<tr> <td>2010-10-18</td> <td>\ref_rfc20101018</td> <td></td> </tr>
+<tr> <td>2010-09-02</td> <td>\ref_rfc20100902</td> <td></td> </tr>
+<tr> <td>2010-07-27</td> <td>\ref_rfc20100727</td> <td></td> </tr>
+<tr> <td>2010-07-26</td> <td>\ref_rfc20100726</td> <td></td> </tr>
+<tr> <td>2010-05-11</td> <td>\ref_rfc20100511</td> <td></td> </tr>
+<tr> <td>2010-04-22</td> <td>\ref_rfc20100422</td> <td></td> </tr>
+<tr> <td>2010-03-12</td> <td>\ref_rfc20100312</td> <td></td> </tr>
+<tr> <td>2009-12-18</td> <td>\ref_rfc20091218</td> <td></td> </tr>
+<tr> <td>2009-09-07</td> <td>\ref_rfc20090907</td> <td></td> </tr>
+<tr> <td>2009-06-12</td> <td>\ref_rfc20090612</td> <td></td> </tr>
+<tr> <td>2008-12-18</td> <td>\ref_rfc20081218</td> <td></td> </tr>
+<tr> <td>2008-09-15</td> <td>\ref_rfc20080915</td> <td></td> </tr>
+<tr> <td>2008-09-04</td> <td>\ref_rfc20080904</td> <td></td> </tr>
+<tr> <td>2008-03-01</td> <td>\ref_rfc20080301</td> <td></td> </tr>
+<tr> <td>2008-02-09</td> <td>\ref_rfc20080209</td> <td></td> </tr>
+<tr> <td>2008-02-06</td> <td>\ref_rfc20080206</td> <td></td> </tr>
+<tr> <td>2007-11-11</td> <td>\ref_rfc20071111</td> <td></td> </tr>
+<tr> <td>2007-10-18</td> <td>\ref_rfc20071018</td> <td></td> </tr>
+<tr> <td>2007-08-01</td> <td>\ref_rfc20070801</td> <td></td> </tr>
+<tr> <td>2007-04-13</td> <td>\ref_rfc20070413</td> <td></td> </tr>
+<tr> <td>2007-01-15</td> <td>\ref_rfc20070115</td> <td></td> </tr>
+<tr> <td>2006-06-23</td> <td>\ref_rfc20060623</td> <td></td> </tr>
+<tr> <td>2006-06-04</td> <td>\ref_rfc20060604</td> <td></td> </tr>
+<tr> <td>2006-05-05</td> <td>\ref_rfc20060505</td> <td></td> </tr>
+<tr> <td>2006-04-10</td> <td>\ref_rfc20060410</td> <td></td> </tr>
+<tr> <td>2006-03-17</td> <td>\ref_rfc20060317</td> <td></td> </tr>
+<tr> <td>2006-01-24</td> <td>\ref_rfc20060124</td> <td></td> </tr>
+<tr> <td>2004-08-11</td> <td>\ref_rfc20040811</td> <td></td> </tr>
+</table>
+
+*/ \ No newline at end of file
diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox
index 054f4c6..53f64a7 100644
--- a/doxygen/dox/ReferenceManual.dox
+++ b/doxygen/dox/ReferenceManual.dox
@@ -3,35 +3,83 @@
The functions provided by the HDF5 C-API are grouped into the following
\Emph{modules}:
-\li \ref H5A "Attributes" — Management of HDF5 attributes (\ref H5A)
-\li \ref H5D "Datasets" — Management of HDF5 datasets (\ref H5D)
-\li \ref H5S "Dataspaces" — Management of HDF5 dataspaces which describe the shape of datasets and attributes (\ref H5S)
-\li \ref H5T "Datatypes" — Management of datatypes which describe elements of datasets and attributes (\ref H5T)
-\li \ref H5E "Error Handling" — Functions for handling HDF5 errors (\ref H5E)
-\li \ref H5F "Files" — Management of HDF5 files (\ref H5F)
-\li \ref H5Z "Filters" — Configuration of filters that process data during I/O operation (\ref H5Z)
-\li \ref H5G "Groups" — Management of groups in HDF5 files (\ref H5G)
-\li \ref H5I "Identifiers" — Management of object identifiers and object names (\ref H5I)
-\li \ref H5 "Library" — General purpose library functions (\ref H5)
-\li \ref H5L "Links" — Management of links in HDF5 groups (\ref H5L)
-\li \ref H5O "Objects" — Management of objects in HDF5 files (\ref H5O)
-\li \ref H5PL "Plugins" — Programmatic control over dynamically loaded plugins (\ref H5PL)
-\li \ref H5P "Property Lists" — Management of property lists to control HDF5 library behavior (\ref H5P)
-\li \ref H5R "References" — Management of references to specific objects and data regions in an HDF5 file (\ref H5R)
-
-\par API Versioning
- See \ref api-compat-macros
-
-\par Deprecated Functions and Types
- A list of deprecated functions and types can be found
- <a href="./deprecated.html">here</a>.
-
-\par Etiquette
- Here are a few simple rules to follow:
- \li \Bold{Handle discipline:} If you acquire a handle (by creation or copy), \Emph{you own it!} (..., i.e., you have to close it.)
- \li \Bold{Dynamic memory allocation:} ...
- \li \Bold{Use of locations:} Identifier + name combo
+<table>
+<tr><th>Modules</th></tr>
+<tr valign="top">
+<td>
+
+<table>
+<tr><td style="border: none;">
+\li \ref H5A "Attributes (H5A)"
+\li \ref H5D "Datasets (H5D)"
+\li \ref H5S "Dataspaces (H5S)"
+\li \ref H5T "Datatypes (H5T)"
+\li \ref H5E "Error Handling (H5E)"
+\li \ref H5F "Files (H5F)"
+\li \ref H5Z "Filters (H5Z)"
+\li \ref H5G "Groups (H5G)"
+</td><td style="border: none;">
+\li \ref H5I "Identifiers (H5I)"
+\li \ref H5 "Library General (H5)"
+\li \ref H5L "Links (H5L)"
+\li \ref H5O "Objects (H5O)"
+\li \ref H5P "Property Lists (H5P)"
+\li \ref H5PL "Dynamically-loaded Plugins (H5PL)"
+\li \ref H5R "References (H5R)"
+</td><td style="border: none;vertical-align: top;">
+\li \ref api-compat-macros
+\li <a href="./deprecated.html">Deprecated functions</a>
+\li High-level Extensions
+ <ul>
+ <li><a href="https://portal.hdfgroup.org/display/HDF5/Lite">\Bold{HDF5 Lite} (H5LT)</a></li>
+ <li><a href="https://portal.hdfgroup.org/display/HDF5/Images">\Bold{HDF5 Image} (H5IM)</a></li>
+ <li><a href="https://portal.hdfgroup.org/display/HDF5/Tables">\Bold{HDF5 Table} (H5TB)</a></li>
+ <li><a href="https://portal.hdfgroup.org/display/HDF5/Packet+Tables">\Bold{HDF5 Packet Table} (H5TB)</a></li>
+ <li><a href="https://portal.hdfgroup.org/display/HDF5/Dimension+Scales">\Bold{HDF5 Dimension Scale} (H5DS)</a></li>
+ </ul>
+</td></tr>
+<tr><td colspan="3" style="border: none;">
+\ref H5 \ref H5A \ref H5D \ref H5E \ref H5F \ref H5G \ref H5I \ref H5L
+\ref H5O \ref H5P \ref H5PL \ref H5R \ref H5S \ref H5T \ref H5Z
+</td></tr>
+</table>
+
+</td></tr>
+<tr><th>Mind the gap</th></tr>
+<tr><td>
+Follow these simple rules and stay out of trouble:
+
+\li \Bold{Handle discipline:} The HDF5 C-API is rife with handles or
+ identifiers, which you typically obtain by creating new HDF5 items, copying
+ items, or retrieving facets of items. \Emph{You acquire a handle, you own it!}
+ (Colin Powell) In other words, you are responsible for releasing the underlying
+ resources via the matching \Code{H5*close()} call, or deal with the consequences
+ of resource leakage.
+\li \Bold{Closed means closed:} Do not pass identifiers that were previously
+ \Code{H5*close()}-d to other API functions! It will generate an error.
+\li \Bold{Dynamic memory allocation:} The API contains a few functions in which the
+ HDF5 library dynamically allocates memory on the caller's behalf. The caller owns
+ this memory and eventually must free it by calling H5free_memory(). (\Bold{Not}
+ the `free` function \Emph{du jour}!)
+\li \Bold{Be careful with that saw:} Do not modify the underlying collection when an
+ iteration is in progress!
+\li \Bold{Use of locations:} Certain API functions, typically called \Code{H5***_by_name}
+ use a combination of identifiers and path names to refer to HDF5 objects.
+ If the identifier fully specifies the object in question, pass \Code{'.'} (a dot)
+ for the name!
+
+Break a leg!
+</td>
+</tr>
+</table>
\cpp_c_api_note
+\par Don't like what you see? - You can help to improve this Reference Manual
+ Complete the survey linked near the top of this page!\n
+ We treat documentation like code: Fork the
+ <a href="https://github.com/HDFGroup/hdf5">HDF5 repo</a>, make changes, and create a
+ <a href="https://github.com/HDFGroup/hdf5/pulls">pull request</a> !\n
+ See the \ref RMT for general guidance.
+
*/ \ No newline at end of file
diff --git a/doxygen/dox/Specifications.dox b/doxygen/dox/Specifications.dox
index bd7e849..f6fee78 100644
--- a/doxygen/dox/Specifications.dox
+++ b/doxygen/dox/Specifications.dox
@@ -18,4 +18,40 @@
\li <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf">
HDF5 Dimension Scale Specification</a>
-*/ \ No newline at end of file
+*/
+
+/** \page FMT3 HDF5 File Format Specification Version 3.0
+
+\htmlinclude H5.format.html
+
+*/
+
+/** \page FMT2 HDF5 File Format Specification Version 2.0
+
+\htmlinclude H5.format.2.0.html
+
+*/
+
+/** \page FMT11 HDF5 File Format Specification Version 1.1
+
+\htmlinclude H5.format.1.1.html
+
+*/
+
+/** \page FMT1 HDF5 File Format Specification Version 1.0
+
+\htmlinclude H5.format.1.0.html
+
+*/
+
+/** \page IMG HDF5 Image and Palette Specification Version 1.2
+
+\htmlinclude ImageSpec.html
+
+*/
+
+/** \page TBL HDF5 Table Specification Version 1.0
+
+\htmlinclude TableSpec.html
+
+*/
diff --git a/doxygen/dox/TechnicalNotes.dox b/doxygen/dox/TechnicalNotes.dox
index 2bda175..9bd2802 100644
--- a/doxygen/dox/TechnicalNotes.dox
+++ b/doxygen/dox/TechnicalNotes.dox
@@ -1,6 +1,10 @@
/** \page TN Technical Notes
\li \link api-compat-macros API Compatibility Macros \endlink
+\li \ref APPDBG "Debugging HDF5 Applications"
+\li \ref FMTDISC "File Format Walkthrough"
+\li \ref FILTER "Filters"
+\li \ref IOFLOW "HDF5 Raw I/O Flow Notes"
\li \ref TNMDC "Metadata Caching in HDF5"
\li \ref MT "Thread Safe library"
\li \ref VFL "Virtual File Layer"
@@ -13,8 +17,32 @@
*/
+/** \page IOFLOW HDF5 Raw I/O Flow Notes
+
+\htmlinclude IOFlow.html
+
+*/
+
/** \page VFL HDF5 Virtual File Layer
\htmlinclude VFL.html
*/
+
+/** \page FMTDISC HDF5 File Format Discussion
+
+\htmlinclude FileFormat.html
+
+*/
+
+/** \page FILTER HDF5 Filters
+
+\htmlinclude Filters.html
+
+*/
+
+/** \page APPDBG Debugging HDF5 Applications
+
+\htmlinclude DebuggingHDF5Applications.html
+
+*/ \ No newline at end of file
diff --git a/doxygen/dox/cookbook/Accessibility.c b/doxygen/dox/cookbook/Accessibility.c
new file mode 100644
index 0000000..9f8fe55
--- /dev/null
+++ b/doxygen/dox/cookbook/Accessibility.c
@@ -0,0 +1,46 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [set_libver_bounds] -->
+ {
+ __label__ fail_fapl, fail_file;
+ hid_t fapl, file, aspace, attr;
+
+ if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_fapl;
+ }
+#if H5_VERSION_GE(1, 8, 0)
+ if (H5Pset_libver_bounds(fapl, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) < 0) {
+#else
+#error Only HDF5 1.8.x and later supported.
+#endif
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ if ((file = H5Fcreate("set_libver_bounds.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ H5Fclose(file);
+fail_file:
+ H5Pclose(fapl);
+fail_fapl:;
+ }
+ //! <!-- [set_libver_bounds] -->
+
+ assert(ret_val == EXIT_SUCCESS);
+
+ return ret_val;
+}
diff --git a/doxygen/dox/cookbook/Accessibility.dox b/doxygen/dox/cookbook/Accessibility.dox
new file mode 100644
index 0000000..f100283
--- /dev/null
+++ b/doxygen/dox/cookbook/Accessibility.dox
@@ -0,0 +1,39 @@
+/** \page Accessibility
+
+\section Accessibility
+
+\subsection CB_MaintainCompat Maintaining Compatibility with other HDF5 Library Versions
+
+\par Problem
+You want to ensure that the HDF5 files you produce or modify are accessible by all
+releavnt tools and applications
+
+\par Solution
+For HDF5 items (objects, attributes, etc.) that you would like to
+create in new or existing HDF5 files, ascertain the supported range of HDF5
+library versions as lower and upper bounds. When creating new or opening
+existing HDF5 files, use a file access property list and configure the supported
+range via the H5Pset_libver_bounds() function.\n
+In the example below, we restrict HDF5 item creation to the HDF5 1.8.x family of
+library versions.
+\snippet{lineno} Accessibility.c set_libver_bounds
+
+\par Discussion
+See RFC \ref_rfc20160105 for a detailed and comprehensive account of HDF5
+versioning (library, file format spec., etc.) and the H5Pset_libver_bounds()
+function.\n
+The default range #H5F_LIBVER_EARLIEST (low) - #H5F_LIBVER_LATEST (high) offers the
+widest compatibility range, but may not be suitable for certain (feature-)use
+cases.\n
+The HDF5 library comes with a \Emph{forward-} and \Emph{backward-compatibility}
+guarantee: This means that the latest version of the library can always read
+HDF5 files created by a version realesed earlier (backward compatibility).
+It also means that a given release of the library can read the contents of
+HDF5 files created with later versions of the library as long as the files
+do not contain features introduced in later versions (forward compatibility).
+
+\par See Also
+See the recipe \ref CB_LargeAttributes for an example where we use HDF5
+compatibility settings to enable the creation of large HDF5 attributes.
+
+*/ \ No newline at end of file
diff --git a/doxygen/dox/cookbook/Attributes.c b/doxygen/dox/cookbook/Attributes.c
new file mode 100644
index 0000000..6e51cab
--- /dev/null
+++ b/doxygen/dox/cookbook/Attributes.c
@@ -0,0 +1,59 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [large_attribute] -->
+ {
+ __label__ fail_attr, fail_aspace, fail_fapl, fail_file;
+ hid_t fapl, file, aspace, attr;
+
+ if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_fapl;
+ }
+#if H5_VERSION_GE(1, 8, 0)
+ if (H5Pset_libver_bounds(fapl, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) < 0) {
+#else
+#error Only HDF5 1.8.x and later supported.
+#endif
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ if ((file = H5Fcreate("large_attribute.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+
+ if ((aspace = H5Screate_simple(1, (hsize_t[]){1024 * 1024}, NULL)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_aspace;
+ }
+ if ((attr = H5Acreate(file, "4MiB", H5T_IEEE_F32LE, aspace, H5P_DEFAULT, H5P_DEFAULT)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_attr;
+ }
+
+ H5Aclose(attr);
+fail_attr:
+ H5Sclose(aspace);
+fail_aspace:
+ H5Fclose(file);
+fail_file:
+ H5Pclose(fapl);
+fail_fapl:;
+ }
+ //! <!-- [large_attribute] -->
+
+ assert(ret_val == EXIT_SUCCESS);
+
+ return ret_val;
+}
diff --git a/doxygen/dox/cookbook/Attributes.dox b/doxygen/dox/cookbook/Attributes.dox
new file mode 100644
index 0000000..68fd159
--- /dev/null
+++ b/doxygen/dox/cookbook/Attributes.dox
@@ -0,0 +1,38 @@
+/** \page Attributes
+
+\section Attributes
+
+\subsection CB_LargeAttributes Creating "Large" HDF5 Attributes
+
+\par Problem
+You would like to use HDF5 attributes the size of whose values
+exceeds a few dozen kilobytes
+
+\par Solution
+A file format change in the HDF5 1.8.x family of library releases made it
+possible to have attributes larger than about 64 KiB. Ensure that the lower
+library version bound for new HDF5 item creation is at least 1.8.x, and create
+larger attributes as usual.\n
+In the example below, we create an attribute whose value occupies 4 MiB.
+
+\note This feature is only supported in HDF5 1.8.x+
+
+\snippet{lineno} Attributes.c large_attribute
+
+\par Discussion
+Large attributes are supported only in HDF5 versions 1.8.x and higher.
+This has implications for the accessibility of your HDF5 files and
+is your call.\n
+Since there are no size limitations for large attributes, it might
+seem tempting to mistake them for dataset stand-ins. This is not the
+case, for at least two reasons:
+1. Attributes decorate HDF5 objects, have their own local namespace,
+ and can't be link targets.
+2. Attribute I/O treats the attribute value as atomic, i.e., there
+ is no support for partial I/O. A large attribute will always be
+ read or written in its entirety.
+
+\par See Also
+See \ref CB_MaintainCompat for HDF5 compatibility implications.
+
+ */ \ No newline at end of file
diff --git a/doxygen/dox/cookbook/Files.c b/doxygen/dox/cookbook/Files.c
new file mode 100644
index 0000000..1f1f4b1
--- /dev/null
+++ b/doxygen/dox/cookbook/Files.c
@@ -0,0 +1,71 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+ int ret_val = EXIT_SUCCESS;
+
+ //! <!-- [free_space] -->
+ {
+ __label__ fail_fcpl, fail_fapl, fail_file;
+ hid_t fcpl, fapl, file;
+
+ if ((fcpl = H5Pcreate(H5P_FILE_CREATE)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_fcpl;
+ }
+
+ if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_fapl;
+ }
+
+ if ((file = H5Fcreate("free_space.h5", H5F_ACC_TRUNC, fcpl, fapl)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ H5Fclose(file);
+
+fail_file:
+ H5Pclose(fapl);
+fail_fapl:
+ H5Pclose(fcpl);
+fail_fcpl:;
+ }
+ //! <!-- [free_space] -->
+
+ //! <!-- [user_block] -->
+ {
+ __label__ fail_fcpl, fail_file;
+ hid_t fcpl, file;
+
+ if ((fcpl = H5Pcreate(H5P_FILE_CREATE)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_fcpl;
+ }
+ if (H5Pset_userblock(fcpl, 8192 * 1024) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ if ((file = H5Fcreate("userblock.h5", H5F_ACC_TRUNC, fcpl, H5P_DEFAULT)) < 0) {
+ ret_val = EXIT_FAILURE;
+ goto fail_file;
+ }
+ H5Fclose(file);
+
+fail_file:
+ H5Pclose(fcpl);
+fail_fcpl:;
+ }
+ //! <!-- [user_block] -->
+
+ assert(ret_val == EXIT_SUCCESS);
+
+ return ret_val;
+}
diff --git a/doxygen/dox/cookbook/Files.dox b/doxygen/dox/cookbook/Files.dox
new file mode 100644
index 0000000..0b918a0
--- /dev/null
+++ b/doxygen/dox/cookbook/Files.dox
@@ -0,0 +1,31 @@
+/** \page Files
+
+\section Files
+
+\subsection CB_UserBlock Creating an HDF5 File User Block
+
+\par Problem
+You would like to include certain ancillary, non-HDF5 content in an
+HDF5 file such that it can be accessed without the HDF5 library.
+
+\par Solution
+Use a file creation property list in which the user block size is set via
+H5Pset_userblock(). In the example below, we create an 8 MiB user block.
+\snippet{lineno} Files.c user_block
+
+\par Discussion
+The user block begins at offset 0 and must be at least 512 bytes and a power
+of 2. The HDF5 library ignores any content between the beginning of the
+file and the end of the user block.\n
+You can add or strip a user block to/from an existing HDF5 file with the
+\Code{h5jam}/\Code{h5unjam} tool, respectively.
+\warning
+If you try to embed content into the user block for use by other applications,
+pay close attention to how they handle space beyond the last used byte in the
+user block or the user block in general. In the worst case, applications might
+try to truncate the rest of the file and destroy the HDF5 portion of the file.
+
+\par See Also
+References to related recipes
+
+ */ \ No newline at end of file
diff --git a/doxygen/dox/cookbook/Performance.dox b/doxygen/dox/cookbook/Performance.dox
new file mode 100644
index 0000000..7ac3a18
--- /dev/null
+++ b/doxygen/dox/cookbook/Performance.dox
@@ -0,0 +1,21 @@
+/** \page Performance
+
+\section Performance
+
+\subsection CB_MDCPerf Assessing HDF5 Metadata Cache Performance
+
+\par Problem
+You are trying to diagnose and improve the I/O performance of an application
+and would like to understand if a simple metadata cache adjustment might
+yield substantial performance gains
+
+\par Solution
+The to-the-point solution, i.e., the solution w/o any background or explanation
+
+\par Discussion
+A discussion of the fine points and variants of the solution
+
+\par See Also
+References to related recipes
+
+ */ \ No newline at end of file
diff --git a/doxygen/dox/maybe_metadata_reads.dox b/doxygen/dox/maybe_metadata_reads.dox
new file mode 100644
index 0000000..1bb53e0
--- /dev/null
+++ b/doxygen/dox/maybe_metadata_reads.dox
@@ -0,0 +1,50 @@
+/**
+ * \page maybe_metadata_reads Functions with No Access Property List Parameter that May Generate Metadata Reads
+ *
+ * \ingroup GACPL
+ *
+ * Currently there are several operations in HDF5 that can issue metadata reads
+ * from the metadata cache, but that take no property list. It is therefore not
+ * possible to set a collective requirement individually for those operations. The
+ * only solution with the HDF5 1.10.0 release is to set the collective requirement
+ * globally on H5Fopen() or H5Fcreate() for all metadata operations to be
+ * collective.
+ *
+ * The following is a list of those functions in the HDF5 library. This list is
+ * integral to the discussion in the H5Pset_all_coll_metadata_ops() entry:
+ *
+ * H5Awrite(), H5Aread(), H5Arename(), H5Aiterate2(), H5Adelete(), H5Aexists()
+ *
+ * H5Dget_space_status(), H5Dget_storage_size(), H5Dset_extent(), H5Ddebug(),
+ * H5Dclose(), H5Dget_create_plist(), H5Dget_space() (for virtual datasets)
+ *
+ * H5Gget_create_plist(), H5Gget_info(), H5Gclose()
+ *
+ * H5Literate(), H5Lvisit()
+ *
+ * H5Rcreate(), H5Rdereference2() (for object references),
+ * H5Rget_region(), H5Rget_obj_type2(), H5Rget_name()
+ *
+ * H5Ocopy(), H5Oopen_by_addr(), H5Oincr_refcount(), H5Odecr_refcount(),
+ * H5Oget_info(), H5Oset_comment(), H5Ovisit()
+ *
+ * H5Fis_hdf5(), H5Fflush(), H5Fclose(), H5Fget_file_image(), H5Freopen(),
+ * H5Fget_freespace(), H5Fget_info2(), H5Fget_free_sections(), H5Fmount(),
+ * H5Funmount()
+ *
+ * H5Iget_name()
+ *
+ * H5Tget_create_plist(), H5Tclose()
+ *
+ * H5Zunregister()
+ *
+ * In addition, \b most deprecated functions fall into this category.
+ *
+ * The HDF Group may address the above limitation in a future major release, but
+ * no decision has been made at this time. Such a change might, for example,
+ * include adding new versions of some or all the above functions with an extra
+ * property list parameter to allow an individual setting for the collective
+ * calling requirement.
+ *
+ * \sa_metadata_ops
+ */
generated by cgit v0.12 at 2024-07-01 02:28:15 (GMT)