Skip to content

Commit 709ce9c

Browse files
chrissimpkinschrissimpkins
committed
updated README files
1 parent a60220e commit 709ce9c

File tree

2 files changed

+203
-127
lines changed

2 files changed

+203
-127
lines changed

‎README.md

Lines changed: 199 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,189 +1,267 @@
1-
## font-line [![Build Status](https://travis-ci.org/source-foundry/font-line.svg?branch=master)](https://travis-ci.org/source-foundry/font-line) [![Build status](https://ci.appveyor.com/api/projects/status/2s4725o5mxh2298c/branch/master?svg=true)](https://ci.appveyor.com/project/chrissimpkins/font-line/branch/master)
1+
font-line |Build Status| |Build status|
2+
---------------------------------------
23

4+
About
5+
~~~~~
36
4-
### About
5-
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.
7+
font-line is a libre, open source command line tool for OpenType
8+
vertical metrics reporting and command line based font line spacing
9+
modifications. It currently supports ``.ttf`` and ``.otf`` font builds.
610
7-
### Contents
11+
Contents
12+
~~~~~~~~
813
9-
- [Install Guide](https://github.com/source-foundry/font-line#install)
10-
- [Usage](https://github.com/source-foundry/font-line#usage)
11-
- [Vertical Metrics Reporting](https://github.com/source-foundry/font-line#vertical-metrics-reporting)
12-
- [Line Spacing Modifications](https://github.com/source-foundry/font-line#vertical-metrics-modifications)
13-
- [Changelog](https://github.com/source-foundry/font-line/blob/master/CHANGELOG.md)
14-
- [License](https://github.com/source-foundry/font-line/blob/master/docs/LICENSE)
14+
- `Install
15+
Guide <https://github.com/source-foundry/font-line#install>`__
16+
- `Usage <https://github.com/source-foundry/font-line#usage>`__
1517
16-
### Install
18+
- `Vertical Metrics
19+
Reporting <https://github.com/source-foundry/font-line#vertical-metrics-reporting>`__
20+
- `Line Spacing
21+
Modifications <https://github.com/source-foundry/font-line#vertical-metrics-modifications>`__
1722
18-
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:
23+
- `Changelog <https://github.com/source-foundry/font-line/blob/master/CHANGELOG.md>`__
24+
- `License <https://github.com/source-foundry/font-line/blob/master/docs/LICENSE>`__
1925
20-
```
21-
$ python --version
22-
```
26+
Install
27+
~~~~~~~
28+
29+
font-line is built with Python and can be used on systems with Python
30+
2.7+ and Python 3.3+ interpreters, including current releases of pypy
31+
and pypy3. You can verify your installed Python version on the command
32+
line with the command:
33+
34+
::
35+
36+
$ python --version
2337
2438
Use either of the following methods to install font-line on your system.
2539
26-
#### pip Install
40+
pip Install
41+
^^^^^^^^^^^
2742
28-
The latest font-line release is available through the Python Package Index and can be installed with pip:
43+
The latest font-line release is available through the Python Package
44+
Index and can be installed with pip:
2945
30-
```
31-
$ pip install font-line
32-
```
46+
::
3347
34-
To upgrade to a new version of font-line after a pip install, use the command `pip install --upgrade font-line`.
48+
$ pip install font-line
3549
36-
#### Download Project Repository and Install
50+
To upgrade to a new version of font-line after a pip install, use the
51+
command ``pip install --upgrade font-line``.
3752
38-
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:
53+
Download Project Repository and Install
54+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3955
40-
```
41-
git clone https://github.com/source-foundry/font-line.git
42-
```
56+
The current repository version (which may be ahead of the PyPI release)
57+
can be installed by `downloading the
58+
repository <https://github.com/source-foundry/font-line/archive/master.zip>`__
59+
or cloning it with git:
4360
44-
Navigate to the top level repository directory and enter the following command:
61+
::
4562
46-
```
47-
$ python setup.py install
48-
```
63+
git clone https://github.com/source-foundry/font-line.git
4964
50-
Follow the same instructions to upgrade to a new version of the application if you elect to install with this approach.
65+
Navigate to the top level repository directory and enter the following
66+
command:
5167
52-
### Usage
68+
::
5369
54-
font-line works via sub-commands to the `font-line` command line executable. The following sub-commands are available:
70+
$ python setup.py install
5571
56-
- `percent` - modify the line spacing of a font to a percent of the Ascender to Descender distance
57-
- `report` - report OpenType metrics values for a font
72+
Follow the same instructions to upgrade to a new version of the
73+
application if you elect to install with this approach.
5874
59-
Usage of these sub-commands is described in detail below.
75+
Usage
76+
~~~~~
6077

61-
#### Vertical Metrics Reporting
78+
font-line works via sub-commands to the ``font-line`` command line
79+
executable. The following sub-commands are available:
6280

63-
The following OpenType vertical metrics values and calculated values derived from these data are displayed with the `report` sub-command:
81+
- ``percent`` - modify the line spacing of a font to a percent of the
82+
Ascender to Descender distance
83+
- ``report`` - report OpenType metrics values for a font
6484

65-
- [OS/2] TypoAscender
66-
- [OS/2] TypoDescender
67-
- [OS/2] WinAscent
68-
- [OS/2] WinDescent
69-
- [OS/2] TypoLineGap
70-
- [hhea] Ascent
71-
- [hhea] Descent
72-
- [hhea] lineGap
73-
- [head] unitsPerEm
85+
Usage of these sub-commands is described in detail below.
7486

75-
##### `report` Sub-Command Usage
87+
Vertical Metrics Reporting
88+
^^^^^^^^^^^^^^^^^^^^^^^^^^
7689

77-
Enter one or more font path arguments to the command:
90+
The following OpenType vertical metrics values and calculated values
91+
derived from these data are displayed with the ``report`` sub-command:
7892

79-
```
80-
$ font-line report [fontpath 1] <fontpath ...>
81-
```
93+
- [OS/2] TypoAscender
94+
- [OS/2] TypoDescender
95+
- [OS/2] WinAscent
96+
- [OS/2] WinDescent
97+
- [OS/2] TypoLineGap
98+
- [hhea] Ascent
99+
- [hhea] Descent
100+
- [hhea] lineGap
101+
- [head] unitsPerEm
82102

83-
Here is an example of the report generated with the Hack typeface file `Hack-Regular.ttf` using the command:
103+
``report`` Sub-Command Usage
104+
''''''''''''''''''''''''''''
84105

85-
```
86-
$ font-line report Hack-Regular.ttf
87-
```
106+
Enter one or more font path arguments to the command:
88107

89-
##### Example Font Vertical Metrics Report
90-
```
91-
=== Hack-Regular.ttf ===
92-
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 ""
93-
SHA1: 3d5f3ccfa40406ad252b76a2219cb629df8e5ab3
108+
::
94109

95-
[head] Units per Em: 2048
96-
[OS/2] TypoAscender: 1556
97-
[OS/2] TypoDescender: -492
98-
[OS/2] WinAscent: 1901
99-
[OS/2] WinDescent: 483
100-
[hhea] Ascent: 1901
101-
[hhea] Descent: -483
110+
$ font-line report [fontpath 1] <fontpath ...>
102111

103-
[hhea] LineGap: 0
104-
[OS/2] TypoLineGap: 410
112+
Here is an example of the report generated with the Hack typeface file
113+
``Hack-Regular.ttf`` using the command:
105114

106-
--- Height Calculations by Table Values ---
107-
[OS/2] TypoAscender to TypoDescender: 2048
108-
[OS/2] WinAscent to WinDescent: 2384
109-
[hhea] Ascent to Descent: 2384
115+
::
110116

111-
--- Delta Values ---
112-
WinAscent to TypoAscender: 345
113-
Ascent to TypoAscender: 345
114-
WinDescent to TypoDescender: -9
115-
Descent to TypoDescender: -9
117+
$ font-line report Hack-Regular.ttf
116118

117-
--- Ratio of TypoLineGap to UPM ---
118-
TypoLineGap / UPM: 0.2
119-
```
119+
Example Font Vertical Metrics Report
120+
''''''''''''''''''''''''''''''''''''
120121

121-
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.
122+
::
122123

123-
Unix/Linux/OS X users can write this report to a file with the `>` command line idiom:
124+
=== 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
124127

125-
```
126-
$ font-line report TheFont.ttf > font-report.txt
127-
```
128+
[head] Units per Em: 2048
129+
[OS/2] TypoAscender: 1556
130+
[OS/2] TypoDescender: -492
131+
[OS/2] WinAscent: 1901
132+
[OS/2] WinDescent: 483
133+
[hhea] Ascent: 1901
134+
[hhea] Descent: -483
128135

129-
You can modify `font-report.txt` to the file path of your choice.
136+
[hhea] LineGap: 0
137+
[OS/2] TypoLineGap: 410
130138

131-
#### Vertical Metrics Modifications
139+
--- Height Calculations by Table Values ---
140+
[OS/2] TypoAscender to TypoDescender: 2048
141+
[OS/2] WinAscent to WinDescent: 2384
142+
[hhea] Ascent to Descent: 2384
132143

133-
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.
144+
--- Delta Values ---
145+
WinAscent to TypoAscender: 345
146+
Ascent to TypoAscender: 345
147+
WinDescent to TypoDescender: -9
148+
Descent to TypoDescender: -9
134149

135-
##### `percent` Sub-Command Usage
150+
--- Ratio of TypoLineGap to UPM ---
151+
TypoLineGap / UPM: 0.2
136152

137-
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.
153+
The report includes the font version string, a SHA-1 hash digest of the
154+
font file, and OpenType table metrics that are associated with line
155+
spacing in the font.
138156

139-
```
140-
$ font-line percent [percent change] [fontpath 1] <fontpath ...>
141-
```
157+
Unix/Linux/OS X users can write this report to a file with the ``>``
158+
command line idiom:
142159

143-
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:
160+
::
144161

145-
```
146-
$ font-line percent 20 TheFont.ttf
147-
```
162+
$ font-line report TheFont.ttf > font-report.txt
148163

149-
Increase or decrease the integer value to increase or decrease your line spacing accordingly.
164+
You can modify ``font-report.txt`` to the file path of your choice.
150165

151-
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.
166+
Vertical Metrics Modifications
167+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
152168

153-
You can inspect the vertical metrics in the new font file with the `report` subcommand (see Usage above).
169+
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.
154173

155-
##### Details of Font Metrics Changes with `percent` Sub-Command
174+
``percent`` Sub-Command Usage
175+
'''''''''''''''''''''''''''''
156176

157-
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).
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.
158181

159-
*The following values are preserved from the original font design*:
182+
::
160183

161-
- [OS/2] TypoAscender
162-
- [OS/2] TypoDescender
184+
$ font-line percent [percent change] [fontpath 1] <fontpath ...>
163185

164-
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.
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
188+
enter the following command:
165189

166-
*Changes to OpenType metrics values in the font are defined as*:
190+
::
167191

168-
- [hhea] lineGap is always set to 0
169-
- [OS/2] TypoLineGap = x% * TA:TD value
170-
- [hhea] Ascent = [OS/2] TypoAscender + 0.5(modified TypoLineGap)
171-
- [hhea] Descent = [OS/2] TypoDescender + 0.5(modified TypoLineGap)
172-
- [OS/2] WinAscent = [OS/2] TypoAscender + 0.5(modified TypoLineGap)
173-
- [OS/2] WinDescent = [OS/2] TypoDescender + 0.5(modified TypoLineGap)
192+
$ font-line percent 20 TheFont.ttf
174193

175-
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.
194+
Increase or decrease the integer value to increase or decrease your line
195+
spacing accordingly.
176196

177-
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.
197+
The original font file is preserved in an unmodified version and the
198+
modified file write takes place on a new path defined as
199+
``[original filename]-linegap[percent].[ttf|otf]``. The path to the file
200+
is reported to you in the standard output after the modification is
201+
completed. font-line does not modify the glyph set or hints applied to
202+
the font. See the Details section below for a description of the
203+
OpenType table modifications that occur when the application is used on
204+
a font file.
178205

206+
You can inspect the vertical metrics in the new font file with the
207+
``report`` subcommand (see Usage above).
179208

180-
### Issue Reporting
209+
Details of Font Metrics Changes with ``percent`` Sub-Command
210+
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
181211

182-
Please [submit a new issue report](https://github.com/source-foundry/font-line/issues/new) on the project repository.
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>`__.
183219

220+
*The following values are preserved from the original font design*:
184221

185-
### Acknowledgments
222+
- [OS/2] TypoAscender
223+
- [OS/2] TypoDescender
186224

187-
font-line is built with the fantastic [fontTools](https://github.com/behdad/fonttools) Python library.
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.
188228

229+
*Changes to OpenType metrics values in the font are defined as*:
189230

231+
- [hhea] lineGap is always set to 0
232+
- [OS/2] TypoLineGap = x% \* TA:TD value
233+
- [hhea] Ascent = [OS/2] TypoAscender + 0.5(modified TypoLineGap)
234+
- [hhea] Descent = [OS/2] TypoDescender + 0.5(modified TypoLineGap)
235+
- [OS/2] WinAscent = [OS/2] TypoAscender + 0.5(modified TypoLineGap)
236+
- [OS/2] WinDescent = [OS/2] TypoDescender + 0.5(modified TypoLineGap)
237+
238+
Note that the internal leading modifications are split evenly across
239+
[hhea] Ascent & Descent values, and across [OS/2] WinAscent & WinDescent
240+
values. We add half of the new [OS/2] TypoLineGap value to the original
241+
[OS/2] TypoAscender or TypoDescender in order to define these new
242+
metrics properties.
243+
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.
250+
251+
Issue Reporting
252+
~~~~~~~~~~~~~~~
253+
254+
Please `submit a new issue
255+
report <https://github.com/source-foundry/font-line/issues/new>`__ on
256+
the project repository.
257+
258+
Acknowledgments
259+
~~~~~~~~~~~~~~~
260+
261+
font-line is built with the fantastic
262+
`fontTools <https://github.com/behdad/fonttools>`__ Python library.
263+
264+
.. |Build Status| image:: https://travis-ci.org/source-foundry/font-line.svg?branch=master
265+
:target: https://travis-ci.org/source-foundry/font-line
266+
.. |Build status| image:: https://ci.appveyor.com/api/projects/status/2s4725o5mxh2298c/branch/master?svg=true
267+
:target: https://ci.appveyor.com/project/chrissimpkins/font-line/branch/master

0 commit comments

Comments
 (0)