doc: Update pango_glyph_string_index_to_x

What the docs were saying is no longer strictly true,
now that we are using font metrics. Update them, and
add an illustration.

6 files changed, 131 insertions, 2 deletions

diff --git a/docs/glyphstring-positions-dark.png b/docs/glyphstring-positions-dark.png
new file mode 100644
index 00000000..88b926cd
--- /dev/null
+++ b/docs/glyphstring-positions-dark.png
diff --git a/docs/glyphstring-positions-light.png b/docs/glyphstring-positions-light.png
new file mode 100644
index 00000000..7cdd6ead
--- /dev/null
+++ b/docs/glyphstring-positions-light.png
diff --git a/docs/glyphstring-positions.svg b/docs/glyphstring-positions.svg
new file mode 100644
index 00000000..c518f7f5
--- /dev/null
+++ b/docs/glyphstring-positions.svg
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="157.43535"
+   height="126.08757"
+   viewBox="0 0 41.654768 33.360671"
+   version="1.1"
+   id="svg122363"
+   inkscape:version="1.1 (c68e22c387, 2021-05-23)"
+   sodipodi:docname="glyphstring-positions.svg"
+   inkscape:export-filename="/var/home/mclasen/cursor-positions2-light.png"
+   inkscape:export-xdpi="225.31"
+   inkscape:export-ydpi="225.31"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview122365"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:document-units="mm"
+     showgrid="false"
+     inkscape:zoom="2.7652076"
+     inkscape:cx="2.3506372"
+     inkscape:cy="113.55386"
+     inkscape:window-width="1920"
+     inkscape:window-height="1011"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="layer1"
+     units="px"
+     fit-margin-top="20"
+     fit-margin-left="20"
+     fit-margin-right="20"
+     fit-margin-bottom="20" />
+  <defs
+     id="defs122360" />
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-35.434213,-118.42405)">
+    <rect
+       style="vector-effect:non-scaling-stroke;fill:none;fill-opacity:0.374651;stroke:#000000;stroke-width:0.00070229;stroke-linejoin:round;-inkscape-stroke:hairline"
+       id="rect26849-7-6-3"
+       width="19.828447"
+       height="15.754494"
+       x="50.619915"
+       y="126.2482" />
+    <rect
+       style="vector-effect:non-scaling-stroke;fill:none;fill-opacity:0.374651;stroke:#000000;stroke-width:0.000704165;stroke-linejoin:round;-inkscape-stroke:hairline"
+       id="rect26849-7-6-0-2"
+       width="9.6999998"
+       height="15.754"
+       x="40.920364"
+       y="126.24852" />
+    <g
+       aria-label="w"
+       transform="matrix(0.26458333,0,0,0.26458333,53.283913,76.543917)"
+       id="text4642-7-1"
+       style="font-size:85.3333px;line-height:1.25;font-family:'Source Serif 4 Display';-inkscape-font-specification:'Source Serif 4 Display, Normal';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect4644)">
+      <path
+         d="m 1.2424688,246.68612 0.3413332,0.34133 2.1333324,-0.34133 c 7.3386636,-8.448 14.0799946,-20.90666 17.2373266,-28.92799 0.341333,8.10666 0.767999,18.43199 1.194666,28.92799 l 0.341333,0.34133 2.047999,-0.34133 c 8.191997,-8.448 15.01866,-18.00533 18.090659,-25.25866 1.024,-2.38933 3.754665,-7.08266 3.754665,-11.09333 0,-0.85333 -0.170666,-1.536 -0.341333,-2.21866 -0.597333,-0.59734 -1.450666,-1.024 -2.645332,-1.024 -1.791999,0 -3.327999,1.024 -3.327999,4.43733 0,1.28 0.08533,3.072 1.024,6.99733 l 0.256,1.10933 c -0.170667,0.42667 -0.341333,0.768 -0.512,1.19467 -3.071999,7.168 -8.27733,14.07999 -13.567994,20.39466 -0.426667,-11.008 -0.853333,-22.01599 -1.365333,-33.10932 H 22.74646 c -4.437332,12.11733 -10.410662,23.80799 -16.5546599,32.85332 -0.085333,-9.472 -0.6826664,-20.13866 -1.706666,-27.30666 -0.6826664,-4.608 -2.0479991,-6.57066 -5.37599775,-6.57066 -3.92533165,0 -6.31466405,3.41333 -9.04532955,9.89866 l 1.0239996,0.768 c 3.0719987,-4.94933 4.4373314,-6.31466 5.8879975,-6.31466 1.1093329,0 1.8773326,0.85333 2.38933235,4.52266 1.10933287,8.61866 1.62133265,17.83466 1.87733255,30.71999 z"
+         id="path32016-5-5" />
+    </g>
+    <g
+       aria-label="i"
+       id="text23394-6-9"
+       style="font-size:22.5778px;line-height:1.25;font-family:'Source Serif 4 Display';-inkscape-font-specification:'Source Serif 4 Display, Normal';letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
+       transform="translate(21.723853,-8.999446)">
+      <path
+         d="m 44.502481,150.0899 c 0,0.67734 0.587023,0.99343 1.12889,0.99343 1.399824,0 3.360056,-0.89409 4.059967,-2.04556 l 0.382126,-0.45413 c -0.790223,0.90312 -3.268047,1.34822 -3.697025,1.34822 -0.2032,0 -0.406401,-0.15805 -0.406401,-0.42898 0,-0.22578 0.09031,-0.63218 0.180623,-1.10631 l 1.648179,-7.87965 -0.2032,-0.18063 -4.247235,1.53975 0.504014,0.24314 2.275639,-0.20244 -1.444979,6.79592 c -0.158045,0.79022 -0.180623,1.10631 -0.180623,1.37724 z m 3.138315,-12.21459 c 0.677334,0 1.309512,-0.58702 1.309512,-1.39982 0,-0.58702 -0.383823,-0.99342 -0.970845,-0.99342 -0.677334,0 -1.286935,0.63217 -1.286935,1.44498 0,0.56444 0.4064,0.94826 0.948268,0.94826 z"
+         id="path32019-9-9"
+         sodipodi:nodetypes="ssccsscccccccsssssss" />
+    </g>
+    <circle
+       style="vector-effect:non-scaling-stroke;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.000763294;stroke-linejoin:round;-inkscape-stroke:hairline"
+       id="path35788-2-1"
+       cx="50.619915"
+       cy="141.94321"
+       r="0.25" />
+    <circle
+       style="vector-effect:non-scaling-stroke;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.000763296;stroke-linejoin:round;-inkscape-stroke:hairline"
+       id="path35788-4-82-4"
+       cx="65.832771"
+       cy="141.94321"
+       r="0.25" />
+    <circle
+       style="vector-effect:non-scaling-stroke;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.000763296;stroke-linejoin:round;-inkscape-stroke:hairline"
+       id="path35788-4-8-9-9"
+       cx="70.508347"
+       cy="141.94321"
+       r="0.25" />
+    <circle
+       style="vector-effect:non-scaling-stroke;fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.000763296;stroke-linejoin:round;-inkscape-stroke:hairline"
+       id="path35788-4-8-1-9-1"
+       cx="40.97588"
+       cy="141.94321"
+       r="0.25" />
+    <text
+       xml:space="preserve"
+       style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:22.5778px;line-height:1.25;font-family:'Source Serif 4 Display';-inkscape-font-specification:'Source Serif 4 Display, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
+       x="40.889793"
+       y="141.745"
+       id="text84375-0"><tspan
+         sodipodi:role="line"
+         id="tspan86335-7"
+         x="40.889793"
+         y="141.745">o</tspan></text>
+  </g>
+</svg>
diff --git a/docs/meson.build b/docs/meson.build
index 8ef1a0fb..ac2a2257 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -40,6 +40,8 @@ pango_content_files = [
   'caret-metrics-dark.png',
   'cursor-positions-light.png',
   'cursor-positions-dark.png',
+  'glyphstring-positions-light.png',
+  'glyphstring-positions-dark.png',
 ]
 
 doc_conf = configuration_data()
diff --git a/docs/pango.toml.in b/docs/pango.toml.in
index 1bcdd4a7..01173997 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -98,4 +98,6 @@ content_images = [
   "caret-metrics-dark.png",
   "cursor-positions-light.png",
   "cursor-positions-dark.png",
+  "glyphstring-positions-light.png",
+  "glyphstring-positions-dark.png",
 ]
diff --git a/pango/glyphstring.c b/pango/glyphstring.c
index eb65875b..8d4aa604 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -370,8 +370,15 @@ pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs,
  * Converts from character position to x position.
  *
  * The X position is measured from the left edge of the run.
- * Character positions are computed by dividing up each cluster
- * into equal portions.
+ * Character positions are obtained using font metrics for ligatures
+ * where available, and computed by dividing up each cluster
+ * into equal portions, otherwise.
+ *
+ * <picture>
+ *   <source srcset="glyphstring-positions-dark.png" media="(prefers-color-scheme: dark)">
+ *   <img alt="Glyph positions" src="glyphstring-positions-light.png">
+ * </picture>
+
  */
 void
 pango_glyph_string_index_to_x (PangoGlyphString *glyphs,