Merge branch 'layout-docs' into 'main'

docs: Fix up deps for images

See merge request GNOME/pango!395

17 files changed, 68 insertions, 23 deletions

diff --git a/docs/bidi-annotate-dark.png b/docs/bidi-annotate-dark.png
new file mode 100644
index 00000000..d462f7f4
--- /dev/null
+++ b/docs/bidi-annotate-dark.png
diff --git a/docs/bidi-annotate-light.png b/docs/bidi-annotate-light.png
new file mode 100644
index 00000000..9e23f273
--- /dev/null
+++ b/docs/bidi-annotate-light.png
diff --git a/docs/bidi-annotate.png b/docs/bidi-annotate.png
new file mode 100644
index 00000000..79756f7b
--- /dev/null
+++ b/docs/bidi-annotate.png
diff --git a/docs/bidi-input-dark.png b/docs/bidi-input-dark.png
new file mode 100644
index 00000000..586d64ce
--- /dev/null
+++ b/docs/bidi-input-dark.png
diff --git a/docs/bidi-input-light.png b/docs/bidi-input-light.png
new file mode 100644
index 00000000..932b1d32
--- /dev/null
+++ b/docs/bidi-input-light.png
diff --git a/docs/bidi-input.png b/docs/bidi-input.png
new file mode 100644
index 00000000..fc1892ec
--- /dev/null
+++ b/docs/bidi-input.png
diff --git a/docs/meson.build b/docs/meson.build
index aa21512f..21230ddd 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -7,10 +7,29 @@ pango_content_files = [
   'pango_bidi.md',
   'pango-name.png',
   'layout.png',
-  'pipeline.png',
+  'pipeline-light.png',
+  'pipeline-dark.png',
   'rects1.png',
   'rects2.png',
   'rects3.png',
+  'arabic-markup.png',
+  'blue-text.png',
+  'align-left.png',
+  'align-center.png',
+  'align-right.png',
+  'align-left-justify.png',
+  'align-center-justify.png',
+  'align-right-justify.png',
+  'vertical-light.png',
+  'vertical-dark.png',
+  'm-south.png',
+  'm-west.png',
+  'm-north.png',
+  'm-east.png',
+  'bidi-input-light.png',
+  'bidi-input-dark.png',
+  'bidi-annotate-light.png',
+  'bidi-annotate-dark.png',
 ]
 
 doc_conf = configuration_data()
diff --git a/docs/pango.toml.in b/docs/pango.toml.in
index 6a52cf32..95143360 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -67,7 +67,8 @@ content_files = [
 content_images = [
   "pango-name.png",
   "layout.png",
-  "pipeline.png",
+  "pipeline-light.png",
+  "pipeline-dark.png",
   "rects1.png",
   "rects2.png",
   "arabic-markup.png",
@@ -78,9 +79,14 @@ content_images = [
   "align-left-justify.png",
   "align-center-justify.png",
   "align-right-justify.png",
-  "vertical.png",
+  "vertical-light.png",
+  "vertical-dark.png",
   "m-south.png",
   "m-west.png",
   "m-north.png",
   "m-east.png",
+  "bidi-input-light.png",
+  "bidi-input-dark.png",
+  "bidi-annotate-light.png",
+  "bidi-annotate-dark.png",
 ]
diff --git a/docs/pango_bidi.md b/docs/pango_bidi.md
index 1f77c1e0..996e9781 100644
--- a/docs/pango_bidi.md
+++ b/docs/pango_bidi.md
@@ -14,23 +14,39 @@ control over bidirectional setting of text, Pango provides APIs such as
 [func@unichar_direction], [func@find_base_dir], [func@get_mirror_char]
 or [func@Pango.BidiType.for_unichar].
 
+Here is an example for mixed-direction text (shown in logical order):
+
+<picture>
+  <source srcset="bidi-input-dark.png" media="(prefers-color-scheme: dark)">
+  <img alt="mixed-direction text, logical order" src="bidi-input-light.png">
+</picture>
+
+Pango reorders the text according to the direction of the runs:
+
+<picture>
+  <source srcset="bidi-annotate-dark.png" media="(prefers-color-scheme: dark)">
+  <img alt="mixed-direction text, visual order" src="bidi-annotate-light.png">
+</picture>
+
 # Vertical Text
 
 Pango is not only capable of vertical text layout, it can handle mixed vertical
 and non-vertical text correctly. This section describes the types used for setting
 vertical text parameters.
 
-The way this is implemented is through the concept of *gravity*. Gravity of
-normal Latin text is south. A gravity value of east means that glyphs will be
-rotated ninety degrees counterclockwise. So, to render vertical text one needs
+<picture>
+  <source srcset="vertical-dark.png" media="(prefers-color-scheme: dark)">
+  <img alt="gravity west, rotated 90 degrees" align="right" valign="top" src="vertical-light.png">
+</picture>
+The way this is implemented is through the concept of *gravity*. Gravity tells glyphs which way is down, so the gravity of normal Latin text is south. A gravity value of east means that glyphs will be rotated ninety degrees
+counterclockwise. So, to render vertical text one needs
 to set the gravity and rotate the layout using the matrix machinery already
 in place. This has the huge advantage that most algorithms working on a
 [class@Pango.Layout] do not need any change as the assumption that lines run
 in the X direction and stack in the Y direction holds even for vertical text
 layouts.
 
-Here is an example for some English text rendered with gravity west, rotated
-90 degrees: ![vertical english](vertical.png)
+Here is an example for some English text rendered with gravity west, rotated 90 degrees:
 
 Applications should only need to set base gravity on [class@Pango.Context] in use,
 and let Pango decide the gravity assigned to each run of text. This automatically
diff --git a/docs/pango_markup.md b/docs/pango_markup.md
index c82de9d5..16359777 100644
--- a/docs/pango_markup.md
+++ b/docs/pango_markup.md
@@ -39,7 +39,7 @@ string into the string text plus a [struct@Pango.AttrList] using either of
 A simple example of a marked-up string might be:
 
 ```
-<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!"
+<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!
 ```
 
 ![Markup example](blue-text.png)
@@ -56,7 +56,7 @@ Arabic text:
 Pango uses GMarkup to parse this language, which means that XML features
 such as numeric character entities such as `&#169;` for © can be used too.
 
-The root tag of a marked-up document is `<markup>`, but pango_parse_markup()
+The root tag of a marked-up document is `<markup>`, but [func@Pango.parse_markup]
 allows you to omit this tag, so you will most likely never need to use it.
 The most general markup tag is `<span>`, then there are some convenience
 tags.
@@ -66,7 +66,7 @@ tags.
 font
 font_desc
 : A font description string, such as "Sans Italic 12". See
-  pango_font_description_from_string() for a description of the format of
+  [func@Pango.FontDescription.from_string] for a description of the format of
   the string representation. Note that any other span attributes will override
   this description. So if you have "Sans Italic" and also a style="normal"
   attribute, you will get Sans normal, not italic.
@@ -141,11 +141,11 @@ underline_color
   name such as 'red'.
 
 overline
-: One of 'none' or 'single'. Overline support was added in Pango 1.46/
+: One of 'none' or 'single'. Overline support was added in Pango 1.46.
 
 overline_color
 : The color of overlines; an RGB color specification such as '#00FF00' or a color
-  name such as 'red'. Overline support was added in Pango 1.46/
+  name such as 'red'. Overline support was added in Pango 1.46.
 
 rise
 : Vertical displacement, in Pango units or in points (e.g. '5pt'). Can be
diff --git a/docs/pango_rendering.md b/docs/pango_rendering.md
index 2fd61e93..2745c0c0 100644
--- a/docs/pango_rendering.md
+++ b/docs/pango_rendering.md
@@ -8,28 +8,32 @@ The Pango rendering pipeline takes a string of Unicode characters, converts them
 it into glyphs, and renders them on some output medium. This section describes the
 various stages of this pipeline and the APIs that implement them.
 
-![Pango Rendering Pipeline](pipeline.png)
+<picture>
+  <source srcset="pipeline-dark.png" media="(prefers-color-scheme: dark)">
+  <img alt="Pango Rendering Pipeline" src="pipeline-light.png">
+</picture>
 
 Itemization
 : breaks a piece of text into segments with consistent direction and shaping
   properies. Among other things, this determines which font to use for each
-  character. Use pango_itemize() or pango_itemize_with_base_dir() to itemize text.
+  character. Use [func@Pango.itemize] or [func@Pango.itemize_with_base_dir]
+  to itemize text.
 
 Shaping
-: converts characters into glyphs. Use pango_shape(), pango_shape_full() or
-  pango_shape_with_flags() to shape text.
+: converts characters into glyphs. Use [func@Pango.shape],
+  [func@Pango.shape_full] or [func@Pango.shape_with_flags] to shape text.
 
 Line Breaking
 : determines where line breaks should be inserted into a sequence of glyphs.
-  The function pango_break() determines possible line breaks. The actual line
-  breaking is done by [class@Pango.Layout].
+  The function [func@Pango.break] determines possible line breaks. The actual
+  line breaking is done by [class@Pango.Layout].
 
 Justification
 : adjusts inter-word spacing to form lines of even length. This is done by
   [class@Pango.Layout].
 
 Rendering
-: takes a string of positioned glyphs, and renders them onto a surface. This is
-  accomplished by a [class@Pango.Renderer] object. The functions
+: takes a string of positioned glyphs, and renders them onto a surface.
+  This is accomplished by a [class@Pango.Renderer] object. The functions
   pango_cairo_show_glyph_string() and pango_cairo_show_layout() use a
   [class@Pango.Renderer] to draw text onto a cairo surface.
diff --git a/docs/pipeline-dark.png b/docs/pipeline-dark.png
new file mode 100644
index 00000000..47b8a56e
--- /dev/null
+++ b/docs/pipeline-dark.png
diff --git a/docs/pipeline-light.png b/docs/pipeline-light.png
new file mode 100644
index 00000000..3ba1cb9d
--- /dev/null
+++ b/docs/pipeline-light.png
diff --git a/docs/vertical-dark.png b/docs/vertical-dark.png
new file mode 100644
index 00000000..42b8fc53
--- /dev/null
+++ b/docs/vertical-dark.png
diff --git a/docs/vertical-light.png b/docs/vertical-light.png
new file mode 100644
index 00000000..e57ea80e
--- /dev/null
+++ b/docs/vertical-light.png
diff --git a/docs/vertical.png b/docs/vertical.png
deleted file mode 100644
index 0fd8d29c..00000000
--- a/docs/vertical.png
+++ /dev/null
diff --git a/pango/pango-gravity.h b/pango/pango-gravity.h
index 96875047..12e8d689 100644
--- a/pango/pango-gravity.h
+++ b/pango/pango-gravity.h
@@ -29,9 +29,9 @@ G_BEGIN_DECLS
 /**
  * PangoGravity:
  * @PANGO_GRAVITY_SOUTH: Glyphs stand upright (default) <img align="right" valign="center" src="m-south.png">
- * @PANGO_GRAVITY_EAST: Glyphs are rotated 90 degrees clockwise. <img align="right" valign="center" src="m-east.png">
+ * @PANGO_GRAVITY_EAST: Glyphs are rotated 90 degrees counter-clockwise. <img align="right" valign="center" src="m-east.png">
  * @PANGO_GRAVITY_NORTH: Glyphs are upside-down. <img align="right" valign="cener" src="m-north.png">
- * @PANGO_GRAVITY_WEST: Glyphs are rotated 90 degrees counter-clockwise. <img align="right" valign="center" src="m-west.png">
+ * @PANGO_GRAVITY_WEST: Glyphs are rotated 90 degrees clockwise. <img align="right" valign="center" src="m-west.png">
  * @PANGO_GRAVITY_AUTO: Gravity is resolved from the context matrix
  *
  * `PangoGravity` represents the orientation of glyphs in a segment