[svn-r20231] Purpose:

    Fixed Bug 1904 - h5ls : usage of '-a' option is not clear to display expected output

Description:
    Fixed incorrect content and improved help page for -a option of h5ls.
     
Tested:
 jam (linux32-LE), amani (linux64-LE), heiwa (linuxppc64-BE), tejeda (mac32-LE), Cmake (jam)

7 files changed, 32 insertions, 6 deletions

diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt
index 305fdda..47bfd33 100644
--- a/release_docs/RELEASE.txt
+++ b/release_docs/RELEASE.txt
@@ -506,6 +506,8 @@ Bug Fixes since HDF5-1.8.0 release
 
     Tools
     -----
+        - Fixed and improved help page for -a option of h5ls. 
+          Bug#1904 (JKM 2011/3/11)
         - Fixed h5dump not to include attribute values in the output file when 
           h5dump "-y -o output_file" options were used. The problem was introduced 
           in HDF5 1.8.6 by showing data pointed by region references. (XCAO 2011/3/9)
diff --git a/tools/h5ls/h5ls.c b/tools/h5ls/h5ls.c
index d2233ce..e670470 100644
--- a/tools/h5ls/h5ls.c
+++ b/tools/h5ls/h5ls.c
@@ -105,7 +105,11 @@ usage (void)
 usage: %s [OPTIONS] [OBJECTS...]\n\
   OPTIONS\n\
    -h, -?, --help  Print a usage message and exit\n\
-   -a, --address   Print addresses for raw data\n\
+   -a, --address   Print raw data address.  If dataset is contiguous, address\n\
+                   is offset in file of beginning of raw data. If chunked,\n\
+                   returned list of addresses indicates offset of each chunk.\n\
+                   Must be used with -v, --verbose option.\n\
+                   Provides no information for non-dataset objects.\n\
    -d, --data      Print the values of datasets\n\
    -e, --errors    Show all HDF5 error reporting\n\
    --follow-symlinks\n\
diff --git a/tools/testfiles/help-1.ls b/tools/testfiles/help-1.ls
index 6a2904e..7f8879c 100644
--- a/tools/testfiles/help-1.ls
+++ b/tools/testfiles/help-1.ls
@@ -4,7 +4,11 @@
 usage: h5ls [OPTIONS] [OBJECTS...]
   OPTIONS
    -h, -?, --help  Print a usage message and exit
-   -a, --address   Print addresses for raw data
+   -a, --address   Print raw data address.  If dataset is contiguous, address
+                   is offset in file of beginning of raw data. If chunked,
+                   returned list of addresses indicates offset of each chunk.
+                   Must be used with -v, --verbose option.
+                   Provides no information for non-dataset objects.
    -d, --data      Print the values of datasets
    -e, --errors    Show all HDF5 error reporting
    --follow-symlinks
diff --git a/tools/testfiles/help-2.ls b/tools/testfiles/help-2.ls
index 92163d1..8bc31fb 100644
--- a/tools/testfiles/help-2.ls
+++ b/tools/testfiles/help-2.ls
@@ -4,7 +4,11 @@
 usage: h5ls [OPTIONS] [OBJECTS...]
   OPTIONS
    -h, -?, --help  Print a usage message and exit
-   -a, --address   Print addresses for raw data
+   -a, --address   Print raw data address.  If dataset is contiguous, address
+                   is offset in file of beginning of raw data. If chunked,
+                   returned list of addresses indicates offset of each chunk.
+                   Must be used with -v, --verbose option.
+                   Provides no information for non-dataset objects.
    -d, --data      Print the values of datasets
    -e, --errors    Show all HDF5 error reporting
    --follow-symlinks
diff --git a/tools/testfiles/help-3.ls b/tools/testfiles/help-3.ls
index 7199815..29aed97 100644
--- a/tools/testfiles/help-3.ls
+++ b/tools/testfiles/help-3.ls
@@ -4,7 +4,11 @@
 usage: h5ls [OPTIONS] [OBJECTS...]
   OPTIONS
    -h, -?, --help  Print a usage message and exit
-   -a, --address   Print addresses for raw data
+   -a, --address   Print raw data address.  If dataset is contiguous, address
+                   is offset in file of beginning of raw data. If chunked,
+                   returned list of addresses indicates offset of each chunk.
+                   Must be used with -v, --verbose option.
+                   Provides no information for non-dataset objects.
    -d, --data      Print the values of datasets
    -e, --errors    Show all HDF5 error reporting
    --follow-symlinks
diff --git a/tools/testfiles/textlinksrc-nodangle-1.ls b/tools/testfiles/textlinksrc-nodangle-1.ls
index 8a6144b..306c4f9 100644
--- a/tools/testfiles/textlinksrc-nodangle-1.ls
+++ b/tools/testfiles/textlinksrc-nodangle-1.ls
@@ -6,7 +6,11 @@ Error: --no-dangling-links must be used along with --follow-symlinks option!
 usage: h5ls [OPTIONS] [OBJECTS...]
   OPTIONS
    -h, -?, --help  Print a usage message and exit
-   -a, --address   Print addresses for raw data
+   -a, --address   Print raw data address.  If dataset is contiguous, address
+                   is offset in file of beginning of raw data. If chunked,
+                   returned list of addresses indicates offset of each chunk.
+                   Must be used with -v, --verbose option.
+                   Provides no information for non-dataset objects.
    -d, --data      Print the values of datasets
    -e, --errors    Show all HDF5 error reporting
    --follow-symlinks
diff --git a/tools/testfiles/tgroup-1.ls b/tools/testfiles/tgroup-1.ls
index 03a70fd..54c139c 100644
--- a/tools/testfiles/tgroup-1.ls
+++ b/tools/testfiles/tgroup-1.ls
@@ -6,7 +6,11 @@ Error: 'recursive' option not compatible with 'group info' option!
 usage: h5ls [OPTIONS] [OBJECTS...]
   OPTIONS
    -h, -?, --help  Print a usage message and exit
-   -a, --address   Print addresses for raw data
+   -a, --address   Print raw data address.  If dataset is contiguous, address
+                   is offset in file of beginning of raw data. If chunked,
+                   returned list of addresses indicates offset of each chunk.
+                   Must be used with -v, --verbose option.
+                   Provides no information for non-dataset objects.
    -d, --data      Print the values of datasets
    -e, --errors    Show all HDF5 error reporting
    --follow-symlinks