HDF5 Documentation

1
HDF5 Documentation
An overview of the HDF5 document set
Frank Baker Technical Writer The HDF Group (217)
244-7223 fbaker_at_hdfgroup.org
2
Objectives

• To make sure people are aware of various elements
  of HDF documentation, particularly HDF5
• To encourage feedback
• How can the docs better serve you?
• Let us know when you see errors.help_at_hdfgroup.org
  
• Well come back to this.

3
HDF Documentation

• HDF4
• C Library APIs and Fortran wrappers
• Tools -- Data management and viewing
• HDF5
• C Library APIs and High-level APIs
• Fortran, C and Java wrappers and subroutines
• Tools -- Data management and viewing Software
  configuration, build and install
• HDF4 to HDF5 Conversion Library
• HDF Java products
• HDFview

4
HDF5 Documentation for All Users

• Users with all types of needs can find relevant
  information
• Data users
• Application Developers
• Library and driver developers

Tools Applications
HDF I/O Library
Files
5
HDF5 Data Users
Tools Applications

• To examine data and browse HDF5 files
• HDF5 Tools
• Command-line utilities
• Browsers
• HDFview offers limited editing features
• Glossary

HDF I/O Library
Files
6
HDF5 Application Developers
Tools Applications

• Writing applications for your own data and for
  large projects
• HDF5 Tutorials
• Introduction to HDF5
• HDF5 Users Guide
• HDF5 Reference Manual
• HDF5 Tools
• Example programs and HDF5 source code
• FAQs
• Glossary

HDF I/O Library
Files
7
HDF5 Application Developers (2)
Tools Applications

• As projects progress, programs endure, and
  applications become more complex
• HDF5 Application Developers Guide
• Software Changes from Release to Release
• HDF5 File Format Specification

HDF I/O Library
Files
8
HDF5 Library and I/O Driver Developers
Tools Applications

• Developing I/O drivers and working inside the
  HDF5 Library
• HDF5 Technical Notes for Library and Driver
  Developers

HDF I/O Library
Files
9
Non-C Interfaces to HDF5

• HDF5 Library is written in C.
• But Fortran, C, Java interfaces are also
  available. (And C is on the way.)
• Where would one find that documentation?

10
Fortran, C and Java Interfaces

• All linked from index page
• Under HDF5 and Foreign Languages
• http//hdfgroup.org/HDF5/doc/
• Fortran
• Embedded with C APIs in HDF5 Reference Manual
• http//hdfgroup.org/HDF5/doc/RM/
• C
• Separate reference manual http//hdfgroup.org/HDF5
  /doc/cpplus_RM/index.html
• Java
• Separate subsite
• http//hdfgroup.org/hdf-java-html/

11
Additional HDF5 Documentation, Features

• Pre-release snapshots
• Routinely-provided snapshots at
  doc_dev_snapshot/The current state of a
  development or release branchhttp//hdfgroup.com/
  HDF5/doc_dev_snapshot/
• 1.8 pre-release series, alphas and
  betashttp//hdfgroup.org/HDF5/doc_1.8pre/
• Requests for Comment (RFCs), generally with
  substantial design material
• User input is critical!
• Participation leads to involvement!
• Let us know if youre interested!

12
A Walking Tour
13
Native and Distribution Formats

• Generally HTML
• HDF5 Reference Manual and HDF5 Users Guide
• Printable book style PDF versions generated at
  major releases
• Core documents set designed to be served from a
  website or viewed from a local installation
• All docs except HDF5 Tutorial
• Tarball available for local or behind-the-firewall
  installation

14
Credit Where Credit Is Due

• Developers participate heavily in creating and
  maintaining the documentation
• Core library developers routinely provide
• Initial reference manual entries
• Major chunks of text and examples for the user
  guides
• RFCs, from which other documentation is often
  built
• Entire ADGuide and TechNotes documents
• Binh-Minh Ribler C docs, with doxygen
• Peter Cao HDFview and other Java products, with
  Java Doc
• And everybody reviews!

15
Your feedback matters!

• Let us know when you find any problem
• Errors
• Incomplete information
• Areas where more explanation (or the right,
  targeted explanation) would have helped you avoid
  a problem or otherwise saved you time
• help_at_hdfgroup.org

16
Your feedback matters!

• Beyond that
• Suggestions?
• What gives you the most difficulty?
• What is most helpful?
• Whats missing?

17
The End
This report is based upon work supported in part
by a Cooperative Agreement with NASA under NASA
NNG05GC60A. Any opinions, findings, and
conclusions or recommendations expressed in this
material are those of the author(s) and do not
necessarily reflect the views of the National
Aeronautics and Space Administration.
18
Contact Information

• Frank Baker
• Senior Technical Writer
• The HDF Group
• 1901 South First Street
• Champaign, IL 61820 USA
• [phone]
• fbaker_at_hdfgroup.org

19
URLs

• HDF5 Tools hdfgroup.org/HDF5/doc/Tools.html
• HDF5 Docs Index hdfgroup.org/HDF5/doc/ lt
  Ties it all together.
• Pre-releases and Snapshots hdfgroup.org/HDF5/doc_
  1.8pre/
• hdfgroup.org/HDF5/doc_dev_snapshot/
• RFCs hdfgroup.org/RFC/
• HDF5 Tutorial hdfgroup.org/HDF5/Tutor/index.html
• Printable Documents hdfgroup.org/HDF5/doc/PSandPD
  F/
• Bug Reports and Enhancement Requests help_at_hdfg
  roup.org
• FAQs hdfgroup.org/HDF5-FAQ.html

20
And back to your feedback

• Beyond that
• Suggestions?
• What gives you the most difficulty?
• What is most helpful?
• Whats missing?

21
index.html -- An Alternative Style
22
Slide Title
23
Slide Title
24
Slide Title
Common application-specific data models
HDF5 data model API