[pango/pango2: 91/178] docs: Add a 'first steps' example

[Matthias Clasen <matthiasc src gnome org>]

commit deb9c06d48884a01be7e038ed8bec6aced66c858
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Jun 12 12:44:41 2022 -0400

    docs: Add a 'first steps' example
    
    This is meant to be minimal, just getting some
    text rendered in the least lines of code.

 docs/first_steps.md    | 104 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/meson.build       |   2 +
 docs/pango.toml.in     |   2 +
 examples/first-steps.c |  75 +++++++++++++++++++++++++++++++++++
 examples/meson.build   |   1 +
 5 files changed, 184 insertions(+)
---
diff --git a/docs/first_steps.md b/docs/first_steps.md
new file mode 100644
index 000000000..a863fc336
--- /dev/null
+++ b/docs/first_steps.md
@@ -0,0 +1,104 @@
+---
+Title: First steps with Pango
+---
+
+# First steps with Pango
+
+Pango has a rich API, and it can be hard to figure out what is
+important, and where to begin. To help with this, here is an
+example that aims to show the simplest possible Pango program
+that renders some text into a png image. You can use the example
+as a basis to explore more parts of the API that are not covered
+here.
+
+Useful next steps would be:
+
+- Adding attributes to the text
+- Using different languages in the same paragraph
+- Making parts of the text use a different font
+- Make Pango wrap the text into multiple lines
+
+## A simple example
+
+```
+#include <math.h>
+#include <pango/pangocairo.h>
+
+#define SIZE 150
+
+static void
+draw_text (cairo_t *cr)
+{
+  PangoLayout *layout;
+  PangoFontDescription *desc;
+
+  /* Create a PangoLayout */
+  layout = pango_cairo_create_layout (cr);
+
+  /* Set the text */
+  pango_layout_set_text (layout, "Text", -1);
+
+  /* Set a font for the layout */
+  desc = pango_font_description_from_string ("Sans Bold 20");
+  pango_layout_set_font_description (layout, desc);
+  pango_font_description_free (desc);
+
+  /* Show the layout */
+  pango_cairo_show_layout (cr, layout);
+
+  /* Free the layout object */
+  g_object_unref (layout);
+}
+
+int
+main (int argc, char **argv)
+{
+  cairo_t *cr;
+  char *filename;
+  cairo_status_t status;
+  cairo_surface_t *surface;
+
+  if (argc != 2)
+    {
+      g_printerr ("Usage: first-steps OUTPUT_FILENAME\n");
+      return 1;
+    }
+
+  filename = argv[1];
+
+  /* Prepare a cairo surface to draw on */
+  surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
+                                        2 * SIZE, 2 * SIZE);
+  cr = cairo_create (surface);
+
+  /* White background */
+  cairo_set_source_rgb (cr, 1., 1., 1.);
+  cairo_paint (cr);
+
+  /* Center coordinates on the middle of the region we are drawing */
+  cairo_translate (cr, SIZE, SIZE);
+
+  /* Draw the text, in black */
+  cairo_set_source_rgb (cr, 0., 0., 0.);
+
+  draw_text (cr);
+
+  cairo_destroy (cr);
+
+  status = cairo_surface_write_to_png (surface, filename);
+  cairo_surface_destroy (surface);
+
+  if (status != CAIRO_STATUS_SUCCESS)
+    {
+      g_printerr ("Could not save png to '%s'\n", filename);
+      return 1;
+    }
+
+  return 0;
+}
+```
+
+Once you build and run the example code above, you should see the
+following result:
+
+![Output of example](first-steps.png#frame)
diff --git a/docs/meson.build b/docs/meson.build
index f8aa9141d..0d320590a 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,6 +1,7 @@
 gidocgen = find_program('gi-docgen', required: get_option('docs'))
 
 pango_content_files = [
+  'first_steps.md',
   'pango_rendering.md',
   'pango_markup.md',
   'pango_fonts.md',
@@ -54,6 +55,7 @@ pango_content_files = [
   'line-height3-dark.png',
   'rotated-text.png',
   'bullets.png',
+  'first-steps.png',
 ]
 
 doc_conf = configuration_data()
diff --git a/docs/pango.toml.in b/docs/pango.toml.in
index 4584c870b..bb6ff5392 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -44,6 +44,7 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/main/";
 
 [extra]
 content_files = [
+  "first_steps.md",
   "pango_rendering.md",
   "pango_markup.md",
   "pango_fonts.md",
@@ -99,6 +100,7 @@ content_images = [
   "line-height3-dark.png",
   "rotated-text.png",
   "bullets.png",
+  "first-steps.png",
 ]
 
 urlmap_file = "urlmap.js"
diff --git a/examples/first-steps.c b/examples/first-steps.c
new file mode 100644
index 000000000..ea27bee15
--- /dev/null
+++ b/examples/first-steps.c
@@ -0,0 +1,75 @@
+#include <math.h>
+#include <pango/pangocairo.h>
+
+#define SIZE 150
+
+static void
+draw_text (cairo_t *cr)
+{
+  PangoLayout *layout;
+  PangoFontDescription *desc;
+
+  /* Create a PangoLayout */
+  layout = pango_cairo_create_layout (cr);
+
+  /* Set the text */
+  pango_layout_set_text (layout, "Text", -1);
+
+  /* Set a font for the layout */
+  desc = pango_font_description_from_string ("Sans Bold 20");
+  pango_layout_set_font_description (layout, desc);
+  pango_font_description_free (desc);
+
+  /* Show the layout */
+  pango_cairo_show_layout (cr, layout);
+
+  /* Free the layout object */
+  g_object_unref (layout);
+}
+
+int
+main (int argc, char **argv)
+{
+  cairo_t *cr;
+  char *filename;
+  cairo_status_t status;
+  cairo_surface_t *surface;
+
+  if (argc != 2)
+    {
+      g_printerr ("Usage: first-steps OUTPUT_FILENAME\n");
+      return 1;
+    }
+
+  filename = argv[1];
+
+  /* Prepare a cairo surface to draw on */
+  surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
+                                        2 * SIZE, 2 * SIZE);
+  cr = cairo_create (surface);
+
+  /* White background */
+  cairo_set_source_rgb (cr, 1., 1., 1.);
+  cairo_paint (cr);
+
+  /* Center coordinates on the middle of the region we are drawing */
+  cairo_translate (cr, SIZE, SIZE);
+
+  /* Draw the text, in black */
+  cairo_set_source_rgb (cr, 0., 0., 0.);
+
+  draw_text (cr);
+
+  cairo_destroy (cr);
+
+  status = cairo_surface_write_to_png (surface, filename);
+  cairo_surface_destroy (surface);
+
+  if (status != CAIRO_STATUS_SUCCESS)
+    {
+      g_printerr ("Could not save png to '%s'\n", filename);
+      return 1;
+    }
+
+  return 0;
+}
diff --git a/examples/meson.build b/examples/meson.build
index 4f0b5a6db..e2c138733 100644
--- a/examples/meson.build
+++ b/examples/meson.build
@@ -2,6 +2,7 @@ examples = []
 
 if cairo_png_dep.found()
   examples += [
+    'first-steps',
     'cairoshape',
     'cairosimple',
     'cairotwisted',