Docs: use quotes instead of firstterm

gio/gapplication.c

@@ -55,12 +55,11 @@
  * this class outside of a higher level framework.
  *
  * GApplication provides convenient life cycle management by maintaining
- * a <firstterm>use count</firstterm> for the primary application instance.
+ * a "use count" for the primary application instance. The use count can
- * The use count can be changed using g_application_hold() and
+ * be changed using g_application_hold() and g_application_release(). If
- * g_application_release(). If it drops to zero, the application exits.
+ * it drops to zero, the application exits. Higher-level classes such as
- * Higher-level classes such as #GtkApplication employ the use count to
+ * #GtkApplication employ the use count to ensure that the application
- * ensure that the application stays alive as long as it has any opened
+ * stays alive as long as it has any opened windows.
- * windows.
  *
  * Another feature that GApplication (optionally) provides is process
  * uniqueness. Applications can make use of this functionality by
@@ -70,9 +69,9 @@
  * desktop login. When your application is launched again, its
  * arguments are passed through platform communication to the already
  * running program. The already running instance of the program is
- * called the <firstterm>primary instance</firstterm>; for non-unique
+ * called the "primary instance"; for non-unique applications this is
- * applications this is the always the current instance.
+ * the always the current instance. On Linux, the D-Bus session bus
- * On Linux, the D-Bus session bus is used for communication.
+ * is used for communication.
  *
  * The use of #GApplication differs from some other commonly-used
  * uniqueness libraries (such as libunique) in important ways. The
@@ -128,14 +127,14 @@
  * The #GApplication::startup signal lets you handle the application
  * initialization for all of these in a single place.
  *
- * Regardless of which of these entry points is used to start the application,
+ * Regardless of which of these entry points is used to start the
- * GApplication passes some <firstterm id="platform-data">platform
+ * application, GApplication passes some "platform data from the
- * data</firstterm> from the launching instance to the primary instance,
+ * launching instance to the primary instance, in the form of a
- * in the form of a #GVariant dictionary mapping strings to variants.
+ * #GVariant dictionary mapping strings to variants. To use platform
- * To use platform data, override the @before_emit or @after_emit virtual
+ * data, override the @before_emit or @after_emit virtual functions
- * functions in your #GApplication subclass. When dealing with
+ * in your #GApplication subclass. When dealing with
- * #GApplicationCommandLine objects, the platform data is directly
+ * #GApplicationCommandLine objects, the platform data is
- * available via g_application_command_line_get_cwd(),
+ * directly available via g_application_command_line_get_cwd(),
  * g_application_command_line_get_environ() and
  * g_application_command_line_get_platform_data().
  *

glib/gkeyfile.c

@@ -74,9 +74,8 @@
  * @short_description: parses .ini-like config files
  *
  * #GKeyFile lets you parse, edit or create files containing groups of
- * key-value pairs, which we call <firstterm>key files</firstterm> for
+ * key-value pairs, which we call "key files" for lack of a better name.
- * lack of a better name. Several freedesktop.org specifications use
+ * Several freedesktop.org specifications use key files now, e.g the
- * key files now, e.g the
  * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
  * and the
  * [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec).

glib/gmain.c

@@ -142,11 +142,11 @@
  * is that new types of event source can be created and used in
  * addition to the builtin type of event source. A new event source
  * type is used for handling GDK events. A new source type is created
- * by <firstterm>deriving</firstterm> from the #GSource structure.
+ * by "deriving" from the #GSource structure. The derived type of
- * The derived type of source is represented by a structure that has
+ * source is represented by a structure that has the #GSource structure
- * the #GSource structure as a first element, and other elements specific
+ * as a first element, and other elements specific to the new source
- * to the new source type. To create an instance of the new source type,
+ * type. To create an instance of the new source type, call
- * call g_source_new() passing in the size of the derived structure and
+ * g_source_new() passing in the size of the derived structure and
  * a table of functions. These #GSourceFuncs determine the behavior of
  * the new source type.
  *

glib/gsequence.c

@@ -36,12 +36,11 @@
  * linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
  * or simply pointers to any type of data.
  *
- * A #GSequence is accessed through <firstterm>iterators</firstterm>,
+ * A #GSequence is accessed through "iterators", represented by a
- * represented by a #GSequenceIter. An iterator represents a position
+ * #GSequenceIter. An iterator represents a position between two
- * between two elements of the sequence. For example, the
+ * elements of the sequence. For example, the "begin" iterator
- * <firstterm>begin</firstterm> iterator represents the gap immediately
+ * represents the gap immediately before the first element of the
- * before the first element of the sequence, and the
+ * sequence, and the "end" iterator represents the gap immediately
- * <firstterm>end</firstterm> iterator represents the gap immediately
  * after the last element. In an empty sequence, the begin and end
  * iterators are the same.
  *
@@ -54,7 +53,7 @@
  *
  * The function g_sequence_get() is used with an iterator to access the
  * element immediately following the gap that the iterator represents.
- * The iterator is said to <firstterm>point</firstterm> to that element.
+ * The iterator is said to "point" to that element.
  *
  * Iterators are stable across most operations on a #GSequence. For
  * example an iterator pointing to some element of a sequence will

glib/guniprop.c

@@ -1234,10 +1234,10 @@ g_utf8_casefold (const gchar *str,
  * @ch: a Unicode character
  * @mirrored_ch: location to store the mirrored character
  * 
- * In Unicode, some characters are <firstterm>mirrored</firstterm>. This
+ * In Unicode, some characters are "mirrored". This means that their
- * means that their images are mirrored horizontally in text that is laid
+ * images are mirrored horizontally in text that is laid out from right
- * out from right to left. For instance, "(" would become its mirror image,
+ * to left. For instance, "(" would become its mirror image, ")", in
- * ")", in right-to-left text.
+ * right-to-left text.
  *
  * If @ch has the Unicode mirrored property and there is another unicode
  * character that typically has a glyph that is the mirror image of @ch's

gobject/gclosure.c

@@ -601,13 +601,13 @@ g_closure_unref (GClosure *closure)
  *           still being held
  *
  * Takes over the initial ownership of a closure.  Each closure is
- * initially created in a <firstterm>floating</firstterm> state, which
+ * initially created in a "floating" state, which means that the initial
- * means that the initial reference count is not owned by any caller.
+ * reference count is not owned by any caller. g_closure_sink() checks
- * g_closure_sink() checks to see if the object is still floating, and
+ * to see if the object is still floating, and if so, unsets the
- * if so, unsets the floating state and decreases the reference
+ * floating state and decreases the reference count. If the closure
- * count. If the closure is not floating, g_closure_sink() does
+ * is not floating, g_closure_sink() does nothing. The reason for the
- * nothing. The reason for the existence of the floating state is to
+ * existence of the floating state is to prevent cumbersome code
- * prevent cumbersome code sequences like:
+ * sequences like:
  * |[<!-- language="C" --> 
  * closure = g_cclosure_new (cb_func, cb_data);
  * g_source_set_closure (source, closure);

gobject/gobject.c

@@ -49,10 +49,10 @@
  * <para id="floating-ref">
  * GInitiallyUnowned is derived from GObject. The only difference between
  * the two is that the initial reference of a GInitiallyUnowned is flagged
- * as a <firstterm>floating</firstterm> reference.
+ * as a "floating" reference. This means that it is not specifically
- * This means that it is not specifically claimed to be "owned" by
+ * claimed to be "owned" by any code portion. The main motivation for
- * any code portion. The main motivation for providing floating references is
+ * providing floating references is C convenience. In particular, it
- * C convenience. In particular, it allows code to be written as:
+ * allows code to be written as:
  * |[<!-- language="C" --> 
  * container = create_container ();
  * container_add_child (container, create_child());
@@ -809,11 +809,11 @@ g_object_interface_find_property (gpointer      g_iface,
  * @name: the name of a property registered in a parent class or
  *  in an interface of this class.
  *
- * Registers @property_id as referring to a property with the
+ * Registers @property_id as referring to a property with the name
- * name @name in a parent class or in an interface implemented
+ * @name in a parent class or in an interface implemented by @oclass.
- * by @oclass. This allows this class to <firstterm>override</firstterm>
+ * This allows this class to "override" a property implementation in
- * a property implementation in a parent class or to provide
+ * a parent class or to provide the implementation of a property from
- * the implementation of a property from an interface.
+ * an interface.
  *
  * Internally, overriding is implemented by creating a property of type
  * #GParamSpecOverride; generally operations that query the properties of
@@ -2858,8 +2858,8 @@ toggle_refs_notify (GObject *object,
  * to the proxy object, but when there are other references held to
  * @object, a strong reference is held. The @notify callback is called
  * when the reference from @object to the proxy object should be
- * <firstterm>toggled</firstterm> from strong to weak (@is_last_ref
+ * "toggled" from strong to weak (@is_last_ref true) or weak to strong
- * true) or weak to strong (@is_last_ref false).
+ * (@is_last_ref false).
  *
  * Since a (normal) reference must be held to the object before
  * calling g_object_add_toggle_ref(), the initial state of the reverse