docs/html/utilities.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Utilities: HarfBuzz Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
   7 <link rel="home" href="index.html" title="HarfBuzz Manual">
   8 <link rel="up" href="pt01.html" title="Part I. User's manual">
   9 <link rel="prev" href="level-2.html" title="Level 2">
  10 <link rel="next" href="utilities-common-types-apis.html" title="Common data types and APIs">
  11 <meta name="generator" content="GTK-Doc V1.32.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="level-2.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="utilities-common-types-apis.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="chapter">
  23 <div class="titlepage"><div><div><h2 class="title">
  24 <a name="utilities"></a>Utilities</h2></div></div></div>
  25 <div class="toc"><dl class="toc">
  26 <dt><span class="section"><a href="utilities.html#utilities-command-line-tools">Command-line tools</a></span></dt>
  27 <dd><dl>
  28 <dt><span class="section"><a href="utilities.html#utilities-command-line-hbshape">hb-shape</a></span></dt>
  29 <dt><span class="section"><a href="utilities.html#utilities-command-line-hbview">hb-view</a></span></dt>
  30 <dt><span class="section"><a href="utilities.html#utilities-command-line-hbsubset">hb-subset</a></span></dt>
  31 </dl></dd>
  32 <dt><span class="section"><a href="utilities-common-types-apis.html">Common data types and APIs</a></span></dt>
  33 <dt><span class="section"><a href="utilities-ucdn.html">UCDN</a></span></dt>
  34 </dl></div>
  35 <p>
  36     HarfBuzz includes several auxiliary components in addition to the
  37     main APIs. These include a set of command-line tools, a set of
  38     lower-level APIs for common data types that may be of interest to
  39     client programs, and an embedded library for working with
  40     Unicode Character Database (UCD) data.
  41   </p>
  42 <div class="section">
  43 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  44 <a name="utilities-command-line-tools"></a>Command-line tools</h2></div></div></div>
  45 <p>
  46       HarfBuzz include three command-line tools:
  47       <span class="command"><strong>hb-shape</strong></span>, <span class="command"><strong>hb-view</strong></span>, and
  48       <span class="command"><strong>hb-subset</strong></span>. They can be used to examine
  49       HarfBuzz's functionality, debug font binaries, or explore the
  50       various shaping models and features from a terminal.
  51     </p>
  52 <div class="section">
  53 <div class="titlepage"><div><div><h3 class="title">
  54 <a name="utilities-command-line-hbshape"></a>hb-shape</h3></div></div></div>
  55 <p>
  56         <span class="emphasis"><em><span class="command"><strong>hb-shape</strong></span></em></span> allows you to run HarfBuzz's
  57         <code class="function">hb_shape()</code> function on an input string and
  58         to examine the outcome, in human-readable form, as terminal
  59         output. <span class="command"><strong>hb-shape</strong></span> does
  60         <span class="emphasis"><em>not</em></span> render the results of the shaping call
  61         into rendered text (you can use <span class="command"><strong>hb-view</strong></span>, below, for
  62         that). Instead, it prints out the final glyph indices and
  63         positions, taking all shaping operations into account, as if the
  64         input string were a HarfBuzz input buffer.
  65       </p>
  66 <p>
  67         You can specify the font to be used for shaping and, with
  68         command-line options, you can add various aspects of the
  69         internal state to the output that is sent to the terminal. The
  70         general format is
  71       </p>
  72 <pre class="programlisting">
  73         <span class="command"><strong>hb-shape</strong></span> [<span class="optional">[OPTIONS]</span>]
  74       <em class="parameter"><code>path/to/font/file.ttf</code></em>
  75       <em class="parameter"><code>yourinputtext</code></em>
  76       </pre>
  77 <p>
  78         The default output format is plain text (although JSON output
  79         can be selected instead by specifying the option
  80         [<span class="optional">--output-format=json</span>]). The default output
  81         syntax reports each glyph name (or glyph index if there is no
  82         name) followed by its cluster value, its horizontal and vertical
  83         position displacement, and its horizontal and vertical advances.
  84       </p>
  85 <p>
  86         Output options exist to skip any of these elements in the
  87         output, and to include additional data, such as Unicode
  88         code-point values, glyph extents, glyph flags, or interim
  89         shaping results.
  90       </p>
  91 <p>
  92         Output can also be redirected to a file, or input read from a
  93         file. Additional options enable you to enable or disable
  94         specific font features, to set variation-font axis values, to
  95         alter the language, script, direction, and clustering settings
  96         used, to enable sanity checks, or to change which shaping engine is used.
  97       </p>
  98 <p>
  99         For a complete explanation of the options available, run
 100       </p>
 101 <pre class="programlisting">
 102         <span class="command"><strong>hb-shape</strong></span> <em class="parameter"><code>--help</code></em>
 103       </pre>
 104 </div>
 105 <div class="section">
 106 <div class="titlepage"><div><div><h3 class="title">
 107 <a name="utilities-command-line-hbview"></a>hb-view</h3></div></div></div>
 108 <p>
 109         <span class="emphasis"><em><span class="command"><strong>hb-view</strong></span></em></span> allows you to
 110         see the shaped output of an input string in rendered
 111         form. Like <span class="command"><strong>hb-shape</strong></span>,
 112         <span class="command"><strong>hb-view</strong></span> takes a font file and a text string
 113         as its arguments:
 114       </p>
 115 <pre class="programlisting">
 116         <span class="command"><strong>hb-view</strong></span> [<span class="optional">[OPTIONS]</span>]
 117         <em class="parameter"><code>path/to/font/file.ttf</code></em>
 118         <em class="parameter"><code>yourinputtext</code></em>
 119       </pre>
 120 <p>
 121         By default, <span class="command"><strong>hb-view</strong></span> renders the shaped
 122         text in ASCII block-character images as terminal output. By
 123         appending the
 124         <span class="command"><strong>--output-file=[<span class="optional">filename</span>]</strong></span>
 125         switch, you can write the output to a PNG, SVG, or PDF file
 126         (among other formats).
 127       </p>
 128 <p>
 129         As with <span class="command"><strong>hb-shape</strong></span>, a lengthy set of options
 130         is available, with which you can  enable or disable
 131         specific font features, set variation-font axis values,
 132         alter the language, script, direction, and clustering settings
 133         used, enable sanity checks, or change which shaping engine is
 134         used.
 135       </p>
 136 <p>
 137         You can also set the foreground and background colors used for
 138         the output, independently control the width of all four
 139         margins, alter the line spacing, and annotate the output image
 140         with
 141       </p>
 142 <p>
 143         In general, <span class="command"><strong>hb-view</strong></span> is a quick way to
 144         verify that the output of HarfBuzz's shaping operation looks
 145         correct for a given text-and-font combination, but you may
 146         want to use <span class="command"><strong>hb-shape</strong></span> to figure out exactly
 147         why something does not appear as expected.
 148       </p>
 149 </div>
 150 <div class="section">
 151 <div class="titlepage"><div><div><h3 class="title">
 152 <a name="utilities-command-line-hbsubset"></a>hb-subset</h3></div></div></div>
 153 <p>
 154         <span class="emphasis"><em><span class="command"><strong>hb-subset</strong></span></em></span> allows you
 155         to generate a subset of a given font, with a limited set of
 156         supported characters, features, and variation settings.
 157       </p>
 158 <p>
 159         By default, you provide an input font and an input text string
 160         as the arguments to <span class="command"><strong>hb-subset</strong></span>, and it will
 161         generate a font that covers the input text exactly like the
 162         input font does, but includes no other characters or features.
 163       </p>
 164 <pre class="programlisting">
 165         <span class="command"><strong>hb-subset</strong></span> [<span class="optional">[OPTIONS]</span>]
 166         <em class="parameter"><code>path/to/font/file.ttf</code></em>
 167         <em class="parameter"><code>yourinputtext</code></em>
 168       </pre>
 169 <p>
 170         For example, to create a subset of Noto Serif that just includes the
 171         numerals and the lowercase Latin alphabet, you could run
 172       </p>
 173 <pre class="programlisting">
 174         <span class="command"><strong>hb-subset</strong></span> [<span class="optional">[OPTIONS]</span>]
 175         <em class="parameter"><code>NotoSerif-Regular.ttf</code></em>
 176         <em class="parameter"><code>0123456789abcdefghijklmnopqrstuvwxyz</code></em>
 177       </pre>
 178 <p>
 179         There are options available to remove hinting from the
 180         subsetted font and to specify a list of variation-axis settings.
 181       </p>
 182 </div>
 183 </div>
 184 </div>
 185 <div class="footer">
 186 <hr>Generated by GTK-Doc V1.32.1</div>
 187 </body>
 188 </html>