From 0a55d4c9810fbf9ce95cc7cc4b5d449aa9fc5874 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 18 Jun 2020 17:21:09 +0100 Subject: [PATCH] docs: Clean up the GtkBuilder description Drop the reference to a long since removed RNC schema file and to GtkUIManager; clean up the typography for code elements. --- gtk/gtkbuilder.c | 59 +++++++++++++++++++++--------------------------- 1 file changed, 26 insertions(+), 33 deletions(-) diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index 187d95720d..1361363f8e 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -59,57 +59,50 @@ * # GtkBuilder UI Definitions # {#BUILDER-UI} * * GtkBuilder parses textual descriptions of user interfaces which are - * specified in an XML format which can be roughly described by the - * RELAX NG schema below. We refer to these descriptions as “GtkBuilder + * specified in XML format. We refer to these descriptions as “GtkBuilder * UI definitions” or just “UI definitions” if the context is clear. * - * [RELAX NG Compact Syntax](https://gitlab.gnome.org/GNOME/gtk/tree/master/gtk/gtkbuilder.rnc) - * - * The toplevel element is . It optionally takes a “domain” + * The toplevel element is ``. It optionally takes a “domain” * attribute, which will make the builder look for translated strings - * using dgettext() in the domain specified. This can also be done by + * using `dgettext()` in the domain specified. This can also be done by * calling gtk_builder_set_translation_domain() on the builder. - * Objects are described by elements, which can contain - * elements to set properties, elements which - * connect signals to handlers, and elements, which describe + * Objects are described by `` elements, which can contain + * elements to set properties, `` elements which + * connect signals to handlers, and `` elements, which describe * child objects (most often widgets inside a container, but also e.g. - * actions in an action group, or columns in a tree model). A - * element contains an element which describes the child object. + * actions in an action group, or columns in a tree model). A `` + * element contains an `` element which describes the child object. * The target toolkit version(s) are described by elements, * the “lib” attribute specifies the widget library in question (currently * the only supported value is “gtk+”) and the “version” attribute specifies - * the target version in the form “.”. The builder will error + * the target version in the form “``.``”. The builder will error * out if the version requirements are not met. * - * Typically, the specific kind of object represented by an + * Typically, the specific kind of object represented by an `` * element is specified by the “class” attribute. If the type has not - * been loaded yet, GTK+ tries to find the get_type() function from the + * been loaded yet, GTK tries to find the `get_type()` function from the * class name by applying heuristics. This works in most cases, but if - * necessary, it is possible to specify the name of the get_type() function - * explicitly with the "type-func" attribute. As a special case, GtkBuilder - * allows to use an object that has been constructed by a #GtkUIManager in - * another part of the UI definition by specifying the id of the #GtkUIManager - * in the “constructor” attribute and the name of the object in the “id” - * attribute. + * necessary, it is possible to specify the name of the `get_type()` function + * explicitly with the "type-func" attribute. * * Objects may be given a name with the “id” attribute, which allows the * application to retrieve them from the builder with gtk_builder_get_object(). * An id is also necessary to use the object as property value in other - * parts of the UI definition. GTK+ reserves ids starting and ending - * with ___ (3 underscores) for its own purposes. + * parts of the UI definition. GTK reserves ids starting and ending + * with `___` (three consecutive underscores) for its own purposes. * * Setting properties of objects is pretty straightforward with the * element: the “name” attribute specifies the name of the * property, and the content of the element specifies the value. - * If the “translatable” attribute is set to a true value, GTK+ uses - * gettext() (or dgettext() if the builder has a translation domain set) + * If the “translatable” attribute is set to a true value, GTK uses + * `gettext()` (or `dgettext()` if the builder has a translation domain set) * to find a translation for the value. This happens before the value * is parsed, so it can be used for properties of any type, but it is * probably most useful for string properties. It is also possible to * specify a context to disambiguate short strings, and comments which * may help the translators. * - * GtkBuilder can parse textual representations for the most common + * #GtkBuilder can parse textual representations for the most common * property types: characters, strings, integers, floating-point numbers, * booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted * as %TRUE, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted @@ -122,9 +115,9 @@ * and pixbufs can be specified as a filename of an image file to load. * * Objects can be referred to by their name and by default refer to - * objects declared in the local xml fragment and objects exposed via + * objects declared in the local XML fragment and objects exposed via * gtk_builder_expose_object(). In general, GtkBuilder allows forward - * references to objects — declared in the local xml; an object doesn’t + * references to objects — declared in the local XML; an object doesn’t * have to be constructed before it can be referred to. The exception * to this rule is that an object has to be constructed before it can * be used as the value of a construct-only property. @@ -134,20 +127,20 @@ * "bind-source" to specify the source object of the binding, and * optionally, "bind-property" and "bind-flags" to specify the * source property and source binding flags respectively. - * Internally builder implements this using GBinding objects. + * Internally builder implements this using #GBinding objects. * For more information see g_object_bind_property() * * Sometimes it is necessary to refer to widgets which have implicitly * been constructed by GTK+ as part of a composite widget, to set - * properties on them or to add further children (e.g. the @vbox of - * a #GtkDialog). This can be achieved by setting the “internal-child” - * property of the element to a true value. Note that GtkBuilder - * still requires an element for the internal child, even if it + * properties on them or to add further children (e.g. the content area + * of a #GtkDialog). This can be achieved by setting the “internal-child” + * property of the `` element to a true value. Note that #GtkBuilder + * still requires an `` element for the internal child, even if it * has already been constructed. * * A number of widgets have different places where a child can be added * (e.g. tabs vs. page content in notebooks). This can be reflected in - * a UI definition by specifying the “type” attribute on a + * a UI definition by specifying the “type” attribute on a `` * The possible values for the “type” attribute are described in the * sections describing the widget-specific portions of UI definitions. *