updated readme for v0.6.0

Author: chrissimpkins

README.md

@@ -143,17 +143,17 @@ 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.
+font-line supports automated line spacing modifications to a user-defined percentage of the units per em metric.  This value will be abbreviated as UPM below.
 
 ##### `percent` Sub-Command Usage
 
-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.
+Enter the desired percentage of the UPM 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 ...>
 ```
 
-A common default value used by typeface designers is 20%.  To modify a font on the path `TheFont.ttf` to 20% of the TA:TD metric, you would enter the following command:
+A common default value used by typeface designers is 20% UPM.  To modify a font on the path `TheFont.ttf` to 20% of the UPM metric, you would enter the following command:
 
 ```
 $ font-line percent 20 TheFont.ttf
@@ -163,31 +163,60 @@ 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 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` sub-command (see Usage above).
 
 ##### Details of Font Metrics Changes with `percent` Sub-Command
 
-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 interpretation and display of these multiple vertical metrics values is platform and application dependent.  [There is no broadly accepted "best" approach](https://github.com/source-foundry/font-line/issues/2).  As such, font-line attempts to preserve the original metrics design in the font when modifications are made with the `percent` sub-command.
 
-*The following values are preserved from the original font design*:
+font-line currently supports three commonly used vertical metrics approaches.
 
-- [OS/2] TypoAscender
-- [OS/2] TypoDescender
+**Vertical Metrics Approach 1**:
+
+Where metrics are defined as:
+
+- [OS/2] TypoLinegap = 0
+- [hhea] linegap = 0
+- [OS/2] TypoAscender = [OS/2] winAscent = [hhea] Ascent
+- [OS/2] TypoDescender = [OS/2] winDescent = [hhea] Descent
+
+font-line calculates a delta value for the total expected height based upon the % UPM value defined on the command line.  The difference between this value and the observed number of units that span the [OS/2] winAscent to winDescent values is divided by half and then added to (for increased line spacing) or subtracted from (for decreased line spacing) each of the three sets of Ascender/Descender values in the font.  The [OS/2] TypoLinegap and [hhea] linegap values are not modified.
+
+**Vertical Metrics Approach 2**
 
-We assume that the TypoAscender - TypoDescender delta value is equivalent to the UPM size, and therefore that the percent TA:TD value is equivalent to percent UPM when line spacing is defined.
+Where metrics are defined as:
 
-*Changes to OpenType metrics values in the font are defined as*:
+- [OS/2] TypoLinegap = 0
+- [hhea] linegap = 0
+- [OS/2] TypoAscender + TypoDescender = UPM
+- [OS/2] winAscent = [hhea] Ascent
+- [OS/2] winDescent = [hhea] Descent
 
-- [hhea] lineGap is always set to 0
-- [OS/2] TypoLineGap = x% * TA:TD value
+font-line calculates a delta value for the total expected height based upon the % UPM value defined on the command line.  The difference between this value and the observed number of units that span the [OS/2] winAscent to winDescent values is divided by half and then added to (for increased line spacing) or subtracted from (for decreased line spacing) the [OS/2] winAsc/winDesc and [hhea] Asc/Desc values.  The [OS/2] TypoAsc/TypoDesc values are not modified and maintain a definition of size = UPM value. The [OS/2] TypoLinegap and [hhea] linegap values are not modified.
+
+**Vertical Metrics Approach 3**
+
+Where metrics are defined as:
+
+- [OS/2] TypoAscender + TypoDescender = UPM
+- [OS/2] TypoLinegap is set to leading value
+- [hhea] linegap = 0
+- [OS/2] winAscent = [hhea] Ascent
+- [OS/2] winDescent = [hhea] Descent
+
+*Changes to the metrics values in the font are defined as*:
+
+- [OS/2] TypoLineGap = x% * UPM value
 - [hhea] Ascent = [OS/2] TypoAscender + 0.5(modified TypoLineGap)
 - [hhea] Descent = [OS/2] TypoDescender + 0.5(modified TypoLineGap)
 - [OS/2] WinAscent = [OS/2] TypoAscender + 0.5(modified TypoLineGap)
 - [OS/2] WinDescent = [OS/2] TypoDescender + 0.5(modified TypoLineGap)
 
-Note that the internal leading modifications are split evenly across [hhea] Ascent & Descent values, and across [OS/2] WinAscent & WinDescent values.  We add half of the new [OS/2] TypoLineGap value to the original [OS/2] TypoAscender or TypoDescender in order to define these new metrics properties. 
+Note that the internal leading modifications are split evenly across [hhea] Ascent & Descent values, and across [OS/2] WinAscent & WinDescent values.  We add half of the new [OS/2] TypoLineGap value to the original [OS/2] TypoAscender or TypoDescender in order to define these new metrics properties.   The [hhea] linegap value is always defined as zero.
+
+#### Important
 
-These newly defined properties can lead to clipping of glyph components if not properly defined.  There are no tests in font-line to provide assurance that this does not occur. We assume that the user is versed in these issues before use of the application and leave this testing to the designer / user before the modified fonts are used in a production setting.
+The newly defined vertical metrics values can lead to clipping of glyph components if not properly defined.  There are no tests in font-line to provide assurance that this does not occur. We assume that the user is versed in these issues before use of the application and leave this testing to the designer / user before the modified fonts are used in a production setting.
 
 
 ### Issue Reporting