Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/harfbuzz/docs/usermanual-utilities.xml @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 <?xml version="1.0"?>
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">
6 ]>
7 <chapter id="utilities">
8 <title>Utilities</title>
9 <para>
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.
14 </para>
15
16 <section id="utilities-command-line-tools">
17 <title>Command-line tools</title>
18 <para>
19 HarfBuzz include three command-line tools:
20 <command>hb-shape</command>, <command>hb-view</command>, and
21 <command>hb-subset</command>. They can be used to examine
22 HarfBuzz's functionality, debug font binaries, or explore the
23 various shaping models and features from a terminal.
24 </para>
25
26 <section id="utilities-command-line-hbshape">
27 <title>hb-shape</title>
28 <para>
29 <emphasis><command>hb-shape</command></emphasis> allows you to run HarfBuzz's
30 <function>hb_shape()</function> function on an input string and
31 to examine the outcome, in human-readable form, as terminal
32 output. <command>hb-shape</command> does
33 <emphasis>not</emphasis> render the results of the shaping call
34 into rendered text (you can use <command>hb-view</command>, below, for
35 that). Instead, it prints out the final glyph indices and
36 positions, taking all shaping operations into account, as if the
37 input string were a HarfBuzz input buffer.
38 </para>
39 <para>
40 You can specify the font to be used for shaping and, with
41 command-line options, you can add various aspects of the
42 internal state to the output that is sent to the terminal. The
43 general format is
44 </para>
45 <programlisting>
46 <command>hb-shape</command> <optional>[OPTIONS]</optional>
47 <parameter>path/to/font/file.ttf</parameter>
48 <parameter>yourinputtext</parameter>
49 </programlisting>
50 <para>
51 The default output format is plain text (although JSON output
52 can be selected instead by specifying the option
53 <optional>--output-format=json</optional>). The default output
54 syntax reports each glyph name (or glyph index if there is no
55 name) followed by its cluster value, its horizontal and vertical
56 position displacement, and its horizontal and vertical advances.
57 </para>
58 <para>
59 Output options exist to skip any of these elements in the
60 output, and to include additional data, such as Unicode
61 code-point values, glyph extents, glyph flags, or interim
62 shaping results.
63 </para>
64 <para>
65 Output can also be redirected to a file, or input read from a
66 file. Additional options enable you to enable or disable
67 specific font features, to set variation-font axis values, to
68 alter the language, script, direction, and clustering settings
69 used, to enable sanity checks, or to change which shaping engine is used.
70 </para>
71 <para>
72 For a complete explanation of the options available, run
73 </para>
74 <programlisting>
75 <command>hb-shape</command> <parameter>--help</parameter>
76 </programlisting>
77 </section>
78
79 <section id="utilities-command-line-hbview">
80 <title>hb-view</title>
81 <para>
82 <emphasis><command>hb-view</command></emphasis> allows you to
83 see the shaped output of an input string in rendered
84 form. Like <command>hb-shape</command>,
85 <command>hb-view</command> takes a font file and a text string
86 as its arguments:
87 </para>
88 <programlisting>
89 <command>hb-view</command> <optional>[OPTIONS]</optional>
90 <parameter>path/to/font/file.ttf</parameter>
91 <parameter>yourinputtext</parameter>
92 </programlisting>
93 <para>
94 By default, <command>hb-view</command> renders the shaped
95 text in ASCII block-character images as terminal output. By
96 appending the
97 <command>--output-file=<optional>filename</optional></command>
98 switch, you can write the output to a PNG, SVG, or PDF file
99 (among other formats).
100 </para>
101 <para>
102 As with <command>hb-shape</command>, a lengthy set of options
103 is available, with which you can enable or disable
104 specific font features, set variation-font axis values,
105 alter the language, script, direction, and clustering settings
106 used, enable sanity checks, or change which shaping engine is
107 used.
108 </para>
109 <para>
110 You can also set the foreground and background colors used for
111 the output, independently control the width of all four
112 margins, alter the line spacing, and annotate the output image
113 with
114 </para>
115 <para>
116 In general, <command>hb-view</command> is a quick way to
117 verify that the output of HarfBuzz's shaping operation looks
118 correct for a given text-and-font combination, but you may
119 want to use <command>hb-shape</command> to figure out exactly
120 why something does not appear as expected.
121 </para>
122 </section>
123
124 <section id="utilities-command-line-hbsubset">
125 <title>hb-subset</title>
126 <para>
127 <emphasis><command>hb-subset</command></emphasis> allows you
128 to generate a subset of a given font, with a limited set of
129 supported characters, features, and variation settings.
130 </para>
131 <para>
132 By default, you provide an input font and an input text string
133 as the arguments to <command>hb-subset</command>, and it will
134 generate a font that covers the input text exactly like the
135 input font does, but includes no other characters or features.
136 </para>
137 <programlisting>
138 <command>hb-subset</command> <optional>[OPTIONS]</optional>
139 <parameter>path/to/font/file.ttf</parameter>
140 <parameter>yourinputtext</parameter>
141 </programlisting>
142 <para>
143 For example, to create a subset of Noto Serif that just includes the
144 numerals and the lowercase Latin alphabet, you could run
145 </para>
146 <programlisting>
147 <command>hb-subset</command> <optional>[OPTIONS]</optional>
148 <parameter>NotoSerif-Regular.ttf</parameter>
149 <parameter>0123456789abcdefghijklmnopqrstuvwxyz</parameter>
150 </programlisting>
151 <para>
152 There are options available to remove hinting from the
153 subsetted font and to specify a list of variation-axis settings.
154 </para>
155 </section>
156
157 </section>
158
159 <section id="utilities-common-types-apis">
160 <title>Common data types and APIs</title>
161 <para>
162 HarfBuzz includes several APIs for working with general-purpose
163 data that you may find convenient to leverage in your own
164 software. They include set operations and integer-to-integer
165 mapping operations.
166 </para>
167 <para>
168 HarfBuzz uses set operations for internal bookkeeping, such as
169 when it collects all of the glyph IDs covered by a particular
170 font feature. You can also use the set API to build sets, add
171 and remove elements, test whether or not sets contain particular
172 elements, or compute the unions, intersections, or differences
173 between sets.
174 </para>
175 <para>
176 All set elements are integers (specifically,
177 <type>hb_codepoint_t</type> 32-bit unsigned ints), and there are
178 functions for fetching the minimum and maximum element from a
179 set. The set API also includes some functions that might not
180 be part of a generic set facility, such as the ability to add a
181 contiguous range of integer elements to a set in bulk, and the
182 ability to fetch the next-smallest or next-largest element.
183 </para>
184 <para>
185 The HarfBuzz set API includes some conveniences as well. All
186 sets are lifecycle-managed, just like other HarfBuzz
187 objects. You increase the reference count on a set with
188 <function>hb_set_reference()</function> and decrease it with
189 <function>hb_set_destroy()</function>. You can also attach
190 user data to a set, just like you can to blobs, buffers, faces,
191 fonts, and other objects, and set destroy callbacks.
192 </para>
193 <para>
194 HarfBuzz also provides an API for keeping track of
195 integer-to-integer mappings. As with the set API, each integer is
196 stored as an unsigned 32-bit <type>hb_codepoint_t</type>
197 element. Maps, like other objects, are reference counted with
198 reference and destroy functions, and you can attach user data to
199 them. The mapping operations include adding and deleting
200 integer-to-integer key:value pairs to the map, testing for the
201 presence of a key, fetching the population of the map, and so on.
202 </para>
203 <para>
204 There are several other internal HarfBuzz facilities that are
205 exposed publicly and which you may want to take advantage of
206 while processing text. HarfBuzz uses a common
207 <type>hb_tag_t</type> for a variety of OpenType tag identifiers (for
208 scripts, languages, font features, table names, variation-axis
209 names, and more), and provides functions for converting strings
210 to tags and vice-versa.
211 </para>
212 <para>
213 Finally, HarfBuzz also includes data type for Booleans, bit
214 masks, and other simple types.
215 </para>
216 </section>
217
218 </chapter>