From efd4104a191b61dbccf522073ecdf33e9f5c5d65 Mon Sep 17 00:00:00 2001
From: HuanWeng <huanweng2015@u.northwestern.edu>
Date: Thu, 30 Aug 2018 02:08:52 -0500
Subject: [PATCH] Rewrite README's

---
 packages/Mathematica/README.md | 80 ++++++++++++++++++++++++----------
 packages/Matlab/README.md      | 50 +++++++++++++++------
 packages/Python/README.md      | 53 ++++++++++++++++++++--
 3 files changed, 142 insertions(+), 41 deletions(-)

diff --git a/packages/Mathematica/README.md b/packages/Mathematica/README.md
index eb4532b..709e145 100644
--- a/packages/Mathematica/README.md
+++ b/packages/Mathematica/README.md
@@ -4,29 +4,31 @@ This package is the code library for _Modern Robotics: Mechanics, Planning,
 and Control_. [Here](../../doc/MRlib.pdf) is the introduction. For more 
 details please see the [website](http://modernrobotics.org/).
 
+## Installing the Package ##
+
+### Recommended Installation Instructions ###
+
 If you'd like to be able to use this package inside of any notebook, 
 regardless of the notebook's location on your filesystem, then you can use 
 Mathematica's front end to install this package. Use the following steps:
 
-1. Click `File -> Install...`
-2. Select `Package` for the _Type of Item to Install_
-3. Chose `From File...` for the _Source_
-4. Navigate to the `ModernRobotics.m` and select it as the source for the 
+1. Download this package
+2. Click `File -> Install...`
+3. Select `Package` for the _Type of Item to Install_
+4. Chose `From File...` for the _Source_
+5. Navigate to the `ModernRobotics.m` and select it as the source for the 
    package
-5. The _Install Name_ should default to `ModernRobotics`; if it doesn't then
+6. The _Install Name_ should default to `ModernRobotics`; if it doesn't then
    fill in the install name to be `ModernRobotics`.
-6. Choose whether you want the package installed for a single user or for all
+7. Choose whether you want the package installed for a single user or for all
    users (may require administrative privileges)
-7. Click `OK`
+8. Click `OK`
 
-Now from any notebook you should be able to load the library by running:
+### Manual Installation Instructions ###
 
-```
-<<ModernRobotics`
-```
-
-If you'd like to uninstall the package, you can just delete the file 
-`ModernRobotics.wl` or `ModernRobotics.m` in the following directory.
+If you have any troubles with the front-end installation described above, try
+manually installing the package by copying the `ModernRobotics.m` file into 
+the following director.
 
 ```sh
 $MATHPATH/Applications/ModernRobotics/
@@ -40,22 +42,42 @@ common operating systems:
 + Linux (Debian):      `~/.Mathematica/`
 + Windows:             `%APPDATA%\Mathematica\`
 
+## Loading the Package ##
 
-## Manual Installation Instructions ##
+After installing the package, load the library from any notebook by running
 
-If you have any troubles with the front-end installation described above, you
-can try manually installing the package by copying the `ModernRobotics.m` 
-file into the same directory mentioned for uninstalling.
+```
+<<ModernRobotics`
+```
 
+This process is required for any notebook using this package.
 
-# Using the Package Locally #
+## Using the Package ##
 
-If you don't want to install the package at all, it is possible to place it
-anywhere on your filesystem and then load it into a notebook using
+After loading the package, you should be able to use any function in the 
+package. Taking the function `RotInv` for example, you can check the 
+description and usage example of this function by running
+
+```
+?RotInv
+```
+
+As mentioned in the function usage example, you can try using this function
+by running
+
+```
+invR = RotInv[{{0,0,1},{1,0,0},{0,1,0}}]
+```
+
+You should get the the same output as shown in the function usage example.
+
+## Using the Package Locally ##
+
+It is possible to use the package locally without installation. Download and
+place the package anywhere on your filesystem and then run
 
 ```
 SetDirectory["<PATH-TO-DIRECTORY-CONTAINING-ModernRobotics.m>"]
-<<ModernRobotics`
 ```
 
 If the notebook and the package are located in the same directory you could 
@@ -63,5 +85,17 @@ use
 
 ```
 SetDirectory[NotebookDirectory[]]
-<<ModernRobotics`
 ```
+
+Note that since the package is not installed, you need to set the directory
+shown above in every notebook in which this package is used. Loading is still
+required before using.
+
+## Uninstalling the Package ##
+
+To uninstall the package, delete the file `ModernRobotics.wl` or 
+`ModernRobotics.m` in the following directory.
+
+```sh
+$MATHPATH/Applications/ModernRobotics/
+```
\ No newline at end of file
diff --git a/packages/Matlab/README.md b/packages/Matlab/README.md
index f0f1c65..5a2789a 100644
--- a/packages/Matlab/README.md
+++ b/packages/Matlab/README.md
@@ -1,16 +1,44 @@
-# "mr" Matlab Package Instructions #
+# "mr" Matlab Code Library Instructions #
 
-This package is the code library for _Modern Robotics: Mechanics, Planning, 
-and Control_. [Here](../../doc/MRlib.pdf) is the introduction. For more 
-details please see the [website](http://modernrobotics.org/).
+This is the code library for _Modern Robotics: Mechanics, Planning, and 
+Control_. [Here](../../doc/MRlib.pdf) is the introduction. For more details 
+please see the [website](http://modernrobotics.org/).
 
-To import the package, use `addpath` as
+## Installing the Library ##
+
+This code library does not need installation.
+
+## Importing the Library ##
+
+To import the library, use `addpath` as
 
 ```
 addpath('$FOLDER_PATH/mr')
 ```
 
-where `$FOLDER_PATH` is the path to "mr" directory. 
+where `$FOLDER_PATH` is the path to "mr" folder. This process is required for
+any program using this package.
+
+## Using the Package ##
+
+After importing the library, you should be able to use any function in the 
+library. Taking the function `RotInv` for example, you can check the 
+description and usage example of this function by running
+
+```
+help RotInv
+```
+
+As mentioned in the function usage example, you can try using this function
+by running
+
+```
+R = [0, 0, 1; 1, 0, 0; 0, 1, 0];
+invR = RotInv(R);
+```
+
+You should get the the variable `invR` whose value is the same as the output
+shown in the function usage example.
 
 To check the function list and which chapter in the book do those functions 
 belong to, use `help` as 
@@ -19,13 +47,7 @@ belong to, use `help` as
 help mr
 ```
 
-To check more introduction and example of a function, use `help` as 
-
-```
-help $FUNCTION_NAME
-```
-
-##  ##
+## Library Information ##
 
 Author: Huan Weng, Bill Hunt, Mikhail Todes, Jarvis Schultz
 
@@ -35,4 +57,4 @@ Package Version: 1.0.0
 
 Matlab Version: R2017b
 
-Tested in Matlab R2017b
+Tested in Matlab R2017b
\ No newline at end of file
diff --git a/packages/Python/README.md b/packages/Python/README.md
index d700c87..12e5fb0 100644
--- a/packages/Python/README.md
+++ b/packages/Python/README.md
@@ -4,16 +4,61 @@ This package is the code library for _Modern Robotics: Mechanics, Planning,
 and Control_. [Here](../../doc/MRlib.pdf) is the introduction. For more 
 details please see the [website](http://modernrobotics.org/).
 
-To use the package, you can either
+## Installing the Package ##
 
-* Run `python setup.py build` and `python setup.py install` in the package directory
+### Recommended Method ###
 
-* Run `pip install modern_robotics` to use pip to install
+Use [pip](https://en.wikipedia.org/wiki/Pip_(package_manager)) to install by
+running
 
-* Copy `modern_robotics` directory into working directory
+```
+pip install modern_robotics
+``` 
+
+If pip is not preinstalled, check 
+[here](https://pip.pypa.io/en/stable/installing/) for help of installing pip. 
+
+### Alternative Method ###
+
+Download the package and run `python setup.py build` and 
+`python setup.py install` in the package directory
+
+## Importing the Package ##
 
 To import the package, we recommend using
 
 ```
 import modern_robotics as mr
 ```
+
+This process is required for any Python program using this package.
+
+## Using the Package ##
+
+After importing the package, you should be able to use any function in the 
+package. Taking the function `RotInv` for example, you can check the 
+description and usage example of this function by running
+
+```
+help(mr.RotInv)
+```
+
+As mentioned in the function usage example, you can try using this function
+by running
+
+```
+R = np.array([[0, 0, 1],
+              [1, 0, 0],
+              [0, 1, 0]])
+invR = mr.RotInv(R)
+```
+
+You should get the the variable `invR` whose value is the same as the output
+shown in the function usage example.
+
+## Using the Package Locally ##
+
+It is possible to use the package locally without installation. Download and
+place the package in the working directory. Note that since the package is 
+not installed, you need to move the package if the working directory is
+changed. Importing is still required before using.
\ No newline at end of file