2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
4 <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
5 <!ENTITY version SYSTEM "version.xml">
7 <chapter id="utilities">
8 <title>Utilities</title>
10 HarfBuzz includes several auxiliary components in addition to the
11 main APIs. These include a set of command-line tools, a set of
12 lower-level APIs for common data types that may be of interest to
13 client programs, and an embedded library for working with
14 Unicode Character Database (UCD) data.
17 <section id="utilities-command-line-tools">
18 <title>Command-line tools</title>
20 HarfBuzz include three command-line tools:
21 <command>hb-shape</command>, <command>hb-view</command>, and
22 <command>hb-subset</command>. They can be used to examine
23 HarfBuzz's functionality, debug font binaries, or explore the
24 various shaping models and features from a terminal.
27 <section id="utilities-command-line-hbshape">
28 <title>hb-shape</title>
30 <emphasis><command>hb-shape</command></emphasis> allows you to run HarfBuzz's
31 <function>hb_shape()</function> function on an input string and
32 to examine the outcome, in human-readable form, as terminal
33 output. <command>hb-shape</command> does
34 <emphasis>not</emphasis> render the results of the shaping call
35 into rendered text (you can use <command>hb-view</command>, below, for
36 that). Instead, it prints out the final glyph indices and
37 positions, taking all shaping operations into account, as if the
38 input string were a HarfBuzz input buffer.
41 You can specify the font to be used for shaping and, with
42 command-line options, you can add various aspects of the
43 internal state to the output that is sent to the terminal. The
47 <command>hb-shape</command> <optional>[OPTIONS]</optional>
48 <parameter>path/to/font/file.ttf</parameter>
49 <parameter>yourinputtext</parameter>
52 The default output format is plain text (although JSON output
53 can be selected instead by specifying the option
54 <optional>--output-format=json</optional>). The default output
55 syntax reports each glyph name (or glyph index if there is no
56 name) followed by its cluster value, its horizontal and vertical
57 position displacement, and its horizontal and vertical advances.
60 Output options exist to skip any of these elements in the
61 output, and to include additional data, such as Unicode
62 code-point values, glyph extents, glyph flags, or interim
66 Output can also be redirected to a file, or input read from a
67 file. Additional options enable you to enable or disable
68 specific font features, to set variation-font axis values, to
69 alter the language, script, direction, and clustering settings
70 used, to enable sanity checks, or to change which shaping engine is used.
73 For a complete explanation of the options available, run
76 <command>hb-shape</command> <parameter>--help</parameter>
80 <section id="utilities-command-line-hbview">
81 <title>hb-view</title>
83 <emphasis><command>hb-view</command></emphasis> allows you to
84 see the shaped output of an input string in rendered
85 form. Like <command>hb-shape</command>,
86 <command>hb-view</command> takes a font file and a text string
90 <command>hb-view</command> <optional>[OPTIONS]</optional>
91 <parameter>path/to/font/file.ttf</parameter>
92 <parameter>yourinputtext</parameter>
95 By default, <command>hb-view</command> renders the shaped
96 text in ASCII block-character images as terminal output. By
98 <command>--output-file=<optional>filename</optional></command>
99 switch, you can write the output to a PNG, SVG, or PDF file
100 (among other formats).
103 As with <command>hb-shape</command>, a lengthy set of options
104 is available, with which you can enable or disable
105 specific font features, set variation-font axis values,
106 alter the language, script, direction, and clustering settings
107 used, enable sanity checks, or change which shaping engine is
111 You can also set the foreground and background colors used for
112 the output, independently control the width of all four
113 margins, alter the line spacing, and annotate the output image
117 In general, <command>hb-view</command> is a quick way to
118 verify that the output of HarfBuzz's shaping operation looks
119 correct for a given text-and-font combination, but you may
120 want to use <command>hb-shape</command> to figure out exactly
121 why something does not appear as expected.
125 <section id="utilities-command-line-hbsubset">
126 <title>hb-subset</title>
128 <emphasis><command>hb-subset</command></emphasis> allows you
129 to generate a subset of a given font, with a limited set of
130 supported characters, features, and variation settings.
133 By default, you provide an input font and an input text string
134 as the arguments to <command>hb-subset</command>, and it will
135 generate a font that covers the input text exactly like the
136 input font does, but includes no other characters or features.
139 <command>hb-subset</command> <optional>[OPTIONS]</optional>
140 <parameter>path/to/font/file.ttf</parameter>
141 <parameter>yourinputtext</parameter>
144 For example, to create a subset of Noto Serif that just includes the
145 numerals and the lowercase Latin alphabet, you could run
148 <command>hb-subset</command> <optional>[OPTIONS]</optional>
149 <parameter>NotoSerif-Regular.ttf</parameter>
150 <parameter>0123456789abcdefghijklmnopqrstuvwxyz</parameter>
153 There are options available to remove hinting from the
154 subsetted font and to specify a list of variation-axis settings.
160 <section id="utilities-common-types-apis">
161 <title>Common data types and APIs</title>
163 HarfBuzz includes several APIs for working with general-purpose
164 data that you may find convenient to leverage in your own
165 software. They include set operations and integer-to-integer
169 HarfBuzz uses set operations for internal bookkeeping, such as
170 when it collects all of the glyph IDs covered by a particular
171 font feature. You can also use the set API to build sets, add
172 and remove elements, test whether or not sets contain particular
173 elements, or compute the unions, intersections, or differences
177 All set elements are integers (specifically,
178 <type>hb_codepoint_t</type> 32-bit unsigned ints), and there are
179 functions for fetching the minimum and maximum element from a
180 set. The set API also includes some functions that might not
181 be part of a generic set facility, such as the ability to add a
182 contiguous range of integer elements to a set in bulk, and the
183 ability to fetch the next-smallest or next-largest element.
186 The HarfBuzz set API includes some conveniences as well. All
187 sets are lifecycle-managed, just like other HarfBuzz
188 objects. You increase the reference count on a set with
189 <function>hb_set_reference()</function> and decrease it with
190 <function>hb_set_destroy()</function>. You can also attach
191 user data to a set, just like you can to blobs, buffers, faces,
192 fonts, and other objects, and set destroy callbacks.
195 HarfBuzz also provides an API for keeping track of
196 integer-to-integer mappings. As with the set API, each integer is
197 stored as an unsigned 32-bit <type>hb_codepoint_t</type>
198 element. Maps, like other objects, are reference counted with
199 reference and destroy functions, and you can attach user data to
200 them. The mapping operations include adding and deleting
201 integer-to-integer key:value pairs to the map, testing for the
202 presence of a key, fetching the population of the map, and so on.
205 There are several other internal HarfBuzz facilities that are
206 exposed publicly and which you may want to take advantage of
207 while processing text. HarfBuzz uses a common
208 <type>hb_tag_t</type> for a variety of OpenType tag identifiers (for
209 scripts, languages, font features, table names, variation-axis
210 names, and more), and provides functions for converting strings
211 to tags and vice-versa.
214 Finally, HarfBuzz also includes data type for Booleans, bit
215 masks, and other simple types.
219 <section id="utilities-ucdn">
222 HarfBuzz includes a copy of the <ulink
223 url="https://github.com/grigorig/ucdn">UCDN</ulink> (Unicode
224 Database and Normalization) library, which provides functions
225 for accessing basic Unicode character properties, performing
226 canonical composition, and performing both canonical and
227 compatibility decomposition.
230 Currently, UCDN supports direct queries for several more character
231 properties than HarfBuzz's built-in set of Unicode functions
232 does, such as the BiDirectional Class, East Asian Width, Paired
233 Bracket and Resolved Linebreak properties. If you need to access
234 more properties than HarfBuzz's internal implementation
235 provides, using the built-in UCDN functions may be a useful solution.
238 The built-in UCDN functions are compiled by default when
239 building HarfBuzz from source, but this can be disabled with a