-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathutilities.html
186 lines (186 loc) · 8.92 KB
/
utilities.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Utilities: HarfBuzz Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="HarfBuzz Manual">
<link rel="up" href="user-manual.html" title="Part I. User's manual">
<link rel="prev" href="level-2.html" title="Level 2">
<link rel="next" href="utilities-common-types-apis.html" title="Common data types and APIs">
<meta name="generator" content="GTK-Doc V1.34.0 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="user-manual.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="level-2.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="utilities-common-types-apis.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="utilities"></a>Utilities</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="utilities.html#utilities-command-line-tools">Command-line tools</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="utilities.html#utilities-command-line-hbshape">hb-shape</a></span></dt>
<dt><span class="section"><a href="utilities.html#utilities-command-line-hbview">hb-view</a></span></dt>
<dt><span class="section"><a href="utilities.html#utilities-command-line-hbsubset">hb-subset</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="utilities-common-types-apis.html">Common data types and APIs</a></span></dt>
</dl></div>
<p>
HarfBuzz includes several auxiliary components in addition to the
main APIs. These include a set of command-line tools, a set of
lower-level APIs for common data types that may be of interest to
client programs.
</p>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="utilities-command-line-tools"></a>Command-line tools</h2></div></div></div>
<p>
HarfBuzz include three command-line tools:
<span class="command"><strong>hb-shape</strong></span>, <span class="command"><strong>hb-view</strong></span>, and
<span class="command"><strong>hb-subset</strong></span>. They can be used to examine
HarfBuzz's functionality, debug font binaries, or explore the
various shaping models and features from a terminal.
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="utilities-command-line-hbshape"></a>hb-shape</h3></div></div></div>
<p>
<span class="emphasis"><em><span class="command"><strong>hb-shape</strong></span></em></span> allows you to run HarfBuzz's
<code class="function">hb_shape()</code> function on an input string and
to examine the outcome, in human-readable form, as terminal
output. <span class="command"><strong>hb-shape</strong></span> does
<span class="emphasis"><em>not</em></span> render the results of the shaping call
into rendered text (you can use <span class="command"><strong>hb-view</strong></span>, below, for
that). Instead, it prints out the final glyph indices and
positions, taking all shaping operations into account, as if the
input string were a HarfBuzz input buffer.
</p>
<p>
You can specify the font to be used for shaping and, with
command-line options, you can add various aspects of the
internal state to the output that is sent to the terminal. The
general format is
</p>
<pre class="programlisting">
<span class="command"><strong>hb-shape</strong></span> [<span class="optional">[OPTIONS]</span>]
<em class="parameter"><code>path/to/font/file.ttf</code></em>
<em class="parameter"><code>yourinputtext</code></em>
</pre>
<p>
The default output format is plain text (although JSON output
can be selected instead by specifying the option
[<span class="optional">--output-format=json</span>]). The default output
syntax reports each glyph name (or glyph index if there is no
name) followed by its cluster value, its horizontal and vertical
position displacement, and its horizontal and vertical advances.
</p>
<p>
Output options exist to skip any of these elements in the
output, and to include additional data, such as Unicode
code-point values, glyph extents, glyph flags, or interim
shaping results.
</p>
<p>
Output can also be redirected to a file, or input read from a
file. Additional options enable you to enable or disable
specific font features, to set variation-font axis values, to
alter the language, script, direction, and clustering settings
used, to enable sanity checks, or to change which shaping engine is used.
</p>
<p>
For a complete explanation of the options available, run
</p>
<pre class="programlisting">
<span class="command"><strong>hb-shape</strong></span> <em class="parameter"><code>--help</code></em>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="utilities-command-line-hbview"></a>hb-view</h3></div></div></div>
<p>
<span class="emphasis"><em><span class="command"><strong>hb-view</strong></span></em></span> allows you to
see the shaped output of an input string in rendered
form. Like <span class="command"><strong>hb-shape</strong></span>,
<span class="command"><strong>hb-view</strong></span> takes a font file and a text string
as its arguments:
</p>
<pre class="programlisting">
<span class="command"><strong>hb-view</strong></span> [<span class="optional">[OPTIONS]</span>]
<em class="parameter"><code>path/to/font/file.ttf</code></em>
<em class="parameter"><code>yourinputtext</code></em>
</pre>
<p>
By default, <span class="command"><strong>hb-view</strong></span> renders the shaped
text in ASCII block-character images as terminal output. By
appending the
<span class="command"><strong>--output-file=[<span class="optional">filename</span>]</strong></span>
switch, you can write the output to a PNG, SVG, or PDF file
(among other formats).
</p>
<p>
As with <span class="command"><strong>hb-shape</strong></span>, a lengthy set of options
is available, with which you can enable or disable
specific font features, set variation-font axis values,
alter the language, script, direction, and clustering settings
used, enable sanity checks, or change which shaping engine is
used.
</p>
<p>
You can also set the foreground and background colors used for
the output, independently control the width of all four
margins, alter the line spacing, and annotate the output image
with
</p>
<p>
In general, <span class="command"><strong>hb-view</strong></span> is a quick way to
verify that the output of HarfBuzz's shaping operation looks
correct for a given text-and-font combination, but you may
want to use <span class="command"><strong>hb-shape</strong></span> to figure out exactly
why something does not appear as expected.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="utilities-command-line-hbsubset"></a>hb-subset</h3></div></div></div>
<p>
<span class="emphasis"><em><span class="command"><strong>hb-subset</strong></span></em></span> allows you
to generate a subset of a given font, with a limited set of
supported characters, features, and variation settings.
</p>
<p>
By default, you provide an input font and an input text string
as the arguments to <span class="command"><strong>hb-subset</strong></span>, and it will
generate a font that covers the input text exactly like the
input font does, but includes no other characters or features.
</p>
<pre class="programlisting">
<span class="command"><strong>hb-subset</strong></span> [<span class="optional">[OPTIONS]</span>]
<em class="parameter"><code>path/to/font/file.ttf</code></em>
<em class="parameter"><code>yourinputtext</code></em>
</pre>
<p>
For example, to create a subset of Noto Serif that just includes the
numerals and the lowercase Latin alphabet, you could run
</p>
<pre class="programlisting">
<span class="command"><strong>hb-subset</strong></span> [<span class="optional">[OPTIONS]</span>]
<em class="parameter"><code>NotoSerif-Regular.ttf</code></em>
<em class="parameter"><code>0123456789abcdefghijklmnopqrstuvwxyz</code></em>
</pre>
<p>
There are options available to remove hinting from the
subsetted font and to specify a list of variation-axis settings.
</p>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.34.0</div>
</body>
</html>