[svn-r3176]

Purpose:
    Added h4toh5
Platforms tested:
    IE 5

1 files changed, 247 insertions, 68 deletions

diff --git a/doc/html/Tools.html b/doc/html/Tools.html
index 5b79cbc..1577b09 100644
--- a/doc/html/Tools.html
+++ b/doc/html/Tools.html
@@ -55,14 +55,16 @@ These tools enable the user to examine HDF5 files interactively.
 <table border=0>
 <tr><td valign=top>
 <ul>
-    <li><a href="#Tools-Dump">h5dump</a> -- A tool for displaying 
-        HDF5 file contents
-    <li><a href="#Tools-Ls">h5ls</a> -- A tool for listing specified
-        features of HDF5 file contents
-    <li><a href="#Tools-Repart">h5repart</a> -- A tool for repartitioning 
-        a file, creating a family of files
-    <li><a href="#Tools-H5toh4">h5toh4</a> -- A tool for converting an 
-        HDF5 file to an HDF4 file.
+    <li><a href="#Tools-Dump">h5dump</a> -- 
+        A tool for displaying HDF5 file contents
+    <li><a href="#Tools-Ls">h5ls</a> -- 
+        A tool for listing specified features of HDF5 file contents
+    <li><a href="#Tools-Repart">h5repart</a> -- 
+        A tool for repartitioning a file, creating a family of files
+    <li><a href="#Tools-H5toh4">h5toh4</a> -- 
+        A tool for converting an HDF5 file to an HDF4 file
+    <li><a href="#Tools-H4toh5">h4toh5</a> -- 
+        A tool for converting an HDF4 file to an HDF5 file
 </ul>
 </td></tr>
 </table>
@@ -157,35 +159,36 @@ These tools enable the user to examine HDF5 files interactively.
             <dd>Displays the specified named data type(s).
         <dt><code>-w</code> <em>number</em>
             <dd>Displays the information with the specified number of columns.
-				<dt><code>-o</code> <em>filename</em>
-						<dd>Output the raw data of datasets to a separate file <code>filename</code>.
+        <dt><code>-o</code> <em>filename</em>
+            <dd>Output the raw data of datasets to a separate file 
+                <code>filename</code>.
         <dt><em>file</em>
             <dd>The file to be examined.
     </dl>
 <dt><strong>Examples:</strong>
-		<ol>
-			<li>Dumping the group <code>/GroupFoo/GroupBar</code> in the file
-			    <code>quux.h5</code>:
-					<blockquote>
-						<code>h5dump -g /GroupFoo/GroupBar quux.h5</code>
-					</blockquote></li>
-			<li>Dumping the dataset <code>Fnord</code> in the group
-			    <code>/GroupFoo/GroupBar</code> in the file <code>quux.h5</code>:
-					<blockquote>
-						<code>h5dump -d /GroupFoo/GroupBar/Fnord quux.h5</code>
-					</blockquote></li>
-		  <li>Dumping the attribute <code>metadata</code> of the dataset
-			  	<code>Fnord</code> which is in group
-			  	<code>/GroupFoo/GroupBar</code> in the file <code>quux.h5</code>:
-			  	<blockquote>
-			  		<code>h5dump -a /GroupFoo/GroupBar/Fnord/metadata quux.h5</code>
-			  	</blockquote></li>
-			<li>Dumping the attribute <code>metadata</code> which is an
-			    attribute of the root group in the file <code>quux.h5</code>:
-					<blockquote>
-						<code>h5dump -a /metadata quux.h5</code>
-					</blockquote></li>
-		</ol>
+    <ol>
+       <li>Dumping the group <code>/GroupFoo/GroupBar</code> in the file
+          <code>quux.h5</code>:
+          <blockquote>
+             <code>h5dump -g /GroupFoo/GroupBar quux.h5</code>
+          </blockquote>
+       <li>Dumping the dataset <code>Fnord</code> in the group
+          <code>/GroupFoo/GroupBar</code> in the file <code>quux.h5</code>:
+          <blockquote>
+             <code>h5dump -d /GroupFoo/GroupBar/Fnord quux.h5</code>
+          </blockquote>
+       <li>Dumping the attribute <code>metadata</code> of the dataset
+          <code>Fnord</code> which is in group
+          <code>/GroupFoo/GroupBar</code> in the file <code>quux.h5</code>:
+          <blockquote>
+             <code>h5dump -a /GroupFoo/GroupBar/Fnord/metadata quux.h5</code>
+          </blockquote>
+       <li>Dumping the attribute <code>metadata</code> which is an
+          attribute of the root group in the file <code>quux.h5</code>:
+          <blockquote>
+              <code>h5dump -a /metadata quux.h5</code>
+          </blockquote>
+    </ol>
 <dt><strong>Current Status:</strong>
     <dd>The current version of <code>h5dump</code> displays the
         following information:
@@ -258,44 +261,58 @@ These tools enable the user to examine HDF5 files interactively.
         in the specified format.
 <dt><strong>Options and Parameters:</strong>
     <dl>
-        <dt><code>-h</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>-?</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--help</code>
+        <dt><code>-h</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>-?</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--help</code>
             <dd>Print a usage message and exit.
-				<dt><code>-a</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--address</code>
-						<dd>Primt addresses for raw data.
+        <dt><code>-a</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--address</code>
+            <dd>Primt addresses for raw data.
         <dt><code>-d</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--data</code>
             <dd>Print the values of datasets.
-				<dt><code>-e</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--errors</code>
-						<dd>Show all HDF5 error reporting.
-				<dt><code>-f</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--full</code>
-						<dd>Print full path names instead of base names.
-				<dt><code>-g</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--group</code>
-						<dd>Show information about a group, not its contents.
-				<dt><code>-l</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--label</code>
-						<dd>Label members of compound datasets.
-				<dt><code>-r</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--recursive</code>
-						<dd>List all groups recursively, avoiding cycles.
-				<dt><code>-s</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--string</code>
-						<dd>Print 1-bytes integer datasets as ASCII.
-				<dt><code>-S</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--simple</code>
-						<dd>Use a machine-readable output format.
-        <dt><code>-w</code><em>N</em> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--width=</code><em>N</em>
+        <dt><code>-e</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--errors</code>
+            <dd>Show all HDF5 error reporting.
+        <dt><code>-f</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--full</code>
+            <dd>Print full path names instead of base names.
+       	<dt><code>-g</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--group</code>
+            <dd>Show information about a group, not its contents.
+        <dt><code>-l</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--label</code>
+            <dd>Label members of compound datasets.
+        <dt><code>-r</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--recursive</code>
+            <dd>List all groups recursively, avoiding cycles.
+        <dt><code>-s</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--string</code>
+            <dd>Print 1-bytes integer datasets as ASCII.
+        <dt><code>-S</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--simple</code>
+            <dd>Use a machine-readable output format.
+        <dt><code>-w</code><em>N</em> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--width=</code><em>N</em>
             <dd>Set the number of columns of output.
-        <dt><code>-v</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--verbose</code>
+        <dt><code>-v</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--verbose</code>
             <dd>Generate more verbose output.
-        <dt><code>-V</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--version</code>
+        <dt><code>-V</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--version</code>
             <dd>Print version number and exit.
-				<dt><code>-x</code> &nbsp;&nbsp;or&nbsp;&nbsp; <code>--hexdump</code>
-						<dd>Show raw data in hexadecimal format.
+        <dt><code>-x</code> &nbsp;&nbsp;or&nbsp;&nbsp; 
+              <code>--hexdump</code>
+            <dd>Show raw data in hexadecimal format.
         <dt><em>file</em>
             <dd>The file name may include a printf(3C) integer format 
                 such as <code>%%05d</code> to open a file family.
         <dt><em>objects</em>
             <dd>Each object consists of an HDF5 file name optionally
-						    followed by a slash and an object name within the file
-								(if no object is specified within the file then the
-								 contents of the root group are displayed). The file name
-								may include a <code>printf(3C)</code> integer format such
-								as "%05d" to open a file family.
+                followed by a slash and an object name within the file
+                (if no object is specified within the file then the
+                contents of the root group are displayed). The file name
+                may include a <code>printf(3C)</code> integer format such
+                as "%05d" to open a file family.
     </dl>
 <!--
 <dt><strong>Current Status:</strong>
@@ -392,7 +409,7 @@ These tools enable the user to examine HDF5 files interactively.
         single file name case above.
         <p>
         The <code>-h</code> option causes the following
-        syntax summary to be displayed:<br>
+        syntax summary to be displayed:
         <pre>              h5toh4 file.h5 file.hdf
               h5toh4 file.h5
               h5toh4 -m file1.h5 file2.h5 ...</pre>
@@ -425,10 +442,10 @@ These tools enable the user to examine HDF5 files interactively.
               compound datatype are constrained to be no more 
               than rank 4.
           <li>HDF5 dataset objects of single dimension and fixed length string
-              datatype are converted into HDF4 Vdata objects. The HDF4 Vdata is a
-              single field whose order is the length of the HDF5 string type. The
-              number of records of the Vdata is the length of the single dimension
-              which may be fixed or extendable.
+              datatype are converted into HDF4 Vdata objects.  The HDF4 Vdata 
+              is a single field whose order is the length of the HDF5 string 
+              type.  The number of records of the Vdata is the length of the 
+              single dimension which may be fixed or extendable.
         </ul>
 
         Other objects are not converted and are not recorded
@@ -436,8 +453,8 @@ These tools enable the user to examine HDF5 files interactively.
         <p>
         Attributes associated with any of the supported HDF5 
         objects are carried over to the HDF4 objects.  
-        Attributes may be of integer, floating point, or fixed length string datatype 
-        and they may have up to 32 fixed dimensions.
+        Attributes may be of integer, floating point, or fixed length 
+        string datatype and they may have up to 32 fixed dimensions.
         <p>
         All datatypes are converted to big-endian.  
         Floating point datatypes are converted to IEEE format.
@@ -464,6 +481,168 @@ These tools enable the user to examine HDF5 files interactively.
 
 
 <hr>
+<dl>
+<dt><strong>Tool Name:</strong> <a name="Tools-H4toh5">h4toh5</a>
+<dt><strong>Syntax:</strong>
+    <dd><code>h4toh5 -h</code><br>
+        <code>h4toh5 </code><em>
+            h4file
+            h5file</em><br>
+        <code>h4toh5 </code><em>
+            h4file</em><br>
+        <!--  currently no -m option
+        <code>h4toh5 -m </code><em>
+            h4file1
+            h4file2
+            h4file3</em> ...
+        -->
+<dt><strong>Purpose:</strong>
+    <dd>Converts an HDF4 file to an HDF5 file.
+<dt><strong>Description:</strong>
+    <dd><code>h4toh5</code> is a file conversion utility that reads 
+        an HDF4 file, <em>h4file</em> (<code>input.hdf</code> for example),
+        and writes an HDF5 file, <em>h5file</em> (<code>output.h5</code>
+        for example), containing the same data.
+        <p>
+        If no output file <em>h5file</em> is specified, 
+        <code>h4toh5</code> uses the input filename to designate
+        the output file, replacing the extension <code>.hdf</code>
+        with <code>.h5</code>.
+        For example, if the input file <code>scheme3.hdf</code> is 
+        specified with no output filename, <code>h4toh5</code> will 
+        name the output file <code>scheme3.h5</code>.
+        <p>
+        <!--  currently no -m option
+        The <code>-m</code> option allows multiple HDF5 file 
+        arguments.  Each file name is treated the same as the 
+        single file name case above.
+        <p>
+        -->
+        The <code>-h</code> option causes a syntax summary 
+        similar to the following to be displayed:
+        <pre>              h4toh5 inputfile.hdf outputfile.h5
+              h5toh4 inputfile.hdf                    <!--  currently no -m option
+              h5toh4 -m inputfile1.hdf inputfile2.hdf ...  --> </pre>
+        <p>
+        Each object in the HDF4 file is converted to an equivalent 
+        HDF5 object, according to the mapping described in
+        <a href="ADGuide/H4toH5Mapping.pdf" target=ExternalWinA>
+        <cite>Mapping HDF4 Objects to HDF5 Objects</cite></a>.
+        (If this mapping changes between HDF5 Library releases, a more up-to-date
+        version may be available at
+        <a href="http://hdf.ncsa.uiuc.edu/HDF5/papers/h4toh5/H4-to-H5MappingGuidelines.pdf" target=ExternalWinB>
+        <cite>Mapping HDF4 Objects to HDF5 Objects</cite> on the HDF FTP server</a>.)
+        <p>
+        In this inital version, <code>h4toh5</code> converts the following 
+        HDF4 objects:
+        <center>
+	<table width=75% border=0>
+          <tr><th width=40% valign=top align=left>
+            HDF4 Object
+            </td><th width=60% valign=top align=left>
+            Resulting HDF5 Object
+          </td></tr>
+          <tr><td width=40% valign=top align=left>
+            SDS
+            </td><td width=60% valign=top align=left>
+            Dataset
+          </td></tr>
+          <tr><td width=40% valign=top align=left>
+            GR, RI8, and RI24 image
+            </td><td width=60% valign=top align=left>
+            Dataset 
+          </td></tr>
+          <tr><td width=40% valign=top align=left>
+            Vdata
+            </td><td width=60% valign=top align=left>
+            Dataset
+          </td></tr>
+          <tr><td width=40% valign=top align=left>
+            Vgroup
+            </td><td width=60% valign=top align=left>
+            Group
+          </td></tr>
+          <tr><td width=40% valign=top align=left>
+            Annotation
+            </td><td width=60% valign=top align=left>
+            Attribute
+          </td></tr>
+          <tr><td width=40% valign=top align=left>
+            Palette
+            </td><td width=60% valign=top align=left>
+            Dataset
+          </td></tr>
+        </table>
+        </center>
+<dt><strong>Options and Parameters:</strong>
+    <dl>
+        <dt><code>-h</code>
+            <dd>Displays a syntax summary.
+        <!--  currently no -m option
+        <dt><code>-m</code>
+            <dd>Converts multiple HDF4 files to multiple HDF5 files.
+        -->
+        <dt><em>h4file</em>
+            <dd>The HDF4 file to be converted.
+        <dt><em>h5file</em>
+            <dd>The HDF5 file to be created.
+    </dl>
+<!--
+<dt><strong>Current Status:</strong>
+    <dd>
+<dt><strong>See Also:</strong>
+    <dd>
+-->
+</dl>
+
+
+<!--                     Template, next 40 lines            -->
+<!--                     Template, next 40 lines            -->
+<!--                     Template, next 40 lines
+<hr>
+<dl>
+<dt><strong>Tool Name:</strong> <a name="Tools-H5toh4">h5toh4</a>
+<dt><strong>Syntax:</strong>
+    <dd><code>h5toh4 -h</code><br>
+        <code>h5toh4 </code><em>
+            h5file
+            h4file</em><br>
+        <code>h5toh4 </code><em>
+            h5file</em><br>
+        <code>h5toh4 -m </code><em>
+            h5file1
+            h5file2
+            h5file3</em> ...
+<dt><strong>Purpose:</strong>
+    <dd>Purpose...
+<dt><strong>Description:</strong>
+    <dd><code>TOOL</code> is an HDF5 utility which ...
+        Paragraph
+        <pre>              sample code
+              sample code
+              sample code </pre>
+        <p>
+        Paragraph
+        <p>
+        Paragraph
+<dt><strong>Options and Parameters:</strong>
+    <dl>
+        <dt><code>-option</code>
+            <dd>Description
+        <dt><em>parameter</em>
+            <dd>Description
+    </dl>
+<dt><strong>Current Status:</strong>
+    <dd>
+<dt><strong>See Also:</strong>
+    <dd>
+</dl>
+
+
+-->
+
+
+<hr>
 <center>
 <table border=0 width=98%>
 <tr><td valign=top align=left>
@@ -504,7 +683,7 @@ Tools&nbsp;&nbsp;
 <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
 
 <br>
-Last modified:  17 November 2000
+Last modified:  15 December 2000
 
 <br>
 Describes HDF5 Release 1.4 Beta, December 2000