[gtk/ebassi/gidocgen: 46/481] docs: Update the "Getting Started" page

[Emmanuele Bassi <ebassi src gnome org>]

commit aab1320be6a3cccc17094d3bfacbff4a6bb04984
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Fri Feb 19 22:07:48 2021 +0000

    docs: Update the "Getting Started" page
    
    Drop the Pandoc stuff, add the gi-docgen links, and remove a stray
    docbook element.

 docs/reference/gtk/getting_started.md | 327 ++++++++++++++++++----------------
 1 file changed, 172 insertions(+), 155 deletions(-)
---
diff --git a/docs/reference/gtk/getting_started.md b/docs/reference/gtk/getting_started.md
index b10dd1e572..9daba55a23 100644
--- a/docs/reference/gtk/getting_started.md
+++ b/docs/reference/gtk/getting_started.md
@@ -30,7 +30,7 @@ window.
 
 Create a new file with the following content named `example-0.c`.
 
-``` {.c source=examples/window-default.c }
+```c
 #include <gtk/gtk.h>
 
 static void
@@ -64,7 +64,7 @@ main (int    argc,
 You can compile the program above with GCC using:
 
 ```
-gcc `pkg-config --cflags gtk4` -o example-0 example-0.c `pkg-config --libs gtk4`
+gcc $( pkg-config --cflags gtk4 ) -o example-0 example-0.c $( pkg-config --libs gtk4 )
 ```
 
 For more information on how to compile a GTK application, please
@@ -78,49 +78,51 @@ Even if GTK installs multiple header files, only the top-level `gtk/gtk.h`
 header can be directly included by third-party code. The compiler will abort
 with an error if any other header is directly included.
 
-In a GTK application, the purpose of the main() function is to create a
-GtkApplication object and run it. In this example a GtkApplication pointer
-named `app` is declared and then initialized using gtk_application_new().
+In a GTK application, the purpose of the `main()` function is to create a
+[class@Gtk.Application] object and run it. In this example a
+[class@Gtk.Application] pointer named `app` is declared and then initialized
+using `gtk_application_new()`.
 
-When creating a GtkApplication, you need to pick an application identifier
-(a name) and pass it to gtk_application_new() as parameter. For this example
-`org.gtk.example` is used. For choosing an identifier for your application, see
-[this guide](https://wiki.gnome.org/HowDoI/ChooseApplicationID). Lastly,
-gtk_application_new() takes GApplicationFlags as input for your application,
-if your application would have special needs.
+When creating a [class@Gtk.Application], you need to pick an application
+identifier (a name) and pass it to [ctor Gtk Application new] as parameter. For
+this example `org.gtk.example` is used. For choosing an identifier for your
+application, see [this guide](https://wiki.gnome.org/HowDoI/ChooseApplicationID).
+Lastly, [ctor Gtk Application new] takes `GApplicationFlags` as input
+for your application, if your application would have special needs.
 
 Next the [activate signal](https://wiki.gnome.org/HowDoI/GtkApplication) is
-connected to the activate() function above the main() function. The `activate`
-signal will be emitted when your application is launched with g_application_run()
-on the line below. The g_application_run() call also takes as arguments the
+connected to the activate() function above the `main()` function. The `activate`
+signal will be emitted when your application is launched with `g_application_run()`
+on the line below. The `g_application_run()` call also takes as arguments the
 command line arguments (the `argc` count and the `argv` string array).
 Your application can override the command line handling, e.g. to open
 files passed on the commandline.
 
-Within g_application_run() the activate signal is sent and we then proceed
+Within `g_application_run()` the activate signal is sent and we then proceed
 into the activate() function of the application. This is where we construct
 our GTK window, so that a window is shown when the application is launched.
-The call to gtk_application_window_new() will create a new GtkWindow and
-store it inside the `window` pointer. The window will have a frame, a title
-bar, and window controls depending on the platform.
-
-A window title is set using gtk_window_set_title(). This function takes a
-GtkWindow* pointer and a string as input. As our `window` pointer is a
-GtkWidget pointer, we need to cast it to GtkWindow*. But instead of casting
-`window` via `(GtkWindow*)`, `window` can be cast using the macro
-`GTK_WINDOW()`. `GTK_WINDOW()` will check if the pointer is an instance of
-the GtkWindow class, before casting, and emit a warning if the check fails.
-More information about this convention can be found
-[here](https://developer.gnome.org/gobject/stable/gtype-conventions.html).
-
-Finally the window size is set using gtk_window_set_default_size()
-and the window is then shown by GTK via gtk_widget_show().
-
-When you close the window, by for example pressing the X, the g_application_run()
-call returns with a number which is saved inside an integer variable named
-`status`. Afterwards, the GtkApplication object is freed from memory with
-g_object_unref(). Finally the status integer is returned and the application
-exits.
+The call to [ctor Gtk ApplicationWindow new] will create a new
+[class@Gtk.ApplicationWindow] and store it inside the `window` pointer. The
+window will have a frame, a title bar, and window controls depending on the
+platform.
+
+A window title is set using [`method@Gtk.Window.set_title`]. This function
+takes a `GtkWindow` pointer and a string as input. As our `window` pointer
+is a `GtkWidget` pointer, we need to cast it to `GtkWindow`; instead of
+casting `window` via a typical C cast like `(GtkWindow*)`, `window` can be
+cast using the macro `GTK_WINDOW()`. `GTK_WINDOW()` will check if the
+pointer is an instance of the `GtkWindow` class, before casting, and emit a
+warning if the check fails. More information about this convention can be
+found [here](https://developer.gnome.org/gobject/stable/gtype-conventions.html).
+
+Finally the window size is set using [`method@Gtk.Window.set_default_size`]
+and the window is then shown by GTK via [method Gtk Widget show].
+
+When you close the window, by (for example) pressing the X button, the
+`g_application_run()` call returns with a number which is saved inside an
+integer variable named `status`. Afterwards, the `GtkApplication` object is
+freed from memory with `g_object_unref()`. Finally the status integer is
+returned and the application exits.
 
 While the program is running, GTK is receiving _events_. These are typically
 input events caused by the user interacting with your program, but also things
@@ -139,11 +141,11 @@ this example is called *Hello, World*.
 
 ![Hello, world](hello-world.png)
 
-### Hello World in C {#gtk-getting-started-hello-world}
+### Hello World in C
 
 Create a new file with the following content named `example-1.c`.
 
-``` {.c source=examples/hello-world.c }
+```c
 #include <gtk/gtk.h>
 
 static void
@@ -196,43 +198,44 @@ main (int    argc,
 You can compile the program above with GCC using:
 
 ```
-gcc `pkg-config --cflags gtk4` -o example-1 example-1.c `pkg-config --libs gtk4`
+gcc $( pkg-config --cflags gtk4 ) -o example-1 example-1.c $( pkg-config --libs gtk4 )
 ```
 
-As seen above, example-1.c builds further upon example-0.c by adding a
-button to our window, with the label "Hello World". Two new GtkWidget
+As seen above, `example-1.c` builds further upon `example-0.c` by adding a
+button to our window, with the label "Hello World". Two new `GtkWidget`
 pointers are declared to accomplish this, `button` and `box`. The box
-variable is created to store a GtkBox, which is GTK's way of controlling
-the size and layout of buttons.
+variable is created to store a [class Gtk Box], which is GTK's way of
+controlling the size and layout of buttons.
 
-The GtkBox is created with gtk_box_new() which takes a GtkOrientation
-enum as parameter. The buttons which this box will contain can either be laid
-out horizontally or vertically. This does not matter in this particular case,
-as we are dealing with only one button. After initializing box with the newly
-created GtkBox, the code adds the box widget to the window widget using
-gtk_window_set_child().
+The `GtkBox` widget is created with [ctor Gtk Box new], which takes a
+[enum@Gtk.Orientation] enumeration value as parameter. The buttons which
+this box will contain can either be laid out horizontally or vertically.
+This does not matter in this particular case, as we are dealing with only
+one button. After initializing box with the newly created `GtkBox`, the code
+adds the box widget to the window widget using [`method@Gtk.Window.set_child`].
 
 Next the `button` variable is initialized in similar manner.
-gtk_button_new_with_label() is called which returns a GtkButton to be
-stored in `button`. Afterwards `button` is added to our `box`.
-
-Using g_signal_connect(), the button is connected to a function in our app called
-print_hello(), so that when the button is clicked, GTK will call this function.
-As the print_hello() function does not use any data as input, NULL is passed
-to it. print_hello() calls g_print() with the string "Hello World" which will
+[`ctor@Gtk.Button.new_with_label`] is called which returns a
+[class@Gtk.Button] to be stored in `button`. Afterwards `button` is added to
+our `box`.
+
+Using `g_signal_connect()`, the button is connected to a function in our app called
+`print_hello()`, so that when the button is clicked, GTK will call this function.
+As the `print_hello()` function does not use any data as input, `NULL` is passed
+to it. `print_hello()` calls `g_print()` with the string "Hello World" which will
 print Hello World in a terminal if the GTK application was started from one.
 
-After connecting print_hello(), another signal is connected to the "clicked"
-state of the button using g_signal_connect_swapped(). This functions is similar
-to a g_signal_connect() with the difference lying in how the callback function
-is treated. g_signal_connect_swapped() allows you to specify what the callback
+After connecting `print_hello()`, another signal is connected to the "clicked"
+state of the button using `g_signal_connect_swapped()`. This functions is similar
+to a `g_signal_connect()`, with the difference lying in how the callback function
+is treated; `g_signal_connect_swapped()` allows you to specify what the callback
 function should take as parameter by letting you pass it as data. In this case
-the function being called back is gtk_window_destroy() and the `window` pointer
+the function being called back is [method@Gtk.Window.destroy] and the `window` pointer
 is passed to it. This has the effect that when the button is clicked, the whole
-GTK window is destroyed. In contrast if a normal g_signal_connect() were used
-to connect the "clicked" signal with gtk_window_destroy(), then the function
+GTK window is destroyed. In contrast if a normal `g_signal_connect()` were used
+to connect the "clicked" signal with [method@Gtk.Window.destroy], then the function
 would be called on `button` (which would not go well, since the function expects
-a GtkWindow as argument).
+a `GtkWindow` as argument).
 
 More information about creating buttons can be found
 [here](https://wiki.gnome.org/HowDoI/Buttons).
@@ -256,11 +259,11 @@ arrange several buttons:
 
 ![Grid packing](grid-packing.png)
 
-### Packing buttons {#gtk-getting-started-grid-packing}
+### Packing buttons
 
 Create a new file with the following content named `example-2.c`.
 
-``` {.c source=examples/grid-packing.c }
+```c
 #include <gtk/gtk.h>
 
 static void
@@ -335,7 +338,7 @@ main (int    argc,
 You can compile the program above with GCC using:
 
 ```
-gcc `pkg-config --cflags gtk4` -o example-2 example-2.c `pkg-config --libs gtk4`
+gcc $( pkg-config --cflags gtk4 ) -o example-2 example-2.c $( pkg-config --libs gtk4 )
 ```
 
 ## Custom Drawing
@@ -343,14 +346,14 @@ gcc `pkg-config --cflags gtk4` -o example-2 example-2.c `pkg-config --libs gtk4`
 Many widgets, like buttons, do all their drawing themselves. You just tell
 them the label you want to see, and they figure out what font to use, draw
 the button outline and focus rectangle, etc. Sometimes, it is necessary to
-do some custom drawing. In that case, a GtkDrawingArea might be the right
+do some custom drawing. In that case, a [class@Gtk.DrawingArea] might be the right
 widget to use. It offers a canvas on which you can draw by setting its
 draw function.
 
-The contents of a widget often need to be partially or fully redrawn,
-e.g. when another window is moved and uncovers part of the widget, or
-when the window containing it is resized. It is also possible to explicitly
-cause a widget to be redrawn, by calling gtk_widget_queue_draw(). GTK takes
+The contents of a widget often need to be partially or fully redrawn, e.g.
+when another window is moved and uncovers part of the widget, or when the
+window containing it is resized. It is also possible to explicitly cause a
+widget to be redrawn, by calling [`method@Gtk.Widget.queue_draw`]. GTK takes
 care of most of the details by providing a ready-to-use cairo context to the
 draw function.
 
@@ -360,11 +363,11 @@ demonstrates input event handling with event controllers.
 
 ![Drawing](drawing.png)
 
-### Drawing in response to input {#gtk-getting-started-drawing}
+### Drawing in response to input
 
 Create a new file with the following content named `example-4.c`.
 
-``` {.c source=examples/drawing.c }
+```c
 #include <gtk/gtk.h>
 
 /* Surface to store current scribbles */
@@ -557,7 +560,7 @@ main (int    argc,
 You can compile the program above with GCC using:
 
 ```
-gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4`
+gcc $( pkg-config --cflags gtk4 ) -o example-4 example-4.c $( pkg-config --libs gtk4 )
 ```
 
 ## Building user interfaces
@@ -568,13 +571,13 @@ cumbersome, and making changes becomes next to impossible.
 
 Thankfully, GTK supports the separation of user interface
 layout from your business logic, by using UI descriptions in an
-XML format that can be parsed by the GtkBuilder class.</para>
+XML format that can be parsed by the [class@Gtk.Builder] class.
 
 ### Packing buttons with GtkBuilder
 
 Create a new file with the following content named `example-3.c`.
 
-``` {.c source=examples/builder.c }
+```c
 #include <gtk/gtk.h>
 #include <glib/gstdio.h>
 
@@ -638,7 +641,7 @@ main (int   argc,
 
 Create a new file with the following content named `builder.ui`.
 
-``` {.xml source=examples/builder.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
   <object id="window" class="GtkWindow">
@@ -682,24 +685,24 @@ Create a new file with the following content named `builder.ui`.
 You can compile the program above with GCC using:
 
 ```
-gcc `pkg-config --cflags gtk4` -o example-3 example-3.c `pkg-config --libs gtk4`
+gcc $( pkg-config --cflags gtk4 ) -o example-3 example-3.c $( pkg-config --libs gtk4 )
 ```
 
-Note that GtkBuilder can also be used to construct objects that are
+Note that `GtkBuilder` can also be used to construct objects that are
 not widgets, such as tree models, adjustments, etc. That is the reason
-the method we use here is called gtk_builder_get_object() and returns
-a GObject* instead of a GtkWidget*.
+the method we use here is called [`method@Gtk.Builder.get_object`] and returns
+a `GObject` instead of a `GtkWidget`.
 
-Normally, you would pass a full path to gtk_builder_add_from_file() to
+Normally, you would pass a full path to [`method@Gtk.Builder.add_from_file`] to
 make the execution of your program independent of the current directory.
 A common location to install UI descriptions and similar data is
 `/usr/share/appname`.
 
 It is also possible to embed the UI description in the source code as a
-string and use gtk_builder_add_from_string() to load it. But keeping the
+string and use [`method@Gtk.Builder.add_from_string`] to load it. But keeping the
 UI description in a separate file has several advantages: It is then possible
 to make minor adjustments to the UI without recompiling your program, and,
-more importantly, graphical UI editors such as [glade](http://glade.gnome.org)
+more importantly, graphical UI editors such as [Glade](http://glade.gnome.org)
 can load the file and allow you to create and modify your UI by point-and-click.
 
 ## Building applications
@@ -708,41 +711,45 @@ An application consists of a number of files:
 
 The binary
  : This gets installed in `/usr/bin`.
+
 A desktop file
  : The desktop file provides important information about the application to
    the desktop shell, such as its name, icon, D-Bus name, commandline to launch
    it, etc. It is installed in `/usr/share/applications`.
+
 An icon
  : The icon gets installed in `/usr/share/icons/hicolor/48x48/apps`, where it
-will be found regardless of the current theme.
+   will be found regardless of the current theme.
+
 A settings schema
  : If the application uses GSettings, it will install its schema in
-    `/usr/share/glib-2.0/schemas`, so that tools like dconf-editor can find it.
+   `/usr/share/glib-2.0/schemas`, so that tools like dconf-editor can find it.
+
 Other resources
  : Other files, such as GtkBuilder ui files, are best loaded from
    resources stored in the application binary itself. This eliminates the
    need for most of the files that would traditionally be installed in
    an application-specific location in `/usr/share`.
 
-GTK includes application support that is built on top of GApplication. In this
+GTK includes application support that is built on top of `GApplication`. In this
 tutorial we'll build a simple application by starting from scratch, adding more
-and more pieces over time. Along the way, we'll learn about GtkApplication,
-templates, resources, application menus, settings, GtkHeaderBar, GtkStack,
-GtkSearchBar, GtkListBox, and more.
+and more pieces over time. Along the way, we'll learn about [class@Gtk.Application],
+templates, resources, application menus, settings, [class@Gtk.HeaderBar], [class@Gtk.Stack],
+[class@Gtk.SearchBar], [class@Gtk.ListBox], and more.
 
-The full, buildable sources for these examples can be found in the `examples/`
-directory of the GTK source distribution, or
-[online](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples) in the GTK git
-repository. You can build each example separately by using make with the
-`Makefile.example` file. For more information, see the `README` included in the
-examples directory.
+The full, buildable sources for these examples can be found in the
+`examples` directory of the GTK source distribution, or
+[online](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples) in the GTK
+source code repository. You can build each example separately by using make
+with the `Makefile.example` file. For more information, see the `README`
+included in the examples directory.
 
 ### A trivial application
 
-When using GtkApplication, the main() function can be very simple. We just call
-g_application_run() and give it an instance of our application class.
+When using `GtkApplication`, the `main()` function can be very simple. We just call
+`g_application_run()` and give it an instance of our application class.
 
-``` {.c source=examples/application1/main.c }
+```c
 #include <gtk/gtk.h>
 
 #include "exampleapp.h"
@@ -759,15 +766,15 @@ GtkApplication. Our example does not yet have any interesting functionality.
 All it does is open a window when it is activated without arguments, and open
 the files it is given, if it is started with arguments.
 
-To handle these two cases, we override the activate() vfunc, which gets called
-when the application is launched without commandline arguments, and the open()
-vfunc, which gets called when the application is launched with commandline
-arguments.
+To handle these two cases, we override the activate() vfunc, which gets
+called when the application is launched without commandline arguments, and
+the `open()` virtual function, which gets called when the application is
+launched with commandline arguments.
 
-To learn more about GApplication entry points, consult the GIO
-[documentation](https://developer.gnome.org/gio/2.36/GApplication.html#GApplication.description).
+To learn more about `GApplication` entry points, consult the GIO
+[documentation](https://developer.gnome.org/gio/stable/GApplication.html#GApplication.description).
 
-``` {.c source=examples/application1/exampleapp.c }
+```c
 #include <gtk/gtk.h>
 
 #include "exampleapp.h"
@@ -834,10 +841,10 @@ example_app_new (void)
 ```
 
 Another important class that is part of the application support in GTK is
-GtkApplicationWindow. It is typically subclassed as well. Our subclass does
+`GtkApplicationWindow`. It is typically subclassed as well. Our subclass does
 not do anything yet, so we will just get an empty window.
 
-``` {.c source=examples/application1/examplewin.c }
+```c
 #include <gtk/gtk.h>
 
 #include "exampleapp.h"
@@ -878,7 +885,7 @@ create an icon and a desktop file.
 
 ![An icon](exampleapp.png)
 
-``` { source=examples/application1/org.gtk.exampleapp.desktop }
+```
 [Desktop Entry]
 Type=Application
 Name=Example
@@ -906,7 +913,7 @@ GtkBuilder ui file with our application window class.
 Our simple ui file gives the window a title, and puts a GtkStack
 widget as the main content.
 
-``` { .xml source=examples/application2/window.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
   <template class="ExampleAppWindow" parent="GtkApplicationWindow">
@@ -926,14 +933,14 @@ widget as the main content.
 ```
 
 To make use of this file in our application, we revisit our
-GtkApplicationWindow subclass, and call
-gtk_widget_class_set_template_from_resource() from the class init
+`GtkApplicationWindow` subclass, and call
+`gtk_widget_class_set_template_from_resource()` from the class init
 function to set the ui file as template for this class. We also
-add a call to gtk_widget_init_template() in the instance init
+add a call to `gtk_widget_init_template()` in the instance init
 function to instantiate the template for each instance of our
 class.
 
-```
+```c
  ...
 
 static void
@@ -951,6 +958,7 @@ example_app_window_class_init (ExampleAppWindowClass *class)
 
  ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application2/exampleappwin.c))
 
 You may have noticed that we used the `_from_resource()` variant of the function
@@ -959,7 +967,7 @@ that sets a template. Now we need to use
 to include the ui file in the binary. This is commonly done by listing all resources
 in a `.gresource.xml` file, such as this:
 
-``` { .xml source=examples/application2/exampleapp.gresource.xml }
+```c
 <?xml version="1.0" encoding="UTF-8"?>
 <gresources>
   <gresource prefix="/org/gtk/exampleapp">
@@ -976,8 +984,8 @@ into the application together with the other source files. To do so, we use the
 glib-compile-resources exampleapp.gresource.xml --target=resources.c --generate-source
 ```
 
-The gnome module of the meson build system provides the
-[gnome.compile_resources()](https://mesonbuild.com/Gnome-module.html#gnomecompile_resources)
+The gnome module of the [Meson build system](https://mesonbuild.com)
+provides the [`gnome.compile_resources()`](https://mesonbuild.com/Gnome-module.html#gnomecompile_resources)
 method for this task.
 
 Our application now looks like this:
@@ -990,14 +998,14 @@ In this step, we make our application show the content of all the files
 that it is given on the commandline.
 
 To this end, we add a member to the struct of our application window subclass
-and keep a reference to the GtkStack there. The first member of the struct
+and keep a reference to the `GtkStack` there. The first member of the struct
 should be the parent type from which the class is derived. Here,
-ExampleAppWindow is derived from GtkApplicationWindow. The
-gtk_widget_class_bind_template_child() function arranges things so that after
+`ExampleAppWindow` is derived from `GtkApplicationWindow`. The
+`gtk_widget_class_bind_template_child()` function arranges things so that after
 instantiating the template, the `stack` member of the struct will point to the
 widget of the same name from the template.
 
-```
+```c
 ...
 
 struct _ExampleAppWindow
@@ -1021,13 +1029,14 @@ example_app_window_class_init (ExampleAppWindowClass *class)
 
 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application3/exampleappwin.c))
 
-Now we revisit the example_app_window_open() function that is called for each
+Now we revisit the `example_app_window_open()` function that is called for each
 commandline argument, and construct a GtkTextView that we then add as a page
 to the stack:
 
-```
+```c
 ...
 
 void
@@ -1064,14 +1073,16 @@ example_app_window_open (ExampleAppWindow *win,
 
 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application3/exampleappwin.c))
 
-Lastly, we add a GtkStackSwitcher to the titlebar area in the ui file, and we
+Lastly, we add a [class@Gtk.StackSwitcher] to the titlebar area in the UI file, and we
 tell it to display information about our stack.
 
 The stack switcher gets all its information it needs to display tabs from
 the stack that it belongs to. Here, we are passing the label to show for
-each file as the last argument to the gtk_stack_add_titled() function.
+each file as the last argument to the [`method@Gtk.Stack.add_titled`]
+function.
 
 Our application is beginning to take shape:
 
@@ -1085,7 +1096,7 @@ infrequently used actions that affect the whole application.
 Just like the window template, we specify our menu in a ui file, and add it
 as a resource to our binary.
 
-``` {.xml source=examples/application4/gears-menu.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
   <menu id="menu">
@@ -1113,7 +1124,7 @@ of actions to our application.
 Adding the actions is best done in the startup() vfunc, which is guaranteed
 to be called once for each primary application instance:
 
-```
+```c
 ...
 
 static void
@@ -1163,11 +1174,12 @@ example_app_class_init (ExampleAppClass *class)
 
 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application4/exampleapp.c))
 
 Our preferences menu item does not do anything yet, but the Quit menu item
 is fully functional. Note that it can also be activated by the usual Ctrl-Q
-shortcut. The shortcut was added with gtk_application_set_accels_for_action().
+shortcut. The shortcut was added with `gtk_application_set_accels_for_action()`.
 
 The application menu looks like this:
 
@@ -1179,10 +1191,10 @@ A typical application will have a some preferences that should be remembered
 from one run to the next. Even for our simple example application, we may
 want to change the font that is used for the content.
 
-We are going to use GSettings to store our preferences. GSettings requires
+We are going to use `GSettings` to store our preferences. `GSettings` requires
 a schema that describes our settings:
 
-``` {.xml source=examples/application5/org.gtk.exampleapp.gschema.xml }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <schemalist>
   <schema path="/org/gtk/exampleapp/" id="org.gtk.exampleapp">
@@ -1208,16 +1220,16 @@ a schema that describes our settings:
 Before we can make use of this schema in our application, we need to compile
 it into the binary form that GSettings expects. GIO provides
 [macros](https://developer.gnome.org/gio/2.36/ch31s06.html) to do this in
-autotools-based projects, and the gnome module of the meson build system
-provides the [gnome.compile_schemas()](https://mesonbuild.com/Gnome-module.html#gnomecompile_schemas)
+autotools-based projects, and the gnome module of the Meson build system
+provides the [`gnome.compile_schemas()`](https://mesonbuild.com/Gnome-module.html#gnomecompile_schemas)
 method for this task.
 
 Next, we need to connect our settings to the widgets that they are supposed
-to control. One convenient way to do this is to use GSettings bind
+to control. One convenient way to do this is to use `GSettings` bind
 functionality to bind settings keys to object properties, as we do here
 for the transition setting.
 
-```
+```c
 ...
 
 static void
@@ -1233,6 +1245,7 @@ example_app_window_init (ExampleAppWindow *win)
 
 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application5/exampleappwin.c))
 
 The code to connect the font setting is a little more involved, since there
@@ -1240,15 +1253,15 @@ is no simple object property that it corresponds to, so we are not going to
 go into that here.
 
 At this point, the application will already react if you change one of the
-settings, e.g. using the gsettings commandline tool. Of course, we expect
+settings, e.g. using the `gsettings` command line tool. Of course, we expect
 the application to provide a preference dialog for these. So lets do that
-now. Our preference dialog will be a subclass of GtkDialog, and we'll use
-the same techniques that we've already seen: templates, private structs,
-settings bindings.
+now. Our preference dialog will be a subclass of [class@Gtk.Dialog], and
+we'll use the same techniques that we've already seen: templates, private
+structs, settings bindings.
 
 Lets start with the template.
 
-``` {.xml source=examples/application6/prefs.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
   <template class="ExampleAppPrefs" parent="GtkDialog">
@@ -1320,7 +1333,7 @@ Lets start with the template.
 
 Next comes the dialog subclass.
 
-``` {.c source=examples/application6/exampleappprefs.c }
+```c
 #include <gtk/gtk.h>
 
 #include "exampleapp.h"
@@ -1385,7 +1398,7 @@ example_app_prefs_new (ExampleAppWindow *win)
 Now we revisit the `preferences_activated()` function in our application
 class, and make it open a new preference dialog.
 
-```
+```c
 ...
 
 static void
@@ -1403,6 +1416,7 @@ preferences_activated (GSimpleAction *action,
 
 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application6/exampleapp.c))
 
 After all this work, our application can now show a preference dialog
@@ -1413,14 +1427,14 @@ like this:
 ### Adding a search bar
 
 We continue to flesh out the functionality of our application. For now, we
-add search. GTK supports this with GtkSearchEntry and GtkSearchBar. The
-search bar is a widget that can slide in from the top to present a search
-entry.
+add search. GTK supports this with [class@Gtk.SearchEntry] and
+[class@Gtk.SearchBar]. The search bar is a widget that can slide in from the
+top to present a search entry.
 
 We add a toggle button to the header bar, which can be used to slide out
 the search bar below the header bar.
 
-``` {.xml source=examples/application7/window.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
   <template class="ExampleAppWindow" parent="GtkApplicationWindow">
@@ -1475,7 +1489,7 @@ going to completely go over here. The central piece of the search
 implementation is a signal handler that listens for text changes in
 the search entry.
 
-```
+```c
 ...
 
 static void
@@ -1522,6 +1536,7 @@ example_app_window_init (ExampleAppWindow *win)
 
 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application7/exampleappwin.c))
 
 With the search bar, our application now looks like this:
@@ -1531,9 +1546,9 @@ With the search bar, our application now looks like this:
 ### Adding a side bar
 
 As another piece of functionality, we are adding a sidebar, which demonstrates
-GtkMenuButton, GtkRevealer and GtkListBox.
+[class@Gtk.MenuButton], [class@Gtk.Revealer] and [class@Gtk.ListBox].
 
-``` {.xml source=examples/application8/window.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
   <template class="ExampleAppWindow" parent="GtkApplicationWindow">
@@ -1606,7 +1621,7 @@ The code to populate the sidebar with buttons for the words found in each
 file is a little too involved to go into here. But we'll look at the code
 to add a checkbutton for the new feature to the menu.
 
-``` {.xml source=examples/application8/gears-menu.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
   <menu id="menu">
@@ -1631,9 +1646,9 @@ to add a checkbutton for the new feature to the menu.
 ```
 
 To connect the menuitem to the show-words setting, we use
-a GAction corresponding to the given GSettings key.
+a `GAction` corresponding to the given `GSettings` key.
 
-```
+```c
 ...
 
 static void
@@ -1654,6 +1669,7 @@ example_app_window_init (ExampleAppWindow *win)
 
 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application8/exampleappwin.c))
 
 What our application looks like now:
@@ -1665,7 +1681,7 @@ What our application looks like now:
 Widgets and other objects have many useful properties.
 
 Here we show some ways to use them in new and flexible ways, by wrapping
-them in actions with GPropertyAction or by binding them with GBinding.
+them in actions with `GPropertyAction` or by binding them with `GBinding`.
 
 To set this up, we add two labels to the header bar in our window template,
 named `lines_label` and `lines`, and bind them to struct members in the
@@ -1674,7 +1690,7 @@ private struct, as we've seen a couple of times by now.
 We add a new "Lines" menu item to the gears menu, which triggers the
 show-lines action:
 
-``` {.xml source=examples/application9/gears-menu.ui }
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <interface>
   <menu id="menu">
@@ -1711,7 +1727,7 @@ Since we want both labels to appear and disappear together, we bind
 the visible property of the `lines_label` widget to the same property
 of the `lines` widget.
 
-```
+```c
 ...
 
 static void
@@ -1730,6 +1746,7 @@ example_app_window_init (ExampleAppWindow *win)
 
 ...
 ```
+
 ([full source](https://gitlab.gnome.org/GNOME/gtk/blob/master/examples/application9/exampleappwin.c))
 
 We also need a function that counts the lines of the currently active tab,