HDF5 File Format Specification Version 3.0 missing

News and Announcements Documentation Discussion
1

In the latest incarnation of the documentation ( HDF5: Specifications ), the document “HDF5 File Format Specification Version 3.0” appears to be be not listed.

Here is a copy of the document I am looking for in the archive.
https://support.hdfgroup.org/archive/support/HDF5/doc/H5.format.html

Verison 3 particularly contains " VII. Appendix C: Types of Indexes for Dataset Chunks" which contains details about the “VII.C. The Fixed Array Index” including the format of the “Fixed Array Header” and the “Fixed Array Data Block”.

The information appears to be contained in the develop branch here:

2

HDF has decided that the latest documentation link will point to the version of doxygen in the develop branch. Released versions will continue to be available from the releases download pages. Stay tuned.

3

Thank you for replying.

I am unsure how the branch is relevant to the current issue.
The link for “HDF5 File Format Specification Version 3.0” is missing. The Doxygen source for this document lives in on multiple branches including develop.

I now suspect there is an issue with the Doxygen source code preventing the latest format specification from being linked.

4

So 1.14.x branch did not know about Format 3.
Develop does and if you goto the GH repo and the README;
The latest Doxygen documentation generated on changes to develop, which does not correspond to any particular library release, is available at:

HDF5: Main Page

This will have the 3.0 format in the specifications/file format pages.

5

I’m very confused. I have been referencing “HDF5 File Format Specification Version 3.0” for years now, but you seem to be indicating that version 3.0 is some kind of advanced development version of the specification.

I did some further investigation. I found that “HDF5 File Format Specification Version 3.0” existed with the documention up to 1.14.5. I believe you may have removed it by accident for the 1.14.6 release.

This page indicates it is for “HDF5 Library Release 1.10.1”, modified April 2017:
https://support.hdfgroup.org/archive/support/HDF5/doc/index.html

If I click on “HDF5 Specifications” I go to this page, last modified October 2014 :
https://support.hdfgroup.org/archive/support/HDF5/doc/Specs.html

If I click on the link for “HDF5 File Format Specification”, I get this page titled " HDF5 File Format Specification Version 3.0", last modified April 2016:
https://support.hdfgroup.org/archive/support/HDF5/doc/H5.format.html

Here are links to the same document in the 1.10, 1.12, 1.14, and 1.16 branches:

You removed H5.format.html containing version 3.0 of the specification from 1.14.6 in Pull Request 5261.

In the original version of that pull request to develop (#5204) you correctly replaced H5.format.html with H5.format.3.0.dox.

To summarize, the 1.14.x branch does know about about Format 3. You removed it in from 1.14.6 in #5261. Rather you should have replaced the HTML version with a Doxygen document as in #5204.

1 Like
6

I apologize, yes I was looking at 1.14.6 when I compared the code! So that is why I got it wrong.
However, it is in the current documentation, which will soon be referenced by the “latest” link and going forward, the latest will always be linked to the develop-based documentation.

(It’s been a rough year for documentation)

2 Likes
7

Hi Mark (and community),

I wanted to expand on what Allen said:

I chuckled when I read this. Is it a rough year for documentation, or the group that’s been working to clean up > 25 years of accumulated text? :wink:

Allen (@byrn), myself, and a handful of other coworkers at The HDF Group have a bi-weekly meeting series where we sort through the technical issues and other changes we can make to improve the user experience.

Please keep letting us know when you find missing info, oddities, etc. The forum works as does emailing to help at hdfgroup.org, but for doxygen content held in the Github repositories, feel free to make an issue in the respective repo. It looks like someone else reported this as a GitHub issue around the same time as this post: https://github.com/HDFGroup/HDF5/issues/5435

As Allen mentioned, this remains the URL to keep bookmarked: https://support.hdfgroup.org/documentation/hdf5/latest/

We will be making a subtle change to what shows up at that URL. Instead of being the documentation that came out with the current release (and thus frozen in time until the next release), “latest” will pull from the develop branch, meaning changes/improvements will be immediately accessible. I will make a general announcement here when that’s done.

Again, thanks for pointing out where we can make improvements and fix the potholes.

1 Like