From e4a2aa8f39b8b0d117708e56daff336da7c07f95 Mon Sep 17 00:00:00 2001
From: "Luke T. Shumaker" <lukeshu@lukeshu.com>
Date: Mon, 12 Aug 2024 17:36:59 -0600
Subject: [PATCH] docs: Wrap things that gi-docgen mistakes as HTML tags in
 `backticks`

This are nasty, because they mean words get dropped from the
documentation.  This can be seen at

 - https://docs.gtk.org/gio/ctor.DBusNodeInfo.new_for_xml.html where
   it reads "one top-level element" instead of "one top-level <node>
   element".

 - https://docs.gtk.org/gio/method.ProxyResolver.lookup.html where it
   reads "where could be" instead of "where <protocol> could be".

 - https://docs.gtk.org/gio/method.Socket.get_option.html where it
   reads "[][gio-gnetworking.h]" instead of
   "[<gio/gnetworking.h>][gio-gnetworking.h" (also, this markdown link
   needs fixed, but let's save that for another commit).

 - https://docs.gtk.org/glib/ctor.DateTime.new_from_iso8601.html where
   the text is incomprehensible; "strings of the form are supported"
   instead of "strings of the form <date><sep><time><tz> are
   supported"; further references to <sep>, <date>, <time>, and <tz>
   are similarly mangled.

 - https://docs.gtk.org/glib/method.MatchInfo.fetch_named.html and
   https://docs.gtk.org/glib/method.MatchInfo.fetch_named_pos.html
   where the regex reads as "(?Pa)?b" instead of as "(?P<X>a)?b",
   changing the meaning of it.

 - https://docs.gtk.org/glib/method.Regex.match_all_full.html is all
   wack because the "<a>" in the example string is taken to be an HTML
   link; and all example strings and regexes are mangled (also, one of
   the regexes has a stray ";" in it, but let's save that for another
   commit).

 - https://docs.gtk.org/glib/method.Regex.replace.html where it simply
   reads "\g" instead of "\g<number>" and "\g<name>".

Fix those.
---
 gio/gdbusintrospection.c |  2 +-
 gio/gproxyresolver.c     |  2 +-
 gio/gsocket.c            |  4 ++--
 glib/gdatetime.c         | 10 +++++-----
 glib/gregex.c            | 28 ++++++++++++++--------------
 5 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/gio/gdbusintrospection.c b/gio/gdbusintrospection.c
index 7ee3e32b6..7dcd68f20 100644
--- a/gio/gdbusintrospection.c
+++ b/gio/gdbusintrospection.c
@@ -1747,7 +1747,7 @@ parser_error (GMarkupParseContext *context,
  * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
  *
  * The introspection XML must contain exactly one top-level
- * <node> element.
+ * `<node>` element.
  *
  * Note that this routine is using a
  * [GMarkup][glib-Simple-XML-Subset-Parser.description]-based
diff --git a/gio/gproxyresolver.c b/gio/gproxyresolver.c
index 27908bb31..d59859a9c 100644
--- a/gio/gproxyresolver.c
+++ b/gio/gproxyresolver.c
@@ -133,7 +133,7 @@ g_proxy_resolver_is_supported (GProxyResolver *resolver)
  * Looks into the system proxy configuration to determine what proxy,
  * if any, to use to connect to @uri. The returned proxy URIs are of
  * the form `<protocol>://[user[:password]@]host[:port]` or
- * `direct://`, where <protocol> could be http, rtsp, socks
+ * `direct://`, where `<protocol>` could be http, rtsp, socks
  * or other proxying protocol.
  *
  * If you don't know what network protocol is being used on the
diff --git a/gio/gsocket.c b/gio/gsocket.c
index c2ddadeaf..f8cdd4ca7 100644
--- a/gio/gsocket.c
+++ b/gio/gsocket.c
@@ -6427,7 +6427,7 @@ g_socket_get_credentials (GSocket   *socket,
  * getsockopt(). (If you need to fetch a  non-integer-valued option,
  * you will need to call getsockopt() directly.)
  *
- * The [<gio/gnetworking.h>][gio-gnetworking.h]
+ * The [`<gio/gnetworking.h>`][gio-gnetworking.h]
  * header pulls in system headers that will define most of the
  * standard/portable socket options. For unusual socket protocols or
  * platform-dependent options, you may need to include additional
@@ -6499,7 +6499,7 @@ g_socket_get_option (GSocket  *socket,
  * setsockopt(). (If you need to set a non-integer-valued option,
  * you will need to call setsockopt() directly.)
  *
- * The [<gio/gnetworking.h>][gio-gnetworking.h]
+ * The [`<gio/gnetworking.h>`][gio-gnetworking.h]
  * header pulls in system headers that will define most of the
  * standard/portable socket options. For unusual socket protocols or
  * platform-dependent options, you may need to include additional
diff --git a/glib/gdatetime.c b/glib/gdatetime.c
index 8cc501c9a..ad9c190b6 100644
--- a/glib/gdatetime.c
+++ b/glib/gdatetime.c
@@ -1495,7 +1495,7 @@ parse_iso8601_time (const gchar *text, gsize length,
  *
  * Creates a #GDateTime corresponding to the given
  * [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601)
- * @text. ISO 8601 strings of the form <date><sep><time><tz> are supported, with
+ * @text. ISO 8601 strings of the form `<date><sep><time><tz>` are supported, with
  * some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as
  * mentioned below.
  *
@@ -1503,11 +1503,11 @@ parse_iso8601_time (const gchar *text, gsize length,
  * in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as
  * `23:59:59`.
  *
- * <sep> is the separator and can be either 'T', 't' or ' '. The latter two
+ * `<sep>` is the separator and can be either 'T', 't' or ' '. The latter two
  * separators are an extension from
  * [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6).
  *
- * <date> is in the form:
+ * `<date>` is in the form:
  *
  * - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24.
  * - `YYYYMMDD` - Same as above without dividers.
@@ -1517,12 +1517,12 @@ parse_iso8601_time (const gchar *text, gsize length,
  *   e.g. 2016-W34-3.
  * - `YYYYWwwD` - Same as above without dividers.
  *
- * <time> is in the form:
+ * `<time>` is in the form:
  *
  * - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
  * - `hhmmss(.sss)` - Same as above without dividers.
  *
- * <tz> is an optional timezone suffix of the form:
+ * `<tz>` is an optional timezone suffix of the form:
  *
  * - `Z` - UTC.
  * - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00.
diff --git a/glib/gregex.c b/glib/gregex.c
index d1633a8b2..dca294d7c 100644
--- a/glib/gregex.c
+++ b/glib/gregex.c
@@ -1540,7 +1540,7 @@ get_matched_substring_number (const GMatchInfo *match_info,
  * Retrieves the text matching the capturing parentheses named @name.
  *
  * If @name is a valid sub pattern name but it didn't match anything
- * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
+ * (e.g. sub pattern `"X"`, matching `"b"` against `"(?P<X>a)?b"`)
  * then an empty string is returned.
  *
  * The string is fetched from the string passed to the match function,
@@ -1579,7 +1579,7 @@ g_match_info_fetch_named (const GMatchInfo *match_info,
  * Retrieves the position in bytes of the capturing parentheses named @name.
  *
  * If @name is a valid sub pattern name but it didn't match anything
- * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
+ * (e.g. sub pattern `"X"`, matching `"b"` against `"(?P<X>a)?b"`)
  * then @start_pos and @end_pos are set to -1 and %TRUE is returned.
  *
  * Returns: %TRUE if the position was fetched, %FALSE otherwise.
@@ -2351,15 +2351,15 @@ g_regex_match_all (const GRegex      *regex,
  * Using the standard algorithm for regular expression matching only
  * the longest match in the @string is retrieved, it is not possible
  * to obtain all the available matches. For instance matching
- * "<a> <b> <c>" against the pattern "<.*>"
- * you get "<a> <b> <c>".
+ * `"<a> <b> <c>"` against the pattern `"<.*>"`
+ * you get `"<a> <b> <c>"`.
  *
  * This function uses a different algorithm (called DFA, i.e. deterministic
  * finite automaton), so it can retrieve all the possible matches, all
  * starting at the same point in the string. For instance matching
- * "<a> <b> <c>" against the pattern "<.*>;"
- * you would obtain three matches: "<a> <b> <c>",
- * "<a> <b>" and "<a>".
+ * `"<a> <b> <c>"` against the pattern `"<.*>;"`
+ * you would obtain three matches: `"<a> <b> <c>"`,
+ * `"<a> <b>"` and `"<a>"`.
  *
  * The number of matched strings is retrieved using
  * g_match_info_get_match_count(). To obtain the matched strings and
@@ -3265,13 +3265,13 @@ interpolation_list_needs_match (GList *list)
  * @error: location to store the error occurring, or %NULL to ignore errors
  *
  * Replaces all occurrences of the pattern in @regex with the
- * replacement text. Backreferences of the form '\number' or
- * '\g<number>' in the replacement text are interpolated by the
- * number-th captured subexpression of the match, '\g<name>' refers
- * to the captured subexpression with the given name. '\0' refers
- * to the complete match, but '\0' followed by a number is the octal
- * representation of a character. To include a literal '\' in the
- * replacement, write '\\\\'.
+ * replacement text. Backreferences of the form `\number` or
+ * `\g<number>` in the replacement text are interpolated by the
+ * number-th captured subexpression of the match, `\g<name>` refers
+ * to the captured subexpression with the given name. `\0` refers
+ * to the complete match, but `\0` followed by a number is the octal
+ * representation of a character. To include a literal `\` in the
+ * replacement, write `\\\\`.
  *
  * There are also escapes that changes the case of the following text:
  *