Merge branch 'matthiasc/for-main' into 'main'

docs: Cosmetics

Closes #77

See merge request GNOME/pango!398

7 files changed, 24 insertions, 4 deletions

diff --git a/NEWS b/NEWS
index c6d781f4..1f52b5d2 100644
--- a/NEWS
+++ b/NEWS
@@ -12,6 +12,8 @@ Overview of changes
 * markup: Allow specifying size and rise in points (#67)
 * markup: Allow specifying size as percentage (#23)
 * Rewrite pango_layout_move_cursor_visually (#157, #585, #587)
+* Add a line-height attribute and make logical
+  line extents respect it
 
 Overview of changes in 1.48.7
 =============================
diff --git a/docs/meson.build b/docs/meson.build
index 37a2a9b3..6bdfc1f7 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -31,6 +31,9 @@ pango_content_files = [
   'bidi-input-dark.png',
   'bidi-annotate-light.png',
   'bidi-annotate-dark.png',
+  'split-cursor.png',
+  'split-cursor-light.png',
+  'split-cursor-dark.png'
 ]
 
 doc_conf = configuration_data()
diff --git a/docs/pango.toml.in b/docs/pango.toml.in
index 4317adf4..f5e58194 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -90,4 +90,6 @@ content_images = [
   "bidi-input-dark.png",
   "bidi-annotate-light.png",
   "bidi-annotate-dark.png",
+  "split-cursor-light.png",
+  "split-cursor-dark.png",
 ]
diff --git a/docs/split-cursor-dark.png b/docs/split-cursor-dark.png
new file mode 100644
index 00000000..141d818c
--- /dev/null
+++ b/docs/split-cursor-dark.png
diff --git a/docs/split-cursor-light.png b/docs/split-cursor-light.png
new file mode 100644
index 00000000..2ace0c18
--- /dev/null
+++ b/docs/split-cursor-light.png
diff --git a/docs/split-cursor.png b/docs/split-cursor.png
new file mode 100644
index 00000000..b2be8021
--- /dev/null
+++ b/docs/split-cursor.png
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index bf9be496..fa13ad59 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -2001,9 +2001,8 @@ pango_layout_line_get_cursors (PangoLayoutLine *line,
  * of a run.
  *
  * Motion here is in cursor positions, not in characters, so a single
- * call to [method@Pango.Layout.move_cursor_visually] may move the cursor
- * over multiple characters when multiple characters combine to form a
- * single grapheme.
+ * call to this function may move the cursor over multiple characters
+ * when multiple characters combine to form a single grapheme.
  */
 void
 pango_layout_move_cursor_visually (PangoLayout *layout,
@@ -2432,11 +2431,25 @@ pango_layout_get_direction (PangoLayout *layout,
  * Given an index within a layout, determines the positions that of the
  * strong and weak cursors if the insertion point is at that index.
  *
- * The position of each cursor is stored as a zero-width rectangle.
+ * The position of each cursor is stored as a zero-width rectangle
+ * with the height of the run extents.
+ *
  * The strong cursor location is the location where characters of the
  * directionality equal to the base direction of the layout are inserted.
  * The weak cursor location is the location where characters of the
  * directionality opposite to the base direction of the layout are inserted.
+ *
+ * The following example shows text with both a strong and a weak cursor.
+ *
+ * <picture>
+ *   <source srcset="split-cursor-dark.png" media="(prefers-color-scheme: dark)">
+ *   <img alt="strong and weak cursors" src="split-cursor-light.png">
+ * </picture>
+ *
+ * The strong cursor has a little arrow pointing to the right, the weak
+ * cursor to the left. Typing a 'c' in this situation will insert the
+ * character after the 'b', and typing another Hebrew character, like 'ג',
+ * will insert it at the end.
  */
 void
 pango_layout_get_cursor_pos (PangoLayout    *layout,