This file is indexed.

/usr/share/gtk-doc/html/harfbuzz/hello-harfbuzz.html is in libharfbuzz-doc 1.7.2-1ubuntu1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Hello, Harfbuzz: HarfBuzz Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="HarfBuzz Manual">
<link rel="up" href="pt01.html" title="Part I. User's manual">
<link rel="prev" href="building.html" title="Building">
<link rel="next" href="buffers-language-script-and-direction.html" title="Buffers, language, script and direction">
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="building.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="buffers-language-script-and-direction.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="hello-harfbuzz"></a>Hello, Harfbuzz</h2></div></div></div>
<div class="toc"><dl class="toc"><dt><span class="section"><a href="hello-harfbuzz.html#what-harfbuzz-doesnt-do">What Harfbuzz doesn't do</a></span></dt></dl></div>
<p>
    Here's the simplest Harfbuzz that can possibly work. We will improve
    it later.
  </p>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
        Create a buffer and put your text in it.
      </p></li></ol></div>
<pre class="programlisting">
  #include &lt;hb.h&gt;
  hb_buffer_t *buf;
  buf = hb_buffer_create();
  hb_buffer_add_utf8(buf, text, strlen(text), 0, strlen(text));
</pre>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="2"><p>
        Guess the script, language and direction of the buffer.
      </p></li></ol></div>
<pre class="programlisting">
  hb_buffer_guess_segment_properties(buf);
</pre>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="3"><p>
        Create a face and a font, using FreeType for now.
      </p></li></ol></div>
<pre class="programlisting">
  #include &lt;hb-ft.h&gt;
  FT_New_Face(ft_library, font_path, index, &amp;face)
  hb_font_t *font = hb_ft_font_create(face);
</pre>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="4"><p>
        Shape!
      </p></li></ol></div>
<pre class="programlisting">
  hb_shape(font, buf, NULL, 0);
</pre>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="5"><p>
        Get the glyph and position information.
      </p></li></ol></div>
<pre class="programlisting">
  hb_glyph_info_t *glyph_info    = hb_buffer_get_glyph_infos(buf, &amp;glyph_count);
  hb_glyph_position_t *glyph_pos = hb_buffer_get_glyph_positions(buf, &amp;glyph_count);
</pre>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="6"><p>
        Iterate over each glyph.
      </p></li></ol></div>
<pre class="programlisting">
  for (i = 0; i &lt; glyph_count; ++i) {
    glyphid = glyph_info[i].codepoint;
    x_offset = glyph_pos[i].x_offset / 64.0;
    y_offset = glyph_pos[i].y_offset / 64.0;
    x_advance = glyph_pos[i].x_advance / 64.0;
    y_advance = glyph_pos[i].y_advance / 64.0;
    draw_glyph(glyphid, cursor_x + x_offset, cursor_y + y_offset);
    cursor_x += x_advance;
    cursor_y += y_advance;
  }
</pre>
<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="7"><p>
        Tidy up.
      </p></li></ol></div>
<pre class="programlisting">
  hb_buffer_destroy(buf);
  hb_font_destroy(hb_ft_font);
</pre>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="what-harfbuzz-doesnt-do"></a>What Harfbuzz doesn't do</h2></div></div></div>
<p>
      The code above will take a UTF8 string, shape it, and give you the
      information required to lay it out correctly on a single
      horizontal (or vertical) line using the font provided. That is the
      extent of Harfbuzz's responsibility.
    </p>
<p>
      If you are implementing a text layout engine you may have other
      responsibilities, that Harfbuzz will not help you with:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>
          Harfbuzz won't help you with bidirectionality. If you want to
          lay out text with mixed Hebrew and English, you will need to
          ensure that the buffer provided to Harfbuzz has those
          characters in the correct layout order. This will be different
          from the logical order in which the Unicode text is stored. In
          other words, the user will hit the keys in the following
          sequence:
        </p>
<pre class="programlisting">
A B C [space] ג ב א [space] D E F
        </pre>
<p>
          but will expect to see in the output:
        </p>
<pre class="programlisting">
ABC אבג DEF
        </pre>
<p>
          This reordering is called <span class="emphasis"><em>bidi processing</em></span>
          ("bidi" is short for bidirectional), and there's an
          algorithm as an annex to the Unicode Standard which tells you how
          to reorder a string from logical order into presentation order.
          Before sending your string to Harfbuzz, you may need to apply the
          bidi algorithm to it. Libraries such as ICU and fribidi can do
          this for you.
        </p>
</li>
<li class="listitem"><p>
          Harfbuzz won't help you with text that contains different font
          properties. For instance, if you have the string "a
          <span class="emphasis"><em>huge</em></span> breakfast", and you expect
          "huge" to be italic, you will need to send three
          strings to Harfbuzz: <code class="literal">a</code>, in your Roman font;
          <code class="literal">huge</code> using your italic font; and
          <code class="literal">breakfast</code> using your Roman font again.
          Similarly if you change font, font size, script, language or
          direction within your string, you will need to shape each run
          independently and then output them independently. Harfbuzz
          expects to shape a run of characters sharing the same
          properties.
        </p></li>
<li class="listitem">
<p>
          Harfbuzz won't help you with line breaking, hyphenation or
          justification. As mentioned above, it lays out the string
          along a <span class="emphasis"><em>single line</em></span> of, notionally,
          infinite length. If you want to find out where the potential
          word, sentence and line break points are in your text, you
          could use the ICU library's break iterator functions.
        </p>
<p>
          Harfbuzz can tell you how wide a shaped piece of text is, which is
          useful input to a justification algorithm, but it knows nothing
          about paragraphs, lines or line lengths. Nor will it adjust the
          space between words to fit them proportionally into a line. If you
          want to layout text in paragraphs, you will probably want to send
          each word of your text to Harfbuzz to determine its shaped width
          after glyph substitutions, then work out how many words will fit
          on a line, and then finally output each word of the line separated
          by a space of the correct size to fully justify the paragraph.
        </p>
</li>
</ul></div>
<p>
      As a layout engine implementor, Harfbuzz will help you with the
      interface between your text and your font, and that's something
      that you'll need - what you then do with the glyphs that your font
      returns is up to you. The example we saw above enough to get us
      started using Harfbuzz. Now we are going to use the remainder of
      Harfbuzz's API to refine that example and improve our text shaping
      capabilities.
    </p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.27</div>
</body>
</html>