diff --git a/docs/usermanual-utilities.xml b/docs/usermanual-utilities.xml new file mode 100644 index 000000000..1c5370c11 --- /dev/null +++ b/docs/usermanual-utilities.xml @@ -0,0 +1,244 @@ + + + +]> + + Utilities + + 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, and an embedded library for working with + Unicode Character Database (UCD) data. + + +
+ Command-line tools + + HarfBuzz include three command-line tools: + hb-shape, hb-view, and + hb-subset. They can be used to examine + HarfBuzz's functionality, debug font binaries, or explore the + various shaping models and features from a terminal. + + +
+ hb-shape + + hb-shape allows you to run HarfBuzz's + hb_shape() function on an input string and + to examine the outcome, in human-readable form, as terminal + output. hb-shape does + not render the results of the shaping call + into rendered text (you can use hb-view, 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. + + + 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 + + + hb-shape [OPTIONS] + path/to/font/file.ttf + yourinputtext + + + The default output format is plain text (although JSON output + can be selected instead by specifying the option + --output-format=json). 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. + + + 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. + + + 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. + + + For a complete explanation of the options available, run + + + hb-shape --help + +
+ +
+ hb-view + + hb-view allows you to + see the shaped output of an input string in rendered + form. Like hb-shape, + hb-view takes a font file and a text string + as its arguments: + + + hb-view [OPTIONS] + path/to/font/file.ttf + yourinputtext + + + By default, hb-view renders the shaped + text in ASCII block-character images as terminal output. By + appending the + --output-file=filename + switch, you can write the output to a PNG, SVG, or PDF file + (among other formats). + + + As with hb-shape, 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. + + + 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 + + + In general, hb-view 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 hb-shape to figure out exactly + why something does not appear as expected. + +
+ +
+ hb-subset + + hb-subset allows you + to generate a subset of a given font, with a limited set of + supported characters, features, and variation settings. + + + By default, you provide an input font and an input text string + as the arguments to hb-subset, and it will + generate a font that covers the input text exactly like the + input font does, but includes no other characters or features. + + + hb-subset [OPTIONS] + path/to/font/file.ttf + yourinputtext + + + For example, to create a subset of Noto Serif that just includes the + numerals and the lowercase Latin alphabet, you could run + + + hb-subset [OPTIONS] + NotoSerif-Regular.ttf + 0123456789abcdefghijklmnopqrstuvwxyz + + + There are options available to remove hinting from the + subsetted font and to specify a list of variation-axis settings. + +
+ +
+ +
+ Common data types and APIs + + HarfBuzz includes several APIs for working with general-purpose + data that you may find convenient to leverage in your own + software. They include set operations and integer-to-integer + mapping operations. + + + HarfBuzz uses set operations for internal bookkeeping, such as + when it collects all of the glyph IDs covered by a particular + font feature. You can also use the set API to build sets, add + and remove elements, test whether or not sets contain particular + elements, or compute the unions, intersections, or differences + between sets. + + + All set elements are integers (specifically, + hb_codepoint_t 32-bit unsigned ints), and there are + functions for fetching the minimum and maximum element from a + set. The set API also includes some functions that might not + be part of a generic set facility, such as the ability to add a + contiguous range of integer elements to a set in bulk, and the + ability to fetch the next-smallest or next-largest element. + + + The HarfBuzz set API includes some conveniences as well. All + sets are lifecycle-managed, just like other HarfBuzz + objects. You increase the reference count on a set with + hb_set_reference() and decrease it with + hb_set_destroy(). You can also attach + user data to a set, just like you can to blobs, buffers, faces, + fonts, and other objects, and set destroy callbacks. + + + HarfBuzz also provides an API for keeping track of + integer-to-integer mappings. As with the set API, each integer is + stored as an unsigned 32-bit hb_codepoint_t + element. Maps, like other objects, are reference counted with + reference and destroy functions, and you can attach user data to + them. The mapping operations include adding and deleting + integer-to-integer key:value pairs to the map, testing for the + presence of a key, fetching the population of the map, and so on. + + + There are several other internal HarfBuzz facilities that are + exposed publicly and which you may want to take advantage of + while processing text. HarfBuzz uses a common + hb_tag_t for a variety of OpenType tag identifiers (for + scripts, languages, font features, table names, variation-axis + names, and more), and provides functions for converting strings + to tags and vice-versa. + + + Finally, HarfBuzz also includes data type for Booleans, bit + masks, and other simple types. + +
+ +
+ UCDN + + HarfBuzz includes a copy of the UCDN (Unicode + Database and Normalization) library, which provides functions + for accessing basic Unicode character properties, performing + canonical composition, and performing both canonical and + compatibility decomposition. + + + Currently, UCDN supports direct queries for several more character + properties than HarfBuzz's built-in set of Unicode functions + does, such as the BiDirectional Class, East Asian Width, Paired + Bracket and Resolved Linebreak properties. If you need to access + more properties than HarfBuzz's internal implementation + provides, using the built-in UCDN functions may be a useful solution. + + + The built-in UCDN functions are compiled by default when + building HarfBuzz from source, but this can be disabled with a + compile-time switch. + +
+ +