Deploying to gh-pages from @ 1be0ef8 🚀

Author: LTLA

docs/index.html

@@ -79,8 +79,19 @@ <h1>Overview</h1>
 <p >The <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> repository describes a language-agnostic file format for serializing basic <a href="https://r-project.org">R</a> lists. List elements may be atomic vectors, <code>NULL</code>, or nested lists of such objects. It also supports missing values in the vectors and per-element names on the vectors or lists. A mechanism is also provided to handle external references to more complex objects (e.g., S4 classes) that cannot be directly saved into the format.</p>
 <h1>Specifications</h1>
 <p >We support serialization in either HDF5 or (possibly Gzip-compressed) JSON. Both of these are widely used formats and have complementary strengths for list representation. HDF5 supports random access into list components, which can provide optimization opportunities when the list is large and/or contains large atomic vectors. In contrast, JSON is easier to parse and has less storage overhead per list element.</p>
-<p >The full HDF5 specification is provided here.</p>
-<p >The full JSON specification is provided here.</p>
+<p >Both the HDF5 and JSON specifications have multiple versions. Links to the version-specific HDF5 specifications are listed below, along with the minimum version of the C++ library required to parse them:</p>
+<ul>
+<li><a href="https://artifactdb.github.io/uzuki2/md__github_workspace_docs_specifications_compiled_hdf5_1_3.html">1.3</a>, supported by <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> version ≥ 1.3.</li>
+<li><a href="https://artifactdb.github.io/uzuki2/md__github_workspace_docs_specifications_compiled_hdf5_1_2.html">1.2</a>, supported by <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> version ≥ 1.2.</li>
+<li><a href="https://artifactdb.github.io/uzuki2/md__github_workspace_docs_specifications_compiled_hdf5_1_1.html">1.1</a>, supported by <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> version ≥ 1.1.</li>
+<li><a href="https://artifactdb.github.io/uzuki2/md__github_workspace_docs_specifications_compiled_hdf5_1_0.html">1.0</a>, supported by <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> version ≥ 1.0.</li>
+</ul>
+<p >Similarly, different versions of the JSON specification are listed below:</p>
+<ul>
+<li><a href="https://artifactdb.github.io/uzuki2/md__github_workspace_docs_specifications_compiled_json_1_2.html">1.2</a>, supported by <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> version ≥ 1.2.</li>
+<li><a href="https://artifactdb.github.io/uzuki2/md__github_workspace_docs_specifications_compiled_json_1_1.html">1.1</a>, supported by <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> version ≥ 1.1.</li>
+<li><a href="https://artifactdb.github.io/uzuki2/md__github_workspace_docs_specifications_compiled_json_1_0.html">1.0</a>, supported by <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> version ≥ 1.0.</li>
+</ul>
 <h1>Validation</h1>
 <h2>Quick start</h2>
 <p >A reference implementation of the validator is provided as a header-only C++ library in <a href="include/uzuki2"><code>include/uzuki2</code></a>. This is useful for portable deployment in different frameworks like R, Python, etc. We can check that a JSON/HDF5 file complies with the <b>uzuki</b> specification:</p>
@@ -95,20 +106,7 @@ <h2>Quick start</h2>
 </div><!-- fragment --><p >Advanced users can also use the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> parser to load the list into memory. This is achieved by calling <code>parse()</code> with custom provisioner and external reference classes. For example, <a href="tests/src/test_subclass.h"><code>tests/src/test_subclass.h</code></a> defines the <code>DefaultProvisioner</code> and <code>DefaultExternals</code> classes, which can be used to load the HDF5 contents into <code>std::vector</code>s for easier downstream operations.</p>
 <div class="fragment"><div class="line">DefaultExternals ext(nexpected);</div>
 <div class="line"><span class="keyword">auto</span> ptr = uzuki2::hdf5::parse&lt;DefaultProvisioner&gt;(file_path, group_name, ext);</div>
-</div><!-- fragment --><p >The parser supports multiple specification versions, though note the version number of the specification has no direct relationship to the version number of the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> library.</p>
-<table class="markdownTable">
-<tr class="markdownTableHead">
-<th class="markdownTableHeadNone">Library version   </th><th class="markdownTableHeadNone">HDF5 version   </th><th class="markdownTableHeadNone">JSON version    </th></tr>
-<tr class="markdownTableRowOdd">
-<td class="markdownTableBodyNone">1.0.x   </td><td class="markdownTableBodyNone">1.0   </td><td class="markdownTableBodyNone">1.0    </td></tr>
-<tr class="markdownTableRowEven">
-<td class="markdownTableBodyNone">1.1.x   </td><td class="markdownTableBodyNone">1.0 - 1.1   </td><td class="markdownTableBodyNone">1.0 - 1.1    </td></tr>
-<tr class="markdownTableRowOdd">
-<td class="markdownTableBodyNone">1.2.x   </td><td class="markdownTableBodyNone">1.0 - 1.2   </td><td class="markdownTableBodyNone">1.0 - 1.2    </td></tr>
-<tr class="markdownTableRowEven">
-<td class="markdownTableBodyNone">1.3.x   </td><td class="markdownTableBodyNone">1.0 - 1.3   </td><td class="markdownTableBodyNone">1.0 - 1.2   </td></tr>
-</table>
-<p >Also see the <a href="https://artifactdb.github.io/uzuki2">reference documentation</a> for more details.</p>
+</div><!-- fragment --><p >See the <a href="https://artifactdb.github.io/uzuki2">reference documentation</a> for more details.</p>
 <h2>Building projects</h2>
 <h3>CMake with <code>FetchContent</code></h3>
 <p >If you're using CMake, you just need to add something like this to your <code>CMakeLists.txt</code>:</p>

docs/md__github_workspace_docs_specifications_compiled_hdf5_1_0.html

@@ -78,7 +78,7 @@
 <h2>General</h2>
 <p >Every R object is represented by a HDF5 group. In the descriptions below, we use <code>**/</code> as a placeholder for the name of the group.</p>
 <p >All R objects should be nested inside an R list. In other words, the top-level HDF5 group should represent an R list.</p>
-<p >The top-level group may have a <code>uzuki_version</code> attribute, describing the version of the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification that it uses. This should be a scalar string dataset of the form <code>X.Y</code> for non-negative integers <code>X</code> and <code>Y</code>. The latest version of this specification is <b>1.3</b>; if not provided, it is assumed to be <b>1.0</b> for back-compatibility purposes.</p>
+<p >The top-level group should have a <code>uzuki_version</code> attribute, describing the version of the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification that it uses. This attribute should hold a scalar string dataset containing the value "1.0". If not present, the version is assumed to be "1.0" for back-compatibility purposes.</p>
 <h2>Names</h2>
 <p >Some R objects may have a <code>**/names</code> dataset in their HDF5 group. If <code>**/names</code> is supplied, the contents should always be non-missing, so any <code>missing-value-placeholder</code> will not be respected. Each name is allowed to be any string, including an empty string.</p>
 <p >It is technically permitted to provide duplicate names in <code>**/names</code>, consistent with how R itself supports duplicate names in its lists and vectors. However, this is not recommended as other frameworks may wish to use representations that assume unique names, e.g., using Python dictionaries to represent named lists. By providing unique names, users can improve interoperability with native data structures in other frameworks.</p>

docs/md__github_workspace_docs_specifications_compiled_hdf5_1_1.html

@@ -78,7 +78,7 @@
 <h2>General</h2>
 <p >Every R object is represented by a HDF5 group. In the descriptions below, we use <code>**/</code> as a placeholder for the name of the group.</p>
 <p >All R objects should be nested inside an R list. In other words, the top-level HDF5 group should represent an R list.</p>
-<p >The top-level group may have a <code>uzuki_version</code> attribute, describing the version of the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification that it uses. This should be a scalar string dataset of the form <code>X.Y</code> for non-negative integers <code>X</code> and <code>Y</code>. The latest version of this specification is <b>1.3</b>; if not provided, it is assumed to be <b>1.0</b> for back-compatibility purposes.</p>
+<p >The top-level group should have a <code>uzuki_version</code> attribute, describing the version of the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification that it uses. This attribute should hold a scalar string dataset containing the value "1.1".</p>
 <h2>Names</h2>
 <p >Some R objects may have a <code>**/names</code> dataset in their HDF5 group. If <code>**/names</code> is supplied, the contents should always be non-missing, so any <code>missing-value-placeholder</code> will not be respected. Each name is allowed to be any string, including an empty string.</p>
 <p >It is technically permitted to provide duplicate names in <code>**/names</code>, consistent with how R itself supports duplicate names in its lists and vectors. However, this is not recommended as other frameworks may wish to use representations that assume unique names, e.g., using Python dictionaries to represent named lists. By providing unique names, users can improve interoperability with native data structures in other frameworks.</p>

docs/md__github_workspace_docs_specifications_compiled_hdf5_1_2.html

@@ -78,7 +78,7 @@
 <h2>General</h2>
 <p >Every R object is represented by a HDF5 group. In the descriptions below, we use <code>**/</code> as a placeholder for the name of the group.</p>
 <p >All R objects should be nested inside an R list. In other words, the top-level HDF5 group should represent an R list.</p>
-<p >The top-level group may have a <code>uzuki_version</code> attribute, describing the version of the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification that it uses. This should be a scalar string dataset of the form <code>X.Y</code> for non-negative integers <code>X</code> and <code>Y</code>. The latest version of this specification is <b>1.3</b>; if not provided, it is assumed to be <b>1.0</b> for back-compatibility purposes.</p>
+<p >The top-level group should have a <code>uzuki_version</code> attribute, describing the version of the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification that it uses. This attribute should hold a scalar string dataset containing the value "1.2".</p>
 <h2>Names</h2>
 <p >Some R objects may have a <code>**/names</code> dataset in their HDF5 group. If <code>**/names</code> is supplied, the contents should always be non-missing, so any <code>missing-value-placeholder</code> will not be respected. Each name is allowed to be any string, including an empty string.</p>
 <p >It is technically permitted to provide duplicate names in <code>**/names</code>, consistent with how R itself supports duplicate names in its lists and vectors. However, this is not recommended as other frameworks may wish to use representations that assume unique names, e.g., using Python dictionaries to represent named lists. By providing unique names, users can improve interoperability with native data structures in other frameworks.</p>

docs/md__github_workspace_docs_specifications_compiled_hdf5_1_3.html

@@ -78,7 +78,7 @@
 <h2>General</h2>
 <p >Every R object is represented by a HDF5 group. In the descriptions below, we use <code>**/</code> as a placeholder for the name of the group.</p>
 <p >All R objects should be nested inside an R list. In other words, the top-level HDF5 group should represent an R list.</p>
-<p >The top-level group may have a <code>uzuki_version</code> attribute, describing the version of the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification that it uses. This should be a scalar string dataset of the form <code>X.Y</code> for non-negative integers <code>X</code> and <code>Y</code>. The latest version of this specification is <b>1.3</b>; if not provided, it is assumed to be <b>1.0</b> for back-compatibility purposes.</p>
+<p >The top-level group should have a <code>uzuki_version</code> attribute, describing the version of the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification that it uses. This attribute should hold a scalar string dataset containing the value "1.3".</p>
 <h2>Datatypes</h2>
 <p >The HDF5 datatype specification used by each R object is based on the <a href="https://github.com/ArtifactDB/Bioc-HDF5-policy/tree/v0.1.0">HDF5 policy draft (v0.1.0)</a>. This aims to provide readers with a guaranteed type for faithfully representing the data in memory. The draft also describes the use of placeholders to represent missing values within HDF5 datasets.</p>
 <h2>Names</h2>

docs/md__github_workspace_docs_specifications_compiled_json_1_0.html

@@ -77,7 +77,7 @@
 <div class="textblock"><h1>Comments</h1>
 <h2>General</h2>
 <p >All R objects are represented by JSON objects with a <code>type</code> property. Every R object should be nested inside an R list, i.e., the top-level JSON object should represent an R list.</p>
-<p >The top-level object may have a <code>version</code> property that contains the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification version as a <code>"X.Y"</code> string for non-negative integers <code>X</code> and <code>Y</code>. The latest version of this specification is <b>1.2</b>; if missing, the version can be assumed to be <b>1.0</b>.</p>
+<p >The top-level object should have a <code>version</code> property that contains the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification version. This should be a string containing the value "1.0". If not present, the version is assumed to be "1.0" for back-compatibility purposes.</p>
 <h2>Names</h2>
 <p >Some R objects may have a <code>names</code> property in the JSON object. If <code>names</code> is supplied, its contents should always be non-missing. Each name is allowed to be any string, including an empty string.</p>
 <p >It is technically permitted to provide duplicate names in <code>names</code>, consistent with how R itself supports duplicate names in its lists and vectors. However, this is not recommended as other frameworks may wish to use representations that assume unique names, e.g., using Python dictionaries to represent named lists. By providing unique names, users can improve interoperability with native data structures in other frameworks.</p>

docs/md__github_workspace_docs_specifications_compiled_json_1_1.html

@@ -77,7 +77,7 @@
 <div class="textblock"><h1>Comments</h1>
 <h2>General</h2>
 <p >All R objects are represented by JSON objects with a <code>type</code> property. Every R object should be nested inside an R list, i.e., the top-level JSON object should represent an R list.</p>
-<p >The top-level object may have a <code>version</code> property that contains the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification version as a <code>"X.Y"</code> string for non-negative integers <code>X</code> and <code>Y</code>. The latest version of this specification is <b>1.2</b>; if missing, the version can be assumed to be <b>1.0</b>.</p>
+<p >The top-level object should have a <code>version</code> property that contains the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification version. This should be a string containing the value "1.1".</p>
 <h2>Names</h2>
 <p >Some R objects may have a <code>names</code> property in the JSON object. If <code>names</code> is supplied, its contents should always be non-missing. Each name is allowed to be any string, including an empty string.</p>
 <p >It is technically permitted to provide duplicate names in <code>names</code>, consistent with how R itself supports duplicate names in its lists and vectors. However, this is not recommended as other frameworks may wish to use representations that assume unique names, e.g., using Python dictionaries to represent named lists. By providing unique names, users can improve interoperability with native data structures in other frameworks.</p>

docs/md__github_workspace_docs_specifications_compiled_json_1_2.html

@@ -77,7 +77,7 @@
 <div class="textblock"><h1>Comments</h1>
 <h2>General</h2>
 <p >All R objects are represented by JSON objects with a <code>type</code> property. Every R object should be nested inside an R list, i.e., the top-level JSON object should represent an R list.</p>
-<p >The top-level object may have a <code>version</code> property that contains the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification version as a <code>"X.Y"</code> string for non-negative integers <code>X</code> and <code>Y</code>. The latest version of this specification is <b>1.2</b>; if missing, the version can be assumed to be <b>1.0</b>.</p>
+<p >The top-level object should have a <code>version</code> property that contains the <b><a class="el" href="namespaceuzuki2.html" title="Parse an R list from a HDF5 or JSON file.">uzuki2</a></b> specification version. This should be a string containing the value "1.2".</p>
 <h2>Names</h2>
 <p >Some R objects may have a <code>names</code> property in the JSON object. If <code>names</code> is supplied, its contents should always be non-missing. Each name is allowed to be any string, including an empty string.</p>
 <p >It is technically permitted to provide duplicate names in <code>names</code>, consistent with how R itself supports duplicate names in its lists and vectors. However, this is not recommended as other frameworks may wish to use representations that assume unique names, e.g., using Python dictionaries to represent named lists. By providing unique names, users can improve interoperability with native data structures in other frameworks.</p>