docs/usermanual-utilities.xml

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
  <!ENTITY version SYSTEM "version.xml">
]>
<chapter id="utilities">
  <title>Utilities</title>
  <para>
    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.
  </para>
  
  <section id="utilities-command-line-tools">
    <title>Command-line tools</title>
    <para>
      HarfBuzz include several command-line tools:
      <command>hb-shape</command>, <command>hb-view</command>,
      <command>hb-subset</command>, <command>hb-info</command>,
      <command>hb-raster</command>, and <command>hb-vector</command>.
      They can be used to examine
      HarfBuzz's functionality, debug font binaries, or explore the
      various shaping models and features from a terminal.
    </para>
    
    <section id="utilities-command-line-hbshape">
      <title>hb-shape</title>
      <para>
	<emphasis><command>hb-shape</command></emphasis> allows you to run HarfBuzz's
	<function>hb_shape()</function> function on an input string and
	to examine the outcome, in human-readable form, as terminal
	output. <command>hb-shape</command> does
	<emphasis>not</emphasis> render the results of the shaping call
	into rendered text (you can use <command>hb-view</command>, 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.
      </para>
      <para>
	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
      </para>
      <programlisting><command>hb-shape</command> <optional>OPTIONS</optional> <parameter>path/to/font/file.ttf</parameter> <parameter>yourinputtext</parameter></programlisting>
      <para>
	The default output format is plain text (although JSON output
	can be selected instead by specifying the option
	<optional>--output-format=json</optional>). 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.
      </para>
      <para>
	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.
      </para>
      <para>
	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.
      </para>
      <para>
	For a complete explanation of the options available, run
      </para>
      <programlisting><command>hb-shape</command> <parameter>--help</parameter></programlisting>  
    </section>
    
    <section id="utilities-command-line-hbview">
      <title>hb-view</title>
      <para>
	<emphasis><command>hb-view</command></emphasis> allows you to
	see the shaped output of an input string in rendered
	form. Like <command>hb-shape</command>,
	<command>hb-view</command> takes a font file and a text string
	as its arguments:
      </para>
      <programlisting><command>hb-view</command> <optional>OPTIONS</optional> <parameter>path/to/font/file.ttf</parameter> <parameter>yourinputtext</parameter></programlisting>
      <para>
	By default, <command>hb-view</command> renders the shaped
	text in ASCII block-character images as terminal output. By
	appending the
	<command>--output-file=<optional>filename</optional></command>
	switch, you can write the output to a PNG, SVG, or PDF file
	(among other formats).
      </para>
      <para>
	As with <command>hb-shape</command>, 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.
      </para>
      <para>
	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 
      </para>
      <para>
	In general, <command>hb-view</command> 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 <command>hb-shape</command> to figure out exactly
	why something does not appear as expected.
      </para>
    </section>
    
    <section id="utilities-command-line-hbraster">
      <title>hb-raster</title>
      <para>
	<emphasis><command>hb-raster</command></emphasis> takes a font file
	and a text string, shapes the text, and renders the result as a
	PPM (Portable Pixel Map) raster image.
      </para>
      <programlisting><command>hb-raster</command> <optional>OPTIONS</optional> <parameter>path/to/font/file.ttf</parameter> <parameter>yourinputtext</parameter></programlisting>
      <para>
	It is similar to <command>hb-view</command> but uses HarfBuzz's own rasterizer and currently only outputs PPM images.
      </para>
    </section>

    <section id="utilities-command-line-hbvector">
      <title>hb-vector</title>
      <para>
	<emphasis><command>hb-vector</command></emphasis> takes a font file
	and a text string, shapes the text, and renders the result as a
	SVG vector image.
      </para>
      <programlisting><command>hb-vector</command> <optional>OPTIONS</optional> <parameter>path/to/font/file.ttf</parameter> <parameter>yourinputtext</parameter></programlisting>
      <para>
	It is similar to <command>hb-view</command> but uses HarfBuzz's own vector output routines and currently only outputs SVG images.
      </para>
    </section>

    <section id="utilities-command-line-hbsubset">
      <title>hb-subset</title>
      <para>
	<emphasis><command>hb-subset</command></emphasis> allows you
	to generate a subset of a given font, with a limited set of
	supported characters, features, and variation settings.
      </para>
      <para>
	By default, you provide an input font and an input text string
	as the arguments to <command>hb-subset</command>, and it will
	generate a font that covers the input text exactly like the
	input font does, but includes no other characters or features.
      </para>
      <programlisting><command>hb-subset</command> <optional>OPTIONS</optional> <parameter>path/to/font/file.ttf</parameter> <parameter>yourinputtext</parameter></programlisting>
      <para>
	For example, to create a subset of Noto Serif that just includes the
	numerals and the lowercase Latin alphabet, you could run
      </para>
      <programlisting><command>hb-subset</command> <optional>OPTIONS</optional> <parameter>NotoSerif-Regular.ttf</parameter> <parameter>0123456789abcdefghijklmnopqrstuvwxyz</parameter></programlisting>
      <para>
	There are options available to remove hinting from the
	subsetted font and to specify a list of variation-axis settings.
      </para>
    </section>
    
    <section id="utilities-command-line-hbinfo">
      <title>hb-info</title>
      <para>
	<emphasis><command>hb-info</command></emphasis> allows you to
	query a font file for various information and prints it to the
	terminal.
      </para>
      <para>
	If no query options are specified, it will output a general
	summary about the font.
      </para>
      <programlisting><command>hb-info</command> <optional>OPTIONS</optional> <parameter>path/to/font/file.ttf</parameter></programlisting>
      <para>
	Command-line options are available to list full tables, names,
	characters, layout features, font variation, or color palettes,
	as well as retrieve specific font names, metrics, styles, or baselines.
      </para>
    </section>

  </section>
  
  <section id="utilities-common-types-apis">
    <title>Common data types and APIs</title>
    <para>
      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.
    </para>
    <para>
      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.
    </para>
    <para>
      All set elements are integers (specifically,
      <type>hb_codepoint_t</type> 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.
    </para>
    <para>
      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
      <function>hb_set_reference()</function> and decrease it with
      <function>hb_set_destroy()</function>. 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.
    </para>
    <para>
      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 <type>hb_codepoint_t</type>
      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.
    </para>
    <para>
      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
      <type>hb_tag_t</type> 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. 
    </para>
    <para>
      Finally, HarfBuzz also includes data type for Booleans, bit
      masks, and other simple types.
    </para>
  </section>

</chapter>