[gtk/ebassi/gidocgen: 60/481] docs: Tweak the actions overview

[Emmanuele Bassi <ebassi src gnome org>]

commit 57214e7efcd0e509999108e013bcddc44b192e90
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Feb 20 00:17:20 2021 -0500

    docs: Tweak the actions overview
    
    Fix use of definition lists, and remove some gtk-doc
    markup.

 docs/reference/gtk/actions.md | 51 +++++++++++++++++++++++--------------------
 1 file changed, 27 insertions(+), 24 deletions(-)
---
diff --git a/docs/reference/gtk/actions.md b/docs/reference/gtk/actions.md
index 51af4fbf3f..2482c5c0b9 100644
--- a/docs/reference/gtk/actions.md
+++ b/docs/reference/gtk/actions.md
@@ -3,12 +3,12 @@ Slug: actions
 
 This chapter describes in detail how GTK uses actions to connect
 activatable UI elements to callbacks. GTK inherits the underlying
-architecture of GAction and GMe:u for describing abstract actions
+architecture of `GAction` and `GMenu` for describing abstract actions
 and menus from the GIO library.
 
 ## Basics about actions
 
-A GAction is essentially a way to tell the toolkit about a piece of
+A `GAction` is essentially a way to tell the toolkit about a piece of
 functionality in your program, and to give it a name.
 
 Actions are purely functional. They do not contain any presentational
@@ -77,7 +77,7 @@ state type, and activating them with a particular parameter value is
 equivalent to changing their state to that value.
 
 This approach to handling radio buttons is different than many other
-action systems such as GtkAction. With GAction, there is only one action
+action systems such as `GtkAction`. With `GAction`, there is only one action
 for "text-justify" and "left", "center" and "right" are possible states on
 that action. There are not three separate "justify-left", "justify-center"
 and "justify-right" actions.
@@ -97,7 +97,7 @@ Even though toggle actions have a state, they do not have a parameter.
 Therefore, a target value is not needed when referring to them — they
 will always be toggled on activation.
 
-Most APIs that allow using a GAction (such as GMenuModel and GtkActionable)
+Most APIs that allow using a `GAction` (such as `GMenuModel` and `GtkActionable`)
 allow use of detailed action names. This is a convenient way of specifying
 an action name and an action target with a single string.
 
@@ -141,7 +141,7 @@ separate state for each instance of the action as well as being able to
 control the enabled state of the action on a per-window basis.
 
 Actions are added to their relevant scope (application, window or widget)
-either using the GActionMap interface, or by using
+either using the `GActionMap` interface, or by using
 gtk_widget_insert_action_group(). Actions that will be the same for all
 instances of a widget class can be added globally using
 gtk_widget_class_install_action().
@@ -150,7 +150,7 @@ gtk_widget_class_install_action().
 
 Actions rarely occurs in isolation. It is common to have groups
 of related actions, which are represented by instances of the
-GActionGroup interface.
+`GActionGroup` interface.
 
 Action maps are a variant of action groups that allow to change
 the name of the action as it is looked up. In GTK, the convention
@@ -161,46 +161,46 @@ or "win." for those with window scope.
 When referring to actions on a GActionMap only the name of the
 action itself is used (ie: "quit", not "app.quit"). The
 "app.quit" form is only used when referring to actions from
-places like a GMenu or GtkActionable widget where the scope
+places like a `GMenu` or `GtkActionable` widget where the scope
 of the action is not already known.
 
-GtkApplication and GtkApplicationWindow implement the GActionMap
+`GtkApplication` and `GtkApplicationWindow` implement the `GActionMap`
 interface, so you can just add actions directly to them. For
 other widgets, use gtk_widget_insert_action_group() to add
 actions to it.
 
 If you want to insert several actions at the same time, it is
-typically faster and easier to use GActionEntry.
+typically faster and easier to use `GActionEntry`.
 
 ## Connecting actions to widgets
 
-Any widget that implements the GtkActionable interface can
+Any widget that implements the `GtkActionable` interface can
 be connected to an action just by setting the ::action-name
 property. If the action has a parameter, you will also need
-to set the ::action-target property.
-Widgets that implement GtkActionable include GtkSwitch, GtkButton,
-and their respective subclasses.
+to set the ::action-target property. Widgets that implement
+`GtkActionable` include `GtkSwitch`, `GtkButton`, and their
+respective subclasses.
 
 Another way of obtaining widgets that are connected to actions
-is to create a menu using a GMenu menu model. GMenu provides an
+is to create a menu using a `GMenu` menu model. `GMenu` provides an
 abstract way to describe typical menus: nested groups of items
 where each item can have a label, and icon, and an action.
 
-A typical use of GMenu inside GTK is to set up an application
+A typical use of `GMenu` inside GTK is to set up an application
 menubar with gtk_application_set_menubar(). Another, maybe more
 common use is to create a popover for a menubutton, using
 gtk_menu_button_set_menu_model().
 
 Unlike traditional menus, those created from menu models don't
 have keyboard accelerators associated with menu items. Instead,
-GtkApplication offers the gtk_application_set_accels_for_action()
+`GtkApplication` offers the gtk_application_set_accels_for_action()
 API to associate keyboard shortcuts with actions.
 
 ## Activation
 
 When a widget with a connected action is activated, GTK finds
 the action to activate by walking up the widget hierarchy,
-looking for a matching action, ending up at the GtkApplication.
+looking for a matching action, ending up at the `GtkApplication`.
 
 ## Built-in Actions
 
@@ -210,13 +210,16 @@ you should avoid naming conflicts with them when creating your
 own actions.
 
 default.activate
- :  Activates the default widget in a context (typically a GtkWindow,
-    GtkDialog or GtkPopover)
+: Activates the default widget in a context (typically a `GtkWindow`,
+  `GtkDialog` or `GtkPopover`)
+
 clipboard.cut, clipboard.copy, clipboard.paste
- :  Clipboard operations on entries, text view and labels, typically
-    used in the context menu
+: Clipboard operations on entries, text view and labels, typically
+  used in the context menu
+
 selection.delete, selection.select-all
- : Selection operations on entries, text view and labels
+: Selection operations on entries, text view and labels
+
 color.select, color.customize:
- : Operate on colors in a #GtkColorChooserWidget. These actions are
-   unusual in that they have the non-trivial parameter type (dddd):
+: Operate on colors in a `GtkColorChooserWidget`. These actions are
+  unusual in that they have the non-trivial parameter type (dddd):