updated README file, clarifications

Author: chrissimpkins

README.md

@@ -2,7 +2,7 @@
 
 
 ### About
-font-line is a libre open source command line tool for font vertical metrics reporting and line spacing modifications.  It currently supports reporting and modifications of `.ttf` and `.otf` font builds.
+font-line is a libre open source command line tool for font vertical metrics reporting and line spacing modifications.  It currently supports `.ttf` and `.otf` font builds.
 
 ### Contents
 
@@ -15,16 +15,24 @@ font-line is a libre open source command line tool for font vertical metrics rep
 
 ### Install
 
-font-line is built with Python and can be used on systems with Python 2.7+ and Python 3.3+ interpreters. Use either of the following methods to install font-line on your system.
+font-line is built with Python and can be used on systems with Python 2.7+ and Python 3.3+ interpreters, including current releases of pypy and pypy3. You can verify your installed Python version on the command line with the command: 
+
+```
+$ python --version
+```  
+
+Use either of the following methods to install font-line on your system.
 
 #### pip Install
 
-The latest release version is available through the Python Package Index and can be installed with pip:
+The latest font-line release is available through the Python Package Index and can be installed with pip:
 
 ```
 $ pip install font-line
 ```
 
+To upgrade to a new version of font-line after a pip install, use the command `pip install --upgrade font-line`.
+
 #### Download Project Repository and Install
 
 The current repository version (which may be ahead of the PyPI release) can be installed by [downloading the repository](https://github.com/source-foundry/font-line/archive/master.zip) or cloning it with git:
@@ -39,11 +47,13 @@ Navigate to the top level repository directory and enter the following command:
 $ python setup.py install
 ```
 
+Follow the same instructions to upgrade to a new version of the application if you elect to install with this approach.
+
 ### Usage
 
-font-line works via sub-commands to the `font-line` executable.  The following sub-commands are available:
+font-line works via sub-commands to the `font-line` command line executable.  The following sub-commands are available:
 
-- `percent` - modify the line spacing of a font to a percent of the Ascender to Descender delta value
+- `percent` - modify the line spacing of a font to a percent of the Ascender to Descender distance
 - `report` - report OpenType metrics values for a font
 
 Usage of these sub-commands is described in detail below.
@@ -70,8 +80,13 @@ Enter one or more font path arguments to the command:
 $ font-line report [fontpath 1] <fontpath ...>
 ``` 
 
-Here is an example of the report generated with `font-line report`:
+Here is an example of the report generated with the Hack typeface file `Hack-Regular.ttf` using the command:
 
+```
+$ font-line report Hack-Regular.ttf
+```
+
+##### Example Font Vertical Metrics Report
 ```
 === Hack-Regular.ttf ===
 Version 2.019; ttfautohint (v1.4.1) -l 4 -r 80 -G 350 -x 0 -H 181 -D latn -f latn -w G -W -t -X ""
@@ -103,19 +118,23 @@ Descent to TypoDescender: 	-9
 TypoLineGap / UPM: 	0.2
 ```
 
+The report includes the font version string, a SHA-1 hash digest of the font file, and OpenType table metrics that are associated with line spacing in the font.
+
 Unix/Linux/OS X users can write this report to a file with the `>` command line idiom:
 
 ```
 $ font-line report TheFont.ttf > font-report.txt
 ```
 
+You can modify `font-report.txt` to the file path of your choice.
+
 #### Vertical Metrics Modifications
 
 font-line supports automated line spacing modifications to a user-defined percentage of the TypoAscender to TypoDescender metric (often defined with the same value as the font units per em metric).  This delta value will be abbreviated as TA:TD below.
 
 ##### `percent` Sub-Command Usage
 
-Enter the desired percentage of the TA:TD metric as the first argument to the command.  This should be formatted as an integer value.  Then enter one or more font paths to which you would like to apply your font metrics changes.
+Enter the desired percentage of the TA:TD metric as the first argument to the command.  This should be *entered as an integer value*.  Then enter one or more font paths to which you would like to apply your font metrics changes.
 
 ```
 $ font-line percent [percent change] [fontpath 1] <fontpath ...>
@@ -131,11 +150,11 @@ Increase or decrease the integer value to increase or decrease your line spacing
 
 The original font file is preserved in an unmodified version and the modified file write takes place on a new path defined as `[original filename]-linegap[percent].[ttf|otf]`.  The path to the file is reported to you in the standard output after the modification is completed.  font-line does not modify the glyph set or hints applied to the font.  See the Details section below for a description of the OpenType table modifications that occur when the application is used on a font file.
 
-You can inspect the new vertical metrics in the new font file with the `report` subcommand (see Usage above).
+You can inspect the vertical metrics in the new font file with the `report` subcommand (see Usage above).
 
 ##### Details of Font Metrics Changes with `percent` Sub-Command
 
-The interpretation of the multiple vertical metric values is platform and application dependent.  This has led to [debate over the 'best' approach to font line spacing](https://grahamwideman.wikispaces.com/Font+Vertical+Metrics). The line spacing modification approach used in font-line is defined with a  slightly modified version of Karsten Lücke's approach that is described [here](http://www.kltf.de/downloads/FontMetrics-kltf.pdf).
+The interpretation of these multiple vertical metric values is platform and application dependent.  This has led to [debate over the 'best' approach to cross-platform typeface line spacing](https://grahamwideman.wikispaces.com/Font+Vertical+Metrics). The line spacing modification approach used in font-line is defined with a  slightly modified version of Karsten Lücke's approach that is described [here](http://www.kltf.de/downloads/FontMetrics-kltf.pdf).
 
 *The following values are preserved from the original font design*: