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, and an embedded library for working with 14 Unicode Character Database (UCD) data. 15 </para> 16 17 <section id="utilities-command-line-tools"> 18 <title>Command-line tools</title> 19 <para> 20 HarfBuzz include three command-line tools: 21 <program>hb-shape</program>, <program>hb-view</program>, and 22 <program>hb-subset</program>. 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. 25 </para> 26 27 <section id="utilities-command-line-hbshape"> 28 <title>hb-shape</title> 29 <para> 30 <emphasis><program>hb-shape</program></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. <program>hb-shape</program> does 34 <emphasis>not</emphasis> render the results of the shaping call 35 into rendered text (you can use <program>hb-view</program>, 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. 39 </para> 40 <para> 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 44 general format is 45 </para> 46 <programlisting> 47 <command>hb-shape</command> <optional>[OPTIONS]</optional> 48 <parameter>path/to/font/file.ttf</parameter> 49 <parameter>yourinputtext</parameter> 50 </programlisting> 51 <para> 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. 58 </para> 59 <para> 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 63 shaping results. 64 </para> 65 <para> 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. 71 </para> 72 <para> 73 For a complete explanation of the options available, run 74 </para> 75 <programlisting> 76 <command>hb-shape</command> <parameter>--help</parameter> 77 </programlisting> 78 </section> 79 80 <section id="utilities-command-line-hbview"> 81 <title>hb-view</title> 82 <para> 83 <emphasis><program>hb-view</program></emphasis> allows you to 84 see the shaped output of an input string in rendered 85 form. Like <program>hb-shape</program>, 86 <program>hb-view</program> takes a font file and a text string 87 as its arguments: 88 </para> 89 <programlisting> 90 <command>hb-view</command> <optional>[OPTIONS]</optional> 91 <parameter>path/to/font/file.ttf</parameter> 92 <parameter>yourinputtext</parameter> 93 </programlisting> 94 <para> 95 By default, <program>hb-view</program> renders the shaped 96 text in ASCII block-character images as terminal output. By 97 appending the 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). 101 </para> 102 <para> 103 As with <program>hb-shape</program>, 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 108 used. 109 </para> 110 <para> 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 114 with 115 </para> 116 <para> 117 In general, <program>hb-view</program> 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 <program>hb-shape</program> to figure out exactly 121 why something does not appear as expected. 122 </para> 123 </section> 124 125 <section id="utilities-command-line-hbsubset"> 126 <title>hb-subset</title> 127 <para> 128 <emphasis><program>hb-subset</program></emphasis> allows you 129 to generate a subset of a given font, with a limited set of 130 supported characters, features, and variation settings. 131 </para> 132 <para> 133 By default, you provide an input font and an input text string 134 as the arguments to <program>hb-subset</program>, 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. 137 </para> 138 <programlisting> 139 <command>hb-subset</command> <optional>[OPTIONS]</optional> 140 <parameter>path/to/font/file.ttf</parameter> 141 <parameter>yourinputtext</parameter> 142 </programlisting> 143 <para> 144 For example, to create a subset of Noto Serif that just includes the 145 numerals and the lowercase Latin alphabet, you could run 146 </para> 147 <programlisting> 148 <command>hb-subset</command> <optional>[OPTIONS]</optional> 149 <parameter>NotoSerif-Regular.ttf</parameter> 150 <parameter>0123456789abcdefghijklmnopqrstuvwxyz</parameter> 151 </programlisting> 152 <para> 153 There are options available to remove hinting from the 154 subsetted font and to specify a list of variation-axis settings. 155 </para> 156 </section> 157 158 </section> 159 160 <section id="utilities-common-types-apis"> 161 <title>Common data types and APIs</title> 162 <para> 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 166 mapping operations. 167 </para> 168 <para> 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 174 between sets. 175 </para> 176 <para> 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. 184 </para> 185 <para> 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. 193 </para> 194 <para> 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. 203 </para> 204 <para> 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. 212 </para> 213 <para> 214 Finally, HarfBuzz also includes data type for Booleans, bit 215 masks, and other simple types. 216 </para> 217 </section> 218 219 <section id="utilities-ucdn"> 220 <title>UCDN</title> 221 <para> 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. 228 </para> 229 <para> 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. 236 </para> 237 <para> 238 The built-in UCDN functions are compiled by default when 239 building HarfBuzz from source, but this can be disabled with a 240 compile-time switch. 241 </para> 242 </section> 243 244</chapter> 245