sync readme.txt with readme.rst

Author: fangq

README.txt

@@ -28,14 +28,14 @@ VIII.Acknowledgement
 0. What's New
 
 JSONLab v2.0 - code named "Magnus Prime" - is a stable release of JSONLab and
-a new milestone towards a stable, complete reference implementation for the 
+a new milestone towards a stable, complete reference implementation of the 
 JData Specification (http://openjdata.org) for portable scientific data storage.
 
 There have been many major updates added to this release since the previous 
 release v1.9.8 in Oct. 2019. A list of the major changes are summarized below
 (with key features marked by *), including the support to `_ArrayShape_` to
 efficiently encode special matrices and the addition of `jsave/jload` to save
-and restore variables in MATLAB/Octave like `save/load` commands (experimental):
+and restore variables in MATLAB/Octave like the `save/load` commands (experimental):
 
 * 2020-06-09*[       ] created `jdata` and `bjdata` python modules to share data with MATLAB
 * 2020-06-08*[cbde607] add savebj and loadbj to dedicate to loading and saving bjdata
@@ -71,27 +71,28 @@ and restore variables in MATLAB/Octave like `save/load` commands (experimental):
 * 2019-10-22*[650b5ec] enable jdataencode in savejson and saveubjson
 
 
-Please note that JSONLab v2.0 is now compliant with JData Spec Draft 3, in 
+Please note that JSONLab v2.0 is now compliant with JData Spec Draft 3; in 
 comparison, v1.9.8 is compatible with Draft 2; v1.9 and previous releases are 
 compatible with Draft 1. JSONLab v2.0 can read all data files generated by 
 v1.9.8, but v1.9.8 can not read the new UBJSON markers introduced in v2.0.
 
-The `jsave/jload` functions are experimental. The generated `.jamm` files are
-renamed binary-JData/UBJSON files; they can be 50% smaller than `.mat` files
-(if using `jsave(...,'compression','lzma')`) and can be readily loaded among 
-a long list of programming environments such as Python, JavaScript and Go.
+The newly introduced `jsave/jload` functions are in the experimental stage. 
+They generate `.jamm` files which are renamed binary-JData/UBJSON files; 
+they can be 50% smaller than `.mat` files if using `jsave(...,'compression','lzma')`
+and can be readily opened among a long list of programming environments 
+such as Python, JavaScript and Go.
 
-The `saveubjson/loadubjson` functions now supports Binary JData specification (BJData)
+The `saveubjson/loadubjson` functions added support to the Binary JData specification (BJData)
 Draft 1 (https://github.com/fangq/bjdata) and are now renamed as `savebj/loadbj`
-(we kept `saveubjson/loadubjson` for compatibility purposes as aliases to the new 
+(`saveubjson/loadubjson` are kept for compatibility purposes as aliases to the new 
 functions). The BJData spec is largely compatible with UBJSON spec Draft 12, with the 
 following differences (we are working with the UBJSON maintainer to merge 
 these two specifications):
 
 * BJData adds 4 new numeric data types: `uint16 [u]`, `uint32 [m]`, `uint64 [M]` \
   and `float16 [h]` ('''new in JSONLab v2.0''')
 * BJData supports an optimized ND array container (supported in JSONLab since 2013)
-* BJData does not convert NaN/Inf/-Inf to `null` (supported in JSONLab since 2013)
+* BJData does not convert `NaN/Inf/-Inf` to `null` (supported in JSONLab since 2013)
 
 To avoid using the new type markers, one should attach `'UBJSON',1` in the `savebj`
 command as
@@ -106,27 +107,27 @@ To convert an older file (JSON/UBJSON) to the new format, you should run
    data=loadjson('my_old_data_file.json','FormatVersion',1.9)
    savejson('',data,'FileName','new_file.json')
 
-You are strongly encouraged to convert all previously generated data files using the new
+You are strongly encouraged to convert all pre-v1.9.8 generated data files using the new
 format.
 
 
 -------------------------------------------------------------------------------
 
 I.  Introduction
 
-JSONLab is a free and open-source JSON/UBJSON/MessagePack encoder and a 
-decoder in the native MATLAB language. It can be used to convert a MATLAB 
+JSONLab is a free and open-source JSON/UBJSON/MessagePack encoder and 
+decoder written in the native MATLAB language. It can be used to convert a MATLAB 
 data structure (array, struct, cell, struct array, cell array, and objects) into 
-JSON/UBJSON/MessagePack formatted strings, or to decode a 
+JSON/UBJSON/MessagePack formatted strings and files, or to parse a 
 JSON/UBJSON/MessagePack file into MATLAB data structure. JSONLab supports both 
 MATLAB and [http://www.gnu.org/software/octave GNU Octave] (a free MATLAB clone).
 
 JSON ([http://www.json.org/ JavaScript Object Notation]) is a highly portable, 
 human-readable and [http://en.wikipedia.org/wiki/JSON "fat-free"] text format 
 to represent complex and hierarchical data, widely used for data-exchange in applications.
 UBJSON ([http://ubjson.org/ Universal Binary JSON]) is a binary JSON format,  
-specifically designed to complement the limitations of JSON, permitting the
-storage of binary data with strongly typed data records, resulting in smaller
+specifically designed to specifically address the limitations of JSON, permitting 
+efficient storage of binary data with strongly typed data records, resulting in smaller
 file sizes and fast encoding and decoding. MessagePack is another binary
 JSON-like data format widely used in data exchange in web/native applications.
 It is slightly more compact than UBJSON, but is not directly readable compared
@@ -143,7 +144,10 @@ to standardize serializations of complex scientific data structures, such as
 N-D arrays, sparse/complex-valued arrays, trees, maps, tables and graphs using
 JSON/binary JSON constructs. The text and binary formatted JData files are
 syntactically compatible with JSON/UBJSON formats, and can be readily parsed 
-using existing JSON and UBJSON parsers.
+using existing JSON and UBJSON parsers. JSONLab is not just a parser and writer 
+of JSON/UBJSON data files, but one that systematically converts complex scientific
+data structures into human-readable and universally supported JSON forms using the
+standardized JData data annotations.
 
 -------------------------------------------------------------------------------
 
@@ -200,20 +204,20 @@ JSONLab is also available on Arch Linux. You may install it using the below comm
 
 III.Using JSONLab
 
-JSONLab provides a pair of functions, `loadjson` -- a JSON-to-MATLAB parser, 
-and `savejson` -- a MATLAB-to-JSON encoder, for the text-based JSON, and 
-two equivallent function pairs -- `loadubjson` and `saveubjson` for binary 
-JSON and `loadmsgpack` and `savemsgpack` for MessagePack. The `load*` functions 
-for the 3 supported data formats share almost the same input parameters; 
+JSONLab provides a pair of functions, `loadjson` -- a JSON parser, and 
+`savejson` -- a MATLAB-to-JSON encoder, to read/write the text-based JSON; and 
+two equivallent pairs -- `loadubjson/saveubjson` for binary 
+JSON and `loadmsgpack/savemsgpack` for MessagePack. The `load*` functions 
+for the 3 supported data formats share almost the same input parameter format; 
 similarly for the 3 `save*` functions (`savejson/saveubjson/savemsgpack`).
-These encoders and decoders are capable of converting/storing many different
+These encoders and decoders are capable of processing/sharing almost all 
 data structures supported by MATLAB, thanks to `jdataencode/jdatadecode` - 
-a pair of in-memory data converters that translate complex data structures
+a pair of in-memory data converters translating complex data structures
 to the easy-to-serialized forms according to the JData specifications.
 The detailed help information can be found in the `Contents.m` file. 
 
-In the below section, we simply provide a few examples on how to use
-each of the core functions for encoding/decoding JSON/UBJSON/MessagePack data
+In the below section, we provide a few examples on how to us each of the 
+core functions for encoding/decoding JSON/UBJSON/MessagePack data.
 
 === savejson.m ===
 
@@ -277,7 +281,8 @@ will see the conversions from MATLAB data structure to JSON text and backward.
 In `jsonlab_selftest.m`, we load complex JSON files downloaded from the Internet
 and validate the loadjson/savejson functions for regression testing purposes.
 Similarly, a `demo_ubjson_basic.m` script is provided to test the `saveubjson`
-and `loadubjson` functions for various matlab data structures.
+and `loadubjson` functions for various matlab data structures, and
+``demo_msgpack_basic.m`` is for testing ``savemsgpack`` and ``loadmsgpack``.
 
 Please run these examples and understand how JSONLab works before you use
 it to process your data.
@@ -288,7 +293,7 @@ it to process your data.
 Under the `test` folder, you can find a script to test individual data types and
 inputs using various encoders and decoders. This unit testing script also serves as
 a '''specification validator''' to the JSONLab functions and ensure that the outputs
-are compliant to the specifications.
+are compliant to the underlying specifications.
 
 
 -------------------------------------------------------------------------------
@@ -297,38 +302,38 @@ IV.Using `jsave/jload` to share workspace
 
 Starting from JSONLab v2.0, we provide a pair of functions, `jsave/jload` to store
 and retrieve variables from the current workspace, similar to the `save/load` 
-functions in MATLAB and Octave. The files `jsave/jload` use is by default 
-a binary JData file with a suffix `.jamm`. The file size is comparable
+functions in MATLAB and Octave. The files that `jsave/jload` reads/writes is by  
+default a binary JData file with a suffix `.jamm`. The file size is comparable
 (can be smaller if use `lzma` compression) to `.mat` files. This feature
 is currently experimental.
 
 The main benefits of using .jamm file to share matlab variables include
 
 * a `.jamm` file can be 50% smaller than a `.mat` file when using \
   `jsave(..., "compression","lzma")`; the only drawback is longer saving time.
-* a `.jamm` file can be readily read/used among many programming environments, including \
-  Python, JavaScript, Go, Java etc, where .mat file support is not available. \
+* a `.jamm` file can be readily read/opened among many programming environments, including \
+  Python, JavaScript, Go, Java etc, where `.mat` file support is not generally available. \
   Parsers of `.jamm` is largely compatible with UBJSON's parsers available at \
   http://ubjson.org/?page_id=48
 * a `.jamm` file is quasi-human-readable, one can see the internal data fields \
   even in a command line, for example using `strings -n 2 file.jamm | astyle`, \
-  making the binary data easy to be understood, shared and reused.
+  making the binary data easy to be understood, shared and reused. 
 * `jsave/jload` can also use MessagePack and JSON formats as the underlying \
   data storage format, addressing needs from diverse applications. \
   MessagePack parsers are readily available at https://msgpack.org/
 
 
 === jsave.m ===
 
-      jsave    % save workspace to jamdata.jamm
+      jsave    % save the current workspace to jamdata.jamm
       jsave mydata.jamm
       jsave('mydata.jamm','vars',{'var1','var2'})
       jsave('mydata.jamm','compression','lzma')
       jsave('mydata.json','compression','gzip')
 
 === jload.m ===
 
-      jload    % load from jamdata.jamm
+      jload    % load variables from jamdata.jamm to the current workspace
       jload mydata.jamm
       jload('mydata.jamm','vars',{'var1','var2'})
       jload('mydata.jamm','simplifycell',0)
@@ -338,23 +343,23 @@ The main benefits of using .jamm file to share matlab variables include
 
 V. Sharing JSONLab created data files in Python
 
-Despite the use of data annotation schemes defined by the JData Specification, 
+Despite the use of portable data annotation defined by the JData Specification, 
 the output JSON files created by JSONLab are 100% JSON compatible (with
 the exception that long strings may be broken into multiple lines for better
 readability). Therefore, JSONLab-created JSON files (`.json, .jnii, .jnirs` etc) 
 can be readily read and written by nearly all existing JSON parsers, including
 the built-in `json` module parser in Python.
 
 However, we strongly recommend one to use a lightweight `jdata` module, 
-developed by the same author, to pefrorm the extra JData encoding and decoding
+developed by the same author, to perform the extra JData encoding and decoding
 and convert JSON data directly to convenient Python/Numpy data structures.
 The `jdata` module can also directly read/write UBJSON/Binary JData outputs
 from JSONLab (`.bjd, .ubj, .bnii, .bnirs, .jamm` etc). Using binary JData
 files are exptected to produce much smaller file sizes and faster parsing,
 while maintainining excellent portability and generality.
 
-In short, to conveniently read/write data files created by JSONLab in Python,
-whether they are JSON based or binary JData/UBJSON based, one should download
+In short, to conveniently read/write data files created by JSONLab into Python,
+whether they are JSON based or binary JData/UBJSON based, one just need to download
 the below two light-weight python modules:
 
 * **jdata**: PyPi: https://pypi.org/project/jdata/  ; Github: https://github.com/fangq/pyjdata
@@ -365,18 +370,18 @@ To install these modules on Python 2.x, please first check if your system has
 
       sudo apt-get install python-pip python3-pip python-numpy python3-numpy
 
-After installation is done, one can then install the `jdata` and `bjdata` modules by
+After the installation is done, one can then install the ``jdata`` and ``bjdata`` modules by
 
       pip install jdata --user
       pip install bjdata --user
 
-To install these modules on Python 3.x, please replace `pip` by `pip3`.
+To install these modules for Python 3.x, please replace ``pip`` by ``pip3``.
 If one prefers to install these modules globally for all users, simply
 execute the above commands using `sudo` and remove the `--user` flag.
 
-The above modules requires built-in Python modules `json` and NumPy (`numpy`).
+The above modules require built-in Python modules `json` and NumPy (`numpy`).
 
-Once the necessary modules are installed, one can start `python` (or `python3`), and run
+Once the necessary modules are installed, one can type `python` (or `python3`), and run
 
       import jdata as jd
       import numpy as np
@@ -386,13 +391,13 @@ Once the necessary modules are installed, one can start `python` (or `python3`),
       data2=jd.loadb('myfile.ubj',object_pairs_hook=OrderedDict);
       data3=jd.loadb('myfile.jamm',object_pairs_hook=OrderedDict);
 
-where `jd.loadt()` function loads a text-based JSON file and perform
-JData decoding and convert the enclosed data into Python `dict`, `list` 
+where `jd.loadt()` function loads a text-based JSON file, performs
+JData decoding and converts the enclosed data into Python `dict`, `list` 
 and `numpy` objects. Similarly, `jd.loadb()` function loads a binary 
-JData/UBJSON file and perform similar conversion. One can directly call
+JData/UBJSON file and performs similar conversions. One can directly call
 `jd.load()` to open JSONLab (and derived toolboxes such as jnifti: 
 https://github.com/fangq/jnifti or jsnirfy: https://github.com/fangq/jsnirfy) 
-generated files based on their respective default file suffix.
+generated files based on their respective file suffix.
 
 Similarly, the `jb.savet()`, `jb.saveb()` and `jb.save` functions
 can revert the direction and convert a Python/Numpy object into JData encoded