Skip to content

Commit ab0812e

Browse files
chrissimpkinschrissimpkins
committed
updated PyPI docs
1 parent 06c53eb commit ab0812e

File tree

1 file changed

+111
-50
lines changed

1 file changed

+111
-50
lines changed

‎docs/README.rst

Lines changed: 111 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
1-
font-line |Build Status| |Build status|
2-
---------------------------------------
1+
font-line |Build Status| |Build status| |codecov.io|
2+
----------------------------------------------------
3+
4+
Source Repository: `https://github.com/source-foundry/font-line <https://github.com/source-foundry/font-line>`__
5+
Issue Tracker and Reporting: `https://github.com/source-foundry/font-line/issues <https://github.com/source-foundry/font-line/issues>`__
6+
37

48
About
59
~~~~~
@@ -23,6 +27,13 @@ Contents
2327
- `Changelog <https://github.com/source-foundry/font-line/blob/master/CHANGELOG.md>`__
2428
- `License <https://github.com/source-foundry/font-line/blob/master/docs/LICENSE>`__
2529

30+
Quickstart
31+
~~~~~~~~~~
32+
33+
- Install: ``$ pip install font-line``
34+
- Metrics Report: ``$ font-line report [font path]``
35+
- Modify line spacing: ``$font-line percent [integer %] [font path]``
36+
2637
Install
2738
~~~~~~~
2839

@@ -99,6 +110,8 @@ derived from these data are displayed with the ``report`` sub-command:
99110
- [hhea] Descent
100111
- [hhea] lineGap
101112
- [head] unitsPerEm
113+
- [head] yMax
114+
- [head] yMin
102115

103116
``report`` Sub-Command Usage
104117
''''''''''''''''''''''''''''
@@ -122,33 +135,38 @@ Example Font Vertical Metrics Report
122135
::
123136

124137
=== Hack-Regular.ttf ===
125-
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 ""
126-
SHA1: 3d5f3ccfa40406ad252b76a2219cb629df8e5ab3
138+
Version 2.020;DEV-03192016;
139+
SHA1: 638f033cc1b6a21597359278bee62cf7e96557ff
127140

141+
--- Metrics ---
128142
[head] Units per Em: 2048
143+
[head] yMax: 2001
144+
[head] yMin: -573
129145
[OS/2] TypoAscender: 1556
130146
[OS/2] TypoDescender: -492
131-
[OS/2] WinAscent: 1901
132-
[OS/2] WinDescent: 483
133-
[hhea] Ascent: 1901
134-
[hhea] Descent: -483
147+
[OS/2] WinAscent: 1901
148+
[OS/2] WinDescent: 483
149+
[hhea] Ascent: 1901
150+
[hhea] Descent: -483
135151

136-
[hhea] LineGap: 0
152+
[hhea] LineGap: 0
137153
[OS/2] TypoLineGap: 410
138154

139155
--- Height Calculations by Table Values ---
140156
[OS/2] TypoAscender to TypoDescender: 2048
141-
[OS/2] WinAscent to WinDescent: 2384
142-
[hhea] Ascent to Descent: 2384
157+
[OS/2] WinAscent to WinDescent: 2384
158+
[hhea] Ascent to Descent: 2384
143159

144160
--- Delta Values ---
145-
WinAscent to TypoAscender: 345
146-
Ascent to TypoAscender: 345
147-
WinDescent to TypoDescender: -9
148-
Descent to TypoDescender: -9
161+
WinAscent to TypoAscender: 345
162+
Ascent to TypoAscender: 345
163+
WinDescent to TypoDescender: -9
164+
Descent to TypoDescender: -9
149165

150-
--- Ratio of TypoLineGap to UPM ---
151-
TypoLineGap / UPM: 0.2
166+
--- Ratios ---
167+
(Typo Asc + Desc + Linegap) / UPM: 1.2
168+
(winAsc + winDesc) / UPM: 1.16
169+
(hhea Asc + Desc) / UPM: 1.16
152170

153171
The report includes the font version string, a SHA-1 hash digest of the
154172
font file, and OpenType table metrics that are associated with line
@@ -167,24 +185,23 @@ Vertical Metrics Modifications
167185
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
168186

169187
font-line supports automated line spacing modifications to a
170-
user-defined percentage of the TypoAscender to TypoDescender metric
171-
(often defined with the same value as the font units per em metric).
172-
This delta value will be abbreviated as TA:TD below.
188+
user-defined percentage of the units per em metric. This value will be
189+
abbreviated as UPM below.
173190

174191
``percent`` Sub-Command Usage
175192
'''''''''''''''''''''''''''''
176193

177-
Enter the desired percentage of the TA:TD metric as the first argument
178-
to the command. This should be *entered as an integer value*. Then enter
179-
one or more font paths to which you would like to apply your font
180-
metrics changes.
194+
Enter the desired percentage of the UPM as the first argument to the
195+
command. This should be *entered as an integer value*. Then enter one or
196+
more font paths to which you would like to apply your font metrics
197+
changes.
181198

182199
::
183200

184201
$ font-line percent [percent change] [fontpath 1] <fontpath ...>
185202

186-
A common default value used by typeface designers is 20%. To modify a
187-
font on the path ``TheFont.ttf`` to 20% of the TA:TD metric, you would
203+
A common default value used by typeface designers is 20% UPM. To modify
204+
a font on the path ``TheFont.ttf`` to 20% of the UPM metric, you would
188205
enter the following command:
189206

190207
::
@@ -204,32 +221,71 @@ OpenType table modifications that occur when the application is used on
204221
a font file.
205222

206223
You can inspect the vertical metrics in the new font file with the
207-
``report`` subcommand (see Usage above).
224+
``report`` sub-command (see Usage above).
208225

209226
Details of Font Metrics Changes with ``percent`` Sub-Command
210227
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
211228

212-
The interpretation of these multiple vertical metric values is platform
213-
and application dependent. This has led to `debate over the 'best'
214-
approach to cross-platform typeface line
215-
spacing <https://grahamwideman.wikispaces.com/Font+Vertical+Metrics>`__.
216-
The line spacing modification approach used in font-line is defined with
217-
a slightly modified version of Karsten Lücke's approach that is
218-
described `here <http://www.kltf.de/downloads/FontMetrics-kltf.pdf>`__.
229+
The interpretation and display of these multiple vertical metrics values
230+
is platform and application dependent. `There is no broadly accepted
231+
"best"
232+
approach <https://github.com/source-foundry/font-line/issues/2>`__. As
233+
such, font-line attempts to preserve the original metrics design in the
234+
font when modifications are made with the ``percent`` sub-command.
219235

220-
*The following values are preserved from the original font design*:
236+
font-line currently supports three commonly used vertical metrics
237+
approaches.
221238

222-
- [OS/2] TypoAscender
223-
- [OS/2] TypoDescender
239+
**Vertical Metrics Approach 1**:
240+
241+
Where metrics are defined as:
242+
243+
- [OS/2] TypoLinegap = 0
244+
- [hhea] linegap = 0
245+
- [OS/2] TypoAscender = [OS/2] winAscent = [hhea] Ascent
246+
- [OS/2] TypoDescender = [OS/2] winDescent = [hhea] Descent
224247

225-
We assume that the TypoAscender - TypoDescender delta value is
226-
equivalent to the UPM size, and therefore that the percent TA:TD value
227-
is equivalent to percent UPM when line spacing is defined.
248+
font-line calculates a delta value for the total expected height based
249+
upon the % UPM value defined on the command line. The difference between
250+
this value and the observed number of units that span the [OS/2]
251+
winAscent to winDescent values is divided by half and then added to (for
252+
increased line spacing) or subtracted from (for decreased line spacing)
253+
each of the three sets of Ascender/Descender values in the font. The
254+
[OS/2] TypoLinegap and [hhea] linegap values are not modified.
228255

229-
*Changes to OpenType metrics values in the font are defined as*:
256+
**Vertical Metrics Approach 2**
230257

231-
- [hhea] lineGap is always set to 0
232-
- [OS/2] TypoLineGap = x% \* TA:TD value
258+
Where metrics are defined as:
259+
260+
- [OS/2] TypoLinegap = 0
261+
- [hhea] linegap = 0
262+
- [OS/2] TypoAscender + TypoDescender = UPM
263+
- [OS/2] winAscent = [hhea] Ascent
264+
- [OS/2] winDescent = [hhea] Descent
265+
266+
font-line calculates a delta value for the total expected height based
267+
upon the % UPM value defined on the command line. The difference between
268+
this value and the observed number of units that span the [OS/2]
269+
winAscent to winDescent values is divided by half and then added to (for
270+
increased line spacing) or subtracted from (for decreased line spacing)
271+
the [OS/2] winAsc/winDesc and [hhea] Asc/Desc values. The [OS/2]
272+
TypoAsc/TypoDesc values are not modified and maintain a definition of
273+
size = UPM value. The [OS/2] TypoLinegap and [hhea] linegap values are
274+
not modified.
275+
276+
**Vertical Metrics Approach 3**
277+
278+
Where metrics are defined as:
279+
280+
- [OS/2] TypoAscender + TypoDescender = UPM
281+
- [OS/2] TypoLinegap is set to leading value
282+
- [hhea] linegap = 0
283+
- [OS/2] winAscent = [hhea] Ascent
284+
- [OS/2] winDescent = [hhea] Descent
285+
286+
*Changes to the metrics values in the font are defined as*:
287+
288+
- [OS/2] TypoLineGap = x% \* UPM value
233289
- [hhea] Ascent = [OS/2] TypoAscender + 0.5(modified TypoLineGap)
234290
- [hhea] Descent = [OS/2] TypoDescender + 0.5(modified TypoLineGap)
235291
- [OS/2] WinAscent = [OS/2] TypoAscender + 0.5(modified TypoLineGap)
@@ -239,14 +295,17 @@ Note that the internal leading modifications are split evenly across
239295
[hhea] Ascent & Descent values, and across [OS/2] WinAscent & WinDescent
240296
values. We add half of the new [OS/2] TypoLineGap value to the original
241297
[OS/2] TypoAscender or TypoDescender in order to define these new
242-
metrics properties.
298+
metrics properties. The [hhea] linegap value is always defined as zero.
299+
300+
Important
301+
^^^^^^^^^
243302

244-
These newly defined properties can lead to clipping of glyph components
245-
if not properly defined. There are no tests in font-line to provide
246-
assurance that this does not occur. We assume that the user is versed in
247-
these issues before use of the application and leave this testing to the
248-
designer / user before the modified fonts are used in a production
249-
setting.
303+
The newly defined vertical metrics values can lead to clipping of glyph
304+
components if not properly defined. There are no tests in font-line to
305+
provide assurance that this does not occur. We assume that the user is
306+
versed in these issues before use of the application and leave this
307+
testing to the designer / user before the modified fonts are used in a
308+
production setting.
250309

251310
Issue Reporting
252311
~~~~~~~~~~~~~~~
@@ -265,3 +324,5 @@ font-line is built with the fantastic
265324
:target: https://travis-ci.org/source-foundry/font-line
266325
.. |Build status| image:: https://ci.appveyor.com/api/projects/status/2s4725o5mxh2298c/branch/master?svg=true
267326
:target: https://ci.appveyor.com/project/chrissimpkins/font-line/branch/master
327+
.. |codecov.io| image:: https://codecov.io/github/source-foundry/font-line/coverage.svg?branch=master
328+
:target: https://codecov.io/github/source-foundry/font-line?branch=master

0 commit comments

Comments
 (0)