Docs: Drop entities, switch away from sgml mode

Since all element markup is now gone from the doc comments,
we can turn off the gtk-doc sgml mode, which means that from
now on, docbook markup is no longer allowed in doc comments.

To make this possible, we have to replace all remaining
entities in doc comments by their replacement text, & -> &
and so on.

docs/reference/gio/Makefile.am

@@ -99,7 +99,7 @@ GTKDOC_LIBS = \
 	$(NULL)
 
 # Extra options to supply to gtkdoc-mkdb
-MKDB_OPTIONS = --output-format=xml --sgml-mode --name-space=g \
+MKDB_OPTIONS = --output-format=xml --name-space=g \
 	--ignore-files='libasyncns tests'
 
 # Images to copy into HTML directory

docs/reference/glib/Makefile.am

@@ -15,7 +15,7 @@ DOC_SOURCE_DIR=$(top_srcdir)/glib $(top_srcdir)/gmodule
 SCAN_OPTIONS=--deprecated-guards="G_DISABLE_DEPRECATED" --ignore-decorators="GLIB_VAR|G_GNUC_WARN_UNUSED_RESULT"
 
 # Extra options to supply to gtkdoc-mkdb
-MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=g
+MKDB_OPTIONS=--output-format=xml --name-space=g
 
 # Used for dependencies
 HFILE_GLOB=$(top_srcdir)/glib/*.h $(top_srcdir)/gmodule/*.h

docs/reference/gobject/Makefile.am

@@ -16,7 +16,7 @@ SCAN_OPTIONS=--deprecated-guards="G_DISABLE_DEPRECATED" \
              --ignore-decorators="G_GNUC_INTERNAL|G_GNUC_WARN_UNUSED_RESULT"
 
 # Extra options to supply to gtkdoc-mkdb
-MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=g
+MKDB_OPTIONS=--output-format=xml --name-space=g
 
 # Used for dependencies
 HFILE_GLOB=$(top_srcdir)/gobject/*.h

gio/gappinfo.c

@@ -41,7 +41,7 @@
  * (using g_file_get_path()) when using g_app_info_launch() even if
  * the application requested an URI and not a POSIX path. For example
  * for an desktop-file based application with Exec key `totem
- * %U` and a single URI, `sftp://foo/file.avi`, then
+ * \%U` and a single URI, `sftp://foo/file.avi`, then
  * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
  * only work if a set of suitable GIO extensions (such as gvfs 2.26
  * compiled with FUSE support), is available and operational; if this

gio/gdbusaddress.c

@@ -60,7 +60,7 @@
  *
  * Routines for working with D-Bus addresses. A D-Bus address is a string
  * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
- * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+ * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html\#addresses).
  */
 
 static gchar *get_session_address_platform_specific (GError **error);

gio/gdbusintrospection.c

@@ -1757,7 +1757,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

gio/gdesktopappinfo.c

@@ -58,7 +58,7 @@
  * #GDesktopAppInfo is an implementation of #GAppInfo based on
  * desktop files.
  *
- * Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
+ * Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
  * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
  * file when using it.
  */

gio/gfileattribute.c

@@ -321,7 +321,7 @@ escape_byte_string (const char *str)
  * Converts a #GFileAttributeValue to a string for display.
  * The returned string should be freed when no longer needed.
  *
- * Returns: a string from the @attr, %NULL on error, or "<invalid>"
+ * Returns: a string from the @attr, %NULL on error, or "<invalid>"
  * if @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID.
  */
 char *

gio/gfiledescriptorbased.c

@@ -32,7 +32,7 @@
  * #GFileDescriptorBased is implemented by streams (implementations of
  * #GInputStream or #GOutputStream) that are based on file descriptors.
  *
- * Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific
+ * Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific
  * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
  * file when using it.
  *

gio/gicon.c

@@ -197,7 +197,7 @@ g_icon_to_string_tokenized (GIcon *icon, GString *s)
  *   (such as `/path/to/my icon.png`) without escaping
  *   if the #GFile for @icon is a native file.  If the file is not
  *   native, the returned string is the result of g_file_get_uri()
- *   (such as `sftp://path/to/my%20icon.png`).
+ *   (such as `sftp://path/to/my\%20icon.png`).
  * 
  * - If @icon is a #GThemedIcon with exactly one name, the encoding is
  *    simply the name (such as `network-server`).

gio/gmenumodel.c

@@ -571,7 +571,7 @@ g_menu_model_get_item_attribute_value (GMenuModel         *model,
  * g_variant_get(), followed by a g_variant_unref().  As such,
  * @format_string must make a complete copy of the data (since the
  * #GVariant may go away after the call to g_variant_unref()).  In
- * particular, no '&' characters are allowed in @format_string.
+ * particular, no '&' characters are allowed in @format_string.
  *
  * Returns: %TRUE if the named attribute was found with the expected
  *     type

gio/gnetworking.c

@@ -28,7 +28,7 @@
  * @short_description: System networking includes
  * @include: gio/gnetworking.h
  *
- * The `<gio/gnetworking.h>` header can be included to get
+ * The `<gio/gnetworking.h>` header can be included to get
  * various low-level networking-related system headers, automatically
  * taking care of certain portability issues for you.
  *

gio/gproxyresolver.c

@@ -98,8 +98,8 @@ 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
+ * the form `<protocol>://[user[:password]@]host:port` or
+ * `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

gio/gsettings.c

@@ -86,9 +86,9 @@
  * Similar to GConf, the default values in GSettings schemas can be
  * localized, but the localized values are stored in gettext catalogs
  * and looked up with the domain that is specified in the
- * gettext-domain attribute of the <schemalist> or <schema>
+ * gettext-domain attribute of the <schemalist> or <schema>
  * elements and the category that is specified in the l10n attribute of
- * the &lt;key&gt; element.
+ * the <key> element.
  *
  * GSettings uses schemas in a compact binary form that is created
  * by the [glib-compile-schemas][glib-compile-schemas]
@@ -101,7 +101,7 @@
  * files to have the extension `.gschema.xml`.
  *
  * At runtime, schemas are identified by their id (as specified in the
- * id attribute of the &lt;schema&gt; element). The convention for schema
+ * id attribute of the <schema> element). The convention for schema
  * ids is to use a dotted name, similar in style to a D-Bus bus name,
  * e.g. "org.gnome.SessionManager". In particular, if the settings are
  * for a specific service that owns a D-Bus bus name, the D-Bus bus name
@@ -110,8 +110,8 @@
  * StudlyCaps, e.g. "org.gnome.font-rendering".
  *
  * In addition to #GVariant types, keys can have types that have
- * enumerated types. These can be described by a &lt;choice&gt;,
- * &lt;enum&gt; or &lt;flags&gt; element, as seen in the
+ * enumerated types. These can be described by a <choice>,
+ * <enum> or <flags> element, as seen in the
  * [example][schema-enumerated]. The underlying type of such a key
  * is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
  * g_settings_get_flags(), g_settings_set_flags() access the numeric values
@@ -2178,7 +2178,7 @@ g_settings_is_writable (GSettings   *settings,
  * @settings.
  *
  * The schema for the child settings object must have been declared
- * in the schema of @settings using a &lt;child&gt; element.
+ * in the schema of @settings using a <child> element.
  *
  * Returns: (transfer full): a 'child' settings object
  *

gio/gsocket.c

@@ -68,7 +68,7 @@
  * SECTION:gsocket
  * @short_description: Low-level socket object
  * @include: gio/gio.h
- * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h]
+ * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h]
  *
  * A #GSocket is a low-level networking primitive. It is a more or less
  * direct mapping of the BSD socket API in a portable GObject based API.
@@ -4516,7 +4516,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 [&lt;gio/gnetworking.h&gt;][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
@@ -4583,7 +4583,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 [&lt;gio/gnetworking.h&gt;][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

gio/gunixconnection.c

@@ -39,7 +39,7 @@
  * It contains functions to do some of the UNIX socket specific
  * functionality like passing file descriptors.
  *
- * Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific
+ * Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific
  * GIO interfaces, thus you have to use the `gio-unix-2.0.pc`
  * pkg-config file when using it.
  *

gio/gunixfdlist.c

@@ -26,7 +26,7 @@
  * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
  * and received using g_socket_receive_message().
  *
- * Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO
+ * Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO
  * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
  * file when using it.
  */

gio/gunixfdmessage.c

@@ -29,7 +29,7 @@
  * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
  * g_unix_connection_receive_fd().
  *
- * Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO
+ * Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO
  * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
  * file when using it.
  */

gio/gunixinputstream.c

@@ -51,7 +51,7 @@
  * asynchronous I/O. If it refers to a regular file, it will fall back
  * to doing asynchronous I/O in another thread.)
  *
- * Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO
+ * Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO
  * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
  * file when using it.
  */

gio/gunixmounts.c

@@ -79,7 +79,7 @@ static const char *_resolve_dev_root (void);
  *
  * Routines for managing mounted UNIX mount points and paths.
  *
- * Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
+ * Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
  * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
  * file when using it.
  */

gio/gunixoutputstream.c

@@ -51,7 +51,7 @@
  * asynchronous I/O. If it refers to a regular file, it will fall back
  * to doing asynchronous I/O in another thread.)
  *
- * Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO
+ * Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO
  * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
  * when using it.
  */

gio/gunixsocketaddress.c

@@ -44,7 +44,7 @@
  * errors. You can use g_unix_socket_address_abstract_names_supported()
  * to see if abstract names are supported.
  *
- * Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO
+ * Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO
  * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
  * when using it.
  */

gio/gwin32inputstream.c

@@ -44,7 +44,7 @@
  * #GWin32InputStream implements #GInputStream for reading from a
  * Windows file handle.
  *
- * Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO
+ * Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO
  * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
  * when using it.
  */

gio/gwin32outputstream.c

@@ -45,7 +45,7 @@
  * #GWin32OutputStream implements #GOutputStream for writing to a
  * Windows file handle.
  *
- * Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO
+ * Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO
  * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
  * when using it.
  */

glib/docs.c

@@ -1526,14 +1526,14 @@
  * G_OS_WIN32:
  *
  * This macro is defined only on Windows. So you can bracket
- * Windows-specific code in "#ifdef G_OS_WIN32".
+ * Windows-specific code in "\#ifdef G_OS_WIN32".
  */
 
 /**
  * G_OS_UNIX:
  *
  * This macro is defined only on UNIX. So you can bracket
- * UNIX-specific code in "#ifdef G_OS_UNIX".
+ * UNIX-specific code in "\#ifdef G_OS_UNIX".
  */
 
 /**

glib/gbookmarkfile.c

@@ -66,11 +66,11 @@
  * Desktop Bookmark Specification, here is a quick summary: bookmark
  * files use a sub-class of the XML Bookmark Exchange Language
  * specification, consisting of valid UTF-8 encoded XML, under the
- * <xbel> root element; each bookmark is stored inside a
- * <bookmark> element, using its URI: no relative paths can
+ * <xbel> root element; each bookmark is stored inside a
+ * <bookmark> element, using its URI: no relative paths can
  * be used inside a bookmark file. The bookmark may have a user defined
  * title and description, to be used instead of the URI. Under the
- * &lt;metadata&gt; element, with its owner attribute set to
+ * <metadata> element, with its owner attribute set to
  * `http://freedesktop.org`, is stored the meta-data about a resource
  * pointed by its URI. The meta-data consists of the resource's MIME
  * type; the applications that have registered a bookmark; the groups

glib/gerror.c

@@ -243,7 +243,7 @@
  *
  * Error domains and codes are conventionally named as follows:
  *
- * - The error domain is called <NAMESPACE>_<MODULE>_ERROR,
+ * - The error domain is called <NAMESPACE>_<MODULE>_ERROR,
  *   for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
  *   |[<!-- language="C" -->
  *   #define G_SPAWN_ERROR g_spawn_error_quark ()
@@ -256,20 +256,20 @@
  *   ]|
  *
  * - The quark function for the error domain is called
- *   &lt;namespace&gt;_&lt;module&gt;_error_quark,
+ *   <namespace>_<module>_error_quark,
  *   for example g_spawn_error_quark() or g_thread_error_quark().
  *
  * - The error codes are in an enumeration called
- *   &lt;Namespace&gt;&lt;Module&gt;Error;
- *   for example,#GThreadError or #GSpawnError.
+ *   <Namespace><Module>Error;
+ *   for example, #GThreadError or #GSpawnError.
  *
  * - Members of the error code enumeration are called
- *   &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_&lt;CODE&gt;,
+ *   <NAMESPACE>_<MODULE>_ERROR_<CODE>,
  *   for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
  *
  * - If there's a "generic" or "unknown" error code for unrecoverable
  *   errors it doesn't make sense to distinguish with specific codes,
- *   it should be called &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED,
+ *   it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED,
  *   for example %G_SPAWN_ERROR_FAILED.
  *
  * Summary of rules for use of #GError:

glib/ggettext.c

@@ -473,8 +473,8 @@ g_dngettext (const gchar *domain,
  * easy-to-use form.
  *
  * In order to use these macros in an application, you must include
- * `<glib/gi18n.h>`. For use in a library, you must include
- * `<glib/gi18n-lib.h>`
+ * `<glib/gi18n.h>`. For use in a library, you must include
+ * `<glib/gi18n-lib.h>`
  * after defining the %GETTEXT_PACKAGE macro suitably for your library:
  * |[<!-- language="C" -->
  * #define GETTEXT_PACKAGE "gtk20"

glib/ghook.c

@@ -91,7 +91,7 @@
  *
  * The position of the first bit which is not reserved for internal
  * use be the #GHook implementation, i.e.
- * `1 << G_HOOK_FLAG_USER_SHIFT` is the first
+ * `1 << G_HOOK_FLAG_USER_SHIFT` is the first
  * bit which can be used for application-defined flags.
  */
 
@@ -973,7 +973,7 @@ g_hook_find_func_data (GHookList *hook_list,
  * Defines the type of function used to compare #GHook elements in
  * g_hook_insert_sorted().
  *
- * Returns: a value &lt;= 0 if @new_hook should be before @sibling
+ * Returns: a value <= 0 if @new_hook should be before @sibling
  */
 
 /**
@@ -1035,7 +1035,7 @@ g_hook_insert_sorted (GHookList	      *hook_list,
  * Compares the ids of two #GHook elements, returning a negative value
  * if the second id is greater than the first.
  *
- * Returns: a value &lt;= 0 if the id of @sibling is >= the id of @new_hook
+ * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook
  */
 gint
 g_hook_compare_ids (GHook *new_hook,

glib/glist.c

@@ -1195,7 +1195,7 @@ g_list_sort_real (GList    *list,
  * value comes before the second, 0 if they are equal, or a positive
  * integer if the first value comes after the second.
  *
- * Returns: negative value if @a < @b; zero if @a = @b; positive
+ * Returns: negative value if @a < @b; zero if @a = @b; positive
  *          value if @a > @b
  */
 GList *
@@ -1227,7 +1227,7 @@ g_list_sort (GList        *list,
  * value comes before the second, 0 if they are equal, or a positive
  * integer if the first value comes after the second.
  *
- * Returns: negative value if @a &lt; @b; zero if @a = @b; positive
+ * Returns: negative value if @a < @b; zero if @a = @b; positive
  *          value if @a > @b
  */
 GList *

glib/gmarkup.c

@@ -77,7 +77,7 @@
  *
  * - Attributes
  *
- * - 5 standard entities: & < > " '
+ * - 5 standard entities: & < > " '
  *
  * - Character references
  *
@@ -631,7 +631,7 @@ unescape_gstring_inplace (GMarkupParseContext  *context,
     normalize_attribute = FALSE;
 
   /*
-   * Meeks' theorum: unescaping can only shrink text.
+   * Meeks' theorem: unescaping can only shrink text.
    * for < etc. this is obvious, for  more
    * thought is required, but this is patently so.
    */
@@ -2215,7 +2215,7 @@ append_escaped_text (GString     *str,
  * of line endings and attribute values.
  *
  * Note also that this function will produce character references in
- * the range of  ...  for all control sequences
+ * the range of  ...  for all control sequences
  * except for tabstop, newline and carriage return.  The character
  * references in this range are not valid XML 1.0, but they are
  * valid XML 1.1 and will be accepted by the GMarkup parser.
@@ -2417,9 +2417,9 @@ g_markup_vprintf_escaped (const gchar *format,
    * To find the span of the first argument, we find the first position
    * where the two arguments differ, which tells us that the first
    * argument formatted to "Susan & Fred". We then escape that
-   * to "Susan & Fred" and join up with the intermediate portions
+   * to "Susan & Fred" and join up with the intermediate portions
    * of the format string and the second argument to get
-   * "Susan & Fred ate 5 apples".
+   * "Susan & Fred ate 5 apples".
    */
 
   /* Create the two modified format strings

glib/grand.c

@@ -92,7 +92,7 @@
  *
  * The g_rand*_range functions will return high quality equally
  * distributed random numbers, whereas for example the
- * `(g_random_int()%max)` approach often
+ * `(g_random_int()\%max)` approach often
  * doesn't yield equally distributed numbers.
  *
  * GLib changed the seeding algorithm for the pseudo-random number

glib/gregex.c

@@ -1103,7 +1103,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,
@@ -1144,7 +1144,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&lt;X&gt;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.
@@ -1824,15 +1824,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
- * "&lt;a&gt; &lt;b&gt; &lt;c&gt;" against the pattern "&lt;.*&gt;"
- * you get "&lt;a&gt; &lt;b&gt; &lt;c&gt;".
+ * "<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
- * "&lt;a&gt; &lt;b&gt; &lt;c&gt;" against the pattern "&lt;.*&gt;"
- * you would obtain three matches: "&lt;a&gt; &lt;b&gt; &lt;c&gt;",
- * "&lt;a&gt; &lt;b&gt;" and "&lt;a&gt;".
+ * "<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
@@ -2694,11 +2694,12 @@ interpolation_list_needs_match (GList *list)
  *
  * Replaces all occurrences of the pattern in @regex with the
  * replacement text. Backreferences of the form '\number' or
- * '\g&lt;number&gt;' in the replacement text are interpolated by the
- * number-th captured subexpression of the match, '\g&lt;name&gt;' 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 '\\'.
+ * '\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:
  *

glib/gstrfuncs.c

@@ -67,21 +67,21 @@
  * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf()
  * are declared in the header `gprintf.h` which is not included in `glib.h`
  * (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to
- * explicitly include `<glib/gprintf.h>` in order to use the GLib
+ * explicitly include `<glib/gprintf.h>` in order to use the GLib
  * printf() functions.
  *
  * ## String precision pitfalls # {#string-precision}
  *
  * While you may use the printf() functions to format UTF-8 strings,
- * notice that the precision of a &percnt;Ns parameter is interpreted
+ * notice that the precision of a \%Ns parameter is interpreted
  * as the number of bytes, not characters to print. On top of that,
  * the GNU libc implementation of the printf() functions has the
- * "feature" that it checks that the string given for the &percnt;Ns
+ * "feature" that it checks that the string given for the \%Ns
  * parameter consists of a whole number of characters in the current
  * encoding. So, unless you are sure you are always going to be in an
  * UTF-8 locale or your know your text is restricted to ASCII, avoid
- * using &percnt;Ns. If your intention is to format strings for a
- * certain number of columns, then &percnt;Ns is not a correct solution
+ * using \%Ns. If your intention is to format strings for a
+ * certain number of columns, then \%Ns is not a correct solution
  * anyway, since it fails to take wide characters (see g_unichar_iswide())
  * into account.
  */
@@ -1234,7 +1234,7 @@ g_ascii_strtoll (const gchar *nptr,
  * not all platforms support the strerror() function.
  *
  * Returns: a UTF-8 string describing the error code. If the error code
- *     is unknown, it returns "unknown error (&lt;code&gt;)".
+ *     is unknown, it returns "unknown error (<code>)".
  */
 const gchar *
 g_strerror (gint errnum)
@@ -1264,7 +1264,7 @@ g_strerror (gint errnum)
  * the strsignal() function.
  *
  * Returns: a UTF-8 string describing the signal. If the signal is unknown,
- *     it returns "unknown signal (&lt;signum&gt;)".
+ *     it returns "unknown signal (<signum>)".
  */
 const gchar *
 g_strsignal (gint signum)
@@ -1734,8 +1734,8 @@ g_ascii_xdigit_value (gchar c)
  *
  * Both @s1 and @s2 must be non-%NULL.
  *
- * Return value: 0 if the strings match, a negative value if @s1 &lt; @s2,
- *     or a positive value if @s1 &gt; @s2.
+ * Return value: 0 if the strings match, a negative value if @s1 < @s2,
+ *     or a positive value if @s1 > @s2.
  */
 gint
 g_ascii_strcasecmp (const gchar *s1,
@@ -1775,8 +1775,8 @@ g_ascii_strcasecmp (const gchar *s1,
  * function only on strings known to be in encodings where bytes
  * corresponding to ASCII letters always represent themselves.
  *
- * Return value: 0 if the strings match, a negative value if @s1 &lt; @s2,
- *     or a positive value if @s1 &gt; @s2.
+ * Return value: 0 if the strings match, a negative value if @s1 < @s2,
+ *     or a positive value if @s1 > @s2.
  */
 gint
 g_ascii_strncasecmp (const gchar *s1,
@@ -1812,8 +1812,8 @@ g_ascii_strncasecmp (const gchar *s1,
  * A case-insensitive string comparison, corresponding to the standard
  * strcasecmp() function on platforms which support it.
  *
- * Return value: 0 if the strings match, a negative value if @s1 &lt; @s2,
- *     or a positive value if @s1 &gt; @s2.
+ * Return value: 0 if the strings match, a negative value if @s1 < @s2,
+ *     or a positive value if @s1 > @s2.
  *
  * Deprecated:2.2: See g_strncasecmp() for a discussion of why this
  *     function is deprecated and how to replace it.
@@ -1860,8 +1860,8 @@ g_strcasecmp (const gchar *s1,
  * to g_strcasecmp() except it only compares the first @n characters of
  * the strings.
  *
- * Return value: 0 if the strings match, a negative value if @s1 &lt; @s2,
- *     or a positive value if @s1 &gt; @s2.
+ * Return value: 0 if the strings match, a negative value if @s1 < @s2,
+ *     or a positive value if @s1 > @s2.
  *
  * Deprecated:2.2: The problem with g_strncasecmp() is that it does
  *     the comparison by calling toupper()/tolower(). These functions

glib/gtestutils.c

@@ -393,7 +393,7 @@
  * g_assert_cmpstr:
  * @s1: a string (may be %NULL)
  * @cmp: The comparison operator to use.
- *     One of ==, !=, <, >, <=, >=.
+ *     One of ==, !=, <, >, <=, >=.
  * @s2: another string (may be %NULL)
  *
  * Debugging macro to compare two strings. If the comparison fails,
@@ -417,7 +417,7 @@
  * g_assert_cmpint:
  * @n1: an integer
  * @cmp: The comparison operator to use.
- *     One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
+ *     One of ==, !=, <, >, <=, >=.
  * @n2: another integer
  *
  * Debugging macro to compare two integers.
@@ -434,7 +434,7 @@
  * g_assert_cmpuint:
  * @n1: an unsigned integer
  * @cmp: The comparison operator to use.
- *     One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
+ *     One of ==, !=, <, >, <=, >=.
  * @n2: another unsigned integer
  *
  * Debugging macro to compare two unsigned integers.
@@ -451,7 +451,7 @@
  * g_assert_cmphex:
  * @n1: an unsigned integer
  * @cmp: The comparison operator to use.
- *     One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
+ *     One of ==, !=, <, >, <=, >=.
  * @n2: another unsigned integer
  *
  * Debugging macro to compare to unsigned integers.
@@ -466,7 +466,7 @@
  * g_assert_cmpfloat:
  * @n1: an floating point number
  * @cmp: The comparison operator to use.
- *     One of ==, !=, &lt;, &gt;, &lt;=, &gt;=.
+ *     One of ==, !=, <, >, <=, >=.
  * @n2: another floating point number
  *
  * Debugging macro to compare two floating point numbers.
@@ -503,8 +503,8 @@
  * the correct #GError.
  *
  * The effect of `g_assert_error (err, dom, c)` is
- * the same as `g_assert_true (err != NULL &amp;&amp; err->domain
- * == dom &amp;&amp; err->code == c)`. The advantage of this
+ * the same as `g_assert_true (err != NULL && err->domain
+ * == dom && err->code == c)`. The advantage of this
  * macro is that it can produce a message that includes the incorrect
  * error message and code.
  *

glib/gunicollate.c

@@ -71,8 +71,8 @@ msc_strxfrm_wrapper (char       *string1,
  * compare the keys with strcmp() when sorting instead of sorting 
  * the original strings.
  * 
- * Return value: < 0 if @str1 compares before @str2, 
- *   0 if they compare equal, > 0 if @str1 compares after @str2.
+ * Return value: < 0 if @str1 compares before @str2, 
+ *   0 if they compare equal, > 0 if @str1 compares after @str2.
  **/
 gint
 g_utf8_collate (const gchar *str1,

glib/gvariant.c

@@ -2762,9 +2762,9 @@ g_variant_equal (gconstpointer one,
  * If you only require an equality comparison, g_variant_equal() is more
  * general.
  *
- * Returns: negative value if a < b;
+ * Returns: negative value if a < b;
  *          zero if a = b;
- *          positive value if a &gt; b.
+ *          positive value if a > b.
  *
  * Since: 2.26
  **/
@@ -3672,17 +3672,17 @@ g_variant_builder_end (GVariantBuilder *builder)
  *     GVariantDict dict;
  *     guint32 count;
  *
- *     g_variant_dict_init (&amp;dict, orig);
- *     if (!g_variant_dict_lookup (&amp;dict, "count", "u", &amp;count))
+ *     g_variant_dict_init (&dict, orig);
+ *     if (!g_variant_dict_lookup (&dict, "count", "u", &count))
  *       {
  *         g_set_error (...);
- *         g_variant_dict_clear (&amp;dict);
+ *         g_variant_dict_clear (&dict);
  *         return NULL;
  *       }
  *
- *     g_variant_dict_insert (&amp;dict, "count", "u", count + 1);
+ *     g_variant_dict_insert (&dict, "count", "u", count + 1);
  *
- *     return g_variant_dict_end (&amp;dict);
+ *     return g_variant_dict_end (&dict);
  *   }
  * ]|
  *
@@ -3699,7 +3699,7 @@ g_variant_builder_end (GVariantBuilder *builder)
  *
  *     dict = g_variant_dict_new (orig);
  *
- *     if (g_variant_dict_lookup (dict, "count", "u", &amp;count))
+ *     if (g_variant_dict_lookup (dict, "count", "u", &count))
  *       {
  *         g_variant_dict_insert (dict, "count", "u", count + 1);
  *         result = g_variant_dict_end (dict);

glib/gwin32.c

@@ -335,8 +335,8 @@ get_package_directory_from_module (const gchar *module_name)
  * the package, typically the same identifier as used for
  * `GETTEXT_PACKAGE` in software configured using GNU
  * autotools. The function first looks in the Windows Registry for the
- * value `#InstallationDirectory` in the key
- * `#HKLM\Software\@package`, and if that value
+ * value `#InstallationDirectory` in the key
+ * `#HKLM\Software\@package`, and if that value
  * exists and is a string, returns that.
  *
  * It is strongly recommended that packagers of GLib-using libraries

gobject/gvaluearray.c

@@ -257,7 +257,7 @@ g_value_array_append (GValueArray  *value_array,
 /**
  * g_value_array_insert:
  * @value_array: #GValueArray to add an element to
- * @index_: insertion position, must be <= value_array->n_values
+ * @index_: insertion position, must be <= value_array-&gt;n_values
  * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
  *
  * Insert a copy of @value at specified position into @value_array. If @value