Merge branch 'doc-links' into 'master'

Doc links

See merge request GNOME/gtk!2361

docs/reference/gtk/gtk-markdown-to-docbook

@@ -180,7 +180,7 @@ def ConvertToDocbook(infile, outfile):
     else:
         division='chapter'
     input_format = "markdown" + "".join(MarkdownExtensions)
-    output_format = "docbook"
+    output_format = "docbook4"
     subprocess.check_call(["pandoc", infile, "-o", outfile,
                            "--from=" + input_format,
                            "--to=" + output_format,

docs/reference/gtk/gtk4-sections.txt

@@ -431,7 +431,7 @@ gtk_single_selection_get_type
 
 <SECTION>
 <FILE>gtkmultiselection</FILE>
-<TITLE>GtkMultiSeledction</TITLE>
+<TITLE>GtkMultiSelection</TITLE>
 GtkMultiSelection
 gtk_multi_selection_new
 gtk_multi_selection_get_model

docs/reference/gtk/question_index.md

@@ -48,7 +48,7 @@ the question you have, this list is a good place to start.
 5.  Why does my program leak memory, if I destroy a widget immediately
     after creating it ?
 
-    If `GtkFooi` isn't a toplevel window, then
+    If `GtkFoo` isn't a toplevel window, then
 
         foo = gtk_foo_new ();
         g_object_unref (foo);
@@ -80,7 +80,7 @@ the question you have, this list is a good place to start.
 
 7.  How do I internationalize a GTK program?
 
-    Most people use <[GNU gettext](https://www.gnu.org/software/gettext/),
+    Most people use [GNU gettext](https://www.gnu.org/software/gettext/),
     already required in order to install GLib. On a UNIX or Linux system with
     gettext installed, type `info gettext` to read the documentation.
 
@@ -108,7 +108,7 @@ the question you have, this list is a good place to start.
 
     Code using these macros ends up looking like this:
 
-        #include &lt;gi18n.h&gt;
+        #include <gi18n.h>
 
         static const char *global_variable = N_("Translate this string");
 
@@ -162,7 +162,7 @@ the question you have, this list is a good place to start.
         if (g_file_get_contents (filename, &amp;text, &amp;length, NULL))
           {
             utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
-                                   NULL, NULL, &amp;error);
+                                   NULL, NULL, &error);
             if (error != NULL)
               {
                 fprintf ("Couldn't convert file %s to UTF-8\n", filename);
@@ -188,9 +188,9 @@ the question you have, this list is a good place to start.
 
       Even if your toolchain can't handle UTF-8 directly, you can still
       encode string literals in UTF-8 by using octal or hexadecimal escapes
-      like `\\212` or `\\xa8` to encode each byte. This is portable, but
+      like `\212` or `\xa8` to encode each byte. This is portable, but
       modifying the escaped strings is not very convenient. Be careful when
-      mixing hexadecimal escapes with ordinary text; `"\\xa8abcd" is a string
+      mixing hexadecimal escapes with ordinary text; `"\xa8abcd" is a string
       of length 1 !
 
     - Runtime conversion
@@ -203,7 +203,7 @@ the question you have, this list is a good place to start.
 
     Here is an example showing the three approaches using the copyright
     sign © which has Unicode and ISO-8859-1 codepoint 169 and is represented
-    in UTF-8 by the two bytes 194, 169, or `"\\302\\251"` as a string literal:
+    in UTF-8 by the two bytes 194, 169, or `"\302\251"` as a string literal:
     
         g_print ("direct UTF-8: ©");
         g_print ("escaped UTF-8: \302\251");
@@ -444,7 +444,7 @@ the question you have, this list is a good place to start.
     So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the
     column.
 
-28. I can set data easily on my #GtkTreeStore/#GtkListStore models using
+28. I can set data easily on my #GtkTreeStore or #GtkListStore models using
     gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
 
     Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel

docs/reference/gtk/resources.md

@@ -33,7 +33,7 @@ good ways to contact the GTK developers, apart from GitLab issues,
 are
 
 - the #gtk IRC channel on irc.gnome.org
-- the gtk tag on the <[GNOME Discourse instance](https://discourse.gnome.org/tag/gtk)
+- the gtk tag on the [GNOME Discourse instance](https://discourse.gnome.org/tag/gtk)
 
 You should not send patches by email, as they will inevitably get lost,
 or forgotten. Always open a merge request.

gtk/gtkcolumnviewcolumn.c

@@ -42,6 +42,13 @@
  * @see_also: #GtkColumnView
  *
  * GtkColumnViewColumn represents the columns being added to #GtkColumnView.
+ *
+ * Columns have a title, and can optionally have a header menu set
+ * with gtk_column_view_column_set_header_menu().
+ *
+ * A sorter can be associated with a column using
+ * gtk_column_view_column_set_sorter(), to let users influence sorting by
+ * clicking on the column header.
  */
 
 struct _GtkColumnViewColumn
@@ -756,6 +763,9 @@ gtk_column_view_column_remove_from_sorter (GtkColumnViewColumn *self)
  *
  * This sorter can be made active by clicking on the column
  * header, or by calling gtk_column_view_sort_by_column().
+ *
+ * See gtk_column_view_get_sorter() for the necessary steps
+ * for setting up customizable sorting for #GtkColumnView.
  */
 void
 gtk_column_view_column_set_sorter (GtkColumnViewColumn *self,

gtk/gtkdirectorylist.c

@@ -34,21 +34,22 @@
  * It presents a #GListModel and fills it asynchronously with the #GFileInfos
  * returned from that function.
  *
- * Enumeration will start automatically when a the GtkDirectoryList:file property
+ * Enumeration will start automatically when a the #GtkDirectoryList:file property
  * is set.
  *
- * While the #GtkDirectoryList is being filled, the GtkDirectoryList:loading
+ * While the #GtkDirectoryList is being filled, the #GtkDirectoryList:loading
  * property will be set to %TRUE. You can listen to that property if you want
  * to show information like a #GtkSpinner or a "Loading..." text.
- * If loading fails at any point, the GtkDirectoryList:error property will be set
+ *
- * to give more indication about the failure.
+ * If loading fails at any point, the #GtkDirectoryList:error property will be
+ * set to give more indication about the failure.
  *
  * The #GFileInfos returned from a #GtkDirectoryList have the "standard::file"
  * attribute set to the #GFile they refer to. This way you can get at the file
  * that is referred to in the same way you would via g_file_enumerator_get_child().
  * This means you do not need access to the #GtkDirectoryList but can access
- * the #GFile directly from the #GFileInfo when operating with a #GtkListView or
+ * the #GFile directly from the #GFileInfo when operating with a #GtkListView
- * similar.
+ * or similar.
  */
 
 /* random number that everyone else seems to use, too */
@@ -817,6 +818,7 @@ gtk_directory_list_get_io_priority (GtkDirectoryList *self)
  *
  * Returns %TRUE if the children enumeration is currently in
  * progress.
+ *
  * Files will be added to @self from time to time while loading is
  * going on. The order in which are added is undefined and may change
  * inbetween runs.

gtk/gtkdropdown.c

@@ -58,13 +58,11 @@
  *
  * The options are given to GtkDropDown in the form of #GListModel,
  * and how the individual options are represented is determined by
- * a #GtkListItemFactory. The default factory displays simple strings,
+ * a #GtkListItemFactory. The default factory displays simple strings.
- * and expects to obtain these from the model by evaluating an expression
- * that has to be provided via gtk_drop_down_set_expression().
  *
  * GtkDropDown knows how to obtain strings from the items in a
  * #GtkStringList; for other models, you have to provide an expression
- * to find the strings.
+ * to find the strings via gtk_drop_down_set_expression().
  *
  * GtkDropDown can optionally allow search in the popup, which is
  * useful if the list of options is long. To enable the search entry,

gtk/gtkfilter.c

@@ -38,7 +38,7 @@
  * ones that the function returns %TRUE for.
  *
  * Filters may change what items they match through their lifetime. In that
- * case, they will emit the #GtkFilter:changed signal to notify that previous
+ * case, they will emit the #GtkFilter::changed signal to notify that previous
  * filter results are no longer valid and that items should be checked again
  * via gtk_filter_match().
  *
@@ -141,7 +141,7 @@ gtk_filter_match (GtkFilter *self,
  * Gets the known strictness of @filters. If the strictness is not known,
  * %GTK_FILTER_MATCH_SOME is returned.
  *
- * This value may change after emission of the #GtkFilter:changed signal.
+ * This value may change after emission of the #GtkFilter::changed signal.
  *
  * This function is meant purely for optimization purposes, filters can
  * choose to omit implementing it, but #GtkFilterListModel uses it.
@@ -161,7 +161,7 @@ gtk_filter_get_strictness (GtkFilter *self)
  * @self: a #GtkFilter
  * @change: How the filter changed
  *
- * Emits the #GtkFilter:changed signal to notify all users of the filter that
+ * Emits the #GtkFilter::changed signal to notify all users of the filter that
  * the filter changed. Users of the filter should then check items again via
  * gtk_filter_match().
  *

gtk/gtkfilterlistmodel.c

@@ -786,6 +786,9 @@ gtk_filter_list_model_get_model (GtkFilterListModel *self)
  * interesting around 10,000 to 100,000 items.
  *
  * By default, incremental filtering is disabled.
+ *
+ * See gtk_filter_list_model_get_pending() for progress information
+ * about an ongoing incremental filtering operation.
  **/
 void
 gtk_filter_list_model_set_incremental (GtkFilterListModel *self,
@@ -837,8 +840,6 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
  *
  * Returns the number of items that have not been filtered yet.
  *
- * When incremental filtering is not enabled, this always returns 0.
- *
  * You can use this value to check if @self is busy filtering by
  * comparing the return value to 0 or you can compute the percentage
  * of the filter remaining by dividing the return value by the total
@@ -850,6 +851,9 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
  *   percentage = pending / (double) g_list_model_get_n_items (model);
  * ]|
  *
+ * If no filter operation is ongoing - in particular when
+ * #GtkFilterListModel:incremental is %FALSE - this function returns 0.
+ *
  * Returns: The number of items not yet filtered
  **/
 guint

gtk/gtkmultiselection.c

@@ -347,7 +347,7 @@ gtk_multi_selection_class_init (GtkMultiSelectionClass *klass)
   gobject_class->dispose = gtk_multi_selection_dispose;
 
   /**
-   * GtkMultiSelection:model
+   * GtkMultiSelection:model:
    *
    * The list managed by this selection
    */

gtk/gtkselectionmodel.c

@@ -31,40 +31,40 @@
  * @Short_description: An extension of the list model interface that handles selections
  * @See_also: #GListModel, #GtkSingleSelection
  *
- * #GtkSelectionModel is an interface that extends the #GListModel interface by adding
+ * #GtkSelectionModel is an interface that extends the #GListModel interface by
- * support for selections. This support is then used by widgets using list models to add
+ * adding support for selections. This support is then used by widgets using list
- * the ability to select and unselect various items.
+ * models to add the ability to select and unselect various items.
  *
- * GTK provides default implementations of the mode common selection modes such as
+ * GTK provides default implementations of the most common selection modes such
- * #GtkSingleSelection, so you will only need to implement this interface if you want
+ * as #GtkSingleSelection, so you will only need to implement this interface if
- * detailed control about how selections should be handled.
+ * you want detailed control about how selections should be handled.
  *
- * A #GtkSelectionModel supports a single boolean per item indicating if an item is selected
+ * A #GtkSelectionModel supports a single boolean per item indicating if an item
- * or not. This can be queried via gtk_selection_model_is_selected(). When the selected
+ * is selected or not. This can be queried via gtk_selection_model_is_selected().
- * state of one or more items changes, the model will emit the
+ * When the selected state of one or more items changes, the model will emit the
  * #GtkSelectionModel::selection-changed signal by calling the
- * gtk_selection_model_selection_changed() function. The positions given in that signal
+ * gtk_selection_model_selection_changed() function. The positions given in that
- * may have their selection state changed, though that is not a requirement.
+ * signal may have their selection state changed, though that is not a requirement.
- * If new items added to the model via the #GListModel::items-changed signal are selected
+ * If new items added to the model via the #GListModel::items-changed signal are
- * or not is up to the implementation.
+ * selected or not is up to the implementation.
  *
  * Note that items added via #GListModel::items-changed may already be selected
  * and no #GtkSelectionModel::selection-changed will be emitted for them. So to
  * track which items are selected, it is necessary to listen to both signals.
  *
- * Additionally, the interface can expose functionality to select and unselect items.
+ * Additionally, the interface can expose functionality to select and unselect
- * If these functions are implemented, GTK's list widgets will allow users to select and
+ * items. If these functions are implemented, GTK's list widgets will allow users
- * unselect items. However, #GtkSelectionModels are free to only implement them
+ * to select and unselect items. However, #GtkSelectionModels are free to only
- * partially or not at all. In that case the widgets will not support the unimplemented
+ * implement them partially or not at all. In that case the widgets will not
- * operations.
+ * support the unimplemented operations.
  *
- * When selecting or unselecting is supported by a model, the return values of the
+ * When selecting or unselecting is supported by a model, the return values of
- * selection functions do NOT indicate if selection or unselection happened. They are
+ * the selection functions do *not* indicate if selection or unselection happened.
- * only meant to indicate complete failure, like when this mode of selecting is not
+ * They are only meant to indicate complete failure, like when this mode of
- * supported by the model.
+ * selecting is not supported by the model.
  *
- * Selections may happen asynchronously, so the only reliable way to find out when an
+ * Selections may happen asynchronously, so the only reliable way to find out
- * item was selected is to listen to the signals that indicate selection.
+ * when an item was selected is to listen to the signals that indicate selection.
  */
 
 G_DEFINE_INTERFACE (GtkSelectionModel, gtk_selection_model, G_TYPE_LIST_MODEL)
@@ -318,13 +318,13 @@ gtk_selection_model_get_selection (GtkSelectionModel *model)
  * @position: start of the queired range
  * @n_items: number of items in the queried range
  *
- * Gets a set containing a set where the values in the range [position,
+ * Gets a set containing a set where the values in the range `[position,
- * position + n_items) match the selected state of the items in that range.
+ * position + n_items)` match the selected state of the items in that range.
  * All values outside that range are undefined.
  *
  * This function is an optimization for gtk_selection_model_get_selection() when
  * you are only interested in part of the model's selected state. A common use
- * case is in response to the :selection-changed signal.
+ * case is in response to the #GtkSelectionModel::selection-changed signal.
  *
  * Returns: A #GtkBitset that matches the selection state for the given state
  *     with all other values being undefined.
@@ -544,8 +544,8 @@ gtk_selection_model_set_selection (GtkSelectionModel *model,
  * @n_items: the number of changed items
  *
  * Helper function for implementations of #GtkSelectionModel.
- * Call this when a the selection changes to emit the ::selection-changed
+ * Call this when a the selection changes to emit the
- * signal.
+ * #GtkSelectionModel::selection-changed signal.
  */
 void
 gtk_selection_model_selection_changed (GtkSelectionModel *model,

gtk/gtksignallistitemfactory.c

@@ -163,7 +163,7 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
    * The ::setup signal is emitted when a new listitem has been created and
    * needs to be setup for use. It is the first signal emitted for every listitem.
    *
-   * The GtkSignalListItemFactory::teardown signal is the opposite of this signal
+   * The #GtkSignalListItemFactory::teardown signal is the opposite of this signal
    * and can be used to undo everything done in this signal.
    */
   signals[SETUP] =
@@ -184,13 +184,13 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
    * @self: The #GtkSignalListItemFactory
    * @listitem: The #GtkListItem to bind
    *
-   * The ::bind signal is emitted when a new GtkListItem:item has been set
+   * The ::bind signal is emitted when a new #GtkListItem:item has been set
    * on the @listitem and should be bound for use.
    *
    * After this signal was emitted, the listitem might be shown in a #GtkListView
    * or other list widget.
    *
-   * The GtkSignalListItemFactory::unbind signal is the opposite of this signal
+   * The #GtkSignalListItemFactory::unbind signal is the opposite of this signal
    * and can be used to undo everything done in this signal.
    */
   signals[BIND] =
@@ -212,9 +212,9 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
    * @listitem: The #GtkListItem to unbind
    *
    * The ::unbind signal is emitted when a listitem has been removed from use
-   * in a list widget and its new GtkListItem:item is about to be unset.
+   * in a list widget and its new #GtkListItem:item is about to be unset.
    *
-   * This signal is the opposite of the GtkSignalListItemFactory::bind signal
+   * This signal is the opposite of the #GtkSignalListItemFactory::bind signal
    * and should be used to undo everything done in that signal.
    */
   signals[UNBIND] =
@@ -238,7 +238,7 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
    * The ::teardown signal is emitted when a listitem is about to be destroyed.
    * It is the last signal ever emitted for this @listitem.
    *
-   * This signal is the opposite of the GtkSignalListItemFactory::setup signal
+   * This signal is the opposite of the #GtkSignalListItemFactory::setup signal
    * and should be used to undo everything done in that signal.
    */
   signals[TEARDOWN] =

gtk/gtksingleselection.c

@@ -36,8 +36,8 @@
  * used by list widgets in GTK.
  *
  * Note that the selection is *persistent* -- if the selected item is removed
- * and re-added in the same ::items-changed emission, it stays selected. In
+ * and re-added in the same #GListModel::items-changed emission, it stays selected.
- * particular, this means that changing the sort order of an underlying sort
+ * In particular, this means that changing the sort order of an underlying sort
  * model will preserve the selection.
  */
 struct _GtkSingleSelection
@@ -570,11 +570,13 @@ gtk_single_selection_get_selected (GtkSingleSelection *self)
  * @self: a #GtkSingleSelection
  * @position: the item to select or #GTK_INVALID_LIST_POSITION
  *
- * Selects the item at the given position. If the list does not have an item at
+ * Selects the item at the given position.
- * @position or #GTK_INVALID_LIST_POSITION is given, the behavior depends on the
+ *
- * value of the GtkSingleSelection:autoselect property: If it is set, no change
+ * If the list does not have an item at @position or
- * will occur and the old item will stay selected. If it is unset, the selection
+ * #GTK_INVALID_LIST_POSITION is given, the behavior depends on the
- * will be unset and no item will be selected.
+ * value of the #GtkSingleSelection:autoselect property: If it is set,
+ * no change will occur and the old item will stay selected. If it is
+ * unset, the selection will be unset and no item will be selected.
  **/
 void
 gtk_single_selection_set_selected (GtkSingleSelection *self,
@@ -619,7 +621,9 @@ gtk_single_selection_set_selected (GtkSingleSelection *self,
  * gtk_single_selection_get_selected_item:
  * @self: a #GtkSingleSelection
  *
- * Gets the selected item. If no item is selected, %NULL is returned.
+ * Gets the selected item.
+ *
+ * If no item is selected, %NULL is returned.
  *
  * Returns: (transfer none): The selected item
  */
@@ -703,9 +707,9 @@ gtk_single_selection_get_can_unselect (GtkSingleSelection *self)
  * If %TRUE, unselecting the current item via
  * gtk_selection_model_unselect_item() is supported.
  *
- * Note that setting GtkSingleSelection:autoselect will cause the
+ * Note that setting #GtkSingleSelection:autoselect will cause the
  * unselecting to not work, so it practically makes no sense to set
- * both at the same time the same time..
+ * both at the same time the same time.
  **/
 void
 gtk_single_selection_set_can_unselect (GtkSingleSelection *self,

gtk/gtksortlistmodel.c

@@ -61,6 +61,10 @@
  * #GtkSortListModel is a list model that takes a list model and
  * sorts its elements according to a #GtkSorter.
  *
+ * The model can be set up to do incremental sorting, so that
+ * sorting long lists doesn't block the UI. See
+ * gtk_sort_list_model_set_incremental() for details.
+ *
  * #GtkSortListModel is a generic model and because of that it
  * cannot take advantage of any external knowledge when sorting.
  * If you run into performance issues with #GtkSortListModel, it
@@ -978,6 +982,9 @@ gtk_sort_list_model_get_sorter (GtkSortListModel *self)
  * interesting around 10,000 to 100,000 items.
  *
  * By default, incremental sorting is disabled.
+ *
+ * See gtk_sort_list_model_get_pending() for progress information
+ * about an ongoing incremental sorting operation.
  */
 void
 gtk_sort_list_model_set_incremental (GtkSortListModel *self,
@@ -1032,8 +1039,9 @@ gtk_sort_list_model_get_incremental (GtkSortListModel *self)
  *
  * If you want to estimate the progress, you can use code like this:
  * |[<!-- language="C" -->
- * double progress = 1.0 - (double) gtk_sort_list_model_get_pending (self) 
+ *   pending = gtk_sort_list_model_get_pending (self);
- *                         / MAX (1, g_list_model_get_n_items (G_LIST_MODEL (sort)));
+ *   model = gtk_sort_list_model_get_model (self);
+ *   progress = 1.0 - pending / (double) MAX (1, g_list_model_get_n_items (model));
  * ]|
  *
  * If no sort operation is ongoing - in particular when

gtk/gtkstringlist.c

@@ -466,11 +466,11 @@ gtk_string_list_new (const char * const *strings)
  * Changes @self by removing @n_removals strings and adding @additions
  * to it.
  *
- * This function is more efficient than gtk_string_list_insert() and
+ * This function is more efficient than gtk_string_list_append() and
  * gtk_string_list_remove(), because it only emits
  * #GListModel::items-changed once for the change.
  *
- * This function takes a ref on each item in @additions.
+ * This function copies the strings in @additions.
  *
  * The parameters @position and @n_removals must be correct (ie:
  * @position + @n_removals must be less than or equal to the length