Docs: Use markdown for lists

This greatly reduces the amount of xml in the docs.

16 files changed, 191 insertions, 312 deletions

diff --git a/gtk/gtkdrawingarea.c b/gtk/gtkdrawingarea.c
index 07c1053b8b..50ff45abe5 100644
--- a/gtk/gtkdrawingarea.c
+++ b/gtk/gtkdrawingarea.c
@@ -38,34 +38,19 @@
  * elements. It's essentially a blank widget; you can draw on it. After
  * creating a drawing area, the application may want to connect to:
  *
- * <itemizedlist>
- *   <listitem>
- *     <para>
- *     Mouse and button press signals to respond to input from
- *     the user. (Use gtk_widget_add_events() to enable events
- *     you wish to receive.)
- *     </para>
- *   </listitem>
- *   <listitem>
- *     <para>
- *     The #GtkWidget::realize signal to take any necessary actions
- *     when the widget is instantiated on a particular display.
- *     (Create GDK resources in response to this signal.)
- *     </para>
- *   </listitem>
- *   <listitem>
- *     <para>
- *     The #GtkWidget::configure-event signal to take any necessary
- *     actions when the widget changes size.
- *     </para>
- *   </listitem>
- *   <listitem>
- *     <para>
- *     The #GtkWidget::draw signal to handle redrawing the
- *     contents of the widget.
- *     </para>
- *   </listitem>
- * </itemizedlist>
+ * - Mouse and button press signals to respond to input from
+ *   the user. (Use gtk_widget_add_events() to enable events
+ *   you wish to receive.)
+ *
+ * - The #GtkWidget::realize signal to take any necessary actions
+ *   when the widget is instantiated on a particular display.
+ *   (Create GDK resources in response to this signal.)
+ * 
+ * - The #GtkWidget::configure-event signal to take any necessary
+ *   actions when the widget changes size.
+ *
+ * - The #GtkWidget::draw signal to handle redrawing the
+ *   contents of the widget.
  *
  * The following code portion demonstrates using a drawing
  * area to display a circle in the normal widget foreground
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index 01ca5c3e1d..8c050aa1f7 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -1599,11 +1599,9 @@ gtk_entry_class_init (GtkEntryClass *class)
    * the variant with the Shift modifier extends the selection,
    * the variant without the Shift modifer does not.
    * There are too many key combinations to list them all here.
-   * <itemizedlist>
-   * <listitem>Arrow keys move by individual characters/lines</listitem>
-   * <listitem>Ctrl-arrow key combinations move by words/paragraphs</listitem>
-   * <listitem>Home/End keys move to the ends of the buffer</listitem>
-   * </itemizedlist>
+   * - Arrow keys move by individual characters/lines
+   * - Ctrl-arrow key combinations move by words/paragraphs
+   * - Home/End keys move to the ends of the buffer
    */
   signals[MOVE_CURSOR] = 
     g_signal_new (I_("move-cursor"),
diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c
index 1ae2574ceb..d2622bc4a4 100644
--- a/gtk/gtkfilechooserdialog.c
+++ b/gtk/gtkfilechooserdialog.c
@@ -110,26 +110,23 @@
  * ]|
  * </para>
  * </example>
- * <section id="gtkfilechooserdialog-setting-up">
- * <title>Setting up a file chooser dialog</title>
+ *
+ * ## Setting up a file chooser dialog
+ *
+ * <para id="gtkfilechooserdialog-setting-up">
  * There are various cases in which you may need to use a #GtkFileChooserDialog:
- * <itemizedlist><listitem>To select a file for opening. Use
- *   #GTK_FILE_CHOOSER_ACTION_OPEN.
- * </listitem>
- * <listitem>To save a file for the first time. Use
- *   #GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as
- *   "Untitled" with gtk_file_chooser_set_current_name().
- * </listitem>
- * <listitem>To save a file under a different name. Use
- *   #GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing filename
- *   with gtk_file_chooser_set_filename().
- * </listitem>
- * <listitem>To choose a folder instead of a file.  Use
- *   #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
- * </listitem></itemizedlist>
- * <note>
- * <para>
- * Old versions of the file chooser's documentation suggested
+ *
+ * - To select a file for opening. Use #GTK_FILE_CHOOSER_ACTION_OPEN.
+ *
+ * - To save a file for the first time. Use #GTK_FILE_CHOOSER_ACTION_SAVE,
+ *   and suggest a name such as "Untitled" with gtk_file_chooser_set_current_name().
+ * 
+ * - To save a file under a different name. Use #GTK_FILE_CHOOSER_ACTION_SAVE,
+ *   and set the existing filename with gtk_file_chooser_set_filename().
+ *
+ * - To choose a folder instead of a file. Use #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
+ *
+ * Note that old versions of the file chooser's documentation suggested
  * using gtk_file_chooser_set_current_folder() in various
  * situations, with the intention of letting the application
  * suggest a reasonable default folder.  This is no longer
@@ -139,16 +136,14 @@
  * when it is appropriate to use gtk_file_chooser_set_filename(),
  * i.e. when you are doing a Save As command and you already
  * have a file saved somewhere.
- * </para>
- * </note>
- * </section>
- * <section id="gtkfilechooserdialog-response-codes">
- * <title>Response Codes</title>
+ *
+ * ## Response Codes
+ *
+ * <para id="gtkfilechooserdialog-response-codes">
  * #GtkFileChooserDialog inherits from #GtkDialog, so buttons that
  * go in its action area have response codes such as
  * #GTK_RESPONSE_ACCEPT and #GTK_RESPONSE_CANCEL.  For example, you
  * could call gtk_file_chooser_dialog_new() as follows:
- * <para>
  * |[
  * GtkWidget *dialog;
  *
@@ -160,6 +155,8 @@
  *                                       NULL);
  * ]|
  * </para>
+ *
+ * <para id="gtkfilechooserdialog-responses">
  * This will create buttons for "Cancel" and "Open" that use stock
  * response identifiers from #GtkResponseType.  For most dialog
  * boxes you can use your own custom response codes rather than the
@@ -167,27 +164,21 @@
  * its "accept"-type action, e.g. an "Open" or "Save" button,
  * will have one of the following response
  * codes:
- * <para>
- * <simplelist id="gtkfilechooserdialog-responses">
- * <member>#GTK_RESPONSE_ACCEPT</member>
- * <member>#GTK_RESPONSE_OK</member>
- * <member>#GTK_RESPONSE_YES</member>
- * <member>#GTK_RESPONSE_APPLY</member>
- * </simplelist>
+ * - #GTK_RESPONSE_ACCEPT
+ * - #GTK_RESPONSE_OK
+ * - #GTK_RESPONSE_YES
+ * - #GTK_RESPONSE_APPLY
  * </para>
+ *
  * This is because #GtkFileChooserDialog must intercept responses
  * and switch to folders if appropriate, rather than letting the
  * dialog terminate &mdash; the implementation uses these known
  * response codes to know which responses can be blocked if
  * appropriate.
- * <para>
- * <note>
+ *
  * To summarize, make sure you use a
  * <link linkend="gtkfilechooserdialog-responses">stock response code</link>
  * when you use #GtkFileChooserDialog to ensure proper operation.
- * </note>
- * </para>
- * </section>
  */
 
 
diff --git a/gtk/gtkfixed.c b/gtk/gtkfixed.c
index 1d2ab3f772..07665b2977 100644
--- a/gtk/gtkfixed.c
+++ b/gtk/gtkfixed.c
@@ -37,23 +37,18 @@
  * results in broken applications.  With #GtkFixed, the following
  * things will result in truncated text, overlapping widgets, and
  * other display bugs:
- * <itemizedlist>
- *  <listitem><para>
- *   Themes, which may change widget sizes.
- *  </para></listitem>
- *  <listitem><para>
- *   Fonts other than the one you used to write the app will of course
+ *
+ * - Themes, which may change widget sizes.
+ *
+ * - Fonts other than the one you used to write the app will of course
  *   change the size of widgets containing text; keep in mind that
  *   users may use a larger font because of difficulty reading the
  *   default, or they may be using Windows or the framebuffer port of
  *   GTK+, where different fonts are available.
- *  </para></listitem>
- *  <listitem><para>
- *   Translation of text into other languages changes its size. Also,
+ *
+ * - Translation of text into other languages changes its size. Also,
  *   display of non-English text will use a different font in many
  *   cases.
- *  </para></listitem>
- * </itemizedlist>
  *
  * In addition, the fixed widget can't properly be mirrored in
  * right-to-left languages such as Hebrew and Arabic. i.e. normally
diff --git a/gtk/gtkflowbox.c b/gtk/gtkflowbox.c
index 6bdadbe7e6..2d6a4a330b 100644
--- a/gtk/gtkflowbox.c
+++ b/gtk/gtkflowbox.c
@@ -3841,11 +3841,9 @@ gtk_flow_box_class_init (GtkFlowBoxClass *class)
    * the variant with the Shift modifier extends the selection,
    * the variant without the Shift modifer does not.
    * There are too many key combinations to list them all here.
-   * <itemizedlist>
-   * <listitem>Arrow keys move by individual children</listitem>
-   * <listitem>Home/End keys move to the ends of the box</listitem>
-   * <listitem>PageUp/PageDown keys move vertically by pages</listitem>
-   * </itemizedlist>
+   * - Arrow keys move by individual children
+   * - Home/End keys move to the ends of the box
+   * - PageUp/PageDown keys move vertically by pages
    */
   signals[MOVE_CURSOR] = g_signal_new ("move-cursor",
                                        GTK_TYPE_FLOW_BOX,
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index 898898a7bb..685cc02e1c 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -80,27 +80,23 @@
  * Named icons are similar to the <xref linkend="gtk3-Themeable-Stock-Images"/>
  * facility, and the distinction between the two may be a bit confusing.
  * A few things to keep in mind:
- * <itemizedlist>
- * <listitem>
- * Stock images usually are used in conjunction with
- * <xref linkend="gtk3-Stock-Items"/>, such as %GTK_STOCK_OK or
- * %GTK_STOCK_OPEN. Named icons are easier to set up and therefore
- * are more useful for new icons that an application wants to
- * add, such as application icons or window icons.
- * </listitem>
- * <listitem>
- * Stock images can only be loaded at the symbolic sizes defined
- * by the #GtkIconSize enumeration, or by custom sizes defined
- * by gtk_icon_size_register(), while named icons are more flexible
- * and any pixel size can be specified.
- * </listitem>
- * <listitem>
- * Because stock images are closely tied to stock items, and thus
- * to actions in the user interface, stock images may come in
- * multiple variants for different widget states or writing
- * directions.
- * </listitem>
- * </itemizedlist>
+ * 
+ * - Stock images usually are used in conjunction with
+ *   <xref linkend="gtk3-Stock-Items"/>, such as %GTK_STOCK_OK or
+ *   %GTK_STOCK_OPEN. Named icons are easier to set up and therefore
+ *   are more useful for new icons that an application wants to
+ *   add, such as application icons or window icons.
+ * 
+ * - Stock images can only be loaded at the symbolic sizes defined
+ *   by the #GtkIconSize enumeration, or by custom sizes defined
+ *   by gtk_icon_size_register(), while named icons are more flexible
+ *   and any pixel size can be specified.
+ * 
+ * - Because stock images are closely tied to stock items, and thus
+ *   to actions in the user interface, stock images may come in
+ *   multiple variants for different widget states or writing
+ *   directions.
+ *
  * A good rule of thumb is that if there is a stock image for what
  * you want to use, use it, otherwise use a named icon. It turns
  * out that internally stock images are generally defined in
diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index 39d257d2ee..68ab8aeb60 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -849,12 +849,9 @@ gtk_icon_view_class_init (GtkIconViewClass *klass)
    * programmatically.
    *
    * The default bindings for this signal include
-   * <itemizedlist>
-   * <listitem>Arrow keys which move by individual steps</listitem>
-   * <listitem>Home/End keys which move to the first/last item</listitem>
-   * <listitem>PageUp/PageDown which move by "pages"</listitem>
-   * </itemizedlist>
-   *
+   * - Arrow keys which move by individual steps
+   * - Home/End keys which move to the first/last item
+   * - PageUp/PageDown which move by "pages"
    * All of these will extend the selection when combined with
    * the Shift modifier.
    */
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index acff4b5263..778c435c70 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -593,10 +593,9 @@ gtk_label_class_init (GtkLabelClass *class)
    * the variant with the Shift modifier extends the selection,
    * the variant without the Shift modifer does not.
    * There are too many key combinations to list them all here.
-   * <itemizedlist>
-   * <listitem>Arrow keys move by individual characters/lines</listitem>
-   * <listitem>Ctrl-arrow key combinations move by words/paragraphs</listitem>
-   * <listitem>Home/End keys move to the ends of the buffer</listitem>
+   * - Arrow keys move by individual characters/lines
+   * - Ctrl-arrow key combinations move by words/paragraphs
+   * - Home/End keys move to the ends of the buffer
    * </itemizedlist>
    */
   signals[MOVE_CURSOR] = 
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 72c2e19f9c..a83669ad56 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -1467,51 +1467,33 @@ rewrite_event_for_grabs (GdkEvent *event)
  * know how exactly events are handled. So here is what this function
  * does with the event:
  *
- * <orderedlist>
- * <listitem><para>
- *   Compress enter/leave notify events. If the event passed build an
- *   enter/leave pair together with the next event (peeked from GDK), both
- *   events are thrown away. This is to avoid a backlog of (de-)highlighting
- *   widgets crossed by the pointer.
- * </para></listitem>
- * <listitem><para>
- *   Find the widget which got the event. If the widget can't be determined
- *   the event is thrown away unless it belongs to a INCR transaction.
- * </para></listitem>
- * <listitem><para>
- *   Then the event is pushed onto a stack so you can query the currently
- *   handled event with gtk_get_current_event().
- * </para></listitem>
- * <listitem><para>
- *   The event is sent to a widget. If a grab is active all events for widgets
- *   that are not in the contained in the grab widget are sent to the latter
- *   with a few exceptions:
- *   <itemizedlist>
- *   <listitem><para>
- *     Deletion and destruction events are still sent to the event widget for
- *     obvious reasons.
- *   </para></listitem>
- *   <listitem><para>
- *     Events which directly relate to the visual representation of the event
- *     widget.
- *   </para></listitem>
- *   <listitem><para>
- *     Leave events are delivered to the event widget if there was an enter
- *     event delivered to it before without the paired leave event.
- *   </para></listitem>
- *   <listitem><para>
- *     Drag events are not redirected because it is unclear what the semantics
- *     of that would be.
- *   </para></listitem>
- *   </itemizedlist>
- *   Another point of interest might be that all key events are first passed
- *   through the key snooper functions if there are any. Read the description
- *   of gtk_key_snooper_install() if you need this feature.
- * </para></listitem>
- * <listitem><para>
- *   After finishing the delivery the event is popped from the event stack.
- * </para></listitem>
- * </orderedlist>
+ * 1. Compress enter/leave notify events. If the event passed build an
+ *    enter/leave pair together with the next event (peeked from GDK), both
+ *    events are thrown away. This is to avoid a backlog of (de-)highlighting
+ *    widgets crossed by the pointer.
+ * 
+ * 2. Find the widget which got the event. If the widget can't be determined
+ *    the event is thrown away unless it belongs to a INCR transaction.
+ *
+ * 3. Then the event is pushed onto a stack so you can query the currently
+ *    handled event with gtk_get_current_event().
+ * 
+ * 4. The event is sent to a widget. If a grab is active all events for widgets
+ *    that are not in the contained in the grab widget are sent to the latter
+ *    with a few exceptions:
+ *    - Deletion and destruction events are still sent to the event widget for
+ *      obvious reasons.
+ *    - Events which directly relate to the visual representation of the event
+ *      widget.
+ *    - Leave events are delivered to the event widget if there was an enter
+ *      event delivered to it before without the paired leave event.
+ *    - Drag events are not redirected because it is unclear what the semantics
+ *      of that would be.
+ *    Another point of interest might be that all key events are first passed
+ *    through the key snooper functions if there are any. Read the description
+ *    of gtk_key_snooper_install() if you need this feature.
+ * 
+ * 5. After finishing the delivery the event is popped from the event stack.
  */
 void
 gtk_main_do_event (GdkEvent *event)
diff --git a/gtk/gtkshow.c b/gtk/gtkshow.c
index 58f1cb3fab..2de66be56d 100644
--- a/gtk/gtkshow.c
+++ b/gtk/gtkshow.c
@@ -37,11 +37,9 @@
  * need to install gvfs to get support for uri schemes such as http://
  * or ftp://, as only local files are handled by GIO itself).
  * Typical examples are
- * <simplelist>
- *   <member><filename>file:///home/gnome/pict.jpg</filename></member>
- *   <member><filename>http://www.gnome.org</filename></member>
- *   <member><filename>mailto:me&commat;gnome.org</filename></member>
- * </simplelist>
+ * - <filename>file:///home/gnome/pict.jpg</filename>
+ * - <filename>http://www.gnome.org</filename>
+ * - <filename>mailto:me&commat;gnome.org</filename>
  * Ideally the timestamp is taken from the event triggering
  * the gtk_show_uri() call. If timestamp is not known you can take
  * %GDK_CURRENT_TIME.
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index e63147bc18..e684c7fed2 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -940,13 +940,11 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * the variant with the Shift modifier extends the selection,
    * the variant without the Shift modifer does not.
    * There are too many key combinations to list them all here.
-   * <itemizedlist>
-   * <listitem>Arrow keys move by individual characters/lines</listitem>
-   * <listitem>Ctrl-arrow key combinations move by words/paragraphs</listitem>
-   * <listitem>Home/End keys move to the ends of the buffer</listitem>
-   * <listitem>PageUp/PageDown keys move vertically by pages</listitem>
-   * <listitem>Ctrl-PageUp/PageDown keys move horizontally by pages</listitem>
-   * </itemizedlist>
+   * - Arrow keys move by individual characters/lines
+   * - Ctrl-arrow key combinations move by words/paragraphs
+   * - Home/End keys move to the ends of the buffer
+   * - PageUp/PageDown keys move vertically by pages
+   * - Ctrl-PageUp/PageDown keys move horizontally by pages
    */
   signals[MOVE_CURSOR] = 
     g_signal_new (I_("move-cursor"),
diff --git a/gtk/gtktoolitem.c b/gtk/gtktoolitem.c
index 01634d0c21..ceb3331a26 100644
--- a/gtk/gtktoolitem.c
+++ b/gtk/gtktoolitem.c
@@ -37,22 +37,7 @@
  * SECTION:gtktoolitem
  * @short_description: The base class of widgets that can be added to GtkToolShell
  * @Title: GtkToolItem
- * @see_also: <variablelist>
- *   <varlistentry>
- *     <term>#GtkToolbar</term>
- *     <listitem><para>The toolbar widget</para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>#GtkToolButton</term>
- *     <listitem><para>A subclass of #GtkToolItem that displays buttons on
- *         the toolbar</para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>#GtkSeparatorToolItem</term>
- *     <listitem><para>A subclass of #GtkToolItem that separates groups of
- *         items on a toolbar</para></listitem>
- *   </varlistentry>
- * </variablelist>
+ * @see_also: #GtkToolbar, #GtkToolButton, #GtkSeparatorToolItem
  *
  * #GtkToolItem<!-- -->s are widgets that can appear on a toolbar. To
  * create a toolbar item that contain something else than a button, use
@@ -221,20 +206,17 @@ gtk_tool_item_class_init (GtkToolItemClass *klass)
  * This signal is emitted when the toolbar needs information from @tool_item
  * about whether the item should appear in the toolbar overflow menu. In
  * response the tool item should either
- * <itemizedlist>
- * <listitem>call gtk_tool_item_set_proxy_menu_item() with a %NULL
- * pointer and return %TRUE to indicate that the item should not appear
- * in the overflow menu
- * </listitem>
- * <listitem> call gtk_tool_item_set_proxy_menu_item() with a new menu
- * item and return %TRUE, or 
- * </listitem>
- * <listitem> return %FALSE to indicate that the signal was not
- * handled by the item. This means that
- * the item will not appear in the overflow menu unless a later handler
- * installs a menu item.
- * </listitem>
- * </itemizedlist>
+ * 
+ * - call gtk_tool_item_set_proxy_menu_item() with a %NULL
+ *   pointer and return %TRUE to indicate that the item should not appear
+ *   in the overflow menu
+ * 
+ * - call gtk_tool_item_set_proxy_menu_item() with a new menu
+ *   item and return %TRUE, or 
+ *
+ * - return %FALSE to indicate that the signal was not handled by the item.
+ *   This means that the item will not appear in the overflow menu unless
+ *   a later handler installs a menu item.
  *
  * The toolbar may cache the result of this signal. When the tool item changes
  * how it will respond to this signal it must call gtk_tool_item_rebuild_menu()
@@ -259,12 +241,10 @@ gtk_tool_item_class_init (GtkToolItemClass *klass)
  * This signal is emitted when some property of the toolbar that the
  * item is a child of changes. For custom subclasses of #GtkToolItem,
  * the default handler of this signal use the functions
- * <itemizedlist>
- * <listitem>gtk_tool_shell_get_orientation()</listitem>
- * <listitem>gtk_tool_shell_get_style()</listitem>
- * <listitem>gtk_tool_shell_get_icon_size()</listitem>
- * <listitem>gtk_tool_shell_get_relief_style()</listitem>
- * </itemizedlist>
+ * - gtk_tool_shell_get_orientation()
+ * - gtk_tool_shell_get_style()
+ * - gtk_tool_shell_get_icon_size()
+ * - gtk_tool_shell_get_relief_style()
  * to find out what the toolbar should look like and change
  * themselves accordingly.
  **/
@@ -796,16 +776,12 @@ gtk_tool_item_get_orientation (GtkToolItem *tool_item)
  * the toolbar is displayed and change themselves accordingly 
  *
  * Possibilities are:
- * <itemizedlist>
- * <listitem> GTK_TOOLBAR_BOTH, meaning the tool item should show
- * both an icon and a label, stacked vertically </listitem>
- * <listitem> GTK_TOOLBAR_ICONS, meaning the toolbar shows
- * only icons </listitem>
- * <listitem> GTK_TOOLBAR_TEXT, meaning the tool item should only
- * show text</listitem>
- * <listitem> GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show
- * both an icon and a label, arranged horizontally</listitem>
- * </itemizedlist>
+ * - %GTK_TOOLBAR_BOTH, meaning the tool item should show
+ *   both an icon and a label, stacked vertically
+ * - %GTK_TOOLBAR_ICONS, meaning the toolbar shows only icons
+ * - %GTK_TOOLBAR_TEXT, meaning the tool item should only show text
+ * - %GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show
+ *   both an icon and a label, arranged horizontally
  * 
  * Return value: A #GtkToolbarStyle indicating the toolbar style used
  * for @tool_item.
diff --git a/gtk/gtktooltip.c b/gtk/gtktooltip.c
index 71b99646c4..d0a544804b 100644
--- a/gtk/gtktooltip.c
+++ b/gtk/gtktooltip.c
@@ -52,58 +52,34 @@
  * When you need a tooltip with a little more fancy contents, like adding an
  * image, or you want the tooltip to have different contents per #GtkTreeView
  * row or cell, you will have to do a little more work:
- * <itemizedlist>
- * <listitem>
- * <para>
- * Set the #GtkWidget:has-tooltip property to %TRUE, this will make GTK+
- * monitor the widget for motion and related events which are needed to
- * determine when and where to show a tooltip.
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * Connect to the #GtkWidget::query-tooltip signal.  This signal will be
- * emitted when a tooltip is supposed to be shown. One of the arguments passed
- * to the signal handler is a GtkTooltip object. This is the object that we
- * are about to display as a tooltip, and can be manipulated in your callback
- * using functions like gtk_tooltip_set_icon(). There are functions for setting
- * the tooltip's markup, setting an image from a named icon, or even putting in
- * a custom widget.
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * Return %TRUE from your query-tooltip handler. This causes the tooltip to be
- * show. If you return %FALSE, it will not be shown.
- * </para>
- * </listitem>
- * </itemizedlist>
+ * 
+ * - Set the #GtkWidget:has-tooltip property to %TRUE, this will make GTK+
+ *   monitor the widget for motion and related events which are needed to
+ *   determine when and where to show a tooltip.
+ *
+ * - Connect to the #GtkWidget::query-tooltip signal.  This signal will be
+ *   emitted when a tooltip is supposed to be shown. One of the arguments passed
+ *   to the signal handler is a GtkTooltip object. This is the object that we
+ *   are about to display as a tooltip, and can be manipulated in your callback
+ *   using functions like gtk_tooltip_set_icon(). There are functions for setting
+ *   the tooltip's markup, setting an image from a named icon, or even putting in
+ *   a custom widget.
+ *
+ *   Return %TRUE from your query-tooltip handler. This causes the tooltip to be
+ *   show. If you return %FALSE, it will not be shown.
  *
  * In the probably rare case where you want to have even more control over the
  * tooltip that is about to be shown, you can set your own #GtkWindow which
  * will be used as tooltip window.  This works as follows:
- * <itemizedlist>
- * <listitem>
- * <para>
- * Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as
- * before.
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * Use gtk_widget_set_tooltip_window() to set a #GtkWindow created by you as
- * tooltip window.
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * In the #GtkWidget::query-tooltip callback you can access your window using
- * gtk_widget_get_tooltip_window() and manipulate as you wish. The semantics of
- * the return value are exactly as before, return %TRUE to show the window,
- * %FALSE to not show it.
- * </para>
- * </listitem>
- * </itemizedlist>
+ * 
+ * - Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as before.
+ *   Use gtk_widget_set_tooltip_window() to set a #GtkWindow created by you as
+ *   tooltip window.
+ *
+ * - In the #GtkWidget::query-tooltip callback you can access your window using
+ *   gtk_widget_get_tooltip_window() and manipulate as you wish. The semantics of
+ *   the return value are exactly as before, return %TRUE to show the window,
+ *   %FALSE to not show it.
  */
 
 
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index 6cb6da3f84..931d9ff766 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -209,21 +209,20 @@
  *
  * When working with reference counting, the following rules must be taken
  * into account:
- * <itemizedlist>
- * <listitem><para>Never take a reference on a node without owning a
- * reference on its parent. This means that all parent nodes of a referenced
- * node must be referenced as well.</para></listitem>
- * <listitem><para>Outstanding references on a deleted node are not released.
- * This is not possible because the node has already been deleted by the
- * time the row-deleted signal is received.
- * </para></listitem>
- * <listitem><para>Models are not obligated to emit a signal on rows of
- * which none of its siblings are referenced. To phrase this differently,
- * signals are only required for levels in which nodes are referenced. For
- * the root level however, signals must be emitted at all times (however the
- * root level is always referenced when any view is attached).
- * </para></listitem>
- * </itemizedlist>
+ *
+ * - Never take a reference on a node without owning a reference on its parent.
+ *   This means that all parent nodes of a referenced node must be referenced
+ *   as well.
+ *
+ * - Outstanding references on a deleted node are not released. This is not
+ *   possible because the node has already been deleted by the time the
+ *   row-deleted signal is received.
+ *
+ * - Models are not obligated to emit a signal on rows of which none of its
+ *   siblings are referenced. To phrase this differently, signals are only
+ *   required for levels in which nodes are referenced. For the root level
+ *   however, signals must be emitted at all times (however the root level
+ *   is always referenced when any view is attached).
  */
 
 #define INITIALIZE_TREE_ITER(Iter) \
diff --git a/gtk/gtktreemodelfilter.c b/gtk/gtktreemodelfilter.c
index f4c6a81c78..17029a0a72 100644
--- a/gtk/gtktreemodelfilter.c
+++ b/gtk/gtktreemodelfilter.c
@@ -32,25 +32,21 @@
  *
  * A #GtkTreeModelFilter is a tree model which wraps another tree model,
  * and can do the following things:
- * <itemizedlist>
- * <listitem><para>
- * Filter specific rows, based on data from a "visible column", a column
- * storing booleans indicating whether the row should be filtered or not,
- * or based on the return value of a "visible function", which gets a
- * model, iter and user_data and returns a boolean indicating whether the
- * row should be filtered or not.
- * </para></listitem>
- * <listitem><para>
- * Modify the "appearance" of the model, using a modify function.
- * This is extremely powerful and allows for just changing
- * some values and also for creating a completely different model based on
- * the given child model.
- * </para></listitem>
- * <listitem><para>
- * Set a different root node, also known as a "virtual root". You can pass in
- * a #GtkTreePath indicating the root node for the filter at construction time.
- * </para></listitem>
- * </itemizedlist>
+ * 
+ * - Filter specific rows, based on data from a "visible column", a column
+ *   storing booleans indicating whether the row should be filtered or not,
+ *   or based on the return value of a "visible function", which gets a
+ *   model, iter and user_data and returns a boolean indicating whether the
+ *   row should be filtered or not.
+ * 
+ * - Modify the "appearance" of the model, using a modify function.
+ *   This is extremely powerful and allows for just changing some
+ *   values and also for creating a completely different model based
+ *   on the given child model.
+ *
+ * - Set a different root node, also known as a "virtual root". You can pass
+ *   in a #GtkTreePath indicating the root node for the filter at construction
+ *   time.
  *
  * The basic API is similar to #GtkTreeModelSort. For an example on its usage,
  * see the section on #GtkTreeModelSort.
diff --git a/gtk/gtktreesortable.c b/gtk/gtktreesortable.c
index 0eeadc5e8b..14100190ca 100644
--- a/gtk/gtktreesortable.c
+++ b/gtk/gtktreesortable.c
@@ -147,16 +147,11 @@ gtk_tree_sortable_get_sort_column_id (GtkTreeSortable  *sortable,
  * resort itself to reflect this change, after emitting a
  * #GtkTreeSortable::sort-column-changed signal. @sort_column_id may either be
  * a regular column id, or one of the following special values:
- * <variablelist>
- * <varlistentry>
- *   <term>%GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID</term>
- *   <listitem>the default sort function will be used, if it is set</listitem>
- * </varlistentry>
- * <varlistentry>
- *   <term>%GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID</term>
- *   <listitem>no sorting will occur</listitem>
- * </varlistentry>
- * </variablelist>
+ * 
+ * - %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID: the default sort function
+ *   will be used, if it is set
+ * 
+ * - %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID: no sorting will occur
  */
 void
 gtk_tree_sortable_set_sort_column_id (GtkTreeSortable  *sortable,