Skip to content

Commit 34dbc28

Browse files
committed
docs: drop confusing "HDF5 v3" phrasing in favor of H5Z_class3_t
"HDF5 v3" reads as "HDF5 library 3.0", but the new plugin class H5Z_class3_t ships in HDF5 2.x. Rename the section heading, the subsection on updating existing registrations, and replace "v3-aware library" / "v3 build" / "HDF5 v3 plugin" wording with direct references to H5Z_class3_t or "HDF5 2.x" as appropriate. The plugin-class version ("v3", as in v1/v2/v3 of H5Z_class_t) is retained only where the versioning of the class itself is the subject.
1 parent 83e401a commit 34dbc28

1 file changed

Lines changed: 9 additions & 9 deletions

File tree

docs/RegisteredFilterPlugins.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Any member of the HDF5 community can register a plugin for their or a third-part
1111
* Maintainer's contact information. Minimum an email address, preferably additional information like personal website, GitHub or social network handles. More ways to contact the responsible maintainer is better.
1212
* Filter plugin's respository.
1313
* Description of the new plugin including the specifics of the filter parameters (`cd_nelmts` and `cd_values[]`) supported by the plugin.
14-
* A proposed **canonical name** for the filter. This is the short, stable string identifier that an HDF5 v3 (`H5Z_class3_t`) plugin will advertise in its `name` field and that the library will write into the on-disk filter-pipeline message. The canonical name must be non-empty, no more than 255 bytes, drawn from the character class `[A-Za-z0-9_.-]`, and is matched case-sensitively. See [Canonical Names](#canonical-names-hdf5-v3--h5z_class3_t) below for details. (Existing v1/v2 plugins without a canonical name continue to work unchanged; this only becomes load-bearing when a plugin opts into v3.)
14+
* A proposed **canonical name** for the filter. This is the short, stable string identifier that an `H5Z_class3_t` plugin will advertise in its `name` field and that the library will write into the on-disk filter-pipeline message. The canonical name must be non-empty, no more than 255 bytes, drawn from the character class `[A-Za-z0-9_.-]`, and is matched case-sensitively. See [Canonical Names](#canonical-names-h5z_class3_t-plugin-class) below for details. (Existing `H5Z_class1_t`/`H5Z_class2_t` plugins without a canonical name continue to work unchanged; this only becomes load-bearing when a plugin opts into the v3 plugin class.)
1515
* Links to any relevant documentation, including the licensing information.
1616

1717
Upon receiving a request with the above information, HDF Group will register the new plugin by assigning it a filter plugin _identifier_. The current policy for assigning an identifier is explained below:
@@ -25,7 +25,7 @@ Upon receiving a request with the above information, HDF Group will register the
2525

2626
## List of Filter Plugins Registered with The HDF Group
2727

28-
The **Canonical Name** column is the string identifier used by HDF5 v3 (`H5Z_class3_t`) plugins. Entries marked _(proposed)_ are pending confirmation by the plugin maintainer; see [Canonical Names](#canonical-names-hdf5-v3--h5z_class3_t) and the [tracking issue](https://github.com/HDFGroup/hdf5_plugins/issues/255).
28+
The **Canonical Name** column is the string identifier used by `H5Z_class3_t` plugins. Entries marked _(proposed)_ are pending confirmation by the plugin maintainer; see [Canonical Names](#canonical-names-h5z_class3_t-plugin-class) and the [tracking issue](https://github.com/HDFGroup/hdf5_plugins/issues/255).
2929

3030
| Plugin Identifier | Canonical Name | For Filter | Short Description|
3131
|--------|--------|----------------|---------------------|
@@ -69,14 +69,14 @@ The **Canonical Name** column is the string identifier used by HDF5 v3 (`H5Z_cla
6969
> [!NOTE]
7070
> Please contact the maintainer of a filter plugin for help with the plugin or its filter in the HDF5 library.
7171
72-
## Canonical Names (HDF5 v3 / `H5Z_class3_t`)
72+
## Canonical Names (`H5Z_class3_t` plugin class)
7373

74-
Starting with the v3 plugin class (`H5Z_class3_t`) introduced in HDF5 2.x, every registered filter has a **canonical name**: a short, stable string identifier used by callers, tools, and the on-disk format.
74+
Starting with the v3 filter plugin class (`H5Z_class3_t`), introduced in HDF5 2.x, every registered filter has a **canonical name**: a short, stable string identifier used by callers, tools, and the on-disk format.
7575

7676
### Where the canonical name appears
7777

78-
* **In the plugin source.** A v3 plugin sets `H5Z_class3_t::name` to its canonical name.
79-
* **In the file.** When a v3-aware library adds a filter to a dataset's pipeline, it writes the canonical name into the filter-pipeline message (`H5O_PLINE`), so tools like `h5dump` can identify the filter even when the plugin shared library is not installed.
78+
* **In the plugin source.** An `H5Z_class3_t` plugin sets its `name` to the canonical name.
79+
* **In the file.** When an HDF5 library that supports `H5Z_class3_t` adds a filter to a dataset's pipeline, it writes the canonical name into the filter-pipeline message (`H5O_PLINE`), so tools like `h5dump` can identify the filter even when the plugin shared library is not installed.
8080
* **In the API.** The forthcoming `H5Pappend_filter("canonical_name", "params")` interface accepts the canonical name to identify the filter, and accepts a TOML inline table parameter string for typed configuration. (Numeric filter IDs continue to work via the existing `H5Pset_filter` interface.)
8181
* **In CLI tools.** `h5repack`, `h5dump`, and other tools display the canonical name when printing filter information.
8282

@@ -97,13 +97,13 @@ The HDF Group assigns a canonical name alongside the numeric `id` at filter-regi
9797

9898
Third-party plugins that have not gone through HDF Group filter registration should self-namespace their canonical names (for example, `org.example.fastlz`) to make accidental collisions vanishingly unlikely. Coordinated registration through The HDF Group remains the recommended path for plugins that want a short, bare name.
9999

100-
### Updating an existing registration for v3
100+
### Updating an existing registration for `H5Z_class3_t`
101101

102-
Existing filter plugins continue to work unchanged with HDF5 v3-aware libraries; the canonical name only becomes load-bearing when a plugin opts into the new `H5Z_class3_t` class. Maintainers of currently registered plugins should:
102+
Existing filter plugins continue to work unchanged with HDF5 2.x; the canonical name only becomes load-bearing when a plugin opts into the new `H5Z_class3_t` class. Maintainers of currently registered plugins should:
103103

104104
1. Review the proposed canonical name in the table above for your filter ID.
105105
2. Confirm or propose a correction by replying on the [tracking issue](https://github.com/HDFGroup/hdf5_plugins/issues/255) or contacting the HDF Group [Helpdesk](mailto:help@hdfgroup.org). Confirmations replace _(proposed)_ in the table.
106-
3. When shipping a v3 build of the plugin, set `H5Z_class3_t::name` to the registered canonical name byte-identically.
106+
3. When porting the plugin to `H5Z_class3_t`, set the `name` field to the registered canonical name byte-identically.
107107

108108
See the HDF5 RFC on string-configured filters (RFC-HDFG-2026-001) for the full v3 design.
109109

0 commit comments

Comments
 (0)