docs: Corrections, updates, and improvements

docs/collect-sections.py

@@ -98,7 +98,7 @@ def rst_to_md(lines: list[str]) -> str:
         line = lines[i].rstrip()
         i += 1
         if line == ".. rst-class:: grammar-block":
-            print_block(strip_links=True)
+            print_block("text", strip_links=True)
         elif line == ".. code-block:: blueprint":
             print_block("blueprint")
         elif line == ".. note::":

docs/reference/diagnostics.rst

@@ -21,7 +21,7 @@ The tokenizer encountered an unexpected sequence of characters that aren't part
 
 child_not_accepted
 ------------------
-The parent class does not have child widgets (it does not implement `Gtk.Buildable <https://docs.gtk.org/gtk4/iface.Buildable.html>`_ and is not a subclass of `Gio.ListStore <https://docs.gtk.org/gio/class.ListStore.html>`_). Some classes use properties instead of children to add widgets. Check the parent class's documentation.
+The parent class does not have child objects (it does not implement `Gtk.Buildable <https://docs.gtk.org/gtk4/iface.Buildable.html>`_ and is not a subclass of `Gio.ListStore <https://docs.gtk.org/gio/class.ListStore.html>`_). Some classes use properties instead of children to add widgets. Check the parent class's documentation.
 
 
 .. _Diagnostic conversion_error:

docs/reference/expressions.rst

@@ -8,10 +8,10 @@ automatically.
 
 .. code-block:: blueprint
 
-   label: bind MyAppWindow.account.username;
-   /*     ^               ^       ^
-          |               creates lookup expressions that are re-evaluated when
-          |               the account's username *or* the account itself changes
+   label: bind template.account.username;
+   /*     ^             ^       ^
+          |             creates lookup expressions that are re-evaluated when
+          |             the account's username *or* the account itself changes
           |
           binds the `label` property to the expression's output
     */
@@ -49,7 +49,7 @@ Lookup Expressions
 
    LookupExpression = '.' <property::ref:`IDENT<Syntax IDENT>`>
 
-Lookup expressions perform a GObject property lookup on the preceding expression. They are recalculated whenever the property changes, using the `notify signal <https://docs.gtk.org/gobject/signal.Object.notify.html>`_
+Lookup expressions perform a GObject property lookup on the preceding expression. They are recalculated whenever the property changes, using the `notify signal <https://docs.gtk.org/gobject/signal.Object.notify.html>`_.
 
 The type of a property expression is the type of the property it refers to.
 
@@ -65,7 +65,7 @@ Closure Expressions
 
 Closure expressions allow you to perform additional calculations that aren't supported in blueprint by writing those calculations as application code. These application-defined functions are created in the same way as :ref:`signal handlers<Syntax Signal>`.
 
-Expressions are only reevaluated when their inputs change. Because blueprint doesn't manage a closure's application code, it can't tell what changes might affect the result. Therefore, closures must be *pure*, or deterministic. They may only calculate the result based on their immediate inputs, properties of their inputs or outside variables.
+Expressions are only reevaluated when their inputs change. Because blueprint doesn't manage a closure's application code, it can't tell what changes might affect the result. Therefore, closures must be *pure*, or deterministic. They may only calculate the result based on their immediate inputs, not properties of their inputs or outside variables.
 
 Blueprint doesn't know the closure's return type, so closure expressions must be cast to the correct return type using a :ref:`cast expression<Syntax CastExpression>`.
 
@@ -79,7 +79,7 @@ Cast Expressions
 
    CastExpression = 'as' '<' :ref:`TypeName<Syntax TypeName>` '>'
 
-Cast expressions allow Blueprint to know the type of an expression when it can't otherwise determine it.
+Cast expressions allow Blueprint to know the type of an expression when it can't otherwise determine it. This is necessary for closures and for properties of application-defined types.
 
 .. code-block:: blueprint
 

docs/reference/index.rst

@@ -31,7 +31,7 @@ Tokens
 IDENT
 ~~~~~
 
-An identifier starts with an ASCII underscore ``_`` or letter ``[A-Za-z]`` and consists of ASCII underscores, letters, digits ``[0-9]``, and dashes ``-``. Dashes are included for historical reasons, since GObject properties are traditionally kebab-case.
+An identifier starts with an ASCII underscore ``_`` or letter ``[A-Za-z]`` and consists of ASCII underscores, letters, digits ``[0-9]``, and dashes ``-``. Dashes are included for historical reasons, since GObject properties and signals are traditionally kebab-case.
 
 .. _Syntax NUMBER:
 

docs/reference/templates.rst

@@ -90,6 +90,7 @@ To reference the template object in a binding or expression, use the ``template`
 Language Implementations
 ------------------------
 
-- ``gtk_widget_class_set_template ()`` in C: https://docs.gtk.org/gtk4/class.Widget.html#building-composite-widgets-from-template-xml
-- ``#[template]`` in gtk-rs: https://gtk-rs.org/gtk4-rs/stable/latest/book/composite_templates.html
-- ``GObject.registerClass()`` in GJS: https://gjs.guide/guides/gtk/3/14-templates.html
+- **C** ``gtk_widget_class_set_template ()``: https://docs.gtk.org/gtk4/class.Widget.html#building-composite-widgets-from-template-xml
+- **gtk-rs** ``#[template]``: https://gtk-rs.org/gtk4-rs/stable/latest/book/composite_templates.html
+- **GJS** ``GObject.registerClass()``: https://gjs.guide/guides/gtk/3/14-templates.html
+- **PyGObject** ``@Gtk.Template``: https://pygobject.gnome.org/guide/gtk_template.html

docs/reference/values.rst

@@ -109,7 +109,7 @@ Bindings
 .. rst-class:: grammar-block
 
    Binding = 'bind' :ref:`Expression<Syntax Expression>` (BindingFlag)*
-   BindingFlag = 'inverted' | 'bidirectional' | 'sync-create'
+   BindingFlag = 'inverted' | 'bidirectional' | 'no-sync-create'
 
 Bindings keep a property updated as other properties change. They can be used to keep the UI in sync with application data, or to connect two parts of the UI.
 
@@ -120,8 +120,8 @@ Simple Bindings
 
 A binding that consists of a source object and a single lookup is called a "simple binding". These are implemented using `GObject property bindings <https://docs.gtk.org/gobject/method.Object.bind_property.html>`_ and support a few flags:
 
-- ``bidirectional``: The binding is two-way, so changes to the target property will also update the source property.
 - ``inverted``: For boolean properties, the target is set to the inverse of the source property.
+- ``bidirectional``: The binding is two-way, so changes to the target property will also update the source property.
 - ``no-sync-create``: Normally, when a binding is created, the target property is immediately updated with the current value of the source property. This flag disables that behavior, and the bound property will be updated the next time the source property changes.
 
 Complex Bindings
@@ -137,11 +137,11 @@ Example
    /* Use bindings to show a label when a switch
     * is active, without any application code */
 
-   Switch advanced_feature {}
+   Switch show_label {}
 
-   Label warning {
-     visible: bind advanced_feature.active;
-     label: _("This is an advanced feature. Use with caution!");
+   Label {
+     visible: bind show_label.active;
+     label: _("I'm a label that's only visible when the switch is enabled!");
    }
 
 .. _Syntax ObjectValue: