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> 219