improve description

README.rst

@@ -4,31 +4,32 @@ Darr
 |Github CI Status| |Appveyor Status| |PyPi version| |Conda Forge|
 |Codecov Badge| |Docs Status| |Zenodo Badge|
 
-Darr is a Python science library that allows you to work efficiently with
-potentially very large, disk-based Numpy arrays that are widely readable and
-self-documented. Documentation includes copy-paste ready code to read arrays
-in many popular data science languages such as R, Julia, Scilab, IDL,
-Matlab, Maple, and Mathematica, or in Python/Numpy without Darr. Without
-exporting them and with minimal effort.
+Darr is a Python science library to work efficiently with potentially very
+large, disk-based Numpy arrays that are widely readable and self-documented.
+Every array has its own documentation that includes copy-paste ready code to
+read it in many popular data science languages, such as R, Julia, Scilab,
+IDL, Matlab, Maple, and Mathematica, or in Python/Numpy without Darr. Your
+numerical arrays can be read in other analysis environments with minimal
+effort and without any need for exporting/copying data.
+
+In essence, Darr makes it trivially easy to share your numerical arrays and
+metadata with others or with yourself when working in different computing
+environments, and stores them in a future-proof way.
 
 Universal readability of data is a pillar of good scientific practice. It is
-also generally a good idea for anyone who wants to flexibly move between
-analysis environments, who wants to save data for the longer term, or who
+also generally a good idea for anyone  who wants to save data for the longer
+term, who wants to flexibly move between analysis environments, or who
 wants to share data with others without spending much time on figuring out
-and/or explaining how the receiver can read it. No idea how to read
-your 7-dimensional uint32 numpy array in Matlab to quickly try out an
-algorithm your colleague wrote? No worries, a quick copy-paste of code from
-the array documentation is all that is needed to read your data in, e.g. R or
-Matlab (see `example
+and/or explaining how the receiver can read it. Want to quickly try out an
+algorithm your colleague wrote in R or Matlab, but no idea how to
+read your 7-dimensional uint32 numpy array in those environments? A quick
+copy-paste of code from the documentation included with the array is all that
+is needed to read it (see `example
 <https://github.com/gbeckers/Darr/tree/master/examplearrays/arrays/array_int32_2D.darr>`__).
-As you work with your array, its documentation is automatically kept
-up to date. No need to export anything, make notes, or to provide elaborate
-explanation. No looking up things. No dependence on complicated formats or
-specialized libraries for reading you data elsewhere later.
-
-In essence, Darr makes it trivially easy to share your numerical arrays with
-others or with yourself when working in different computing environments,
-and stores them in a future-proof way.
+No need to export anything. Want to share your array with non-Python
+colleagues? No looking up things, no need to make notes or to provide
+elaborate explanation. No dependence on complicated formats or specialized
+libraries.
 
 More rationale for a tool-independent approach to numeric array storage is
 provided `here <https://darr.readthedocs.io/en/latest/rationale.html>`__.
@@ -39,17 +40,18 @@ which makes Darr fully NumPy compatible. This enables efficient out-of-core
 read/write access to potentially very large arrays. In addition to
 automatic documentation, Darr adds other functionality to NumPy's memmap,
 such as easy the appending and truncating of data, support for ragged arrays,
-the ability to create arrays from iterators, and easy use of metadata. Flat
-binary files and (JSON) text files are accompanied by a README text file
-that explains how the array and metadata are stored (`see example arrays
-<https://github.com/gbeckers/Darr/tree/master/examplearrays/>`__).
+the ability to create arrays from iterators, and easy use of metadata. When
+you change the size of your array, its documentation is automatically
+kept up to date. Flat binary files and (JSON) text files are accompanied by
+a README text file that explains how the array and metadata are stored (`see
+ example arrays <https://github.com/gbeckers/Darr/tree/master/examplearrays/>`__).
 
 See this `tutorial <https://darr.readthedocs.io/en/latest/tutorialarray.html>`__
 for a brief introduction, or the
 `documentation <http://darr.readthedocs.io/>`__ for more info.
 
-Darr is currently pre-1.0, still undergoing development. It is open source and
-freely available under the `New BSD License
+Darr is currently pre-1.0, and still undergoing development. It is open source
+and freely available under the `New BSD License
 <https://opensource.org/licenses/BSD-3-Clause>`__ terms.
 
 Features

docs/index.rst

@@ -9,31 +9,32 @@ Darr
 |Github CI Status| |Appveyor Status| |PyPi version| |Conda Forge|
 |Codecov Badge| |Docs Status| |Zenodo Badge|
 
-Darr is a Python science library that allows you to work efficiently with
-potentially very large, disk-based Numpy arrays that are widely readable and
-self-documented. Documentation includes copy-paste ready code to read arrays
-in many popular data science languages such as R, Julia, Scilab, IDL,
-Matlab, Maple, and Mathematica, or in Python/Numpy without Darr. Without
-exporting them and with minimal effort.
+Darr is a Python science library to work efficiently with potentially very
+large, disk-based Numpy arrays that are widely readable and self-documented.
+Every array has its own documentation that includes copy-paste ready code to
+read it in many popular data science languages, such as R, Julia, Scilab,
+IDL, Matlab, Maple, and Mathematica, or in Python/Numpy without Darr. Your
+numerical arrays can be read in other analysis environments with minimal
+effort and without any need for exporting/copying data.
+
+In essence, Darr makes it trivially easy to share your numerical arrays and
+metadata with others or with yourself when working in different computing
+environments, and stores them in a future-proof way.
 
 Universal readability of data is a pillar of good scientific practice. It is
-also generally a good idea for anyone who wants to flexibly move between
-analysis environments, who wants to save data for the longer term, or who
+also generally a good idea for anyone  who wants to save data for the longer
+term, who wants to flexibly move between analysis environments, or who
 wants to share data with others without spending much time on figuring out
-and/or explaining how the receiver can read it. No idea how to read
-your 7-dimensional uint32 numpy array in Matlab to quickly try out an
-algorithm your colleague wrote? No worries, a quick copy-paste of code from
-the array documentation is all that is needed to read your data in, e.g. R or
-Matlab (see `example
+and/or explaining how the receiver can read it. Want to quickly try out an
+algorithm your colleague wrote in R or Matlab, but no idea how to
+read your 7-dimensional uint32 numpy array in those environments? A quick
+copy-paste of code from the documentation included with the array is all that
+is needed to read it (see `example
 <https://github.com/gbeckers/Darr/tree/master/examplearrays/arrays/array_int32_2D.darr>`__).
-As you work with your array, its documentation is automatically kept
-up to date. No need to export anything, make notes, or to provide elaborate
-explanation. No looking up things. No dependence on complicated formats or
-specialized libraries for reading you data elsewhere later.
-
-In essence, Darr makes it trivially easy to share your numerical arrays with
-others or with yourself when working in different computing environments,
-and stores them in a future-proof way.
+No need to export anything. Want to share your array with non-Python
+colleagues? No looking up things, no need to make notes or to provide
+elaborate explanation. No dependence on complicated formats or specialized
+libraries.
 
 More rationale for a tool-independent approach to numeric array storage is
 provided `here <https://darr.readthedocs.io/en/latest/rationale.html>`__.
@@ -44,10 +45,11 @@ which makes Darr fully NumPy compatible. This enables efficient out-of-core
 read/write access to potentially very large arrays. In addition to
 automatic documentation, Darr adds other functionality to NumPy's memmap,
 such as easy the appending and truncating of data, support for ragged arrays,
-the ability to create arrays from iterators, and easy use of metadata. Flat
-binary files and (JSON) text files are accompanied by a README text file
-that explains how the array and metadata are stored (`see example arrays
-<https://github.com/gbeckers/Darr/tree/master/examplearrays/>`__).
+the ability to create arrays from iterators, and easy use of metadata. When
+you change the size of your array, its documentation is automatically
+kept up to date. Flat binary files and (JSON) text files are accompanied by
+a README text file that explains how the array and metadata are stored (`see
+ example arrays <https://github.com/gbeckers/Darr/tree/master/examplearrays/>`__).
 
 See this `tutorial <https://darr.readthedocs.io/en/latest/tutorialarray.html>`__
 for a brief introduction, or the

setup.py

@@ -10,31 +10,32 @@
 """|Github CI Status| |Appveyor Status| |PyPi version| |Conda Forge|
 |Codecov Badge| |Docs Status| |Zenodo Badge|
 
-Darr is a Python science library that allows you to work efficiently with
-potentially very large, disk-based Numpy arrays that are widely readable and
-self-documented. Documentation includes copy-paste ready code to read arrays
-in many popular data science languages such as R, Julia, Scilab, IDL, 
-Matlab, Maple, and Mathematica, or in Python/Numpy without Darr. Without 
-exporting them and with minimal effort.
+Darr is a Python science library to work efficiently with potentially very
+large, disk-based Numpy arrays that are widely readable and self-documented.
+Every array has its own documentation that includes copy-paste ready code to
+read it in many popular data science languages, such as R, Julia, Scilab,
+IDL, Matlab, Maple, and Mathematica, or in Python/Numpy without Darr. Your
+numerical arrays can be read in other analysis environments with minimal
+effort and without any need for exporting/copying data.
+
+In essence, Darr makes it trivially easy to share your numerical arrays and
+metadata with others or with yourself when working in different computing
+environments, and stores them in a future-proof way.
 
 Universal readability of data is a pillar of good scientific practice. It is
-also generally a good idea for anyone who wants to flexibly move between
-analysis environments, who wants to save data for the longer term, or who
+also generally a good idea for anyone  who wants to save data for the longer
+term, who wants to flexibly move between analysis environments, or who
 wants to share data with others without spending much time on figuring out
-and/or explaining how the receiver can read it. No idea how to read 
-your 7-dimensional uint32 numpy array in Matlab to quickly try out an 
-algorithm your colleague wrote? No worries, a quick copy-paste of code from 
-the array documentation is all that is needed to read your data in, e.g. R or 
-Matlab (see `example
+and/or explaining how the receiver can read it. Want to quickly try out an
+algorithm your colleague wrote in R or Matlab, but no idea how to
+read your 7-dimensional uint32 numpy array in those environments? A quick
+copy-paste of code from the documentation included with the array is all that
+is needed to read it (see `example
 <https://github.com/gbeckers/Darr/tree/master/examplearrays/arrays/array_int32_2D.darr>`__).
-As you work with your array, its documentation is automatically kept 
-up to date. No need to export anything, make notes, or to provide elaborate 
-explanation. No looking up things. No dependence on complicated formats or 
-specialized libraries for reading you data elsewhere later. 
-
-In essence, Darr makes it trivially easy to share your numerical arrays with
-others or with yourself when working in different computing environments,
-and stores them in a future-proof way.
+No need to export anything. Want to share your array with non-Python
+colleagues? No looking up things, no need to make notes or to provide
+elaborate explanation. No dependence on complicated formats or specialized
+libraries.
 
 More rationale for a tool-independent approach to numeric array storage is
 provided `here <https://darr.readthedocs.io/en/latest/rationale.html>`__.
@@ -45,10 +46,11 @@
 read/write access to potentially very large arrays. In addition to
 automatic documentation, Darr adds other functionality to NumPy's memmap,
 such as easy the appending and truncating of data, support for ragged arrays,
-the ability to create arrays from iterators, and easy use of metadata. Flat
-binary files and (JSON) text files are accompanied by a README text file
-that explains how the array and metadata are stored (`see example arrays
-<https://github.com/gbeckers/Darr/tree/master/examplearrays/>`__).
+the ability to create arrays from iterators, and easy use of metadata. When
+you change the size of your array, its documentation is automatically
+kept up to date. Flat binary files and (JSON) text files are accompanied by
+a README text file that explains how the array and metadata are stored (`see
+ example arrays <https://github.com/gbeckers/Darr/tree/master/examplearrays/>`__).
 
 See this `tutorial <https://darr.readthedocs.io/en/latest/tutorialarray.html>`__
 for a brief introduction, or the