minor markup cleanups

diff --git a/docs/reference/gobject/tmpl/signals.sgml b/docs/reference/gobject/tmpl/signals.sgml
index 5512300..558b973 100644 (file)
--- a/docs/reference/gobject/tmpl/signals.sgml
+++ b/docs/reference/gobject/tmpl/signals.sgml
@@ -7,7 +7,8 @@ as general purpose notification mechanism.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The basic concept of the signal system is that of the @emission of a signal.
+The basic concept of the signal system is that of the <emphasis>emission</emphasis>
+of a signal.
 Signals are introduced per-type and are identified through strings.
 Signals introduced for a parent type are availale in derived types as well,
 so basically they are a per-type facility that is inherited.
@@ -15,7 +16,7 @@ A signal emission mainly involves invocation of a certain set of callbacks in
 precisely defined manner. There are two main categories of such callbacks,
 per-object
        <footnote><para> Although signals can deal with any kind of type, i'm
-       referring to those types as "@object @types" in the following, simply
+       referring to those types as "object types" in the following, simply
        because that is the context most users will encounter signals in.
        </para></footnote>
 ones and user provided ones.
@@ -31,19 +32,19 @@ signal on certain object instances.
 A signal emission consists of five stages, unless prematurely stopped:
 <variablelist>
   <varlistentry><term></term><listitem><para>
-       1 - Invocation of the object method handler for @G_SIGNAL_RUN_FIRST signals
+       1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
   </para></listitem></varlistentry>
   <varlistentry><term></term><listitem><para>
-       2 - Invocation of normal user-provided signal handlers (@after flag @FALSE)
+       2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE)
   </para></listitem></varlistentry>
   <varlistentry><term></term><listitem><para>
-       3 - Invocation of the object method handler for @G_SIGNAL_RUN_LAST signals
+       3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
   </para></listitem></varlistentry>
   <varlistentry><term></term><listitem><para>
-       4 - Invocation of user provided signal handlers, connected with an @after flag of @TRUE
+       4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE
   </para></listitem></varlistentry>
   <varlistentry><term></term><listitem><para>
-       5 - Invocation of the object method handler for @G_SIGNAL_RUN_CLEANUP signals
+       5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
   </para></listitem></varlistentry>
 </variablelist>
 The user provided signal handlers are called in the order they were
@@ -53,11 +54,11 @@ handlers may be connected, disconnected, blocked or unblocked during
 a signal emission.
 There are certain criteria for skipping user handlers in stages 2 and 4
 of a signal emission.
-First, user handlers may be @blocked, blocked handlers are omitted
+First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted
 during callback invocation, to return from the "blocked" state, a
 handler has to get unblocked exactly the same amount of times
 it has been blocked before.
-Second, upon emission of a @G_SIGNAL_DETAILED signal, an additional
+Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional
 "detail" argument passed in to g_signal_emit() has to match the detail
 argument of the signal handler currently subject to invocation.
 Specification of no detail argument for signal handlers (omission of the
@@ -72,15 +73,15 @@ wildcard and matches any detail argument passed in to emission.
 
 <!-- ##### STRUCT GSignalInvocationHint ##### -->
 <para>
-The @GSignalInvocationHint structure is used to pass on additional information
+The #GSignalInvocationHint structure is used to pass on additional information
 to callbacks during a signal emission.
 </para>
 
 @signal_id:    The signal id of the signal invoking the callback
 @detail:       The detail passed on for this emission
 @run_type:     The stage the signal emission is currently in, this
-               field will contain one of @G_SIGNAL_RUN_FIRST,
-               @G_SIGNAL_RUN_LAST or @G_SIGNAL_RUN_CLEANUP.
+               field will contain one of %G_SIGNAL_RUN_FIRST,
+               %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP.
 
 <!-- ##### USER_FUNCTION GSignalAccumulator ##### -->
 <para>
@@ -92,20 +93,20 @@ values is perfomed. The return value of signal emissions is then the
 value returned by the last callback.
 </para>
 
-@ihint:        Signal invokation hint, see @GSignalInvocationHint
+@ihint:        Signal invokation hint, see #GSignalInvocationHint.
 @return_accu:  Accumulator to collect callback return values in, this
-               is the return value of the current signal emission
-@return_value:         The return value of the most recent callback function
+               is the return value of the current signal emission.
+@return_value:         The return value of the most recent callback function.
 @Returns:      The accumulator function returns whether the signal emission
-               should be aborted. Returning @FALSE means to abort the
-               current emission and @TRUE is returned for continuation.
+               should be aborted. Returning %FALSE means to abort the
+               current emission and %TRUE is returned for continuation.
 
 
 <!-- ##### TYPEDEF GSignalCMarshaller ##### -->
 <para>
 This is the signature of marshaller functions, required to marshall
 arrays of parameter values to signal emissions into C language callback
-invocations. It is merely an alias to @GClosureMarshal since the @GClosure
+invocations. It is merely an alias to #GClosureMarshal since the #GClosure
 mechanism takes over responsibility of actuall function invocation for the
 signal system.
 </para>
@@ -167,18 +168,18 @@ filled in by the g_signal_query() function.
 </para>
 
 @signal_id:    The signal id of the signal being querried, or 0 if the
-               signal to be querried was unknown
-@signal_name:  The signal name
-@itype:        The interface/instance type that this signal can be emitted for
-@signal_flags:         The signal flags as passed in to @g_signal_new()
-@return_type:  The return type for user callbacks
-@n_params:     The number of parameters that user callbacks take
+               signal to be querried was unknown.
+@signal_name:  The signal name.
+@itype:        The interface/instance type that this signal can be emitted for.
+@signal_flags:         The signal flags as passed in to g_signal_new().
+@return_type:  The return type for user callbacks.
+@n_params:     The number of parameters that user callbacks take.
 @param_types:  The individual parameter types for user callbacks, note that the
                effective callback signature is:
 <msgtext><programlisting>
-@return_type callback (@gpointer     data1,
-                      [@param_types param_names,]
-                      @gpointer     data2);
+@return_type callback (#gpointer     data1,
+                      [#param_types param_names,]
+                       #gpointer     data2);
 </programlisting></msgtext>
 
 <!-- ##### FUNCTION g_signal_newc ##### -->
@@ -237,12 +238,12 @@ filled in by the g_signal_query() function.
 Query the signal system for in-depth information about a
 specific signal. This function will fill in a user-provided
 structure to hold signal-specific information. If an invalid
-dignal id is passed in, the @signal_id member of the @GSignalQuery
-is 0. All members filled into the @GSignalQuery structure should
+dignal id is passed in, the @signal_id member of the #GSignalQuery
+is 0. All members filled into the #GSignalQuery structure should
 be considered constant and have to be left untouched.
 </para>
 
-@signal_id:    The signal id of the signal to query information for
+@signal_id:    The signal id of the signal to query information for.
 @query:        A user provided structure that is filled in with constant
                values upon success.
 
@@ -273,9 +274,9 @@ created. Further information about the signals can be aquired through
 g_signal_query().
 </para>
 
-@itype:        Instance or interface type
-@n_ids:        Location to store the number of signal ids for @itype
-@Returns:      Newly allocated array of signal ids
+@itype:        Instance or interface type.
+@n_ids:        Location to store the number of signal ids for @itype.
+@Returns:      Newly allocated array of signal IDs.
 
 
 <!-- ##### FUNCTION g_signal_emit ##### -->
@@ -391,8 +392,8 @@ to be a valid signal handler id, connected to a signal of
 @instance.
 </para>
 
-@instance:     The instance to block the signal handler of
-@handler_id:   Handler id of the handler to be blocked
+@instance:     The instance to block the signal handler of.
+@handler_id:   Handler id of the handler to be blocked.
 
 
 <!-- ##### FUNCTION g_signal_handler_unblock ##### -->
@@ -413,8 +414,8 @@ to be a valid id of a signal handler that is connected to a
 signal of @instance and is currently blocked.
 </para>
 
-@instance:     The instance to unblock the signal handler of
-@handler_id:   Handler id of the handler to be unblocked
+@instance:     The instance to unblock the signal handler of.
+@handler_id:   Handler id of the handler to be unblocked.
 
 
 <!-- ##### FUNCTION g_signal_handler_disconnect ##### -->
@@ -428,8 +429,8 @@ to be a valid signal handler id, connected to a signal of
 @instance.
 </para>
 
-@instance:     The instance to remove the signal handler from
-@handler_id:   Handler id of the handler to be disconnected
+@instance:     The instance to remove the signal handler from.
+@handler_id:   Handler id of the handler to be disconnected.
 
 
 <!-- ##### FUNCTION g_signal_handler_find ##### -->
@@ -441,15 +442,15 @@ The match @mask has to be non-0 for successfull matches.
 If no handler was found, 0 is returned.
 </para>
 
-@instance:     The instance owning the signal handler to be found
+@instance:     The instance owning the signal handler to be found.
 @mask:                 Mask indicating which of @signal_id, @detail,
-               @closure, @func and/or @data the handler has to match
-@signal_id:    Signal the handler has to be connected to
-@detail:       Signal detail the handler has to be connected to
-@closure:      The closure the handler will invoke
-@func:                 The C closure callback of the handler (useless for non-C closures)
-@data:                 The closure data of the handler's closure
-@Returns:      A valid non-0 signal handler id for a successfull match
+               @closure, @func and/or @data the handler has to match.
+@signal_id:    Signal the handler has to be connected to.
+@detail:       Signal detail the handler has to be connected to.
+@closure:      The closure the handler will invoke.
+@func:                 The C closure callback of the handler (useless for non-C closures).
+@data:                 The closure data of the handler's closure.
+@Returns:      A valid non-0 signal handler id for a successfull match.
 
 
 <!-- ##### FUNCTION g_signal_handlers_block_matched ##### -->
@@ -463,15 +464,15 @@ If no handlers were found, 0 is returned, the number of blocked handlers
 otherwise.
 </para>
 
-@instance:     The instance to block handlers from
+@instance:     The instance to block handlers from.
 @mask:                 Mask indicating which of @signal_id, @detail,
-               @closure, @func and/or @data the handlers have to match
-@signal_id:    Signal the handlers have to be connected to
-@detail:       Signal detail the handlers have to be connected to
-@closure:      The closure the handlers will invoke
-@func:                 The C closure callback of the handlers (useless for non-C closures)
-@data:                 The closure data of the handlers' closures
-@Returns:      The amount of handlers that got blocked
+               @closure, @func and/or @data the handlers have to match.
+@signal_id:    Signal the handlers have to be connected to.
+@detail:       Signal detail the handlers have to be connected to.
+@closure:      The closure the handlers will invoke.
+@func:                 The C closure callback of the handlers (useless for non-C closures).
+@data:                 The closure data of the handlers' closures.
+@Returns:      The amount of handlers that got blocked.
 
 
 <!-- ##### FUNCTION g_signal_handlers_unblock_matched ##### -->
@@ -486,15 +487,15 @@ otherwise. The match criteria should not apply to any handlers that are
 not currently blocked.
 </para>
 
-@instance:     The instance to unblock handlers from
+@instance:     The instance to unblock handlers from.
 @mask:                 Mask indicating which of @signal_id, @detail,
-               @closure, @func and/or @data the handlers have to match
-@signal_id:    Signal the handlers have to be connected to
-@detail:       Signal detail the handlers have to be connected to
-@closure:      The closure the handlers will invoke
-@func:                 The C closure callback of the handlers (useless for non-C closures)
-@data:                 The closure data of the handlers' closures
-@Returns:      The amount of handlers that got unblocked
+               @closure, @func and/or @data the handlers have to match.
+@signal_id:    Signal the handlers have to be connected to.
+@detail:       Signal detail the handlers have to be connected to.
+@closure:      The closure the handlers will invoke.
+@func:                 The C closure callback of the handlers (useless for non-C closures).
+@data:                 The closure data of the handlers' closures.
+@Returns:      The amount of handlers that got unblocked.
 
 
 <!-- ##### FUNCTION g_signal_handlers_disconnect_matched ##### -->
@@ -508,15 +509,15 @@ If no handlers were found, 0 is returned, the number of disconnected handlers
 otherwise.
 </para>
 
-@instance:     The instance to remove handlers from
+@instance:     The instance to remove handlers from.
 @mask:                 Mask indicating which of @signal_id, @detail,
-               @closure, @func and/or @data the handlers have to match
-@signal_id:    Signal the handlers have to be connected to
-@detail:       Signal detail the handlers have to be connected to
-@closure:      The closure the handlers will invoke
-@func:                 The C closure callback of the handlers (useless for non-C closures)
-@data:                 The closure data of the handlers' closures
-@Returns:      The amount of handlers that got disconnected
+               @closure, @func and/or @data the handlers have to match.
+@signal_id:    Signal the handlers have to be connected to.
+@detail:       Signal detail the handlers have to be connected to.
+@closure:      The closure the handlers will invoke.
+@func:                 The C closure callback of the handlers (useless for non-C closures).
+@data:                 The closure data of the handlers' closures.
+@Returns:      The amount of handlers that got disconnected.
 
 
 <!-- ##### FUNCTION g_signal_has_handler_pending ##### -->
@@ -566,11 +567,11 @@ Internal function to parse a signal names into its @signal_id
 and @detail quark.
 </para>
 
-@detailed_signal:      A string of the form "signal-name::detail"
-@itype:                The interface/instance type taht introduced "signal-name"
-@signal_id_p:          Location to store the signal id
-@detail_p:             Location to stroe the detail quark
-@force_detail_quark:   %TRUE forces creation of a GQuark for the detail
+@detailed_signal:      A string of the form "signal-name::detail".
+@itype:                The interface/instance type that introduced "signal-name".
+@signal_id_p:          Location to store the signal id.
+@detail_p:             Location to stroe the detail quark.
+@force_detail_quark:   %TRUE forces creation of a GQuark for the detail.
 @Returns:              Whether the signal name could successfully be parsed and
                        @signal_id_p and @detail_p contain valid return values.