Skip to content

Commit bd87172

Browse files
chrissimpkinschrissimpkins
committed
Revert "updated README files"
This reverts commit 709ce9c.
1 parent 709ce9c commit bd87172

File tree

2 files changed

+127
-203
lines changed

2 files changed

+127
-203
lines changed

‎README.md

Lines changed: 121 additions & 199 deletions
Original file line numberDiff line numberDiff line change
@@ -1,267 +1,189 @@
1-
font-line |Build Status| |Build status|
2-
---------------------------------------
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)
32

4-
About
5-
~~~~~
63

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.
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.
106

11-
Contents
12-
~~~~~~~~
7+
### Contents
138

14-
- `Install
15-
Guide <https://github.com/source-foundry/font-line#install>`__
16-
- `Usage <https://github.com/source-foundry/font-line#usage>`__
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)
1715

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>`__
16+
### Install
2217

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>`__
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:
2519

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
20+
```
21+
$ python --version
22+
```
3723

3824
Use either of the following methods to install font-line on your system.
3925

40-
pip Install
41-
^^^^^^^^^^^
26+
#### pip Install
4227

43-
The latest font-line release is available through the Python Package
44-
Index and can be installed with pip:
28+
The latest font-line release is available through the Python Package Index and can be installed with pip:
4529

46-
::
30+
```
31+
$ pip install font-line
32+
```
4733

48-
$ pip install font-line
34+
To upgrade to a new version of font-line after a pip install, use the command `pip install --upgrade font-line`.
4935

50-
To upgrade to a new version of font-line after a pip install, use the
51-
command ``pip install --upgrade font-line``.
36+
#### Download Project Repository and Install
5237

53-
Download Project Repository and Install
54-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:
5539

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:
40+
```
41+
git clone https://github.com/source-foundry/font-line.git
42+
```
6043

61-
::
44+
Navigate to the top level repository directory and enter the following command:
6245

63-
git clone https://github.com/source-foundry/font-line.git
46+
```
47+
$ python setup.py install
48+
```
6449

65-
Navigate to the top level repository directory and enter the following
66-
command:
50+
Follow the same instructions to upgrade to a new version of the application if you elect to install with this approach.
6751

68-
::
52+
### Usage
6953

70-
$ python setup.py install
54+
font-line works via sub-commands to the `font-line` command line executable. The following sub-commands are available:
7155

72-
Follow the same instructions to upgrade to a new version of the
73-
application if you elect to install with this approach.
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
7458

75-
Usage
76-
~~~~~
59+
Usage of these sub-commands is described in detail below.
7760

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

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
63+
The following OpenType vertical metrics values and calculated values derived from these data are displayed with the `report` sub-command:
8464

85-
Usage of these sub-commands is described in detail below.
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
8674

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

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

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
79+
```
80+
$ font-line report [fontpath 1] <fontpath ...>
81+
```
10282

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

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

108-
::
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
10994
110-
$ font-line report [fontpath 1] <fontpath ...>
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
111102
112-
Here is an example of the report generated with the Hack typeface file
113-
``Hack-Regular.ttf`` using the command:
103+
[hhea] LineGap: 0
104+
[OS/2] TypoLineGap: 410
114105
115-
::
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
116110
117-
$ font-line report Hack-Regular.ttf
111+
--- Delta Values ---
112+
WinAscent to TypoAscender: 345
113+
Ascent to TypoAscender: 345
114+
WinDescent to TypoDescender: -9
115+
Descent to TypoDescender: -9
118116
119-
Example Font Vertical Metrics Report
120-
''''''''''''''''''''''''''''''''''''
117+
--- Ratio of TypoLineGap to UPM ---
118+
TypoLineGap / UPM: 0.2
119+
```
121120

122-
::
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.
123122

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

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
125+
```
126+
$ font-line report TheFont.ttf > font-report.txt
127+
```
135128

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

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
131+
#### Vertical Metrics Modifications
143132

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

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

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.
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.
156138

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

160-
::
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:
161144

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

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

166-
Vertical Metrics Modifications
167-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
168152

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

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

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.
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).
181158

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

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

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:
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.
189165

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

192-
$ font-line percent 20 TheFont.ttf
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)
193174

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

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.
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.
205178

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

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

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

220-
*The following values are preserved from the original font design*:
221184

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

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

229-
*Changes to OpenType metrics values in the font are defined as*:
230189

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)