DOC: reword Changelog

Rewrite change log to be a little easier to read.

Author: matthew-brett

Changelog

@@ -9,10 +9,6 @@ NiBabel Development Changelog
 NiBabel is the successor to the much-loved PyNifti package. Here we list the
 releases for both packages.
 
-'Close gh-' statements refer to GitHub issues that are available at::
-
-  http://github.com/nipy/nibabel/issues
-
 The full VCS changelog is available here:
 
   http://github.com/nipy/nibabel/commits/master
@@ -23,8 +19,8 @@ Releases
 NiBabel
 +++++++
 
-Most work on NiBabel so far has been by Matthew Brett (MB) and Michael Hanke
-(MH) and Stephan Gerhard (SG).
+Most work on NiBabel so far has been by Matthew Brett (MB), Michael Hanke (MH)
+and Stephan Gerhard (SG).
 
 * 2.0.0 (soon)
 
@@ -33,30 +29,35 @@ Most work on NiBabel so far has been by Matthew Brett (MB) and Michael Hanke
 
   * New feature, bugfix release with minor API breakage;
   * Minor API breakage: default write of NIfTI / Analyze image data offset
-    value changed from keeping the value as read from file, to shrinking the
-    offset the minimum necessary to make room for the header and any
-    extensions;
-  * Minor API breakage: data scaling in NIfTI / Analyze now set to NaN when
-    reading images.  To read the original data scaling you need to look at the
-    ``slope`` and ``inter`` properties of the image ``dataobj`` attribute;
-  * Minor API breakage: image data offset in NIfTI / Analyze now set to zero
-    when reading images.  TO read the original data offset use the ``offset``
+    value. The data offset is the number of bytes from the beginning of file
+    to skip before reading the image data.  Nibabel behavior changed from
+    keeping the value as read from file, to setting the offset to zero on
+    read, and setting the offset when writing the header. The value of the
+    offset will now be the minimum value necessary to make room for the header
+    and any extensions when writing the file. You can override the default
+    offset by setting value explicitly to some value other than zero. To read
+    the original data offset as read from the header, use the ``offset``
     property of the image ``dataobj`` attribute;
+  * Minor API breakage: data scaling in NIfTI / Analyze now set to NaN when
+    reading images.  Data scaling refers to the data intercept and slope
+    values in the NIfTI / Analyze header.  To read the original data scaling
+    you need to look at the ``slope`` and ``inter`` properties of the image
+    ``dataobj`` attribute.  You can set scaling explicitly by setting the
+    slope and intercept values in the header to values other than NaN;
   * New API for managing image caching; images have an ``in_memory`` property
     that is true if the image data has been loaded into cache, or is already
     an array in memory; ``get_data`` has new keyword argument ``caching`` to
     specify whether the cache should be filled by ``get_data``;
-  * Images now have properties ``dataobj``, ``affine``, ``header``; we will
+  * Images now have properties ``dataobj``, ``affine``, ``header``. We will
     slowly phase out the ``get_affine`` and ``get_header`` image methods;
   * The image ``dataobj`` can be sliced using an efficient algorithm to avoid
-    reading unneccesary data from disk.  This makes it possible to do very
+    reading unnecessary data from disk.  This makes it possible to do very
     efficient reads of single volumes from a time series;
-  * You can now set NIfTI / Analyze data scaling explicitly to force this
-    scaling to be written into the header;
   * NIfTI2 read / write support;
   * Read support for MINC2;
-  * Much extended read support for PAR / REC, largely due to the work of Eric
-    Larson and Gregory R. Lee giving new code, advice and code review;
+  * Much extended read support for PAR / REC, largely due to work from Eric
+    Larson and Gregory R. Lee on new code, advice and code review. Thanks also
+    to Jeff Stevenson and Bennett Landman for helpful discussion;
   * ``parrec2nii`` script outputs images in LAS voxel orientation, which
     appears to be necessary for compatibility with FSL ``dtifit`` /
     ``fslview`` diffusion analysis pipeline;
@@ -65,19 +66,19 @@ Most work on NiBabel so far has been by Matthew Brett (MB) and Michael Hanke
   * New function to save Freesurfer annotation files (by Github user ohinds);
   * Method to return MGH format ``vox2ras_tkr`` affine (Eric Larson);
   * A new API for reading unscaled data from NIfTI and other images, using
-    ``img.dataobj.get_unscaled()``; deprecate previous way of doing this with
-    ``read_img_data`` function;
-  * Bug fix replacing NaN values with zero when writing floating point data as
-    integers.  If the input floating point data range did not include zero,
-    then NaN would not get written to a value corresponding to zero in the
-    output;
+    ``img.dataobj.get_unscaled()``. Deprecate previous way of doing this,
+    which was to read data with the ``read_img_data`` function;
+  * Fix for bug when replacing NaN values with zero when writing floating
+    point data as integers.  If the input floating point data range did not
+    include zero, then NaN would not get written to a value corresponding to
+    zero in the output;
   * Improvements and bug fixes to image orientation calculation and DICOM
     wrappers by Brendan Moloney;
-  * Bug fix writing GIfTI files with base64 encoding that didn't match the
-    spec, and the wrong field name for the endian code. Thanks to Basile
-    Pinsard and Russ Poldrack for diagnosis and fixes;
-  * Bug fix in freesurfer.read_annot with orig_ids=False when annot contains
-    vertices with no label (Alexandre Gramfort);
+  * Bug fixes writing GIfTI files. We were using a base64 encoding that didn't
+    match the spec, and the wrong field name for the endian code. Thanks to
+    Basile Pinsard and Russ Poldrack for diagnosis and fixes;
+  * Bug fix in ``freesurfer.read_annot`` with ``orig_ids=False`` when annot
+    contains vertices with no label (Alexandre Gramfort);
   * More tutorials in the documentation, including introductory tutorial on
     DICOM, and on coordinate systems;
   * Lots of code refactoring, including moving to common code-base for Python

doc/source/links_names.txt

@@ -18,6 +18,7 @@
 .. _`nibabel mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
 .. _nibabel pypi: http://pypi.python.org/pypi/nibabel
 .. _nibabel issues: http://github.com/nipy/nibabel/issues
+.. _nibabel github issues: http://github.com/nipy/nibabel/issues
 
 .. other related projects
 .. _nipy community: http://nipy.org