Next batch of Doxygen updates. (#1180)

* Sketch of the H5S life cycle.

* Committing clang-format changes

* Fix H5S_UNLIMITED snafu.

* Updated RM template and RM page.

* Added H5S life cycle.

* Committing clang-format changes

* Added H5T life cycle.

* Committing clang-format changes

* Cleaner layout (?)

* Cleaned the H5F life cycle. Called out unfinished biz.

* Committing clang-format changes

* Remaining life cycle skeletons.

* Committing clang-format changes

* Committing clang-format changes

* Added H5Z life cycle.

* Committing clang-format changes

* Added H5G life cycle.

* Committing clang-format changes

* H5 and H5I life cycle updates.

* Committing clang-format changes

* Added H5PL life cycle.

* Committing clang-format changes

* Added H5L life cycle.

* Committing clang-format changes

* Fix for Chris' comment.

* Add a variable for Doxygen pre-processor definitions.

* Forgot to add the H5M API.

* Clarify the H5Z life cycle.

* Committing clang-format changes

* Add H5Zdevelop.h to Doxygen.in. Added H5I life cycle.

* Committing clang-format changes

* Clarified introduction and fixed missing label declaration.

* Added H5O life cycle.

* Committing clang-format changes

* H5O cleanup, part 1.

* Committing clang-format changes

* Cleaned up some of the endless repetition in H5O.

* Committing clang-format changes

* Cookbook & RFC draft layouts.

* Updated manifest.

* Updated the manifest, the example paths, and sketched the 1st recipe.

* Committing clang-format changes

* Outlined two more recipes.

* Committing clang-format changes

* More recipes and RFCs.

* Committing clang-format changes

* Draft of templatized RFC references.

* Another batch of RFC changes.

* Another batch of RFCs.

* Fixed reference.

* RFCs in reverse chronological order.

* First cut of RFCs.

* Fixed reference.

* Updated recipes.

* Updated recipes.

* More RFCs.

* Updated D*PL comments.

* Added H5P descriptions.

* Committing clang-format changes

* H5R life-cycle snapshot.

* Committing clang-format changes

* H5R life-cycle. Added line numbers to life-cycle examples.

* Committing clang-format changes

* Fixed formatting for H5Dchunk_iter().

* Added comment on collective mode requirement w/ compression.

* Simplified API compat. macro dox.

* More API vers. updates.

* Hide the async macro entrails.

* Latest VFD SWMR RFC.

* Create a tag file for permalinks.

* Added TODOs for metadoc.

* Removed duplication.

* Revised RM landing page.

* Trimmed more duplication.

* Committing clang-format changes

* Revised H5D.

* Committing clang-format changes

* Updated survey link.

* Added Doxygen RM entry template link.

* Added the "Multi-Thread HDF5" RFC.

* Added DOXYGEN_TAG_FILE.

* Added selection I/O RFC.

* Added the VFD Sub-filing RFC.

* Updated meta-documentation and added two old presentations.

* Added a few more RFCs (4).

* Fixed MANIFEST.

* Updated meta-documentation.

* Added Filters technical note.

* Fixed MANIFEST.

* Restore the path stripper.

* Experimental full-text search via Google.

* Better full-text search integration.

* Whoops. Forgot this one.

* Oh boy.

* Make CMake happy.

* Added "Debugging HDF5 Applications" technical note.

* Another batch of RFCs.

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

7 files changed, 195 insertions, 42 deletions

diff --git a/doxygen/dox/About.dox b/doxygen/dox/About.dox
index 32930a8..0b21fcc 100644
--- a/doxygen/dox/About.dox
+++ b/doxygen/dox/About.dox
@@ -12,12 +12,118 @@ of <em>documentation done right</em>.
 
 \section about_documentation Documentation about Documentation
 
-\li \todo Describe how to add a reference or a new RFC
-\li \todo Describe how to add an example
-\li \todo Describe how to include plain HTML
-\li \todo Describe how to add an API macro
-\li \todo Describe the custom commands
-\li \todo Describe the S3 bucket layout and update routine
-\li \todo Link the RM template
+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!
+
+\todo Make the publication a GitHub action!
 
 */
\ 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/FileFormatSpec.dox b/doxygen/dox/FileFormatSpec.dox
deleted file mode 100644
index fc10574..0000000
--- a/doxygen/dox/FileFormatSpec.dox
+++ /dev/null
@@ -1,23 +0,0 @@
-/** \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
-
-*/
\ No newline at end of file
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/RFC.dox b/doxygen/dox/RFC.dox
index c16dcea..c2562b0 100644
--- a/doxygen/dox/RFC.dox
+++ b/doxygen/dox/RFC.dox
@@ -3,10 +3,17 @@
 <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>2021-02-19</td> <td>\ref_rfc20210219</td> <td></td></tr>
+<tr> <td>2020-02-13</td> <td>\ref_rfc20200213</td> <td></td></tr>
+<tr> <td>2020-02-10</td> <td>\ref_rfc20200210</td> <td></td></tr>
 <tr> <td>2019-09-23</td> <td>\ref_rfc20190923</td> <td></td></tr>
+<tr> <td>2019-07-15</td> <td>\ref_rfc20190715</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-08-30</td> <td>\ref_rfc20180830</td> <td></td> </tr>
+<tr> <td>2018-08-29</td> <td>\ref_rfc20180829</td> <td></td> </tr>
+<tr> <td>2018-08-15</td> <td>\ref_rfc20180815</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>
@@ -69,8 +76,12 @@
 <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-12-05</td> <td>\ref_rfc20081205</td> <td></td> </tr>
+<tr> <td>2008-10-30</td> <td>\ref_rfc20081030</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-07-28</td> <td>\ref_rfc20080728</td> <td></td> </tr>
+<tr> <td>2008-07-23</td> <td>\ref_rfc20080723</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>
diff --git a/doxygen/dox/Specifications.dox b/doxygen/dox/Specifications.dox
index 4ae48d0..5a36d61 100644
--- a/doxygen/dox/Specifications.dox
+++ b/doxygen/dox/Specifications.dox
@@ -19,4 +19,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..0cabdeb 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,30 @@
 
 */
 
+/** \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