further clarify hints and changes

Author: wkliao

sneak_peek.md

@@ -3,8 +3,8 @@ This is essentially a placeholder for the next release note ...
 ------------------------------------------------------------------------------
 
 * New features
-  + Flexible APIs now can be used as high-level APIs, when argument bufcount
-    is NC_COUNT_IGNORE and buftype is an MPI predefined data type. See
+  + Flexible APIs now can be used as high-level APIs, when argument `bufcount`
+    is `NC_COUNT_IGNORE` and `buftype` is an MPI predefined data type. See
     [PR #82](https://github.com/Parallel-NetCDF/PnetCDF/pull/82). Below is an
     example of writing from a memory buffer of type float.
     ```
@@ -36,26 +36,26 @@ This is essentially a placeholder for the next release note ...
     See [PR #122](https://github.com/Parallel-NetCDF/PnetCDF/pull/122)
 
 * Configure updates:
-  + Upgrade config.guess config.sub to 2024-01-01.
+  + Upgrade `config.guess` and `config.sub` to 2024-01-01.
     See [PR #116](https://github.com/Parallel-NetCDF/PnetCDF/pull/116)
   + FLASH-IO benchmark - add compile flag "-fallow-argument-mismatch" for GNU
     Fortran 10 and later.
     See [PR #114](https://github.com/Parallel-NetCDF/PnetCDF/pull/114)
-  + Handle the case when MPICC env is not set and "--with-mpi" is not used.
-    See commit 6142135.
-  + Upgrade autotools version requirement to autoconf 2.71, automake 1.16.5, and
-    libtool 2.4.6.
+  + Handle the case when MPICC environment variable is not set and `--with-mpi`
+    is not used.  See commit 6142135.
+  + Upgrade Autotools version requirement to autoconf 2.71, automake 1.16.5, and
+    libtool 2.4.6. (Note this change affects PnetCDF developers only.)
     See [PR #95](https://github.com/Parallel-NetCDF/PnetCDF/pull/95)
     Thanks to Blaise Bourdin for pointing out in
     [Issue #94](https://github.com/Parallel-NetCDF/PnetCDF/issues/94)
     that configure failed when using Intel OneAPI 2022.2.0 compilers. The fix
     is to use autoconf 2.70 and newer.
 
 * New constants
-  + NC_COUNT_IGNORE - This is used in flexible APIs. When argument bufcount is
-    NC_COUNT_IGNORE, buftype must be a predefine MPI datatype and the APIs
-    operate as the high-level APIs. Fortran equivalents are NF_COUNT_IGNORE and
-    NF90_COUNT_IGNORE.
+  + `NC_COUNT_IGNORE` - This is used in flexible APIs. When argument `bufcount`
+    is `NC_COUNT_IGNORE`, `buftype` must be a predefine MPI datatype and the
+    APIs operate as the high-level APIs. Fortran equivalents are
+    `NF_COUNT_IGNORE` and `NF90_COUNT_IGNORE`.
 
 * New APIs
   + none
@@ -64,13 +64,13 @@ This is essentially a placeholder for the next release note ...
   + none
 
 * API semantics updates
-  + File open flag NC_SHARE is now deprecated. It is still defined, but takes
+  + File open flag `NC_SHARE` is now deprecated. It is still defined, but takes
     no effect.
-  + NC_SHARE alone is not sufficient to provide data consistency for accessing
+  + `NC_SHARE` alone is not sufficient to provide data consistency for accessing
     a shared file in parallel and thus is now deprecated.  Because PnetCDF
     follows the MPI file consistency, which only addresses the case when all
     file accesses are relative to a specific file handle created from a
-    collective open, NC_SHARE becomes invalid. See doc/README.consistency.md
+    collective open, `NC_SHARE` becomes invalid. See doc/README.consistency.md
     for more information.
 
 * New error code precedence
@@ -83,7 +83,7 @@ This is essentially a placeholder for the next release note ...
   + none
 
 * New PnetCDF hint
-  + nc_header_collective -- to instruct PnetCDF to call MPI collective APIs to
+  + `nc_header_collective` -- to instruct PnetCDF to call MPI collective APIs to
     read and write the file header. The default is "false", meaning the file
     header is only read/written by rank 0, using MPI independent read and write
     APIs. When set to "true", collective APIs will be used with all other
@@ -97,7 +97,7 @@ This is essentially a placeholder for the next release note ...
   + none
 
 * Updated utility program
-  + ncvalidator - When the file size is larger and smaller than expected, the
+  + `ncvalidator` - When the file size is larger and smaller than expected, the
     file may still be a valid netCDF file.
     * When larger, this can happen if opening an existing file that contains no
       variable. Deleting a global attribute reduces the file header size. The
@@ -107,20 +107,24 @@ This is essentially a placeholder for the next release note ...
     * When smaller, this can happen if the last variable is partially written.
       The expected file size is calculated based on the full sizes of all
       variables. The file is still a valid netCDF file.
-    * In the former case, PR #99 changes ncvalidator to report a warning,
+    * In the former case, PR #99 changes `ncvalidator` to report a warning,
       rather than an error.
-  + ncvalidator - Add printing of the dimension size of a variable when its
+  + `ncvalidator` - Add printing of the dimension size of a variable when its
     size is larger than the limitation allowed by the file format. See commit
     5584d44.
   + Add file src/utils/README.md which gives short descriptions of the utility
     programs and collapsible bullets to display their manual pages.
 
 * Other updates:
-  + File stripe size is no longer used to set the size of file header extent.
-    Automatically set the size of file header extent using the file striping
-    size obtained from MPI-IO hint 'striping_unit' may yield an unexpectedly
-    large file header extent and cause movement of data sections if new
-    metadata is added when the program re-enter the define mode.
+  + Since version 1.1.0, PnetCDF has been using file striping size, if
+    obtainable from hint `striping_unit` set by users or MPI-IO underneath, to
+    align the starting file offset of data section. This offset is also
+    referred to as the file header extent, which can be larger than the header
+    size to allow header to grow if new data objects are added. Starting from
+    this release of 1.13.0, file stripe size is no longer used for this
+    purpose. This is because automatically setting file header extent using the
+    file striping size may yield an unexpectedly large file header extent and
+    cause movement of data sections if new metadata is added.
     See [PR #124](https://github.com/Parallel-NetCDF/PnetCDF/pull/124) and
     [PR #125](https://github.com/Parallel-NetCDF/PnetCDF/pull/125).
   + Use unsigned int to do byte swap.
@@ -142,14 +146,17 @@ This is essentially a placeholder for the next release note ...
     See [PR #79](https://github.com/Parallel-NetCDF/PnetCDF/pull/79).
 
 * Bug fixes
-  + Fix Fortran APIs internal call to nfmpi_inq_buffer_size.
+  + Fix residual values of `v_align` and `r_align` when re-entering the define
+    mode multiple times.
+    See [PR #126](https://github.com/Parallel-NetCDF/PnetCDF/pull/126).
+  + Fix Fortran APIs internal call to `nfmpi_inq_buffer_size`.
     See [PR #111](https://github.com/Parallel-NetCDF/PnetCDF/pull/111).
-  + Fix ncmpi_inq_num_rec_vars and ncmpi_inq_num_fix_vars when opening an
-    existing file. See
+  + Fix `ncmpi_inq_num_rec_vars()` and `ncmpi_inq_num_fix_vars()` when opening
+    an existing file. See
     [PR #103](https://github.com/Parallel-NetCDF/PnetCDF/pull/103).
-  + ncmpidiff -  when checking the dimensions defined in the second files
+  + `ncmpidiff` -  when checking the dimensions defined in the second files
     whether they are defined in the first file. See 88cd9c1.
-  + Use Fortran subroutine Get_Environment_Variable instead of getenv.
+  + Use Fortran subroutine `Get_Environment_Variable` instead of `getenv`.
     See commit a0b8aca, b796759.
 
 * New example programs
@@ -159,19 +166,20 @@ This is essentially a placeholder for the next release note ...
   + none
 
 * New test program
-  + test/testcases/tst_redefine.c - test multiple entries of ncmpi__enddef
+  + test/testcases/tst_redefine.c - test multiple entries of `ncmpi__enddef`
     [PR #126](https://github.com/Parallel-NetCDF/PnetCDF/pull/126).
-  + test/testcases/tst_symlink.c - test NC_CLOBBER on a symbolic link.
+  + test/testcases/tst_symlink.c - test `NC_CLOBBER` on a symbolic link.
   + test/testcases/tst_del_attr.c - test delete attributes. See
     [PR #99](https://github.com/Parallel-NetCDF/PnetCDF/pull/99).
-  + test/testcases/test_get_varn.c - test get_varn API. See
+  + test/testcases/test_get_varn.c - test `get_varn` API. See
     [PR #90](https://github.com/Parallel-NetCDF/PnetCDF/pull/90).
   + test/testcases/flexible_var.c - test flexible var API
-  + test/testcases/flexible_api.f - test flexible API when bufcount == -1
+  + test/testcases/flexible_api.f - test flexible API when `bufcount == -1`
   + test/testcases/scalar.c - add tests for scalar variables using nonblocking
     APIs. See commit 07ff7b1
   + test/nonblocking/test_bputf.f90, test/nonblocking/test_bputf77.f -
-    add tests of APIs inq_buffer_usage and inq_buffer_size. See commit 94ce438
+    add tests of APIs `inq_buffer_usage` and `inq_buffer_size`.
+    See commit 94ce438
 
 * Issues with NetCDF library
   + none
@@ -189,18 +197,24 @@ This is essentially a placeholder for the next release note ...
   + none
 
 * Clarifications
-  + Hints nc_header_align_size, nc_var_align_size, and nc_record_align_size are
-    to align the file header extent, starting file offsets of data section, and
-    record variable section, respectively. Note that nc_var_align_size and
-    nc_record_align_siz are not to align individual variables. They are
-    equivalent to arguments v_align and r_align, respevtively in API
-    ncmpi__enddef().
-  + Using NC_CLOBBER in ncmpi_create() can be expensive if the file already
+  + Hints `nc_header_align_size` and `nc_record_align_size` are to align the
+    file header extent and starting file offset of the record variable section,
+    respectively. Hint `nc_record_align_size` is not to align the offsets of
+    individual record variables.
+  + Prior to version 1.13.0, hint `nc_var_align_size` is used to align the
+    starting file offsets of individual fixed-size variables. Beginning from
+    version 1.13.0, this hint is used to align only the starting file offset of
+    the entire data section, not individual variables. The reason of such
+    change is because PnetCDF nonblocking APIs can aggregate multiple I/O
+    requests and MPI-IO today has been optimized to align I/O to file striping
+    boundaries, which makes aligning starting offsets of individual variables
+    less effective and may create empty space in the file.
+  + Using `NC_CLOBBER` in `ncmpi_create()` can be expensive if the file already
     exists. If the existing file is a regular file, then PnetCDF will delete it
-    with a call to unlink() first and re-created it later. Calling unlink() on
+    with a call to `unlink()` first and re-created it later. Calling `unlink()` on
     may be expensive for some parallel file systems. If the existing file is a
-    symbolic link, then PnetCDF will call truncate() or MPI_File_set_size() to
-    truncate the file size to zero. Calling truncate() may also be very
+    symbolic link, then PnetCDF will call `truncate()` or `MPI_File_set_size()` to
+    truncate the file size to zero. Calling `truncate()` may also be very
     expensive on some file systems, e.g. Lustre. Sporadically a long time spent
-    on unlink() and truncate() was observed on Perlmutter.
+    on `unlink()` and `truncate()` was observed on Perlmutter.