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