docs/usermanual-utilities.xml

   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       <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.
  25     </para>
  26
  27     <section id="utilities-command-line-hbshape">
  28       <title>hb-shape</title>
  29       <para>
  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.
  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><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
  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, <command>hb-view</command> 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 <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
 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, <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.
 122       </para>
 123     </section>
 124
 125     <section id="utilities-command-line-hbsubset">
 126       <title>hb-subset</title>
 127       <para>
 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.
 131       </para>
 132       <para>
 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.
 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>