[svn-r8797]

Purpose:
    To more carefully describe the
        -- behavior of H5Pset_external
        -- appropriate usage of H5Pset_shuffle

Description:
    H5Pset_external
      Add notes that first H5Pset_external call sets the dataset as EXTERNAL
      and identifies the first file in the series of external files that
      will hold the dataset; subsequent calls identify additional files;
      all external files must be declared before the dataset is created;
      and the library will create files that don't yet exist on the system
      at the time that H5Dwrite is called to write data to that file.
    H5Pset_shuffle
      Added notes regarding usage of H5Pset_shuffle in concert with a
      compression filter.
    And, as always, a few copy edits.

1 files changed, 33 insertions, 14 deletions

diff --git a/doc/html/RM_H5P.html b/doc/html/RM_H5P.html
index 1b15b8a..9897793 100644
--- a/doc/html/RM_H5P.html
+++ b/doc/html/RM_H5P.html
@@ -2328,7 +2328,6 @@ END SUBROUTINE h5pget_class_parent_f
         include the following:
         <pre>
            H5FD_CORE
-           H5FD_DPSS
            H5FD_FAMILY
            H5FD_GASS
            H5FD_LOG
@@ -6428,35 +6427,49 @@ END SUBROUTINE h5pset_edc_check_f
   <dt><strong>Purpose:</strong>
     <dd>Adds an external file to the list of external files.
   <dt><strong>Description:</strong>
-    <dd><code>H5Pset_external</code> adds an external file to the 
-        list of external files. 
+    <dd>The first call to <code>H5Pset_external</code> sets the 
+	<i>external storage</i> property in the property list,
+	thus designating that the dataset will be stored in 
+	one or more non-HDF5 file(s) external to the HDF5 file.
+	This call also adds the file <code>name</code> as the 
+	first file in the list of external files.
+	Subsequent calls to the function add the named file as
+	the next file in the list.
         <p>
-        If a dataset is split across multiple files then the files
+        If a dataset is split across multiple files, then the files
         should be defined in order. The total size of the dataset is
         the sum of the <code>size</code> arguments for all the external files.  If
         the total size is larger than the size of a dataset then the
         dataset can be extended (provided the data space also allows
         the extending).
         <p>
-        The <code>size</code> argument specifies number of bytes reserved 
+        The <code>size</code> argument specifies the number of bytes reserved 
         for data in the external file.
         If  <code>size</code> is set to <code>H5F_UNLIMITED</code>, the 
-        external file can be of unlimited size and no more files can be added to
-        the external files list.
+        external file can be of unlimited size and no more files can be added 
+        to the external files list.
+        <p>
+	All of the external files for a given dataset must be 
+	specified with <code>H5Pset_external</code> 
+	<i>before</i> <code>H5Dcreate</code> is called to create 
+	the dataset. 
+	If one these files does not exist on the system when 
+	<code>H5Dwrite</code> is called to write data to it, 
+        the library will create the file.
   <dt><strong>Parameters:</strong>
     <ul><table>
         <tr>
-		    <td valign="top"><em>hid_t</em> <code>plist</code></td>
+            <td valign="top"><em>hid_t</em> <code>plist</code></td>
             <td valign="top">IN: Identifier of a dataset creation property list.</td></tr>
         <tr>
-		    <td valign="top"><em>const&nbsp;char</em>&nbsp;<code>*name&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
+            <td valign="top"><em>const&nbsp;char</em>&nbsp;<code>*name&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
             <td valign="top">IN: Name of an external file.</td></tr>
         <tr>
-		    <td valign="top"><em>off_t</em> <code>offset</code></td>
+            <td valign="top"><em>off_t</em> <code>offset</code></td>
             <td valign="top">IN: Offset, in bytes, from the beginning of the file
                 to the location in the file where the data starts.</td></tr>
         <tr>
-		    <td valign="top"><em>hsize_t</em> <code>size</code></td>
+            <td valign="top"><em>hsize_t</em> <code>size</code></td>
             <td valign="top">IN: Number of bytes reserved in the file for the data.</td></tr>
     </table></ul>
   <dt><strong>Returns:</strong>
@@ -8694,8 +8707,14 @@ END SUBROUTINE h5pset_preserve_f
 	closely related to each other and putting them together 
         can increase the compression ratio.
 	<p>
-	This filter is designed to be used in combination with 
-	a compression filter.
+	As  implied above, the primary value of the shuffle filter 
+        lies in its coordinated use with a compression filter; 
+	it does not provide data compression when used alone. 
+        When the shuffle filter is applied to a dataset 
+        immediately prior to the use of a compression filter, 
+        the compression ratio achieved is often superior to that
+        achieved by the use of a compression filter without 
+        the shuffle filter.
   <dt><strong>Parameters:</strong>
     <ul><table>
         <tr>
@@ -9683,7 +9702,7 @@ And in this document, the
 Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0
 </address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT">
 <!--
-document.writeln("Last modified: 10 March 2004");
+document.writeln("Last modified: 2 July 2004");
 -->
 </SCRIPT>