Tutorial: Fixed .rst rendering issues

docs/tutorial.rst

@@ -8,17 +8,18 @@ Read this if you want to learn how to use Blueprint and never used
 the XML syntax that can be read by GtkBuilder.
 
 For compatibility with Blueprint IDE extensions, blueprint files
-should end with `.blp`.
+should end with ``.blp``.
 
 
 Namespaces
 ----------
 
 Blueprint needs the widget library to be imported. These include Gtk,
-Libadwaita, Shumate, etc. To import a namespace, write `using` followed
+Libadwaita, Shumate, etc. To import a namespace, write ``using`` followed
 by the library and version number.
 
 .. code-block::
+
     using Gtk 4.0;
     using Adw 1;
 
@@ -32,6 +33,7 @@ Comments
 Blueprint has inline or multi-line comments
 
 .. code-block::
+
     // This is an inline comment
     /* This is
        a multiline
@@ -42,6 +44,7 @@ will interpret the inner comment's closing token as the outer comment's
 closing token. For example, the following will not compile:
 
 .. code-block::
+
     // Bad comment below:
     /* Outer comment 
         /* Inner comment */
@@ -54,6 +57,7 @@ Widgets
 Create widgets in the following format:
 
 .. code-block::
+
     Namespace.WidgetClass {
 
     }
@@ -62,6 +66,7 @@ The Gtk namespace is implied for widgets, so you can just write the
 widget class
 
 .. code-block::
+
     Box {
     
     }
@@ -69,6 +74,7 @@ widget class
 Other namespaces must be written explicitly.
 
 .. code-block::
+
     Adw.Leaflet {
 
     }
@@ -84,13 +90,14 @@ Widgets can be given **name/ID**s so that they can be referenced by other
 widgets in the blueprint.
 
 .. code-block::
+
     Namespace.WidgetClass widget_id {
     
     }
 
 Any time you want to use this widget as a property (more about that in the
 next section) or something else, write the widget's **ID** (e.g.
-`main_window`).
+``main_window``).
 
 
 Properties
@@ -102,6 +109,7 @@ For example, the Libadwaita documentation lists the
 Write properties inside the curly brackets of a widget:
 
 .. code-block::
+
     Namespace.WidgetClass {
         property-name: value;
     }
@@ -113,14 +121,14 @@ Property Types
 ~~~~~~~~~~~~~~
 
 These are the **types** of values that can be used in properties:
-    - Booleans: `true`, `false`
+    - Booleans: ``true``, ``false``
-    - Numbers: e.g. `1`, `1.5`, `-2`, `-2.5`
+    - Numbers: e.g. ``1``, ``1.5``, ``-2``, ``-2.5``
-    - Strings (single- or double-quoted): e.g. `"a string"`, `'another string'`
+    - Strings (single- or double-quoted): e.g. ``"a string"``, ``'another string'``
     - Enums
     - Widgets
 
 Properties are **strongly typed**, so you can't use, for example, a string
-for the orientation property, which requires an `Orientation` enum
+for the orientation property, which requires an ``Orientation`` enum
 vartiant as its value.
 
 Enum Properties
@@ -138,6 +146,7 @@ In the blueprint, you would only write the *variant* part of the enum in
 *lowercase*, just like you would in the XML.
 
 .. code-block::
+
     Box {
         orientation: horizontal;
     }
@@ -146,11 +155,12 @@ Widget Properties
 ~~~~~~~~~~~~~~~~~
 
 Some widgets take other widgets as properties. For example, the
-`Gtk.StackSidebar` has a stack property which takes a `Gtk.Stack` widget.
+``Gtk.StackSidebar`` has a stack property which takes a ``Gtk.Stack`` widget.
 You can create a new widget for the value, or you can reference another
 widget by its **ID**.
 
 .. code-block::
+
     StackSidebar {
         stack: Stack { };
     }
@@ -158,6 +168,7 @@ widget by its **ID**.
 OR
 
 .. code-block::
+
     StackSidebar {
         stack: my_stack;
     }
@@ -174,12 +185,13 @@ Property Bindings
 -----------------
 
 If you want a widget's property to have the same value as another widget's
-property (without hard-coding the value), you could `bind` two widgets'
+property (without hard-coding the value), you could ``bind`` two widgets'
 properties of the same type. Bindings must reference a *source* widget by
 **ID**. As long as the two properties have the same type, you can bind
 properties of different names and of widgets with different widget classes.
 
 .. code-block::
+
     Box my_box {
         halign: fill; // Source
     }
@@ -197,6 +209,7 @@ changed to the *Source*'s value when the binding is created and when the
 *Source* value changes.
 
 .. code-block::
+
     Box my_box {
         hexpand: true; // Source
     }
@@ -214,13 +227,13 @@ no-sync-create
 bidirectional
     When either the *Source* or *Target* value is modified, the other's
     value will be updated. For example, if the logic of the program
-    changes the Button's vexpand value to `false`, then the Box's halign
+    changes the Button's vexpand value to ``false``, then the Box's halign
-    value will also be updated to `false`.
+    value will also be updated to ``false``.
 
 inverted
     If the property is a boolean, the value of the bind can be negated
-    with this flag. For example, if the Box's hexpand property is `true`,
+    with this flag. For example, if the Box's hexpand property is ``true``,
-    the Button's vexpand property will be `false` in the code above.
+    the Button's vexpand property will be ``false`` in the code above.
 
 
 Signals
@@ -239,6 +252,7 @@ To register a handler with the application, consult the documentation for
 your language's bindings of Gtk.
 
 .. code-block::
+
     WidgetClass {
         event_name => handler_name() flags;
     }
@@ -251,6 +265,7 @@ widget that is passed to the handler by referencing its **id** inside the
 parenthesis.
 
 .. code-block::
+
     Label my_label {
         label: "Hide me"; 
     }
@@ -265,7 +280,7 @@ Custom Widget Classes
 
 Some programs have custom widgets defined in their logic, and so blueprint
 won't know that they exist. Writing widgets not defined in the GIR will
-result in an error. Prepend a custom widget with a `.` to prevent the
+result in an error. Prepend a custom widget with a ``.`` to prevent the
 compiler from trying to validate the widget. This is essentially leaving
 out the *namespace*.
 
@@ -273,6 +288,7 @@ To register a custom widget with the application consult the documentation
 for your language's bindings of Gtk.
 
 .. code-block::
+
     .MyCustomWidget {
 
     }
@@ -291,6 +307,7 @@ Widgets can be given style classes that can be used with your CSS or
 in libraries like Libadwaita.
 
 .. code-block::
+
     Button {
         label: "Click me";
         styles ["my-style", "pill"]
@@ -309,9 +326,10 @@ Some widgets will have elements which are not properties, but they sort
 of act like properties. Most of the time they will be specific only to a
 certain widget. *Styles* is one of these elements, except that styles can
 be used for any widget. Similarly to how every widget has styles,
-`Gtk.ComboBoxText` has *items*:
+``Gtk.ComboBoxText`` has *items*:
 
 .. code-block::
+
     Gtk.ComboBoxText {
         items [
             item1: "Item 1",
@@ -329,17 +347,18 @@ Menus
 
 Menus are usually the widgets that are placed along the top-bar of a
 window, or pop up when you right-click some other widget. In Blueprint a
-`menu` is a `Gio.MenuModel` that can be shown by MenuButtons or other
+``menu`` is a ``Gio.MenuModel`` that can be shown by MenuButtons or other
 widgets.
 
-In Blueprint, `menu`s have *items*, *sections*, and *submenus*.
+In Blueprint, ``menu``s have *items*, *sections*, and *submenus*.
-Like widgets, `menu`s can also be given a **ID**.
+Like widgets, ``menu``s can also be given a **ID**.
 The `Menu Model section of the Gtk.PopoverMenu documentation <https://docs.gtk.org/gtk4/class.PopoverMenu.html#menu-models>`_
 has complete details on the menu model.
 
 Here is an example of a menu:
 
 .. code-block::
+
     menu my_menu {
         section {
             label: "File";
@@ -368,16 +387,18 @@ There is a shorthand for *items*. Items require at least a label. The
 action and icon-name are optional.
 
 .. code-block::
+
     menu {
         item ( "Item 2" )
         item ( "Item 2", "app.action", "icon-name" )
     }
 
-A widget that uses a `menu` is `Gtk.MenuButton`. It has the *menu-model*
+A widget that uses a ``menu`` is ``Gtk.MenuButton``. It has the *menu-model*
 property, which takes a menu. Write the menu at the root of the blueprint
 (meaning not inside any widgets) and reference it by **ID**.
 
 .. code-block::
+
     MenuButton {
         menu-model: my_menu;
     }
@@ -398,6 +419,7 @@ the child the type is for.
 The following blueprint code...
 
 .. code-block::
+
     HeaderBar {
         [start]
         Button {
@@ -414,6 +436,7 @@ The following blueprint code...
 And the following blueprint code...
 
 .. code-block::
+
     HeaderBar {
         [end]
         Button {
@@ -431,15 +454,16 @@ And the following blueprint code...
 Translatable Strings
 --------------------
 
-Mark any string as translatable using this syntax: `_("...")`.
+Mark any string as translatable using this syntax: ``_("...")``.
 
 Two strings that are the same in English could be translated in different
 ways in other languages because of different *contexts*. Translatable
-strings with context look like this: `C_("context", "...")`. An example
+strings with context look like this: ``C_("context", "...")``. An example
 where a context is needed is the word "have", which in Spanish could
 translate to "tener" or "haber".
 
 .. code-block::
+
     Label {
         label: C_("1st have", "have");
     }