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.
This commit is contained in:
Luke T. Shumaker 2024-08-12 17:36:59 -06:00
parent d0b59da656
commit e4a2aa8f39
5 changed files with 23 additions and 23 deletions

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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:
*