Merge lp:~noskcaj/ubuntu/trusty/gtk-doc/1.20 into lp:ubuntu/trusty/gtk-doc

[Jackson Doak]

Merge from debian

[Iain Lane (laney)]

Just did this myself, then I thought about checking the queue & I saw your one here. Uploaded!

review: Approve

=== modified file 'Makefile.am'
--- Makefile.am	2013-12-19 07:58:53 +0000
+++ Makefile.am	2014-02-17 20:15:47 +0000
@@ -34,11 +34,14 @@
 	gtk-doc.notmpl.make	\
 	gtk-doc.flat.make	\
 	gtk-doc.notmpl-flat.make	\
-	home.png			\
-	left.png			\
-	right.png		\
-	up.png			\
-	style.css
+	style/home.png			\
+	style/left.png			\
+	style/left-insensitive.png		\
+	style/right.png		\
+	style/right-insensitive.png		\
+	style/up.png			\
+	style/up-insensitive.png		\
+	style/style.css
 
 pkgconfigdir = $(datadir)/pkgconfig
 pkgconfig_DATA = gtk-doc.pc
@@ -57,25 +60,14 @@
 
 EXTRA_DIST = \
 	MAINTAINERS     \
+	$(gtkdocdata_DATA) \
 	gtk-doc.pc.in   \
 	gtk-doc.m4      \
-	gtk-doc.make    \
-	gtk-doc.notmpl.make \
-	gtk-doc.flat.make \
-	gtk-doc.notmpl-flat.make \
 	gtk-doc.doap \
 	gtk-doc.spec.in \
 	gtk-doc.spec    \
-	gtk-doc.dcl     \
-	gtk-doc.xsl     \
 	gtk-doc-fo.xsl     \
-	version-greater-or-equal.xsl \
-	devhelp2.xsl     \
 	gtk-doc.cat.in  \
-	home.png  \
-	left.png  \
-	right.png \
-	up.png    \
 	doc/README            \
 	doc/authors.txt       \
 	doc/gnome.txt         \
@@ -89,7 +81,6 @@
 	examples/Makefile.am  \
 	tools/docpercentages.pl \
 	tools/gtk-doc.el \
-	style.css \
 	COPYING-DOCS
 
 MAINTAINERCLEANFILES = \
 
=== modified file 'Makefile.in'
--- Makefile.in	2013-12-19 07:58:53 +0000
+++ Makefile.in	2014-02-17 20:15:47 +0000
@@ -54,10 +54,11 @@
 	build-aux/config.sub build-aux/depcomp build-aux/install-sh \
 	build-aux/ltmain.sh build-aux/missing
 ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/libtool.m4 \
-	$(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \
-	$(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \
-	$(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.ac
+am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+	$(top_srcdir)/m4/gtkdoc_jh_path_xml_catalog.m4 \
+	$(top_srcdir)/m4/libtool.m4 $(top_srcdir)/m4/ltoptions.m4 \
+	$(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \
+	$(top_srcdir)/m4/lt~obsolete.m4 $(top_srcdir)/configure.ac
 am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
 	$(ACLOCAL_M4)
 am__CONFIG_DISTCLEAN_FILES = config.status config.cache config.log \
@@ -179,6 +180,7 @@
 CPP = @CPP@
 CPPFLAGS = @CPPFLAGS@
 CYGPATH_W = @CYGPATH_W@
+DATE_FMT_CMD = @DATE_FMT_CMD@
 DBLATEX = @DBLATEX@
 DEFS = @DEFS@
 DEPDIR = @DEPDIR@
@@ -189,6 +191,7 @@
 ECHO_N = @ECHO_N@
 ECHO_T = @ECHO_T@
 EGREP = @EGREP@
+ELAPSED_FMT = @ELAPSED_FMT@
 EXEEXT = @EXEEXT@
 FGREP = @FGREP@
 FOP = @FOP@
@@ -329,11 +332,14 @@
 	gtk-doc.notmpl.make	\
 	gtk-doc.flat.make	\
 	gtk-doc.notmpl-flat.make	\
-	home.png			\
-	left.png			\
-	right.png		\
-	up.png			\
-	style.css
+	style/home.png			\
+	style/left.png			\
+	style/left-insensitive.png		\
+	style/right.png		\
+	style/right-insensitive.png		\
+	style/up.png			\
+	style/up-insensitive.png		\
+	style/style.css
 
 pkgconfigdir = $(datadir)/pkgconfig
 pkgconfig_DATA = gtk-doc.pc
@@ -343,25 +349,14 @@
 sgml_DATA = gtk-doc.cat
 EXTRA_DIST = \
 	MAINTAINERS     \
+	$(gtkdocdata_DATA) \
 	gtk-doc.pc.in   \
 	gtk-doc.m4      \
-	gtk-doc.make    \
-	gtk-doc.notmpl.make \
-	gtk-doc.flat.make \
-	gtk-doc.notmpl-flat.make \
 	gtk-doc.doap \
 	gtk-doc.spec.in \
 	gtk-doc.spec    \
-	gtk-doc.dcl     \
-	gtk-doc.xsl     \
 	gtk-doc-fo.xsl     \
-	version-greater-or-equal.xsl \
-	devhelp2.xsl     \
 	gtk-doc.cat.in  \
-	home.png  \
-	left.png  \
-	right.png \
-	up.png    \
 	doc/README            \
 	doc/authors.txt       \
 	doc/gnome.txt         \
@@ -375,7 +370,6 @@
 	examples/Makefile.am  \
 	tools/docpercentages.pl \
 	tools/gtk-doc.el \
-	style.css \
 	COPYING-DOCS
 
 MAINTAINERCLEANFILES = \
 
=== modified file 'NEWS'
--- NEWS	2013-12-19 07:58:53 +0000
+++ NEWS	2014-02-17 20:15:47 +0000
@@ -1,3 +1,77 @@
+GTK-Doc 1.20    (Feb 16 2014)
+============
+
+ Important notice - starting with the next release these long deprecated
+ features will be removed, please write to [e-mail] and tell us
+ your concerns:
+ o gtkdoc-scanobj (only used for gtkobject)
+ o return values need to be documented using "Returns:". We will remove the
+   heuristic that turns a paragraph starting with "Returns " into return docs.
+ o gtkdoc-mktmpl - please move all the comments into the sources.
+ o generating html via sgml tools (jade/openjade), using xsltproc and
+   docbook-xslt is pretty common and preferred since version 1.6
+
+ Changes
+
+ o 605537 : Returns: listed among parameters
+ o 624001 : Support attribute-based method to deprecate symbols
+ o 662424 : Class hierarchy about interfaces not generated by default
+ o 665926 : should not have to document object structures
+ o 666509 : Specifying --enable-gtk-doc should not be required to build source packages
+ o 669417 : Duplicate IDs generated for unions registered as boxed types
+ o 671519 : Self-test relies on nonportable (GNU enhanced) 'date' command
+ o 692367 : gtkdocize should take a srcdir argument
+ o 696570 : style updates
+ o 697940 : Race condition between setup-build.stamp and scan-build.stamp
+ o 701259 : /bin/bash: -chmod: command not found
+ o 701638 : Support automake parallel test harness (fix error with GTKDOC_CHECK)
+ o 706404 : Minor bug in gtkdoc-mkdb
+ o 706438 : Empty lines added at the beginning and at the end of a programlisting
+ o 707426 : master is broken in picking up flavour from configure.ac
+ o 707717 : Support " Deprecated: X.Y " 
+ o 708268 : New *-insensitive.png files are not distributes
+ o 710478 : gtkdoc-mkdb: Don't complain about annotations with hyphen
+ o 711111 : gtkdoc-mkdb: sort entries in the glossary
+ o 711598 : gtkdoc-scan doesn't ignore decorators containing parentheses
+ o 719644 : docs: make yelp usage conditional in manual
+ o 719645 : configure: emit message when looking for yelp
+ o 720061 : make: create subdirectories of the content_files to the  builddir
+ o 721228 : configure: search for xml catalog in XDG_DATA_DIRS
+ o 722479 : cp -u is not portable
+ o 723118 : Mark |[ blocks as CDATA
+ o 723288 : Fix MarkDown support
+ o 723417 : New MarkDown parser
+ o 723696 : Add support for blockquote
+ o 723812 : Add support for reference links
+ o 723913 : List in markdown: < p > inside the last element of a < ul > list
+ o 723991 : Improve the display of the synopsis
+ o 724002 : gtkdoc-scan: Fix use of uninitialised value in trace logging
+
+ Contributors
+
+ Alban Browaeys
+ Alexander Kanavin
+ Carlos Garcia Campos
+ Christian Kirbach
+ Daniel Mustieles
+ David King
+ David Nečas
+ Dieter Verfaillie
+ Dimitris Spingos
+ Hib Eris
+ Matthias Clasen
+ Philip Chimento
+ Philip Withnall
+ Rafael Ferreira
+ Rico Tzschichholz
+ Ryan Lortie
+ Sebastian Rasmussen
+ Sébastien Wilmet
+ Stefan Sauer
+ Stef Walter
+ William Jon McCann
+ Zbigniew Jędrzejewski-Szmek
+
 GTK-Doc 1.19    (Jun 05 2013)
 ============
 
 
=== modified file 'TODO'
--- TODO	2013-12-19 07:58:53 +0000
+++ TODO	2014-02-17 20:15:47 +0000
@@ -16,11 +16,30 @@
 
 Developers can also add items here :)
 
-= Cleanups =
-== get rid of the -section.txt file ==
-* section-title can be in SECTION comment already
-* when scanning a header file, everything will be put to one section
-  * like we do for autogenerated section.txt file (gtkdoc-scan)
+= Less files to manually edit =
+The goal is that we configure gtk-doc in configure.ac and Makefile.am and
+document the code in the sources. Right no we also have to edit a bunch of extra
+files:
+ * $(DOC_MODULE).types
+ * $(DOC_MODULE)-docs.xml
+ * $(DOC_MODULE)-sections.txt
+
+== .types ==
+
+* using SCAN_OPTION="--rebuild-types" can be used to avoid maintaining the types
+  file
+* we need to check if this works well for all kind of _types (e.g. boxed)
+  https://bugzilla.gnome.org/show_bug.cgi?id=605025
+  
+== -section.txt ==
+https://bugzilla.gnome.org/show_bug.cgi?id=646094
+
+* using SCAN_OPTION="--rebuild-sections" can be used to use the audogenerated
+  sections file
+* when scanning a header file, everything of the header and the respective .c 
+  file will be put to one section
+* symbols can be hidden using __GTK_DOC_IGNORE__
+
 * we need comment markup to override the section
   e.g.: " * InSection: xxxx"
   this needs gtkdoc-mkdb::ScanSourceFile to understand a new tag, which
 
=== removed file 'acinclude.m4'
--- acinclude.m4	2004-05-15 23:11:36 +0000
+++ acinclude.m4	1970-01-01 00:00:00 +0000
@@ -1,55 +0,0 @@
-
-# Checks the location of the XML Catalog
-# Usage:
-#   JH_PATH_XML_CATALOG([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])
-# Defines XMLCATALOG and XML_CATALOG_FILE substitutions
-AC_DEFUN([JH_PATH_XML_CATALOG],
-[
-  # check for the presence of the XML catalog
-  AC_ARG_WITH([xml-catalog],
-              AC_HELP_STRING([--with-xml-catalog=CATALOG],
-                             [path to xml catalog to use]),,
-              [with_xml_catalog=/etc/xml/catalog])
-  jh_found_xmlcatalog=true
-  XML_CATALOG_FILE="$with_xml_catalog"
-  AC_SUBST([XML_CATALOG_FILE])
-  AC_MSG_CHECKING([for XML catalog ($XML_CATALOG_FILE)])
-  if test -f "$XML_CATALOG_FILE"; then
-    AC_MSG_RESULT([found])
-  else
-    jh_found_xmlcatalog=false
-    AC_MSG_RESULT([not found])
-  fi
-
-  # check for the xmlcatalog program
-  AC_PATH_PROG(XMLCATALOG, xmlcatalog, no)
-  if test "x$XMLCATALOG" = xno; then
-    jh_found_xmlcatalog=false
-  fi
-
-  if $jh_found_xmlcatalog; then
-    ifelse([$1],,[:],[$1])
-  else
-    ifelse([$2],,[AC_MSG_ERROR([could not find XML catalog])],[$2])
-  fi
-])
-
-# Checks if a particular URI appears in the XML catalog
-# Usage:
-#   JH_CHECK_XML_CATALOG(URI, [FRIENDLY-NAME], [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])
-AC_DEFUN([JH_CHECK_XML_CATALOG],
-[
-  AC_REQUIRE([JH_PATH_XML_CATALOG],[JH_PATH_XML_CATALOG(,[:])])dnl
-  AC_MSG_CHECKING([for ifelse([$2],,[$1],[$2]) in XML catalog])
-  if $jh_found_xmlcatalog && \
-     AC_RUN_LOG([$XMLCATALOG --noout "$XML_CATALOG_FILE" "$1" >&2]); then
-    AC_MSG_RESULT([found])
-    ifelse([$3],,,[$3
-])dnl
-  else
-    AC_MSG_RESULT([not found])
-    ifelse([$4],,
-       [AC_MSG_ERROR([could not find ifelse([$2],,[$1],[$2]) in XML catalog])],
-       [$4])
-  fi
-])
 
=== modified file 'aclocal.m4'
--- aclocal.m4	2013-12-19 07:58:53 +0000
+++ aclocal.m4	2014-02-17 20:15:47 +0000
@@ -1643,9 +1643,10 @@
 AC_SUBST([am__untar])
 ]) # _AM_PROG_TAR
 
+m4_include([m4/gtkdoc_jh_check_xml_catalog.m4])
+m4_include([m4/gtkdoc_jh_path_xml_catalog.m4])
 m4_include([m4/libtool.m4])
 m4_include([m4/ltoptions.m4])
 m4_include([m4/ltsugar.m4])
 m4_include([m4/ltversion.m4])
 m4_include([m4/lt~obsolete.m4])
-m4_include([acinclude.m4])
 
=== modified file 'configure'
--- configure	2013-12-19 07:58:53 +0000
+++ configure	2014-02-17 20:15:47 +0000
@@ -1,6 +1,6 @@
 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.68 for gtk-doc 1.19.
+# Generated by GNU Autoconf 2.68 for gtk-doc 1.20.
 #
 # Report bugs to <http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc>.
 #
@@ -571,8 +571,8 @@
 # Identity of this package.
 PACKAGE_NAME='gtk-doc'
 PACKAGE_TARNAME='gtk-doc'
-PACKAGE_VERSION='1.19'
-PACKAGE_STRING='gtk-doc 1.19'
+PACKAGE_VERSION='1.20'
+PACKAGE_STRING='gtk-doc 1.20'
 PACKAGE_BUGREPORT='http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc'
 PACKAGE_URL=''
 
@@ -623,6 +623,8 @@
 XMLLINT
 ITSTOOL
 HELP_DIR
+DATE_FMT_CMD
+ELAPSED_FMT
 TS_FMT
 TRACE
 glib_prefix
@@ -1349,7 +1351,7 @@
   # Omit some internal or obsolete options to make the list less imposing.
   # This message is too long to be a string in the A/UX 3.1 sh.
   cat <<_ACEOF
-\`configure' configures gtk-doc 1.19 to adapt to many kinds of systems.
+\`configure' configures gtk-doc 1.20 to adapt to many kinds of systems.
 
 Usage: $0 [OPTION]... [VAR=VALUE]...
 
@@ -1419,7 +1421,7 @@
 
 if test -n "$ac_init_help"; then
   case $ac_init_help in
-     short | recursive ) echo "Configuration of gtk-doc 1.19:";;
+     short | recursive ) echo "Configuration of gtk-doc 1.20:";;
    esac
   cat <<\_ACEOF
 
@@ -1542,7 +1544,7 @@
 test -n "$ac_init_help" && exit $ac_status
 if $ac_init_version; then
   cat <<\_ACEOF
-gtk-doc configure 1.19
+gtk-doc configure 1.20
 generated by GNU Autoconf 2.68
 
 Copyright (C) 2010 Free Software Foundation, Inc.
@@ -1820,7 +1822,7 @@
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.
 
-It was created by gtk-doc $as_me 1.19, which was
+It was created by gtk-doc $as_me 1.20, which was
 generated by GNU Autoconf 2.68.  Invocation command line was
 
   $ $0 $@
@@ -2639,7 +2641,7 @@
 
 # Define the identity of the package.
  PACKAGE='gtk-doc'
- VERSION='1.19'
+ VERSION='1.20'
 
 
 cat >>confdefs.h <<_ACEOF
@@ -12044,31 +12046,51 @@
 fi
 
 
-  # check for the presence of the XML catalog
 
 # Check whether --with-xml-catalog was given.
 if test "${with_xml_catalog+set}" = set; then :
   withval=$with_xml_catalog;
 else
-  with_xml_catalog=/etc/xml/catalog
+  with_xml_catalog=''
 fi
 
-  jh_found_xmlcatalog=true
-  XML_CATALOG_FILE="$with_xml_catalog"
-
-  { $as_echo "$as_me:${as_lineno-$LINENO}: checking for XML catalog ($XML_CATALOG_FILE)" >&5
-$as_echo_n "checking for XML catalog ($XML_CATALOG_FILE)... " >&6; }
-  if test -f "$XML_CATALOG_FILE"; then
-    { $as_echo "$as_me:${as_lineno-$LINENO}: result: found" >&5
-$as_echo "found" >&6; }
-  else
-    jh_found_xmlcatalog=false
-    { $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
+	{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for XML catalog" >&5
+$as_echo_n "checking for XML catalog... " >&6; }
+	if test -n "$with_xml_catalog"; then
+				if test -f "$with_xml_catalog"; then
+			jh_found_xmlcatalog=true
+		else
+			jh_found_xmlcatalog=false
+		fi
+	else
+						if test -z "$XDG_DATA_DIRS"; then
+						jh_xml_catalog_searchdirs="/etc:/usr/local/share:/usr/share"
+		else
+			jh_xml_catalog_searchdirs="/etc:$XDG_DATA_DIRS"
+		fi
+		jh_found_xmlcatalog=false
+				jh_xml_catalog_saved_ifs="$IFS"
+		IFS=':'
+		for d in $jh_xml_catalog_searchdirs; do
+			if test -f "$d/xml/catalog"; then
+				with_xml_catalog="$d/xml/catalog"
+				jh_found_xmlcatalog=true
+				break
+			fi
+		done
+		IFS="$jh_xml_catalog_saved_ifs"
+	fi
+	if $jh_found_xmlcatalog; then
+		{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $with_xml_catalog" >&5
+$as_echo "$with_xml_catalog" >&6; }
+	else
+		{ $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
 $as_echo "not found" >&6; }
-  fi
-
-  # check for the xmlcatalog program
-  # Extract the first word of "xmlcatalog", so it can be a program name with args.
+	fi
+	XML_CATALOG_FILE="$with_xml_catalog"
+
+
+		# Extract the first word of "xmlcatalog", so it can be a program name with args.
 set dummy xmlcatalog; ac_word=$2
 { $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
 $as_echo_n "checking for $ac_word... " >&6; }
@@ -12109,49 +12131,51 @@
 fi
 
 
-  if test "x$XMLCATALOG" = xno; then
-    jh_found_xmlcatalog=false
-  fi
-
-  if $jh_found_xmlcatalog; then
-    :
-  else
-    :
-  fi
-
-
-    { $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook XML DTD V4.3 in XML catalog" >&5
+	if test "x$XMLCATALOG" = xno; then
+		jh_found_xmlcatalog=false
+	fi
+
+	if $jh_found_xmlcatalog; then
+		:
+	else
+		:
+	fi
+
+
+		{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook XML DTD V4.3 in XML catalog" >&5
 $as_echo_n "checking for DocBook XML DTD V4.3 in XML catalog... " >&6; }
-  if $jh_found_xmlcatalog && \
-     { { $as_echo "$as_me:${as_lineno-$LINENO}: \$XMLCATALOG --noout \"\$XML_CATALOG_FILE\" \"-//OASIS//DTD DocBook XML V4.3//EN\" >&2"; } >&5
+	if $jh_found_xmlcatalog && \
+		{ { $as_echo "$as_me:${as_lineno-$LINENO}: \$XMLCATALOG --noout \"\$XML_CATALOG_FILE\" \"-//OASIS//DTD DocBook XML V4.3//EN\" >&2"; } >&5
   ($XMLCATALOG --noout "$XML_CATALOG_FILE" "-//OASIS//DTD DocBook XML V4.3//EN" >&2) 2>&5
   ac_status=$?
   $as_echo "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5
   test $ac_status = 0; }; then
-    { $as_echo "$as_me:${as_lineno-$LINENO}: result: found" >&5
+		{ $as_echo "$as_me:${as_lineno-$LINENO}: result: found" >&5
 $as_echo "found" >&6; }
-      else
-    { $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
+
+	else
+		{ $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
 $as_echo "not found" >&6; }
-    as_fn_error $? "could not find DocBook XML DTD V4.3 in XML catalog" "$LINENO" 5
-  fi
-
-
-    { $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook XSL Stylesheets in XML catalog" >&5
+		as_fn_error $? "could not find DocBook XML DTD V4.3 in XML catalog" "$LINENO" 5
+	fi
+
+
+		{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook XSL Stylesheets in XML catalog" >&5
 $as_echo_n "checking for DocBook XSL Stylesheets in XML catalog... " >&6; }
-  if $jh_found_xmlcatalog && \
-     { { $as_echo "$as_me:${as_lineno-$LINENO}: \$XMLCATALOG --noout \"\$XML_CATALOG_FILE\" \"http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl\" >&2"; } >&5
+	if $jh_found_xmlcatalog && \
+		{ { $as_echo "$as_me:${as_lineno-$LINENO}: \$XMLCATALOG --noout \"\$XML_CATALOG_FILE\" \"http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl\" >&2"; } >&5
   ($XMLCATALOG --noout "$XML_CATALOG_FILE" "http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl" >&2) 2>&5
   ac_status=$?
   $as_echo "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5
   test $ac_status = 0; }; then
-    { $as_echo "$as_me:${as_lineno-$LINENO}: result: found" >&5
+		{ $as_echo "$as_me:${as_lineno-$LINENO}: result: found" >&5
 $as_echo "found" >&6; }
-      else
-    { $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
+
+	else
+		{ $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
 $as_echo "not found" >&6; }
-    as_fn_error $? "could not find DocBook XSL Stylesheets in XML catalog" "$LINENO" 5
-  fi
+		as_fn_error $? "could not find DocBook XSL Stylesheets in XML catalog" "$LINENO" 5
+	fi
 
 
 
@@ -12516,16 +12540,43 @@
 fi
 
 
-date +%s.%N | grep -q "%N"
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking whether date can output nanoseconds" >&5
+$as_echo_n "checking whether date can output nanoseconds... " >&6; }
+date +%s.%N | grep -q '%N'
 if test "$?" == "1"; then
   TS_FMT="+%s.%N"
+  ELAPSED_FMT="+%H:%M:%S.%N"
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: yes" >&5
+$as_echo "yes" >&6; }
 else
   TS_FMT="+%s.0"
-fi
-
-
+  ELAPSED_FMT="+%H:%M:%S"
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking whether date can format dates" >&5
+$as_echo_n "checking whether date can format dates... " >&6; }
+date >/dev/null 2>&1 --utc --date @1.1 $ELAPSED_FMT
+if test "$?" == "0"; then
+  DATE_FMT_CMD="date --utc $ELAPSED_FMT --date @0"
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: yes" >&5
+$as_echo "yes" >&6; }
+else
+  DATE_FMT_CMD="echo "
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for yelp-tools" >&5
+$as_echo_n "checking for yelp-tools... " >&6; }
 have_yelp_tools=no
 
+{ $as_echo "$as_me:${as_lineno-$LINENO}: result: yes" >&5
+$as_echo "yes" >&6; }
 
 
 
@@ -12797,6 +12848,10 @@
 
 have_yelp_tools=yes
 
+if test "x$have_yelp_tools" != "xyes"; then
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
  if test x$have_yelp_tools = xyes; then
   HAVE_YELP_TOOLS_TRUE=
   HAVE_YELP_TOOLS_FALSE='#'
@@ -13427,7 +13482,7 @@
 # report actual input values of CONFIG_FILES etc. instead of their
 # values after options handling.
 ac_log="
-This file was extended by gtk-doc $as_me 1.19, which was
+This file was extended by gtk-doc $as_me 1.20, which was
 generated by GNU Autoconf 2.68.  Invocation command line was
 
   CONFIG_FILES    = $CONFIG_FILES
@@ -13484,7 +13539,7 @@
 cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
 ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
 ac_cs_version="\\
-gtk-doc config.status 1.19
+gtk-doc config.status 1.20
 configured by $0, generated by GNU Autoconf 2.68,
   with options \\"\$ac_cs_config\\"
 
 
=== modified file 'configure.ac'
--- configure.ac	2013-12-19 07:58:53 +0000
+++ configure.ac	2014-02-17 20:15:47 +0000
@@ -5,7 +5,7 @@
 dnl Makefile can only cope with that, i.e. use 1.1, 1.2, 1.3 ... 9.9.
 dnl FIXME: I can't see anything failing (1.14.1), lets try to use a three digit
 dnl number for the development version
-m4_define(gtk_doc_version, 1.19)
+m4_define(gtk_doc_version, 1.20)
 
 AC_INIT([gtk-doc],[gtk_doc_version],[http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc],[gtk-doc])
 
@@ -210,22 +210,44 @@
 AC_SUBST(TRACE)
 
 dnl check what date format we can use for the makefile tracing in tests
-date +%s.%N | grep -q "%N"
+AC_MSG_CHECKING(whether date can output nanoseconds)
+date +%s.%N | grep -q '%N'
 if test "$?" == "1"; then
   TS_FMT="+%s.%N"
+  ELAPSED_FMT="+%H:%M:%S.%N"
+  AC_MSG_RESULT(yes)
 else
   TS_FMT="+%s.0"
+  ELAPSED_FMT="+%H:%M:%S"
+  AC_MSG_RESULT(no)
 fi
 AC_SUBST(TS_FMT)
+AC_SUBST(ELAPSED_FMT)
+
+AC_MSG_CHECKING(whether date can format dates)
+date >/dev/null 2>&1 --utc --date @1.1 $ELAPSED_FMT
+if test "$?" == "0"; then
+  DATE_FMT_CMD="date --utc $ELAPSED_FMT --date @0"
+  AC_MSG_RESULT(yes)
+else
+  DATE_FMT_CMD="echo "
+  AC_MSG_RESULT(no)
+fi
+AC_SUBST(DATE_FMT_CMD)
 
 dnl
 dnl Documentation
 dnl
+AC_MSG_CHECKING([for yelp-tools])
 have_yelp_tools=no
 m4_ifdef([YELP_HELP_INIT],[
+AC_MSG_RESULT([yes])
 YELP_HELP_INIT
 have_yelp_tools=yes
 ])
+if test "x$have_yelp_tools" != "xyes"; then
+  AC_MSG_RESULT([no])
+fi
 AM_CONDITIONAL([HAVE_YELP_TOOLS],[test x$have_yelp_tools = xyes])
 
 AC_CONFIG_FILES([Makefile
 
=== modified file 'debian/changelog'
--- debian/changelog	2013-12-19 07:58:53 +0000
+++ debian/changelog	2014-02-17 20:15:47 +0000
@@ -1,3 +1,17 @@
+gtk-doc (1.20-1ubuntu1) UNRELEASED; urgency=medium
+
+  * Merge from debian. Remaining changes:
+    - debian/control.in: Drop optional highlight dependency, which is in
+      universe.
+
+ -- Jackson Doak <[e-mail]>  Tue, 18 Feb 2014 06:25:54 +1100
+
+gtk-doc (1.20-1) unstable; urgency=medium
+
+  * New upstream release.
+
+ -- Emilio Pozuelo Monfort <[e-mail]>  Sun, 16 Feb 2014 22:58:37 +0100
+
 gtk-doc (1.19-1ubuntu1) trusty; urgency=medium
 
   * Merge from debian. Remaining changes:
 
=== modified file 'examples/Makefile.am'
--- examples/Makefile.am	2013-12-19 07:58:53 +0000
+++ examples/Makefile.am	2014-02-17 20:15:47 +0000
@@ -96,7 +96,7 @@
 # Comment this out if you want 'make check' to test you doc status
 # and run some sanity checks
 if ENABLE_GTK_DOC
-TESTS_ENVIRONMENT = cd $(srcdir) && \
+TESTS_ENVIRONMENT = \
   DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
   SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
 #TESTS = $(GTKDOC_CHECK)
 
=== added file 'gtk-doc.dsl'
--- gtk-doc.dsl	1970-01-01 00:00:00 +0000
+++ gtk-doc.dsl	2014-02-17 20:15:47 +0000
@@ -0,0 +1,464 @@
+<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
+<!ENTITY dbstyle PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
+]>
+
+<style-sheet>
+<style-specification use="docbook">
+<style-specification-body>
+
+(define gtkdoc-version "")
+(define gtkdoc-bookname "")
+
+;; These are some customizations to the standard HTML output produced by the
+;; Modular DocBook Stylesheets.
+;; I've copied parts of a few functions from the stylesheets so these should
+;; be checked occasionally to ensure they are up to date.
+;;
+;; The last check was with version 1.40 of the stylesheets.
+;; It will not work with versions < 1.19 since the $shade-verbatim-attr$
+;; function was added then. Versions 1.19 to 1.39 may be OK, if you're lucky!
+
+;;(define %generate-book-toc% #f)
+
+;; If a Chapter has role="no-toc" we don't generate a table of contents.
+;; This is useful if a better contents page has been added manually, e.g. for
+;; the GTK+ Widgets & Objects page. (But it is a bit of a hack.)
+(define ($generate-chapter-toc$)
+  (not (equal? (attribute-string (normalize "role") (current-node)) "no-toc")))
+
+(define %chapter-autolabel% 
+  ;; Are chapters enumerated?
+  #f)
+
+(define %use-id-as-filename% #t)
+
+(define %html-ext% ".html")
+
+(define ($user-html-header$ #!optional
+                            (home (empty-node-list))
+                            (up (empty-node-list))
+                            (prev (empty-node-list))
+                            (next (empty-node-list)))
+  (make sequence
+    (if (not (string=? gtkdoc-version ""))
+	(make empty-element gi: "META"
+	      attributes: (list
+			   (list "NAME" "GENERATOR")
+			   (list "CONTENT" (string-append
+					  "GTK-Doc V"
+					  gtkdoc-version
+					  " (SGML mode)"))))
+	(empty-sosofo))
+    (make element gi: "STYLE"
+	  attributes: (list (list "TYPE" "text/css"))
+	  (literal ".synopsis, .classsynopsis {
+    background: #eeeeee;
+    border: solid 1px #aaaaaa;
+    padding: 0.5em;
+}
+.programlisting {
+    background: #eeeeff;
+    border: solid 1px #aaaaff;
+    padding: 0.5em;
+}
+.variablelist {
+    padding: 4px;
+    margin-left: 3em;
+}
+.navigation {
+    background: #ffeeee;
+    border: solid 1px #ffaaaa;
+    margin-top: 0.5em;
+    margin-bottom: 0.5em;
+}
+.navigation a {
+    color: #770000;
+}
+.navigation a:visited {
+    color: #550000;
+}
+.navigation .title {
+    font-size: 200%;
+}"))))
+
+
+(mode book-titlepage-recto-mode
+  (element title 
+    (make element gi: "TABLE"
+	  attributes: (list
+		       (list "CLASS" "navigation")
+		       (list "WIDTH" %gentext-nav-tblwidth%)
+		       (list "CELLPADDING" "2")
+		       (list "CELLSPACING" "0"))
+	  (make element gi: "TR"
+		(make element gi: "TH"
+		      attributes: (list
+				   (list "ALIGN" "center")
+                                  (list "VALIGN" "MIDDLE"))
+		      (make element gi: "P"
+			    attributes: (list (list "CLASS" (gi)))
+			    (process-children-trim)
+			    (make empty-element gi: "A"
+				  attributes: (list (list "NAME" (element-id))))))))))
+
+(define (book-titlepage-separator side)
+  (empty-sosofo))
+
+
+;; This overrides the variablelist definition (copied from 1.76,
+;; dblists.dsl).  It changes the table background color, cell spacing
+;; and cell padding.
+;;
+;; I have also removed the code to handle the non-table case.
+(element variablelist
+    (make sequence
+      (if %spacing-paras%
+          (make element gi: "P" (empty-sosofo))
+          (empty-sosofo))
+      (para-check)
+
+      (make element gi: "TABLE"
+            attributes: '(("CLASS" "variablelist")
+			  ("BORDER" "0")
+			  ("CELLSPACING" "0")
+			  ("CELLPADDING" "4"))
+            (if %html40%
+                (make element gi: "TBODY"
+                      (with-mode variablelist-table
+                        (process-children)))
+                (with-mode variablelist-table
+                  (process-children))))
+      (para-check 'restart)))
+
+(mode variablelist-table
+  (element (variablelist title)
+    (make element gi: "TR"
+          attributes: '(("CLASS" "TITLE"))
+          (make element gi: "TH"
+                attributes: '(("ALIGN" "LEFT")
+                              ("VALIGN" "TOP")
+                              ("COLSPAN" "2"))
+                (process-children))))
+
+  (element varlistentry
+    (let* ((terms      (select-elements (children (current-node))
+                                        (normalize "term")))
+           (listitem   (select-elements (children (current-node))
+                                        (normalize "listitem"))))
+
+      (make element gi: "TR"
+            (make element gi: "TD"
+                  attributes: '(("ALIGN" "LEFT")
+                                ("VALIGN" "TOP"))
+                  (make empty-element gi: "A"
+                        attributes: (list
+                                     (list "NAME" (element-id))))
+                  (process-node-list terms))
+            (make element gi: "TD"
+                  attributes: '(("ALIGN" "LEFT")
+                                ("VALIGN" "TOP"))
+                  (process-node-list listitem)))))
+  
+  (element (varlistentry term)
+    (make sequence
+      (if %css-decoration%
+          (make element gi: "SPAN"
+                attributes: '(("STYLE" "white-space: nowrap"))
+                (process-children-trim))
+          (make element gi: "NOBR"
+                (process-children-trim)))
+      (if (not (last-sibling?))
+          (literal ", ")
+          (literal ""))))
+
+  (element (varlistentry listitem)
+    (process-children))
+)
+
+
+;; This overrides the refsect2 definition (copied from 1.20, dbrfntry.dsl).
+;; It puts a horizontal rule before each function/struct/... description,
+;; except the first one in the refsect1.
+(element refsect2
+  (make sequence
+    (if (first-sibling?)
+	(empty-sosofo)
+	(make empty-element gi: "HR"))
+    ($block-container$)))
+
+;; Override the book declaration, so that we generate a crossreference
+;; for the book
+
+(element book 
+  (let* ((bookinfo  (select-elements (children (current-node)) (normalize "bookinfo")))
+	 (ititle   (select-elements (children bookinfo) (normalize "title")))
+	 (title    (if (node-list-empty? ititle)
+		       (select-elements (children (current-node)) (normalize "title"))
+		       (node-list-first ititle)))
+	 (nl       (titlepage-info-elements (current-node) bookinfo))
+	 (tsosofo  (with-mode head-title-mode
+		     (process-node-list title)))
+	 (dedication (select-elements (children (current-node)) (normalize "dedication"))))
+    (make sequence
+     (html-document 
+      tsosofo
+      (make element gi: "DIV"
+	    attributes: '(("CLASS" "BOOK"))
+	    (if %generate-book-titlepage%
+		(make sequence
+		  (book-titlepage nl 'recto)
+		  (book-titlepage nl 'verso))
+		(empty-sosofo))
+	    
+	    (if (node-list-empty? dedication)
+		(empty-sosofo)
+		(with-mode dedication-page-mode
+		  (process-node-list dedication)))
+	    
+	    (if (not (generate-toc-in-front))
+		(process-children)
+		(empty-sosofo))
+	    
+	    (if %generate-book-toc%
+		(build-toc (current-node) (toc-depth (current-node)))
+		(empty-sosofo))
+	    
+	    ;;	  (let loop ((gilist %generate-book-lot-list%))
+	    ;;	    (if (null? gilist)
+	    ;;		(empty-sosofo)
+	    ;;		(if (not (node-list-empty? 
+	    ;;			  (select-elements (descendants (current-node))
+	    ;;					   (car gilist))))
+	    ;;		    (make sequence
+	    ;;		      (build-lot (current-node) (car gilist))
+	    ;;		      (loop (cdr gilist)))
+	    ;;		    (loop (cdr gilist)))))
+	  
+	    (if (generate-toc-in-front)
+		(process-children)
+		(empty-sosofo))))
+     (make entity 
+       system-id: "index.sgml"
+       (with-mode generate-index-mode
+	 (process-children))))))
+
+;; Mode for generating cross references
+
+(define (process-child-elements)
+  (process-node-list
+   (node-list-map (lambda (snl)
+                    (if (equal? (node-property 'class-name snl) 'element)
+                        snl
+                        (empty-node-list)))
+                  (children (current-node)))))
+
+(mode generate-index-mode
+  (element anchor
+    (if (attribute-string "href" (current-node))
+	(empty-sosofo)
+	(make formatting-instruction data:
+	      (string-append "\less-than-sign;ANCHOR id =\""
+			     (attribute-string "id" (current-node))
+			     "\" href=\""
+			     (if (not (string=? gtkdoc-bookname ""))
+				 (string-append gtkdoc-bookname "/")
+				 "")
+			     (href-to (current-node))
+			     "\"\greater-than-sign;
+"))))
+
+  ;; We also want to be able to link to complete RefEntry.
+  (element refentry
+    (make sequence
+      (make formatting-instruction data:
+	    (string-append "\less-than-sign;ANCHOR id =\""
+			   (attribute-string "id" (current-node))
+			   "\" href=\""
+			   (if (not (string=? gtkdoc-bookname ""))
+			       (string-append gtkdoc-bookname "/")
+			       "")
+			   (href-to (current-node))
+			   "\"\greater-than-sign;
+"))
+      (process-child-elements)))
+
+  (default
+    (process-child-elements)))
+
+;; For hypertext links for which no target is found in the document, we output
+;; our own special tag which we use later to resolve cross-document links.
+(element link 
+  (let* ((target (element-with-id (attribute-string (normalize "linkend")))))
+    (if (node-list-empty? target)
+      (make element gi: "GTKDOCLINK"
+	    attributes: (list
+			 (list "HREF" (attribute-string (normalize "linkend"))))
+            (process-children))
+      (make element gi: "A"
+            attributes: (list
+                         (list "HREF" (href-to target)))
+            (process-children)))))
+
+
+;; This overrides default-header-nav-tbl-noff (copied from 1.20, dbnavig.dsl).
+;; I want 'Home' and 'Up' links at the top of each page, and white text on
+;; black.
+(define (default-header-nav-tbl-noff elemnode prev next prevsib nextsib)
+  (let* ((up (parent elemnode))
+	 (home (nav-home elemnode))
+	 (show-title? (nav-banner? elemnode))
+	 (title-sosofo
+	      (make element gi: "TH"
+		    attributes: (list
+				 (list "WIDTH" "100%")
+				 (list "align" "center"))
+		    (if show-title?
+			(nav-banner elemnode)
+			(empty-sosofo))))
+	 (show-banner? (or show-title?
+			   (not (node-list-empty? prev))
+			   (not (node-list-empty? next))
+			   (nav-context? elemnode)))
+	 (banner-sosofo
+	      (make element gi: "TR"
+		    attributes: (list
+				 (list "VALIGN" "middle"))
+		    (if (not (node-list-empty? prev))
+			(make element gi: "TD"
+			      (make element gi: "A"
+				    attributes: (list
+						 (list "ACCESSKEY" "p")
+						 (list "HREF"
+						       (href-to prev)))
+				    (make empty-element gi: "IMG"
+					  attributes: (list
+						       (list "SRC" "left.png")
+						       (list "WIDTH" "16")
+						       (list "HEIGHT" "16")
+						       (list "BORDER" "0")
+						       (list "ALT" "Prev")))))
+			(empty-sosofo))
+		    (if (nav-up? elemnode)
+			(make element gi: "TD"
+			      (make element gi: "A"
+				    attributes: (list
+						 (list "ACCESSKEY" "u")
+						 (list "HREF"
+						       (href-to up)))
+				    (make empty-element gi: "IMG"
+					  attributes: (list
+						       (list "SRC" "up.png")
+						       (list "WIDTH" "16")
+						       (list "HEIGHT" "16")
+						       (list "BORDER" "0")
+						       (list "ALT" "Up")))))
+			(empty-sosofo))
+		    (if (nav-home? elemnode)
+			(make element gi: "TD"
+			      (make element gi: "A"
+				    attributes: (list
+						 (list "ACCESSKEY" "h")
+						 (list "HREF"
+						       (href-to home)))
+				    (make empty-element gi: "IMG"
+					  attributes: (list
+						       (list "SRC" "home.png")
+						       (list "WIDTH" "16")
+						       (list "HEIGHT" "16")
+						       (list "BORDER" "0")
+						       (list "ALT" "Home")))))
+			(empty-sosofo))
+		    title-sosofo
+		    (if (not (node-list-empty? next))
+			(make element gi: "TD"
+			      (make element gi: "A"
+				    attributes: (list
+						 (list "ACCESSKEY" "n")
+						 (list "HREF"
+						       (href-to next)))
+				    (make empty-element gi: "IMG"
+					  attributes: (list
+						       (list "SRC" "right.png")
+						       (list "WIDTH" "16")
+						       (list "HEIGHT" "16")
+						       (list "BORDER" "0")
+						       (list "ALT" "Next")))))
+			(empty-sosofo)))))
+	 
+    (if show-banner?
+	(make element gi: "TABLE"
+	      attributes: (list
+			   (list "WIDTH" %gentext-nav-tblwidth%)
+			   (list "CLASS" "navigation")
+			   (list "SUMMARY" "Navigation header")
+			   (list "CELLPADDING" "2")
+			   (list "CELLSPACING" "2"))
+	      banner-sosofo)
+	(empty-sosofo))))
+
+;; This overrides default-footer-nav-tbl (copied from 1.20, dbnavig.dsl).
+;; It matches the header above.
+(define (default-footer-nav-tbl elemnode prev next prevsib nextsib)
+  (let* ((show-footer? (or (not (node-list-empty? prev))
+			  (not (node-list-empty? next))))
+	 (footer-sosofo
+	     (make element gi: "TR"
+		   attributes: (list
+				(list "VALIGN" "middle"))
+		   (make element gi: "TD"
+			 attributes: (list
+				      (list "ALIGN" "left"))
+			 (if (not (node-list-empty? prev))
+			     (make element gi: "A"
+				   attributes: (list
+						(list "ACCESSKEY" "p")
+						(list "HREF" (href-to prev)))
+				   (make element gi: "B"
+					 (make entity-ref name: "lt")
+					 (make entity-ref name: "lt")
+					 (make entity-ref name: "lt")
+					 (make entity-ref name: "nbsp")
+					 (element-title-sosofo prev)))
+			     (empty-sosofo)))
+		   (make element gi: "TD"
+			 attributes: (list
+				      (list "ALIGN" "right"))
+			 (if (not (node-list-empty? next))
+			     (make element gi: "A"
+				   attributes: (list
+						(list "ACCESSKEY" "n")
+						(list "HREF" (href-to next)))
+				   (make element gi: "B"
+					 (element-title-sosofo next)
+					 (make entity-ref name: "nbsp")
+					 (make entity-ref name: "gt")
+					 (make entity-ref name: "gt")
+					 (make entity-ref name: "gt")))
+			     (empty-sosofo))))))
+  
+    (if show-footer?
+	(make element gi: "TABLE"
+	      attributes: (list
+			   (list "CLASS" "navigation")
+			   (list "WIDTH" %gentext-nav-tblwidth%)
+			   (list "SUMMARY" "Navigation footer")
+			   (list "CELLPADDING" "2")
+			   (list "CELLSPACING" "2"))
+	      footer-sosofo)
+	(empty-sosofo))))
+
+
+(define ($section-body$)
+  (make sequence
+    (make empty-element gi: "BR"
+	  attributes: (list (list "CLEAR" "all")))
+    (make element gi: "DIV"
+	  attributes: (list (list "CLASS" (gi)))
+	  ($section-separator$)
+	  ($section-title$)
+	  (process-children))))
+
+</style-specification-body>
+</style-specification>
+<external-specification id="docbook" document="dbstyle">
+</style-sheet>
 
=== modified file 'gtk-doc.dsl.in'
--- gtk-doc.dsl.in	2004-05-15 23:11:36 +0000
+++ gtk-doc.dsl.in	2014-02-17 20:15:47 +0000
@@ -333,8 +333,8 @@
 				    (make empty-element gi: "IMG"
 					  attributes: (list
 						       (list "SRC" "left.png")
-						       (list "WIDTH" "24")
-						       (list "HEIGHT" "24")
+						       (list "WIDTH" "16")
+						       (list "HEIGHT" "16")
 						       (list "BORDER" "0")
 						       (list "ALT" "Prev")))))
 			(empty-sosofo))
@@ -348,8 +348,8 @@
 				    (make empty-element gi: "IMG"
 					  attributes: (list
 						       (list "SRC" "up.png")
-						       (list "WIDTH" "24")
-						       (list "HEIGHT" "24")
+						       (list "WIDTH" "16")
+						       (list "HEIGHT" "16")
 						       (list "BORDER" "0")
 						       (list "ALT" "Up")))))
 			(empty-sosofo))
@@ -363,8 +363,8 @@
 				    (make empty-element gi: "IMG"
 					  attributes: (list
 						       (list "SRC" "home.png")
-						       (list "WIDTH" "24")
-						       (list "HEIGHT" "24")
+						       (list "WIDTH" "16")
+						       (list "HEIGHT" "16")
 						       (list "BORDER" "0")
 						       (list "ALT" "Home")))))
 			(empty-sosofo))
@@ -379,8 +379,8 @@
 				    (make empty-element gi: "IMG"
 					  attributes: (list
 						       (list "SRC" "right.png")
-						       (list "WIDTH" "24")
-						       (list "HEIGHT" "24")
+						       (list "WIDTH" "16")
+						       (list "HEIGHT" "16")
 						       (list "BORDER" "0")
 						       (list "ALT" "Next")))))
 			(empty-sosofo)))))
 
=== modified file 'gtk-doc.flat.make'
--- gtk-doc.flat.make	2013-12-19 07:58:53 +0000
+++ gtk-doc.flat.make	2014-02-17 20:15:47 +0000
@@ -49,9 +49,13 @@
 	$(DOC_MODULE)-undeclared.txt \
 	$(DOC_MODULE)-unused.txt
 
-CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS)
-
-if ENABLE_GTK_DOC
+gtkdoc-check.test: Makefile
+	$(AM_V_GEN)echo "#!/bin/sh -e" > $@; \
+		echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \
+		chmod +x $@
+
+CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test
+
 if GTK_DOC_BUILD_HTML
 HTML_BUILD_STAMP=html-build.stamp
 else
@@ -63,9 +67,11 @@
 PDF_BUILD_STAMP=
 endif
 
-all-local: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
-else
-all-local:
+all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
+.PHONY: all-gtk-doc
+
+if ENABLE_GTK_DOC
+all-local: all-gtk-doc
 endif
 
 docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
@@ -83,12 +89,14 @@
 	    files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
 	    if test "x$$files" != "x" ; then \
 	        for file in $$files ; do \
+	            destdir=`dirname $(abs_builddir)/$$file` ;\
+	            test -d "$$destdir" || mkdir -p "$$destdir"; \
 	            test -f $(abs_srcdir)/$$file && \
-	                cp -pu $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
+	                cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
 	        done; \
 	    fi; \
 	    test -d $(abs_srcdir)/tmpl && \
-	        { cp -rp $(abs_srcdir)/tmpl $(abs_builddir)/; \
+	        { cp -pR $(abs_srcdir)/tmpl $(abs_builddir)/; \
 	        chmod -R u+w $(abs_builddir)/tmpl; } \
 	fi
 	$(AM_V_at)touch setup-build.stamp
@@ -103,7 +111,7 @@
 GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY))
 GTK_DOC_V_INTROSPECT_0=@echo "  DOC   Introspecting gobjects";
 
-scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB)
+scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
 	$(GTK_DOC_V_SCAN)_source_dir='' ; \
 	for i in $(DOC_SOURCE_DIR) ; do \
 	    _source_dir="$${_source_dir} --source-dir=$$i" ; \
@@ -139,7 +147,7 @@
 	$(GTK_DOC_V_TMPL)gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS)
 	$(AM_V_at)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
 	  if test -w $(abs_srcdir) ; then \
-	    cp -rp $(abs_builddir)/tmpl $(abs_srcdir)/; \
+	    cp -pR $(abs_builddir)/tmpl $(abs_srcdir)/; \
 	  fi \
 	fi
 	$(AM_V_at)touch tmpl-build.stamp
@@ -157,7 +165,7 @@
 GTK_DOC_V_XML_0=@echo "  DOC   Building XML";
 
 sgml-build.stamp: tmpl.stamp $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files)
-	$(GTK_DOC_V_XML)-chmod -R u+w $(srcdir) && _source_dir='' ; \
+	-$(GTK_DOC_V_XML)chmod -R u+w $(srcdir) && _source_dir='' ; \
 	for i in $(DOC_SOURCE_DIR) ; do \
 	    _source_dir="$${_source_dir} --source-dir=$$i" ; \
 	done ; \
@@ -235,6 +243,9 @@
 clean-local:
 	@rm -f *~ *.bak
 	@rm -rf .libs
+	@if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \
+	  rm -f $(DOC_MODULE).types; \
+	fi
 
 distclean-local:
 	@rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \
@@ -280,15 +291,17 @@
 #
 # Require gtk-doc when making dist
 #
-if ENABLE_GTK_DOC
+if HAVE_GTK_DOC
 dist-check-gtkdoc: docs
 else
 dist-check-gtkdoc:
-	@echo "*** gtk-doc must be installed and enabled in order to make dist"
+	@echo "*** gtk-doc is needed to run 'make dist'.         ***"
+	@echo "*** gtk-doc was not found when 'configure' ran.   ***"
+	@echo "*** please install gtk-doc and rerun 'configure'. ***"
 	@false
 endif
 
-dist-hook: dist-check-gtkdoc dist-hook-local
+dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local
 	@mkdir $(distdir)/tmpl
 	@mkdir $(distdir)/html
 	@-cp ./tmpl/*.sgml $(distdir)/tmpl
 
=== modified file 'gtk-doc.m4'
--- gtk-doc.m4	2013-12-19 07:58:53 +0000
+++ gtk-doc.m4	2014-02-17 20:15:47 +0000
@@ -1,6 +1,6 @@
 dnl -*- mode: autoconf -*-
 
-# serial 1
+# serial 2
 
 dnl Usage:
 dnl   GTK_DOC_CHECK([minimum-gtk-doc-version])
@@ -10,8 +10,24 @@
   AC_BEFORE([AC_PROG_LIBTOOL],[$0])dnl setup libtool first
   AC_BEFORE([AM_PROG_LIBTOOL],[$0])dnl setup libtool first
 
+  ifelse([$1],[],[gtk_doc_requires="gtk-doc"],[gtk_doc_requires="gtk-doc >= $1"])
+  AC_MSG_CHECKING([for gtk-doc])
+  PKG_CHECK_EXISTS([$gtk_doc_requires],[have_gtk_doc=yes],[have_gtk_doc=no])
+  AC_MSG_RESULT($have_gtk_doc)
+
+  if test "$have_gtk_doc" = "no"; then
+      AC_MSG_WARN([
+  You will not be able to create source packages with 'make dist'
+  because $gtk_doc_requires is not found.])
+  fi
+
   dnl check for tools we added during development
-  AC_PATH_PROG([GTKDOC_CHECK],[gtkdoc-check])
+  dnl Use AC_CHECK_PROG to avoid the check target using an absolute path that
+  dnl may not be writable by the user. Currently, automake requires that the
+  dnl test name must end in '.test'.
+  dnl https://bugzilla.gnome.org/show_bug.cgi?id=701638
+  AC_CHECK_PROG([GTKDOC_CHECK],[gtkdoc-check],[gtkdoc-check.test])
+  AC_PATH_PROG([GTKDOC_CHECK_PATH],[gtkdoc-check])
   AC_PATH_PROGS([GTKDOC_REBASE],[gtkdoc-rebase],[true])
   AC_PATH_PROG([GTKDOC_MKPDF],[gtkdoc-mkpdf])
 
@@ -28,22 +44,22 @@
                    [use gtk-doc to build documentation [[default=no]]]),,
     [enable_gtk_doc=no])
 
-  if test x$enable_gtk_doc = xyes; then
-    ifelse([$1],[],
-      [PKG_CHECK_EXISTS([gtk-doc],,
-                        AC_MSG_ERROR([gtk-doc not installed and --enable-gtk-doc requested]))],
-      [PKG_CHECK_EXISTS([gtk-doc >= $1],,
-                        AC_MSG_ERROR([You need to have gtk-doc >= $1 installed to build $PACKAGE_NAME]))])
-    dnl don't check for glib if we build glib
-    if test "x$PACKAGE_NAME" != "xglib"; then
-      dnl don't fail if someone does not have glib
-      PKG_CHECK_MODULES(GTKDOC_DEPS, glib-2.0 >= 2.10.0 gobject-2.0  >= 2.10.0,,[:])
-    fi
-  fi
-
   AC_MSG_CHECKING([whether to build gtk-doc documentation])
   AC_MSG_RESULT($enable_gtk_doc)
 
+  if test "x$enable_gtk_doc" = "xyes" && test "$have_gtk_doc" = "no"; then
+    AC_MSG_ERROR([
+  You must have $gtk_doc_requires installed to build documentation for
+  $PACKAGE_NAME. Please install gtk-doc or disable building the
+  documentation by adding '--disable-gtk-doc' to '[$]0'.])
+  fi
+
+  dnl don't check for glib if we build glib
+  if test "x$PACKAGE_NAME" != "xglib"; then
+    dnl don't fail if someone does not have glib
+    PKG_CHECK_MODULES(GTKDOC_DEPS, glib-2.0 >= 2.10.0 gobject-2.0  >= 2.10.0,,[:])
+  fi
+
   dnl enable/disable output formats
   AC_ARG_ENABLE([gtk-doc-html],
     AS_HELP_STRING([--enable-gtk-doc-html],
@@ -63,6 +79,7 @@
   fi
   AC_SUBST([AM_DEFAULT_VERBOSITY])
 
+  AM_CONDITIONAL([HAVE_GTK_DOC], [test x$have_gtk_doc = xyes])
   AM_CONDITIONAL([ENABLE_GTK_DOC], [test x$enable_gtk_doc = xyes])
   AM_CONDITIONAL([GTK_DOC_BUILD_HTML], [test x$enable_gtk_doc_html = xyes])
   AM_CONDITIONAL([GTK_DOC_BUILD_PDF], [test x$enable_gtk_doc_pdf = xyes])
 
=== modified file 'gtk-doc.make'
--- gtk-doc.make	2013-12-19 07:58:53 +0000
+++ gtk-doc.make	2014-02-17 20:15:47 +0000
@@ -49,9 +49,13 @@
 	$(DOC_MODULE)-undeclared.txt \
 	$(DOC_MODULE)-unused.txt
 
-CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS)
-
-if ENABLE_GTK_DOC
+gtkdoc-check.test: Makefile
+	$(AM_V_GEN)echo "#!/bin/sh -e" > $@; \
+		echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \
+		chmod +x $@
+
+CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test
+
 if GTK_DOC_BUILD_HTML
 HTML_BUILD_STAMP=html-build.stamp
 else
@@ -63,9 +67,11 @@
 PDF_BUILD_STAMP=
 endif
 
-all-local: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
-else
-all-local:
+all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
+.PHONY: all-gtk-doc
+
+if ENABLE_GTK_DOC
+all-local: all-gtk-doc
 endif
 
 docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
@@ -83,12 +89,14 @@
 	    files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
 	    if test "x$$files" != "x" ; then \
 	        for file in $$files ; do \
+	            destdir=`dirname $(abs_builddir)/$$file` ;\
+	            test -d "$$destdir" || mkdir -p "$$destdir"; \
 	            test -f $(abs_srcdir)/$$file && \
-	                cp -pu $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
+	                cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
 	        done; \
 	    fi; \
 	    test -d $(abs_srcdir)/tmpl && \
-	        { cp -rp $(abs_srcdir)/tmpl $(abs_builddir)/; \
+	        { cp -pR $(abs_srcdir)/tmpl $(abs_builddir)/; \
 	        chmod -R u+w $(abs_builddir)/tmpl; } \
 	fi
 	$(AM_V_at)touch setup-build.stamp
@@ -103,7 +111,7 @@
 GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY))
 GTK_DOC_V_INTROSPECT_0=@echo "  DOC   Introspecting gobjects";
 
-scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB)
+scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
 	$(GTK_DOC_V_SCAN)_source_dir='' ; \
 	for i in $(DOC_SOURCE_DIR) ; do \
 	    _source_dir="$${_source_dir} --source-dir=$$i" ; \
@@ -139,7 +147,7 @@
 	$(GTK_DOC_V_TMPL)gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS)
 	$(AM_V_at)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
 	  if test -w $(abs_srcdir) ; then \
-	    cp -rp $(abs_builddir)/tmpl $(abs_srcdir)/; \
+	    cp -pR $(abs_builddir)/tmpl $(abs_srcdir)/; \
 	  fi \
 	fi
 	$(AM_V_at)touch tmpl-build.stamp
@@ -157,7 +165,7 @@
 GTK_DOC_V_XML_0=@echo "  DOC   Building XML";
 
 sgml-build.stamp: tmpl.stamp $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files)
-	$(GTK_DOC_V_XML)-chmod -R u+w $(srcdir) && _source_dir='' ; \
+	-$(GTK_DOC_V_XML)chmod -R u+w $(srcdir) && _source_dir='' ; \
 	for i in $(DOC_SOURCE_DIR) ; do \
 	    _source_dir="$${_source_dir} --source-dir=$$i" ; \
 	done ; \
@@ -235,6 +243,9 @@
 clean-local:
 	@rm -f *~ *.bak
 	@rm -rf .libs
+	@if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \
+	  rm -f $(DOC_MODULE).types; \
+	fi
 
 distclean-local:
 	@rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \
@@ -280,15 +291,17 @@
 #
 # Require gtk-doc when making dist
 #
-if ENABLE_GTK_DOC
+if HAVE_GTK_DOC
 dist-check-gtkdoc: docs
 else
 dist-check-gtkdoc:
-	@echo "*** gtk-doc must be installed and enabled in order to make dist"
+	@echo "*** gtk-doc is needed to run 'make dist'.         ***"
+	@echo "*** gtk-doc was not found when 'configure' ran.   ***"
+	@echo "*** please install gtk-doc and rerun 'configure'. ***"
 	@false
 endif
 
-dist-hook: dist-check-gtkdoc dist-hook-local
+dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local
 	@mkdir $(distdir)/tmpl
 	@mkdir $(distdir)/html
 	@-cp ./tmpl/*.sgml $(distdir)/tmpl
 
=== modified file 'gtk-doc.notmpl-flat.make'
--- gtk-doc.notmpl-flat.make	2013-12-19 07:58:53 +0000
+++ gtk-doc.notmpl-flat.make	2014-02-17 20:15:47 +0000
@@ -49,9 +49,13 @@
 	$(DOC_MODULE)-undeclared.txt \
 	$(DOC_MODULE)-unused.txt
 
-CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS)
-
-if ENABLE_GTK_DOC
+gtkdoc-check.test: Makefile
+	$(AM_V_GEN)echo "#!/bin/sh -e" > $@; \
+		echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \
+		chmod +x $@
+
+CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test
+
 if GTK_DOC_BUILD_HTML
 HTML_BUILD_STAMP=html-build.stamp
 else
@@ -63,9 +67,11 @@
 PDF_BUILD_STAMP=
 endif
 
-all-local: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
-else
-all-local:
+all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
+.PHONY: all-gtk-doc
+
+if ENABLE_GTK_DOC
+all-local: all-gtk-doc
 endif
 
 docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
@@ -83,8 +89,10 @@
 	    files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
 	    if test "x$$files" != "x" ; then \
 	        for file in $$files ; do \
+	            destdir=`dirname $(abs_builddir)/$$file`; \
+	            test -d "$$destdir" || mkdir -p "$$destdir"; \
 	            test -f $(abs_srcdir)/$$file && \
-	                cp -pu $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
+	                cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
 	        done; \
 	    fi; \
 	fi
@@ -101,7 +109,7 @@
 GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY))
 GTK_DOC_V_INTROSPECT_0=@echo "  DOC   Introspecting gobjects";
 
-scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB)
+scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
 	$(GTK_DOC_V_SCAN)_source_dir='' ; \
 	for i in $(DOC_SOURCE_DIR) ; do \
 	    _source_dir="$${_source_dir} --source-dir=$$i" ; \
@@ -212,6 +220,9 @@
 clean-local:
 	@rm -f *~ *.bak
 	@rm -rf .libs
+	@if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \
+	  rm -f $(DOC_MODULE).types; \
+	fi
 
 distclean-local:
 	@rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \
@@ -256,15 +267,17 @@
 #
 # Require gtk-doc when making dist
 #
-if ENABLE_GTK_DOC
+if HAVE_GTK_DOC
 dist-check-gtkdoc: docs
 else
 dist-check-gtkdoc:
-	@echo "*** gtk-doc must be installed and enabled in order to make dist"
+	@echo "*** gtk-doc is needed to run 'make dist'.         ***"
+	@echo "*** gtk-doc was not found when 'configure' ran.   ***"
+	@echo "*** please install gtk-doc and rerun 'configure'. ***"
 	@false
 endif
 
-dist-hook: dist-check-gtkdoc dist-hook-local
+dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local
 	@mkdir $(distdir)/html
 	@cp ./html/* $(distdir)/html
 	@-cp ./$(DOC_MODULE).pdf $(distdir)/
 
=== modified file 'gtk-doc.notmpl.make'
--- gtk-doc.notmpl.make	2013-12-19 07:58:53 +0000
+++ gtk-doc.notmpl.make	2014-02-17 20:15:47 +0000
@@ -49,9 +49,13 @@
 	$(DOC_MODULE)-undeclared.txt \
 	$(DOC_MODULE)-unused.txt
 
-CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS)
-
-if ENABLE_GTK_DOC
+gtkdoc-check.test: Makefile
+	$(AM_V_GEN)echo "#!/bin/sh -e" > $@; \
+		echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \
+		chmod +x $@
+
+CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test
+
 if GTK_DOC_BUILD_HTML
 HTML_BUILD_STAMP=html-build.stamp
 else
@@ -63,9 +67,11 @@
 PDF_BUILD_STAMP=
 endif
 
-all-local: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
-else
-all-local:
+all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
+.PHONY: all-gtk-doc
+
+if ENABLE_GTK_DOC
+all-local: all-gtk-doc
 endif
 
 docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
@@ -83,8 +89,10 @@
 	    files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
 	    if test "x$$files" != "x" ; then \
 	        for file in $$files ; do \
+	            destdir=`dirname $(abs_builddir)/$$file`; \
+	            test -d "$$destdir" || mkdir -p "$$destdir"; \
 	            test -f $(abs_srcdir)/$$file && \
-	                cp -pu $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
+	                cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
 	        done; \
 	    fi; \
 	fi
@@ -101,7 +109,7 @@
 GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY))
 GTK_DOC_V_INTROSPECT_0=@echo "  DOC   Introspecting gobjects";
 
-scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB)
+scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
 	$(GTK_DOC_V_SCAN)_source_dir='' ; \
 	for i in $(DOC_SOURCE_DIR) ; do \
 	    _source_dir="$${_source_dir} --source-dir=$$i" ; \
@@ -212,6 +220,9 @@
 clean-local:
 	@rm -f *~ *.bak
 	@rm -rf .libs
+	@if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \
+	  rm -f $(DOC_MODULE).types; \
+	fi
 
 distclean-local:
 	@rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \
@@ -256,15 +267,17 @@
 #
 # Require gtk-doc when making dist
 #
-if ENABLE_GTK_DOC
+if HAVE_GTK_DOC
 dist-check-gtkdoc: docs
 else
 dist-check-gtkdoc:
-	@echo "*** gtk-doc must be installed and enabled in order to make dist"
+	@echo "*** gtk-doc is needed to run 'make dist'.         ***"
+	@echo "*** gtk-doc was not found when 'configure' ran.   ***"
+	@echo "*** please install gtk-doc and rerun 'configure'. ***"
 	@false
 endif
 
-dist-hook: dist-check-gtkdoc dist-hook-local
+dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local
 	@mkdir $(distdir)/html
 	@cp ./html/* $(distdir)/html
 	@-cp ./$(DOC_MODULE).pdf $(distdir)/
 
=== modified file 'gtk-doc.pc.in'
--- gtk-doc.pc.in	2011-05-27 09:29:25 +0000
+++ gtk-doc.pc.in	2014-02-17 20:15:47 +0000
@@ -1,6 +1,6 @@
 prefix=@prefix@
 exec_prefix=@exec_prefix@
-data_dir=@PACKAGE_DATA_DIR@
+data_dir=@datadir@/@PACKAGE@/data
 
 Name: gtk-doc
 Description: API documentation generator
 
=== modified file 'gtk-doc.spec'
--- gtk-doc.spec	2013-12-19 07:58:53 +0000
+++ gtk-doc.spec	2014-02-17 20:15:47 +0000
@@ -2,7 +2,7 @@
 
 Summary: 	GTK+ DocBook Documentation Generator
 Name: 		gtk-doc
-Version: 	1.19
+Version: 	1.20
 Release: 	1
 License: 	GPL
 Group: 		Utilities/Text
 
=== modified file 'gtk-doc.xsl'
--- gtk-doc.xsl	2013-12-19 07:58:53 +0000
+++ gtk-doc.xsl	2014-02-17 20:15:47 +0000
@@ -20,6 +20,7 @@
 
   <!-- change some parameters -->
   <!-- http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html -->
+  <xsl:param name="admon.style"/>
   <xsl:param name="toc.section.depth">2</xsl:param>
   <xsl:param name="generate.toc">
     book	toc
@@ -61,6 +62,9 @@
   <xsl:param name="gtkdoc.version" select="''"/>
   <xsl:param name="gtkdoc.bookname" select="''"/>
 
+  <!-- Override the typical template to prevent showing titles -->
+  <xsl:param name="admon.textlabel" select="0"/>
+
   <!-- ========================================================= -->
 
   <!-- l10n is slow, we don't ue it, so we'd like to turn it off
@@ -390,6 +394,15 @@
     <xsl:apply-imports/>
   </xsl:template>
 
+ <xsl:template name="user.head.title">
+   <xsl:param name="node" select="."/>
+   <xsl:param name="title"/>
+   <xsl:variable name="home" select="/*[1]"/>
+   <title>
+     <xsl:apply-templates select="$home" mode="object.title.markup"/>: <xsl:copy-of select="$title"/>
+   </title>
+  </xsl:template>
+
   <xsl:template name="user.head.content">
     <xsl:if test="$gtkdoc.version">
       <meta name="generator" content="GTK-Doc V{$gtkdoc.version} (XML mode)"/>
@@ -454,242 +467,199 @@
 
     <xsl:if test="$suppress.navigation = '0' and $home != .">
       <table class="navigation" id="top" width="100%"
-             summary = "Navigation header" cellpadding="2" cellspacing="2">
+             summary = "Navigation header" cellpadding="2" cellspacing="10">
         <tr valign="middle">
-          <xsl:choose>
-            <xsl:when test="count($prev) > 0">
-              <td>
-                <a accesskey="p">
-                  <xsl:attribute name="href">
-                    <xsl:call-template name="href.target">
-                      <xsl:with-param name="object" select="$prev"/>
-                    </xsl:call-template>
-                  </xsl:attribute>
-                  <img src="left.png" width="24" height="24" border="0">
-                    <xsl:attribute name="alt">
-                      <xsl:call-template name="gentext">
-                        <xsl:with-param name="key">nav-prev</xsl:with-param>
-                      </xsl:call-template>
-                    </xsl:attribute>
-                  </img>
-                </a>
-              </td>
-            </xsl:when>
-            <xsl:otherwise>
-              <td>&#160;</td>
-            </xsl:otherwise>
-          </xsl:choose>
-          <xsl:choose>
-            <xsl:when test="count($up) > 0 and $up != $home">
-              <td>
-                <a accesskey="u">
-                  <xsl:attribute name="href">
-                    <xsl:call-template name="href.target">
-                      <xsl:with-param name="object" select="$up"/>
-                    </xsl:call-template>
-                  </xsl:attribute>
-                  <img src="up.png" width="24" height="24" border="0">
-                    <xsl:attribute name="alt">
-                      <xsl:call-template name="gentext">
-                        <xsl:with-param name="key">nav-up</xsl:with-param>
-                      </xsl:call-template>
-                    </xsl:attribute>
-                  </img>
-                </a>
-              </td>
-            </xsl:when>
-            <xsl:otherwise>
-              <td>&#160;</td>
-            </xsl:otherwise>
-          </xsl:choose>
-          <xsl:choose>
-            <xsl:when test="$home != .">
-              <td>
-                <a accesskey="h">
-                  <xsl:attribute name="href">
-                    <xsl:call-template name="href.target">
-                      <xsl:with-param name="object" select="$home"/>
-                    </xsl:call-template>
-                  </xsl:attribute>
-                  <img src="home.png" width="24" height="24" border="0">
-                    <xsl:attribute name="alt">
-                      <xsl:call-template name="gentext">
-                        <xsl:with-param name="key">nav-home</xsl:with-param>
-                      </xsl:call-template>
-                    </xsl:attribute>
-                  </img>
-                </a>
-              </td>
-            </xsl:when>
-            <xsl:otherwise>
-              <td>&#160;</td>
-            </xsl:otherwise>
-          </xsl:choose>
-          <th width="100%" align="center">
-            <xsl:apply-templates select="$home" mode="object.title.markup"/>
-          </th>
-          <xsl:choose>
-            <xsl:when test="count($next) > 0">
-              <td>
-                <a accesskey="n">
-                  <xsl:attribute name="href">
-                    <xsl:call-template name="href.target">
-                      <xsl:with-param name="object" select="$next"/>
-                    </xsl:call-template>
-                  </xsl:attribute>
-                  <img src="right.png" width="24" height="24" border="0">
-                    <xsl:attribute name="alt">
-                      <xsl:call-template name="gentext">
-                        <xsl:with-param name="key">nav-next</xsl:with-param>
-                      </xsl:call-template>
-                    </xsl:attribute>
-                  </img>
-                </a>
-              </td>
-            </xsl:when>
-            <xsl:otherwise>
-              <td>&#160;</td>
-            </xsl:otherwise>
-          </xsl:choose>
-        </tr>
-        <!--<xsl:if test="name()='refentry'"-->
-        <xsl:choose>
-          <xsl:when test="count($refsections) > 0">
-            <tr>
-              <td colspan="5" class="shortcuts">
-                <xsl:if test="count($sect_synopsis) > 0">
-                  <a href="#{$section_id}.synopsis" class="shortcut">Top</a>
-                </xsl:if>
+          <td width="100%" align="left" class="shortcuts">
+            <!--<xsl:if test="name()='refentry'"-->
+            <xsl:choose>
+              <xsl:when test="count($refsections) > 0">
+                <a href="#" class="shortcut">Top</a>
                 <xsl:if test="count($sect_desc) > 0">
-                  &#160;|&#160;
+                  <span id="nav_description">&#160;<span class="dim">|</span>&#160;
                   <a href="#{$section_id}.description" class="shortcut">
                     <xsl:value-of select="./refsect1[@role='desc']/title"/>
-                  </a>
+                  </a></span>
                 </xsl:if>
                 <xsl:if test="count($sect_object_hierarchy) > 0">
-                  &#160;|&#160;
+                  <span id="nav_hierarchy">&#160;<span class="dim">|</span>&#160;
                   <a href="#{$section_id}.object-hierarchy" class="shortcut">
                     <xsl:value-of select="./refsect1[@role='object_hierarchy']/title"/>
-                  </a>
+                  </a></span>
                 </xsl:if>
                 <xsl:if test="count($sect_impl_interfaces) > 0">
-                  &#160;|&#160;
+                  <span id="nav_interfaces">&#160;<span class="dim">|</span>&#160;
                   <a href="#{$section_id}.implemented-interfaces" class="shortcut">
                     <xsl:value-of select="./refsect1[@role='impl_interfaces']/title"/>
-                  </a>
+                  </a></span>
                 </xsl:if>
                 <xsl:if test="count($sect_prerequisites) > 0">
-                  &#160;|&#160;
+                  <span id="nav_prerequisites">&#160;<span class="dim">|</span>&#160;
                   <a href="#{$section_id}.prerequisites" class="shortcut">
                     <xsl:value-of select="./refsect1[@role='prerequisites']/title"/>
-                  </a>
+                  </a></span>
                 </xsl:if>
                 <xsl:if test="count($sect_derived_interfaces) > 0">
-                  &#160;|&#160;
+                  <span id="nav_derived_interfaces">&#160;<span class="dim">|</span>&#160;
                   <a href="#{$section_id}.derived-interfaces" class="shortcut">
                     <xsl:value-of select="./refsect1[@role='derived_interfaces']/title"/>
-                  </a>
+                  </a></span>
                 </xsl:if>
                 <xsl:if test="count($sect_implementations) > 0">
-                  &#160;|&#160;
+                  <span id="nav_implementations">&#160;<span class="dim">|</span>&#160;
                   <a href="#{$section_id}.implementations" class="shortcut">
                     <xsl:value-of select="./refsect1[@role='implementations']/title"/>
-                  </a>
+                  </a></span>
                 </xsl:if>
                 <xsl:if test="count($sect_properties) > 0">
-                  &#160;|&#160;
+                  <span id="nav_properties">&#160;<span class="dim">|</span>&#160;
                   <a href="#{$section_id}.properties" class="shortcut">
                     <xsl:value-of select="./refsect1[@role='properties']/title"/>
-                  </a>
+                  </a></span>
                 </xsl:if>
                 <xsl:if test="count($sect_child_properties) > 0">
-                  &#160;|&#160;
+                  <span id="nav_child_properties">&#160;<span class="dim">|</span>&#160;
                   <a href="#{$section_id}.child-properties" class="shortcut">
                     <xsl:value-of select="./refsect1[@role='child_properties']/title"/>
-                  </a>
+                  </a></span>
                 </xsl:if>
                 <xsl:if test="count($sect_style_properties) > 0">
-                  &#160;|&#160;
+                  <span id="nav_style_properties">&#160;<span class="dim">|</span>&#160;
                   <a href="#{$section_id}.style-properties" class="shortcut">
                     <xsl:value-of select="./refsect1[@role='style_properties']/title"/>
-                  </a>
+                  </a></span>
                 </xsl:if>
                 <xsl:if test="count($sect_signal_proto) > 0">
-                  &#160;|&#160;
+                  <span id="nav_signals">&#160;<span class="dim">|</span>&#160;
                   <a href="#{$section_id}.signals" class="shortcut">
                     <xsl:value-of select="./refsect1[@role='signal_proto']/title"/>
-                  </a>
-                </xsl:if>
-                <!--
-                <xsl:if test="count($sect_details) > 0">
-                  <a href="#details" class="shortcut">
-                    <xsl:value-of select="./refsect1[@id='details']/title"/>
-                  </a>
-                  &#160;|&#160;
-                </xsl:if>
-                <xsl:if test="count($sect_property_details) > 0">
-                  <a href="#property_details" class="shortcut">
-                    <xsl:value-of select="./refsect1[@id='property_details']/title"/>
-                  </a>
-                  &#160;|&#160;
-                </xsl:if>
-                <xsl:if test="count($sect_child_property_details) > 0">
-                  <a href="#child_property_details" class="shortcut">
-                    <xsl:value-of select="./refsect1[@id='property_child_details']/title"/>
-                  </a>
-                  &#160;|&#160;
-                </xsl:if>
-                <xsl:if test="count($sect_style_property_details) > 0">
-                  <a href="#style_property_details" class="shortcut">
-                    <xsl:value-of select="./refsect1[@id='style_property_details']/title"/>
-                  </a>
-                  &#160;|&#160;
-                </xsl:if>
-                <xsl:if test="count($sect_signals) > 0">
-                  <a href="#signals" class="shortcut">
-                    <xsl:value-of select="./refsect1[@id='signals']/title"/>
-                  </a>
-                  &#160;|&#160;
-                </xsl:if>
-                -->
-              </td>
-            </tr>
-          </xsl:when>
-          <!-- this is not yet very nice, as it requires all glossdic/indexdiv
-          elements having a anchor element. maybe we can customize the xsl
-          to automaticaly create local anchors
-          -->
-          <xsl:when test="count($glssections) > 0">
-            <tr>
-              <td colspan="5" class="shortcuts">
-                 <xsl:for-each select="./glossdiv">
-                   <xsl:if test="position() > 1">
-                     &#160;|&#160;
-                   </xsl:if>
-                   <a class="shortcut">
-                     <xsl:attribute name="href">#gls<xsl:value-of select="./title"/></xsl:attribute>
-                     <xsl:value-of select="./title"/>
-                   </a>
-                 </xsl:for-each>
-              </td>
-            </tr>
-          </xsl:when>
-          <xsl:when test="count($idxsections) > 0">
-            <tr>
-              <td colspan="5" class="shortcuts">
-                 <xsl:for-each select="./indexdiv/indexdiv">
-                   <xsl:if test="position() > 1">
-                     &#160;|&#160;
-                   </xsl:if>
-                   <a class="shortcut">
-                     <xsl:attribute name="href">#idx<xsl:value-of select="./title"/></xsl:attribute>
-                     <xsl:value-of select="./title"/>
-                   </a>
-                 </xsl:for-each>
-              </td>
-            </tr>
-          </xsl:when>
-        </xsl:choose>
+                  </a></span>
+                </xsl:if>
+              </xsl:when>
+              <!-- this is not yet very nice, as it requires all glossdic/indexdiv
+                   elements having a anchor element. maybe we can customize the xsl
+                   to automaticaly create local anchors
+              -->
+              <xsl:when test="count($glssections) > 0">
+                <span id="nav_glossary">
+                <xsl:for-each select="./glossdiv">
+                  <xsl:if test="position() > 1">
+                    &#160;<span class="dim">|</span>&#160;
+                  </xsl:if>
+                  <a class="shortcut">
+                    <xsl:attribute name="href">#gls<xsl:value-of select="./title"/></xsl:attribute>
+                    <xsl:value-of select="./title"/>
+                  </a>
+                </xsl:for-each>
+                </span>
+              </xsl:when>
+              <xsl:when test="count($idxsections) > 0">
+                <span id="nav_index">
+                <xsl:for-each select="./indexdiv/indexdiv">
+                  <xsl:if test="position() > 1">
+                    &#160;<span class="dim">|</span>&#160;
+                  </xsl:if>
+                  <a class="shortcut">
+                    <xsl:attribute name="href">#idx<xsl:value-of select="./title"/></xsl:attribute>
+                    <xsl:value-of select="./title"/>
+                  </a>
+                </xsl:for-each>
+                </span>
+              </xsl:when>
+            </xsl:choose>
+          </td>
+          <xsl:choose>
+            <xsl:when test="$home != .">
+              <td>
+                <a accesskey="h">
+                  <xsl:attribute name="href">
+                    <xsl:call-template name="href.target">
+                      <xsl:with-param name="object" select="$home"/>
+                    </xsl:call-template>
+                  </xsl:attribute>
+                  <img src="home.png" width="16" height="16" border="0">
+                    <xsl:attribute name="alt">
+                      <xsl:call-template name="gentext">
+                        <xsl:with-param name="key">nav-home</xsl:with-param>
+                      </xsl:call-template>
+                    </xsl:attribute>
+                  </img>
+                </a>
+              </td>
+            </xsl:when>
+            <xsl:otherwise>
+              <td>&#160;</td>
+            </xsl:otherwise>
+          </xsl:choose>
+          <xsl:choose>
+            <xsl:when test="count($up) > 0 and $up != $home">
+              <td>
+                <a accesskey="u">
+                  <xsl:attribute name="href">
+                    <xsl:call-template name="href.target">
+                      <xsl:with-param name="object" select="$up"/>
+                    </xsl:call-template>
+                  </xsl:attribute>
+                  <img src="up.png" width="16" height="16" border="0">
+                    <xsl:attribute name="alt">
+                      <xsl:call-template name="gentext">
+                        <xsl:with-param name="key">nav-up</xsl:with-param>
+                      </xsl:call-template>
+                    </xsl:attribute>
+                  </img>
+                </a>
+              </td>
+            </xsl:when>
+            <xsl:otherwise>
+              <td><img src="up-insensitive.png" width="16" height="16" border="0"/></td>
+            </xsl:otherwise>
+          </xsl:choose>
+          <xsl:choose>
+            <xsl:when test="count($prev) > 0">
+              <td>
+                <a accesskey="p">
+                  <xsl:attribute name="href">
+                    <xsl:call-template name="href.target">
+                      <xsl:with-param name="object" select="$prev"/>
+                    </xsl:call-template>
+                  </xsl:attribute>
+                  <img src="left.png" width="16" height="16" border="0">
+                    <xsl:attribute name="alt">
+                      <xsl:call-template name="gentext">
+                        <xsl:with-param name="key">nav-prev</xsl:with-param>
+                      </xsl:call-template>
+                    </xsl:attribute>
+                  </img>
+                </a>
+              </td>
+            </xsl:when>
+            <xsl:otherwise>
+              <td><img src="left-insensitive.png" width="16" height="16" border="0"/></td>
+            </xsl:otherwise>
+          </xsl:choose>
+          <xsl:choose>
+            <xsl:when test="count($next) > 0">
+              <td>
+                <a accesskey="n">
+                  <xsl:attribute name="href">
+                    <xsl:call-template name="href.target">
+                      <xsl:with-param name="object" select="$next"/>
+                    </xsl:call-template>
+                  </xsl:attribute>
+                  <img src="right.png" width="16" height="16" border="0">
+                    <xsl:attribute name="alt">
+                      <xsl:call-template name="gentext">
+                        <xsl:with-param name="key">nav-next</xsl:with-param>
+                      </xsl:call-template>
+                    </xsl:attribute>
+                  </img>
+                </a>
+              </td>
+            </xsl:when>
+            <xsl:otherwise>
+              <td><img src="right-insensitive.png" width="16" height="16" border="0"/></td>
+            </xsl:otherwise>
+          </xsl:choose>
+        </tr>
       </table>
     </xsl:if>
   </xsl:template>
@@ -786,7 +756,7 @@
             <xsl:apply-templates/>
           </p>
         </td>
-        <td valign="top" align="right">
+        <td class="gallery_image" valign="top" align="right">
           <xsl:choose>
             <xsl:when test="../refmeta/refmiscinfo/inlinegraphic">
               <xsl:apply-templates select="../refmeta/refmiscinfo/inlinegraphic"/>
@@ -828,7 +798,7 @@
       <span class="extralinks">
         <xsl:for-each select="../ulink[@role='extralinks']">
           <xsl:if test="position() = 1">[&#160;</xsl:if>
-          <xsl:if test="position() > 1">&#160;|&#160;</xsl:if>
+          <xsl:if test="position() > 1">&#160;<span class="dim">|</span>&#160;</xsl:if>
           <a>
             <xsl:attribute name="href"><xsl:value-of select="@url"/></xsl:attribute>
             <xsl:copy-of select="text()" />
 
=== added file 'gtkdoc-common.pl'
--- gtkdoc-common.pl	1970-01-01 00:00:00 +0000
+++ gtkdoc-common.pl	2014-02-17 20:15:47 +0000
@@ -0,0 +1,543 @@
+#!/usr/bin/perl -w
+# -*- cperl -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2001  Damon Chaplin
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+#
+# These are functions used by several of the gtk-doc Perl scripts.
+# We'll move more of the common routines here eventually, though they need to
+# stop using global variables first.
+#
+
+1;
+
+
+#############################################################################
+# Function    : UpdateFileIfChanged
+# Description : Compares the old version of the file with the new version and
+#                if the file has changed it moves the new version into the old
+#                versions place. This is used so we only change files if
+#                needed, so we can do proper dependency tracking and we don't
+#                needlessly check files into version control systems that haven't
+#               changed.
+#                It returns 0 if the file hasn't changed, and 1 if it has.
+# Arguments   : $old_file - the pathname of the old file.
+#                $new_file - the pathname of the new version of the file.
+#                $make_backup - 1 if a backup of the old file should be kept.
+#                        It will have the .bak suffix added to the file name.
+#############################################################################
+
+sub UpdateFileIfChanged {
+    my ($old_file, $new_file, $make_backup) = @_;
+
+    #LogTrace("Comparing $old_file with $new_file...");
+
+    # If the old file doesn't exist we want this to default to 1.
+    my $exit_code = 1;
+
+    if (-e $old_file) {
+        `cmp -s "$old_file" "$new_file"`;
+        $exit_code = $? >> 8;
+        #LogTrace("   cmp exit code: $exit_code ($?)";
+    }
+
+    if ($exit_code > 1) {
+        die "Error running 'cmp $old_file $new_file'";
+    }
+
+    if ($exit_code == 1) {
+        #LogTrace("   files changed - replacing old version with new version.");
+        if ($make_backup && -e $old_file) {
+            rename ($old_file, "$old_file.bak")
+                || die "Can't move $old_file to $old_file.bak: $!";
+        }
+        rename ($new_file, $old_file)
+            || die "Can't move $new_file to $old_file: $!";
+
+        return 1;
+    } else {
+        #LogTrace("   files the same - deleting new version.");
+        unlink ("$new_file")
+            || die "Can't delete file: $new_file: $!";
+
+        return 0;
+    }
+}
+
+
+#############################################################################
+# Function    : ParseStructDeclaration
+# Description : This function takes a structure declaration and
+#               breaks it into individual type declarations.
+# Arguments   : $declaration - the declaration to parse
+#               $is_object - true if this is an object structure
+#               $output_function_params - true if full type is wanted for
+#                                         function pointer members
+#               $typefunc - function reference to apply to type
+#               $namefunc - function reference to apply to name
+#############################################################################
+
+sub ParseStructDeclaration {
+    my ($declaration, $is_object, $output_function_params, $typefunc, $namefunc) = @_;
+
+    # For forward struct declarations just return an empty array.
+    if ($declaration =~ m/(?:struct|union)\s+\S+\s*;/msg) {
+      return ();
+    }
+
+    # Remove all private parts of the declaration
+
+    # For objects, assume private
+    if ($is_object) {
+        $declaration =~ s!((?:struct|union)\s+\w*\s*\{)
+                          .*?
+                          (?:/\*\s*<\s*public\s*>\s*\*/|(?=\}))!$1!msgx;
+    }
+
+    # Remove private symbols
+    # Assume end of declaration if line begins with '}'
+    $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx;
+
+    # Remove all other comments
+    $declaration =~ s@\n\s*/\*([^*]+|\*(?!/))*\*/\s*\n@\n@msg;
+    $declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g;
+    $declaration =~ s@\n\s*//.*?\n@\n@msg;
+    $declaration =~ s@//.*@@g;
+
+    my @result = ();
+
+    if ($declaration =~ /^\s*$/) {
+        return @result;
+    }
+
+    # Prime match after "struct/union {" declaration
+    if (!scalar($declaration =~ m/(?:struct|union)\s+\w*\s*\{/msg)) {
+        die "Declaration '$declaration' does not begin with struct/union [NAME] {\n";
+    }
+
+    #LogTrace("public fields in struct/union: $declaration");
+
+    # Treat lines in sequence, allowing singly nested anonymous structs
+    # and unions.
+    while ($declaration =~ m/\s*([^{;]+(\{[^\}]*\}[^{;]+)?);/msg) {
+        my $line = $1;
+
+        last if $line =~ /^\s*\}\s*\w*\s*$/;
+
+        # FIXME: Just ignore nested structs and unions for now
+        next if $line =~ /{/;
+
+        # ignore preprocessor directives
+        while ($line =~ /^#.*?\n\s*(.*)/msg) {
+            $line=$1;
+        }
+
+        last if $line =~ /^\s*\}\s*\w*\s*$/;
+
+        # Try to match structure members which are functions
+        if ($line =~ m/^
+                 (const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+)*(struct\s+|enum\s+)?  # mod1
+                 (\w+)\s*                             # type
+                 (\**(?:\s*restrict)?)\s*             # ptr1
+                 (const\s+)?                          # mod2
+                 (\**\s*)                              # ptr2
+                 (const\s+)?                          # mod3
+                 \(\s*\*\s*(\w+)\s*\)\s*              # name
+                 \(([^)]*)\)\s*                       # func_params
+                            $/x) {
+
+            my $mod1 = defined($1) ? $1 : "";
+            if (defined($2)) { $mod1 .= $2; }
+            my $type = $3;
+            my $ptr1 = $4;
+            my $mod2 = defined($5) ? $5 : "";
+            my $ptr2 = $6;
+            my $mod3 = defined($7) ? $7 : "";
+            my $name = $8;
+            my $func_params = $9;
+            my $ptype = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
+            my $pname = defined $namefunc ? $namefunc->($name) : $name;
+
+            push @result, $name;
+
+            if ($output_function_params) {
+              push @result, "$mod1$ptype$ptr1$mod2$ptr2$mod3 (*$pname) ($func_params)";
+            } else {
+              push @result, "$pname&#160;()";
+            }
+
+
+        # Try to match normal struct fields of comma-separated variables/
+        } elsif ($line =~ m/^
+            ((?:const\s+|volatile\s+|unsigned\s+|signed\s+|short\s+|long\s+)?)(struct\s+|enum\s+)? # mod1
+            (\w+)\s*                            # type
+            (\** \s* const\s+)?                 # mod2
+            (.*)                                # variables
+            $/x) {
+
+            my $mod1 = defined($1) ? $1 : "";
+            if (defined($2)) { $mod1 .= $2; }
+            my $type = $3;
+            my $ptype = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
+            my $mod2 = defined($4) ? " " . $4 : "";
+            my $list = $5;
+
+            #LogTrace("'$mod1' '$type' '$mod2' '$list'");
+
+            $mod1 =~ s/ /&#160;/g;
+            $mod2 =~ s/ /&#160;/g;
+
+            my @names = split /,/, $list;
+            for my $n (@names) {
+                # Each variable can have any number of '*' before the
+                # identifier, and be followed by any number of pairs of
+                # brackets or a bit field specifier.
+                # e.g. *foo, ***bar, *baz[12][23], foo : 25.
+                if ($n =~ m/^\s* (\**(?:\s*restrict\b)?) \s* (\w+) \s* (?: ((?:\[[^\]]*\]\s*)+) | (:\s*\d+)?) \s* $/x) {
+                    my $ptrs = $1;
+                    my $name = $2;
+                    my $array = defined($3) ? $3 : "";
+                    my $bits =  defined($4) ? " $4" : "";
+
+                    if ($ptrs && $ptrs !~ m/\*$/) { $ptrs .= " "; }
+                    $array =~ s/ /&#160;/g;
+                    $bits =~ s/ /&#160;/g;
+
+                    push @result, $name;
+                    if (defined $namefunc) {
+                        $name = $namefunc->($name);
+                    }
+                    push @result, "$mod1$ptype$mod2&#160;$ptrs$name$array$bits;";
+
+                    #LogTrace("Matched line: $mod1$ptype$mod2 $ptrs$name$array$bits");
+                } else {
+                    print "WARNING: Couldn't parse struct field: $n\n";
+                }
+            }
+
+        } else {
+            print "WARNING: Cannot parse structure field: \"$line\"\n";
+        }
+    }
+
+    return @result;
+}
+
+
+#############################################################################
+# Function    : ParseEnumDeclaration
+# Description : This function takes a enumeration declaration and
+#               breaks it into individual enum member declarations.
+# Arguments   : $declaration - the declaration to parse
+#############################################################################
+
+sub ParseEnumDeclaration {
+    my ($declaration, $is_object) = @_;
+
+    # For forward enum declarations just return an empty array.
+    if ($declaration =~ m/enum\s+\S+\s*;/msg) {
+        return ();
+    }
+
+    # Remove private symbols
+    # Assume end of declaration if line begins with '}'
+    $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx;
+
+    # Remove all other comments
+    $declaration =~ s@\n\s*/\*([^*]+|\*(?!/))*\*/\s*\n@\n@msg;
+    $declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g;
+    $declaration =~ s@\n\s*//.*?\n@\n@msg;
+    $declaration =~ s@//.*@@g;
+
+    my @result = ();
+
+    if ($declaration =~ /^\s*$/) {
+        return @result;
+    }
+
+    # Remove parenthesized expressions (in macros like GTK_BLAH = BLAH(1,3))
+    # to avoid getting confused by commas they might contain. This
+    # doesn't handle nested parentheses correctly.
+
+    $declaration =~ s/\([^)\n]+\)//g;
+
+    # Remove comma from comma - possible whitespace - closing brace sequence
+    # since it is legal in GNU C and C99 to have a trailing comma but doesn't
+    # result in an actual enum member
+
+    $declaration =~ s/,(\s*})/$1/g;
+
+    # Prime match after "typedef enum {" declaration
+    if (!scalar($declaration =~ m/(typedef\s+)?enum\s*(\S+\s*)?\{/msg)) {
+        die "Enum declaration '$declaration' does not begin with 'typedef enum {' or 'enum XXX {'\n";
+    }
+
+    #LogTrace("public fields in enum: $declaration");
+
+    # Treat lines in sequence.
+    while ($declaration =~ m/\s*([^,\}]+)([,\}])/msg) {
+        my $line = $1;
+        my $terminator = $2;
+
+        # ignore preprocessor directives
+        while ($line =~ /^#.*?\n\s*(.*)/msg) {
+            $line=$1;
+        }
+
+        if ($line =~ m/^(\w+)\s*(=.*)?$/msg) {
+            push @result, $1;
+
+        # Special case for GIOCondition, where the values are specified by
+        # macros which expand to include the equal sign like '=1'.
+        } elsif ($line =~ m/^(\w+)\s*GLIB_SYSDEF_POLL/msg) {
+            push @result, $1;
+
+        # Special case include of <gdk/gdkcursors.h>, just ignore it
+        } elsif ($line =~ m/^#include/) {
+            last;
+
+        # Special case for #ifdef/#else/#endif, just ignore it
+        } elsif ($line =~ m/^#(?:if|else|endif)/) {
+            last;
+
+        } else {
+            warn "Cannot parse enumeration member \"$line\"";
+        }
+
+        last if $terminator eq '}';
+    }
+
+    return @result;
+}
+
+
+#############################################################################
+# Function    : ParseFunctionDeclaration
+# Description : This function takes a function declaration and
+#               breaks it into individual parameter declarations.
+# Arguments   : $declaration - the declaration to parse
+#               $typefunc - function reference to apply to type
+#               $namefunc - function reference to apply to name
+#############################################################################
+
+sub ParseFunctionDeclaration {
+    my ($declaration, $typefunc, $namefunc) = @_;
+
+    my @result = ();
+
+    my ($param_num) = 0;
+    while ($declaration ne "") {
+        #LogTrace("[$declaration]");
+
+        if ($declaration =~ s/^[\s,]+//) {
+            # skip whitespace and commas
+            next;
+
+        } elsif ($declaration =~ s/^void\s*[,\n]//) {
+            if ($param_num != 0) {
+                # FIXME: whats the problem here?
+                warn "void used as parameter in function $declaration";
+            }
+            push @result, "void";
+            my $xref = "<type>void</type>";
+            my $label = defined $namefunc ? $namefunc->($xref) : $xref;
+            push @result, $label;
+
+        } elsif ($declaration =~ s/^\s*[_a-zA-Z0-9]*\.\.\.\s*[,\n]//) {
+            push @result, "...";
+            my $label = defined $namefunc ? $namefunc->("...") : "...";
+            push @result, $label;
+
+        # allow alphanumerics, '_', '[' & ']' in param names
+        # Try to match a standard parameter
+        #                               $1                                                                                                                                            $2                             $3                                                                                                $4       $5
+        } elsif ($declaration =~ s/^\s*((?:(?:G_CONST_RETURN|G_GNUC_[A-Z_]+\s+|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*)((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*\*?\s*(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*(?:G_GNUC_[A-Z_]+)?\s*[,\n]//) {
+            my $pre        = defined($1) ? $1 : "";
+            my $type        = $2;
+            my $ptr        = defined($3) ? $3 : "";
+            my $name        = defined($4) ? $4 : "";
+            my $array        = defined($5) ? $5 : "";
+
+            $pre  =~ s/\s+/ /g;
+            $type =~ s/\s+/ /g;
+            $ptr  =~ s/\s+/ /g;
+            $ptr  =~ s/\s+$//;
+            if ($ptr && $ptr !~ m/\*$/) { $ptr .= " "; }
+
+            #LogTrace("$symbol: '$pre' '$type' '$ptr' '$name' '$array'");
+
+            if (($name eq "") && $pre =~ m/^((un)?signed .*)\s?/ ) {
+                $name = $type;
+                $type = "$1";
+                $pre = "";
+            }
+
+            if ($name eq "") {
+                $name = "Param" . ($param_num + 1);
+            }
+
+            #LogTrace("$symbol: '$pre' '$type' '$ptr' '$name' '$array'");
+
+            push @result, $name;
+            my $xref = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
+            my $label        = "$pre$xref $ptr$name$array";
+            if (defined $namefunc) {
+                $label = $namefunc->($label)
+            }
+            push @result, $label;
+
+        # Try to match parameters which are functions
+        #                            $1                                                                  $2          $3      $4                        $5              $6            $7             $8
+        } elsif ($declaration =~ s/^(const\s+|G_CONST_RETURN\s+|G_GNUC_[A-Z_]+\s+|signed\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*(\*[\s\*]*)\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]//) {
+             my $mod1 = defined($1) ? $1 : "";
+            if (defined($2)) { $mod1 .= $2; }
+            my $type = $3;
+            my $ptr1 = $4;
+            my $mod2 = defined($5) ? $5 : "";
+            my $func_ptr = $6;
+            my $name = $7;
+            my $func_params = defined($8) ? $8 : "";
+
+            #if (!defined($type)) { print "## no type\n"; };
+            #if (!defined($ptr1)) { print "## no ptr1\n"; };
+            #if (!defined($func_ptr)) { print "## no func_ptr\n"; };
+            #if (!defined($name)) { print "## no name\n"; };
+
+            if ($ptr1 && $ptr1 !~ m/\*$/) { $ptr1 .= " "; }
+            $func_ptr  =~ s/\s+//g;
+
+            push @result, $name;
+            my $xref = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
+            #LogTrace("Type: [$mod1][$xref][$ptr1][$mod2] ([$func_ptr][$name]) ($func_params)");
+            my $label = "$mod1$xref$ptr1$mod2 ($func_ptr$name) ($func_params)";
+            if (defined $namefunc) {
+                $label = $namefunc->($label)
+            }
+            push @result, $label;
+        } else {
+            warn "Can't parse args for function in \"$declaration\"";
+            last;
+        }
+        $param_num++;
+    }
+
+    return @result;
+}
+
+
+#############################################################################
+# Function    : ParseMacroDeclaration
+# Description : This function takes a macro declaration and
+#               breaks it into individual parameter declarations.
+# Arguments   : $declaration - the declaration to parse
+#               $namefunc - function reference to apply to name
+#############################################################################
+
+sub ParseMacroDeclaration {
+    my ($declaration, $namefunc) = @_;
+
+    my @result = ();
+
+    if ($declaration =~ m/^\s*#\s*define\s+\w+\(([^\)]*)\)/) {
+        my $params = $1;
+
+        $params =~ s/\\\n//g;
+        foreach $param (split (/,/, $params)) {
+            $param =~ s/^\s+//;
+            $param =~ s/\s*$//;
+            # Allow varargs variations
+            if ($param =~ m/^.*\.\.\.$/) {
+                $param = "...";
+            }
+            if ($param =~ m/\S/) {
+                push @result, $param;
+                push @result, defined $namefunc ? $namefunc->($param) : $param;
+            }
+        }
+    }
+
+    return @result;
+}
+
+
+#############################################################################
+# Function    : LogWarning
+# Description : Log a warning in gcc style format
+# Arguments   : $file - the file the error comes from
+#                $line - line number for the wrong entry
+#                $message - description of the issue
+#############################################################################
+
+sub LogWarning {
+    my ($file, $line, $message) = @_;
+
+    $file="unknown" if !defined($file);
+    $line="0" if !defined($line);
+
+    print "$file:$line: warning: $message\n"
+}
+
+sub LogTrace {
+    my ($message) = @_;
+
+    if (defined($ENV{"GTKDOC_TRACE"})) {
+        my (undef, $file, $line) = caller;
+
+        chomp($message);
+        print "$file:$line: trace: $message\n"
+    }
+}
+
+
+#############################################################################
+# Function    : CreateValidSGMLID
+# Description : Creates a valid SGML 'id' from the given string.
+#               According to http://www.w3.org/TR/html4/types.html#type-id
+#                 "ID and NAME tokens must begin with a letter ([A-Za-z]) and
+#                  may be followed by any number of letters, digits ([0-9]),
+#                  hyphens ("-"), underscores ("_"), colons (":"), and
+#                  periods (".")."
+#
+#                NOTE: When creating SGML IDS, we append ":CAPS" to all
+#                     all-caps identifiers to prevent name clashes (SGML ids are
+#                     case-insensitive). (It basically never is the case that
+#                     mixed-case identifiers would collide.)
+# Arguments   : $id - the string to be converted into a valid SGML id.
+#############################################################################
+
+sub CreateValidSGMLID {
+    my ($id) = $_[0];
+
+    # Special case, '_' would end up as '' so we use 'gettext-macro' instead.
+    if ($id eq "_") { return "gettext-macro"; }
+
+    $id =~ s/[_ ]/-/g;
+    $id =~ s/[,;]//g;
+    $id =~ s/^-*//;
+    $id =~ s/::/-/g;
+    $id =~ s/:/--/g;
+
+    # Append ":CAPS" to all all-caps identifiers
+    # FIXME: there are some inconsistencies here, we have sgml.index files
+    # containing e.g. TRUE--CAPS
+    if ($id !~ /[a-z]/ && $id !~ /-CAPS$/) { $id .= ":CAPS" };
+
+    return $id;
+}
+
 
=== modified file 'gtkdoc-fixxref.in'
--- gtkdoc-fixxref.in	2013-12-19 07:58:53 +0000
+++ gtkdoc-fixxref.in	2014-02-17 20:15:47 +0000
@@ -472,7 +472,7 @@
     close (NEWFILE);
 
     # format source
-    system "echo 'let html_number_lines=0|let html_use_css=1|let use_xhtml=1|syn on|e $temp_source_file|run! syntax/2html.vim|w! $temp_source_file.html|qa!' | @HIGHLIGHT@ -n -e -u NONE -T xterm >/dev/null";
+    system "echo 'let html_number_lines=0|let html_use_css=1|let html_use_xhtml=1|syn on|e $temp_source_file|run! syntax/2html.vim|w! $temp_source_file.html|qa!' | @HIGHLIGHT@ -n -e -u NONE -T xterm >/dev/null";
 
     my $highlighted_source;
     {
@@ -481,7 +481,7 @@
         $highlighted_source = <NEWFILE>;
         close (NEWFILE);
     }
-    $highlighted_source =~ s#.*<pre>\n##s;
+    $highlighted_source =~ s#.*<pre\b[^>]*>\n##s;
     $highlighted_source =~ s#</pre>.*##s;
 
     # need to rewrite the stylesheet classes
 
=== modified file 'gtkdoc-mkdb.in'
--- gtkdoc-mkdb.in	2013-12-19 07:58:53 +0000
+++ gtkdoc-mkdb.in	2014-02-17 20:15:47 +0000
@@ -25,6 +25,7 @@
 # Description : This creates the DocBook files from the edited templates.
 #############################################################################
 
+use warnings;
 use strict;
 use Getopt::Long;
 
@@ -304,29 +305,73 @@
 my %AnnotationDefinition = (
     'allow-none' => "NULL is ok, both for passing and for returning.",
     'array' => "Parameter points to an array of items.",
-    'attribute' => "Free-form custom annotation.",
+    'attribute' => "Deprecated free-form custom annotation, replaced by (attributes) annotation.",
+    'attributes' => "Free-form key-value pairs.",
     'closure' => "This parameter is a 'user_data', for callbacks; many bindings can pass NULL here.",
+    'constructor' => "This symbol is a constructor, not a static method.",
+    'destroy' => "This parameter is a 'destroy_data', for callbacks.",
     'default' => "Default parameter value (for in case the <acronym>shadows</acronym>-to function has less parameters).",
     'element-type' => "Generics and defining elements of containers and arrays.",
     'error-domains' => "Typed errors. Similar to throws in Java.",
+    'foreign' => "This is a foreign struct.",
+    'get-value-func' => "The specified function is used to convert a struct from a GValue, must be a GTypeInstance.",
     'in' => "Parameter for input. Default is <acronym>transfer none</acronym>.",
     'inout' => "Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.",
     'in-out' => "Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.",
+    'method' => "This is a method",
     'not-error' => "A GError parameter is not to be handled like a normal GError.",
     'out' => "Parameter for returning results. Default is <acronym>transfer full</acronym>.",
     'out caller-allocates' => "Out parameter, where caller must allocate storage.",
     'out callee-allocates' => "Out parameter, where caller must allocate storage.",
+    'ref-func' => "The specified function is used to ref a struct, must be a GTypeInstance.",
+    'rename-to' => "Rename the original symbol's name to SYMBOL.",
+    'scope call' => "The callback is valid only during the call to the method.",
+    'scope async' => "The callback is valid until first called.",
+    'scope notified' => "The callback is valid until the GDestroyNotify argument is called.",
+    'set-value-func' => "The specified function is used to convert from a struct to a GValue, must be a GTypeInstance.",
+    'skip' => "Exposed in C code, not necessarily available in other languages.",
     'transfer container' => "Free data container after the code is done.",
     'transfer floating' => "Alias for <acronym>transfer none</acronym>, used for objects with floating refs.",
     'transfer full' => "Free data after the code is done.",
     'transfer none' => "Don't free data after the code is done.",
-    'scope call' => "The callback is valid only during the call to the method.",
-    'scope async' => "The callback is valid until first called.",
-    'scope notified' => "The callback is valid until the GDestroyNotify argument is called.",
-    'skip' => "Exposed in C code, not necessarily available in other languages.",
-    'type' => "Override the parsed C type with given type."
+    'type' => "Override the parsed C type with given type.",
+    'unref-func' => "The specified function is used to unref a struct, must be a GTypeInstance.",
+    'virtual' => "This is the invoker for a virtual method.",
+    'value' => "The specified value overrides the evaluated value of the constant."
 );
 
+# Elements to consider non-block items in MarkDown parsing
+my %MD_TEXT_LEVEL_ELEMENTS = ( "literal" => 1,
+                               "emphasis" => 1,
+                               "envar" => 1,
+                               "filename" => 1,
+                               "firstterm" => 1,
+                               "function" => 1,
+                               "manvolnum" => 1,
+                               "option" => 1,
+                               "replaceable" => 1,
+                               "structname" => 1,
+                               "title" => 1,
+                               "varname" => 1 );
+my %MD_ESCAPABLE_CHARS = ( "\\" => 1,
+                           "`" => 1,
+                           "*" => 1,
+                           "_" => 1,
+                           "{" => 1,
+                           "}" => 1,
+                           "[" => 1,
+                           "]" => 1,
+                           "(" => 1,
+                           ")" => 1,
+                           ">" => 1,
+                           "#" => 1,
+                           "+" => 1,
+                           "-" => 1,
+                           "." => 1,
+                           "!" => 1 );
+my %MD_GTK_ESCAPABLE_CHARS = ( "@" => 1,
+                               "%" => 1 );
+
 # Create the root DocBook output directory if it doens't exist.
 if (! -e $SGML_OUTPUT_DIR) {
     mkdir ("$SGML_OUTPUT_DIR", 0777)
@@ -336,6 +381,7 @@
 # Function and other declaration output settings.
 my $RETURN_TYPE_FIELD_WIDTH = 20;
 my $SYMBOL_FIELD_WIDTH = 36;
+my $MAX_SYMBOL_FIELD_WIDTH = 40;
 my $SIGNAL_FIELD_WIDTH = 16;
 my $PARAM_FIELD_COUNT = 2;
 
@@ -530,10 +576,12 @@
     my $title = "";
     my $section_id = "";
     my $subsection = "";
-    my $synopsis;
-    my $details;
     my $num_symbols;
     my $changed = 0;
+    my $functions_synop = "";
+    my $other_synop = "";
+    my $functions_details = "";
+    my $other_details = "";
     my $signals_synop = "";
     my $signals_desc = "";
     my $args_synop = "";
@@ -542,7 +590,8 @@
     my $args_desc = "";
     my $child_args_desc = "";
     my $style_args_desc = "";
-    my $hierarchy = "";
+    my $hierarchy_str = "";
+    my @hierarchy = ();
     my $interfaces = "";
     my $implementations = "";
     my $prerequisites = "";
@@ -559,15 +608,14 @@
             next;
 
         } elsif (m/^<SECTION>/) {
-            $synopsis = "";
-            $details = "";
             $num_symbols = 0;
             $in_section = 1;
             @file_objects = ();
             %symbol_def_line = ();
 
         } elsif (m/^<SUBSECTION\s*(.*)>/i) {
-            $synopsis .= "\n";
+            $other_synop .= "\n";
+            $functions_synop .= "\n";
             $subsection = $1;
 
         } elsif (m/^<SUBSECTION>/) {
@@ -638,8 +686,16 @@
                     $signals_synop = <<EOF;
 <refsect1 id="$section_id.signals" role="signal_proto">
 <title role="signal_proto.title">Signals</title>
-<synopsis>
-${signals_synop}</synopsis>
+<informaltable frame="none">
+<tgroup cols="3">
+<colspec colname="signals_return" colwidth="150px"/>
+<colspec colname="signals_name" colwidth="300px"/>
+<colspec colname="signals_flags" colwidth="200px"/>
+<tbody>
+${signals_synop}
+</tbody>
+</tgroup>
+</informaltable>
 </refsect1>
 EOF
                      $signals_desc = TrimTextBlock($signals_desc);
@@ -651,14 +707,22 @@
 EOF
                 }
 
-                 $args_synop =~ s/^\n*//g;
-                 $args_synop =~ s/\n+$/\n/g;
+                $args_synop =~ s/^\n*//g;
+                $args_synop =~ s/\n+$/\n/g;
                 if ($args_synop ne '') {
                     $args_synop = <<EOF;
 <refsect1 id="$section_id.properties" role="properties">
 <title role="properties.title">Properties</title>
-<synopsis>
-${args_synop}</synopsis>
+<informaltable frame="none">
+<tgroup cols="3">
+<colspec colname="properties_type" colwidth="150px"/>
+<colspec colname="properties_name" colwidth="300px"/>
+<colspec colname="properties_flags" colwidth="200px"/>
+<tbody>
+${args_synop}
+</tbody>
+</tgroup>
+</informaltable>
 </refsect1>
 EOF
                      $args_desc = TrimTextBlock($args_desc);
@@ -670,14 +734,22 @@
 EOF
                 }
 
-                 $child_args_synop =~ s/^\n*//g;
-                 $child_args_synop =~ s/\n+$/\n/g;
+                $child_args_synop =~ s/^\n*//g;
+                $child_args_synop =~ s/\n+$/\n/g;
                 if ($child_args_synop ne '') {
                     $args_synop .= <<EOF;
 <refsect1 id="$section_id.child-properties" role="child_properties">
 <title role="child_properties.title">Child Properties</title>
-<synopsis>
-${child_args_synop}</synopsis>
+<informaltable frame="none">
+<tgroup cols="3">
+<colspec colname="child_properties_type" colwidth="150px"/>
+<colspec colname="child_properties_name" colwidth="300px"/>
+<colspec colname="child_properties_flags" colwidth="200px"/>
+<tbody>
+${child_args_synop}
+</tbody>
+</tgroup>
+</informaltable>
 </refsect1>
 EOF
                      $child_args_desc = TrimTextBlock($child_args_desc);
@@ -689,14 +761,22 @@
 EOF
                 }
 
-                 $style_args_synop =~ s/^\n*//g;
-                 $style_args_synop =~ s/\n+$/\n/g;
+                $style_args_synop =~ s/^\n*//g;
+                $style_args_synop =~ s/\n+$/\n/g;
                 if ($style_args_synop ne '') {
                     $args_synop .= <<EOF;
 <refsect1 id="$section_id.style-properties" role="style_properties">
 <title role="style_properties.title">Style Properties</title>
-<synopsis>
-${style_args_synop}</synopsis>
+<informaltable frame="none">
+<tgroup cols="3">
+<colspec colname="style_properties_type" colwidth="150px"/>
+<colspec colname="style_properties_name" colwidth="300px"/>
+<colspec colname="style_properties_flags" colwidth="200px"/>
+<tbody>
+${style_args_synop}
+</tbody>
+</tgroup>
+</informaltable>
 </refsect1>
 EOF
                      $style_args_desc = TrimTextBlock($style_args_desc);
@@ -708,12 +788,12 @@
 EOF
                 }
 
-                 $hierarchy = TrimTextBlock($hierarchy);
-                if ($hierarchy ne "") {
-                    $hierarchy = <<EOF;
+                $hierarchy_str = &AddTreeLineArt(\@hierarchy) . "\n"; 
+                if ($hierarchy_str ne "") {
+                    $hierarchy_str = <<EOF;
 <refsect1 id="$section_id.object-hierarchy" role="object_hierarchy">
 <title role="object_hierarchy.title">Object Hierarchy</title>
-$hierarchy
+<screen>$hierarchy_str</screen>
 </refsect1>
 EOF
                 }
@@ -758,14 +838,51 @@
 EOF
                 }
 
-                $synopsis =~ s/^\n*//g;
-                $synopsis =~ s/\n+$/\n/g;
+                $functions_synop =~ s/^\n*//g;
+                $functions_synop =~ s/\n+$/\n/g;
+                if ($functions_synop ne '') {
+                  $functions_synop = <<EOF;
+<refsect1 id="$section_id.functions" role="functions_proto">
+<title role="functions_proto.title">Functions</title>
+<informaltable pgwide="1" frame="none">
+<tgroup cols="2">
+<colspec colname="functions_return" colwidth="150px"/>
+<colspec colname="functions_name"/>
+<tbody>
+${functions_synop}
+</tbody>
+</tgroup>
+</informaltable>
+</refsect1>
+EOF
+                }
+
+                $other_synop =~ s/^\n*//g;
+                $other_synop =~ s/\n+$/\n/g;
+                if ($other_synop ne '') {
+                  $other_synop = <<EOF;
+<refsect1 id="$section_id.other" role="other_proto">
+<title role="other_proto.title">Types and Values</title>
+<informaltable role="enum_members_table" pgwide="1" frame="none">
+<tgroup cols="2">
+<colspec colname="name" colwidth="150px"/>
+<colspec colname="description"/>
+<tbody>
+${other_synop}
+</tbody>
+</tgroup>
+</informaltable>
+</refsect1>
+EOF
+                }
+
                 my $file_changed = &OutputSGMLFile ($filename, $title, $section_id,
                                                     $section_includes,
-                                                    \$synopsis, \$details,
+                                                    \$functions_synop, \$other_synop,
+                                                    \$functions_details, \$other_details,
                                                     \$signals_synop, \$signals_desc,
                                                     \$args_synop, \$args_desc,
-                                                    \$hierarchy, \$interfaces,
+                                                    \$hierarchy_str, \$interfaces,
                                                     \$implementations,
                                                     \$prerequisites, \$derived,
                                                     \@file_objects);
@@ -778,6 +895,10 @@
             $subsection = "";
             $in_section = 0;
             $section_includes = "";
+            $functions_synop = "";
+            $other_synop = "";
+            $functions_details = "";
+            $other_details = "";
             $signals_synop = "";
             $signals_desc = "";
             $args_synop = "";
@@ -786,52 +907,63 @@
             $args_desc = "";
             $child_args_desc = "";
             $style_args_desc = "";
-            $hierarchy = "";
-             $interfaces = "";
-             $implementations = "";
+            $hierarchy_str = "";
+            @hierarchy = ();
+            $interfaces = "";
+            $implementations = "";
             $prerequisites = "";
             $derived = "";
 
         } elsif (m/^(\S+)/) {
             my $symbol = $1;
-            #print "  Symbol: $symbol\n";
+            @TRACE@("  Symbol: $symbol in subsection: $subsection\n");
 
             # check for duplicate entries
             if (! defined $symbol_def_line{$symbol}) {
                 my $declaration = $Declarations{$symbol};
                 if (defined ($declaration)) {
+                    if (&CheckIsObject ($symbol)) {
+                        push @file_objects, $symbol;
+                    }
                     # We don't want standard macros/functions of GObjects,
                     # or private declarations.
                     if ($subsection ne "Standard" && $subsection ne "Private") {
-                        if (&CheckIsObject ($symbol)) {
-                            push @file_objects, $symbol;
-                        }
                         my ($synop, $desc) = &OutputDeclaration ($symbol,
                                                                  $declaration);
-                        my ($sig_synop, $sig_desc) = &GetSignals ($symbol);
-                        my ($arg_synop, $child_arg_synop, $style_arg_synop,
-                            $arg_desc, $child_arg_desc, $style_arg_desc) = &GetArgs ($symbol);
-                        my $hier = &GetHierarchy ($symbol);
-                        my $ifaces = &GetInterfaces ($symbol);
-                        my $impls = &GetImplementations ($symbol);
-                        my $prereqs = &GetPrerequisites ($symbol);
-                        my $der = &GetDerived ($symbol);
-                        $synopsis .= $synop;
-                        $details .= $desc;
-                        $signals_synop .= $sig_synop;
-                        $signals_desc .= $sig_desc;
-                        $args_synop .= $arg_synop;
-                        $child_args_synop .= $child_arg_synop;
-                        $style_args_synop .= $style_arg_synop;
-                        $args_desc .= $arg_desc;
-                        $child_args_desc .= $child_arg_desc;
-                        $style_args_desc .= $style_arg_desc;
-                        $hierarchy .= $hier;
-                        $interfaces .= $ifaces;
-                        $implementations .= $impls;
-                        $prerequisites .= $prereqs;
-                        $derived .= $der;
+                        my $type = $DeclarationTypes {$symbol};
+        
+                        if ($type eq 'FUNCTION' || $type eq 'USER_FUNCTION') {
+                          $functions_synop .= $synop;
+                          $functions_details .= $desc;
+                        } elsif ($type eq 'MACRO' && $declaration =~ /$symbol[ ]*\(/) {
+                          $functions_synop .= $synop;
+                          $functions_details .= $desc;
+                        } else {
+                          $other_synop .= $synop;
+                          $other_details .= $desc;
+                        }
                     }
+                    my ($sig_synop, $sig_desc) = &GetSignals ($symbol);
+                    my ($arg_synop, $child_arg_synop, $style_arg_synop,
+                        $arg_desc, $child_arg_desc, $style_arg_desc) = &GetArgs ($symbol);
+                    my $ifaces = &GetInterfaces ($symbol);
+                    my $impls = &GetImplementations ($symbol);
+                    my $prereqs = &GetPrerequisites ($symbol);
+                    my $der = &GetDerived ($symbol);
+                    @hierarchy = &GetHierarchy ($symbol, \@hierarchy);
+
+                    $signals_synop .= $sig_synop;
+                    $signals_desc .= $sig_desc;
+                    $args_synop .= $arg_synop;
+                    $child_args_synop .= $child_arg_synop;
+                    $style_args_synop .= $style_arg_synop;
+                    $args_desc .= $arg_desc;
+                    $child_args_desc .= $child_arg_desc;
+                    $style_args_desc .= $style_arg_desc;
+                    $interfaces .= $ifaces;
+                    $implementations .= $impls;
+                    $prerequisites .= $prereqs;
+                    $derived .= $der;
 
                     # Note that the declaration has been output.
                     $DeclarationOutput{$symbol} = 1;
@@ -1107,7 +1239,7 @@
   <title>Annotation Glossary</title>
 EOF
 
-    foreach my $annotation (keys(%AnnotationsUsed)) {
+    foreach my $annotation (sort(keys(%AnnotationsUsed))) {
         if(defined($AnnotationDefinition{$annotation})) {
             my $def = $AnnotationDefinition{$annotation};
             my $curletter = uc(substr($annotation,0,1));
@@ -1255,7 +1387,7 @@
 }
 
 #############################################################################
-# Function    : Outpu{Symbol,Section}ExtraLinks
+# Function    : Output{Symbol,Section}ExtraLinks
 # Description : Returns extralinks for the symbol (if enabled).
 # Arguments   : $symbol - the name of the function/macro begin described.
 #############################################################################
@@ -1319,7 +1451,7 @@
     my ($symbol, $declaration) = @_;
     my $id = &CreateValidSGMLID ($symbol);
     my $condition = &MakeConditionDescription ($symbol);
-    my $synop = &MakeReturnField("#define") . "<link linkend=\"$id\">$symbol</link>";
+    my $synop = "<row><entry role=\"define_keyword\">#define</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link>";
     my $desc;
 
     my @fields = ParseMacroDeclaration($declaration, \&CreateValidSGML);
@@ -1331,25 +1463,9 @@
     $desc .= OutputSymbolExtraLinks($symbol);
 
     if (@fields) {
-        if (length ($symbol) < $SYMBOL_FIELD_WIDTH) {
-            $synop .= (' ' x ($SYMBOL_FIELD_WIDTH - length ($symbol)));
-        }
-
-        $synop .= "(";
-        for (my $i = 1; $i <= $#fields; $i += 2) {
-            my $field_name = $fields[$i];
-
-            if ($i == 1) {
-                $synop .= "$field_name";
-            } else {
-                $synop .= ",\n"
-                    . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH))
-                    . " $field_name";
-            }
-        }
-        $synop .= ")";
+        $synop .= "<phrase role=\"c_punctuation\">()</phrase>";
     }
-    $synop .= "\n";
+    $synop .= "</entry></row>\n";
 
     # Don't output the macro definition if is is a conditional macro or it
     # looks like a function, i.e. starts with "g_" or "_?gnome_", or it is
@@ -1358,9 +1474,9 @@
     if (!defined ($DeclarationConditional{$symbol}) && ($symbol !~ m/^g_/)
         && ($symbol !~ m/^_?gnome_/) && (($declaration =~ tr/\n//) < 2)) {
         my $decl_out = &CreateValidSGML ($declaration);
-        $desc .= "<programlisting>$decl_out</programlisting>\n";
+        $desc .= "<programlisting language=\"C\">$decl_out</programlisting>\n";
     } else {
-        $desc .= "<programlisting>" . &MakeReturnField("#define") . "$symbol";
+        $desc .= "<programlisting language=\"C\">" . &MakeReturnField("#define") . "$symbol";
         if ($declaration =~ m/^\s*#\s*define\s+\w+(\([^\)]*\))/) {
             my $args = $1;
             my $pad = ' ' x ($RETURN_TYPE_FIELD_WIDTH - length ("#define "));
@@ -1377,7 +1493,7 @@
     my $parameters_output = 0;
 
     if (defined ($SymbolDocs{$symbol})) {
-        my $symbol_docs = &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
+        my $symbol_docs = &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
 
         # Try to insert the parameter table at the author's desired position.
         # Otherwise we need to tag it onto the end.
@@ -1409,8 +1525,8 @@
     my ($symbol, $declaration) = @_;
     my $id = &CreateValidSGMLID ($symbol);
     my $condition = &MakeConditionDescription ($symbol);
-    my $synop = &MakeReturnField("typedef") . "<link linkend=\"$id\">$symbol</link>;\n";
     my $desc = "<refsect2 id=\"$id\" role=\"typedef\"$condition>\n<title>$symbol</title>\n";
+    my $synop = "<row><entry role=\"typedef_keyword\">typedef</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link></entry></row>\n";
 
     $desc .= MakeIndexterms($symbol, $id);
     $desc .= "\n";
@@ -1418,13 +1534,13 @@
 
     if (!defined ($DeclarationConditional{$symbol})) {
         my $decl_out = &CreateValidSGML ($declaration);
-        $desc .= "<programlisting>$decl_out</programlisting>\n";
+        $desc .= "<programlisting language=\"C\">$decl_out</programlisting>\n";
     }
 
     $desc .= &MakeDeprecationNote($symbol);
 
     if (defined ($SymbolDocs{$symbol})) {
-        $desc .= &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
+        $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
     }
     $desc .= OutputSymbolTraits ($symbol);
     $desc .= "</refsect2>\n";
@@ -1470,16 +1586,17 @@
       $has_typedef = 1;
     }
 
-    my $synop;
+    my $type_output;
     my $desc;
     if ($has_typedef) {
         # For structs with typedefs we just output the struct name.
-        $synop = &MakeReturnField("") . "<link linkend=\"$id\">$symbol</link>;\n";
+        $type_output = "";
         $desc = "<refsect2 id=\"$id\" role=\"struct\"$condition>\n<title>$symbol</title>\n";
     } else {
-        $synop = &MakeReturnField("struct") . "<link linkend=\"$id\">$symbol</link>;\n";
+        $type_output = "struct";
         $desc = "<refsect2 id=\"$id\" role=\"struct\"$condition>\n<title>struct $symbol</title>\n";
     }
+    my $synop = "<row><entry role=\"datatype_keyword\">${type_output}</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link></entry></row>\n";
 
     $desc .= MakeIndexterms($symbol, $id);
     $desc .= "\n";
@@ -1544,12 +1661,12 @@
     }
 
     $decl_out = &CreateValidSGML ($decl_out);
-    $desc .= "<programlisting>$decl_out</programlisting>\n";
+    $desc .= "<programlisting language=\"C\">$decl_out</programlisting>\n";
 
     $desc .= &MakeDeprecationNote($symbol);
 
     if (defined ($SymbolDocs{$symbol})) {
-        $desc .= &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
+        $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
     }
 
     # Create a table of fields and descriptions
@@ -1582,22 +1699,31 @@
         my $missing_parameters = "";
         my $unused_parameters = "";
 
-        $desc .= "<variablelist role=\"struct\">\n";
+        $desc .= <<EOF;
+<refsect3 role="struct_members">\n<title>Members</title>
+<informaltable role="struct_members_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="struct_members_name" colwidth="300px"/>
+<colspec colname="struct_members_description"/>
+<colspec colname="struct_members_annotations" colwidth="200px"/>
+<tbody>
+EOF
+
         while (@fields) {
             my $field_name = shift @fields;
             my $text = shift @fields;
             my $field_descr = $field_descrs{$field_name};
             my $param_annotations = "";
 
-            $desc .= "<varlistentry><term>$text</term>\n";
+            $desc .= "<row><entry role=\"struct_member_name\"><para>$text</para></entry>\n";
             if (defined $field_descr) {
                 ($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr);
-                $field_descr = &ExpandAbbreviations($symbol, $field_descr);
-                $field_descr .= $param_annotations;
+                $field_descr = &ConvertMarkDown($symbol, $field_descr);
                 # trim
                 $field_descr =~ s/^(\s|\n)+//msg;
                 $field_descr =~ s/(\s|\n)+$//msg;
-                $desc .= "<listitem><simpara>$field_descr</simpara></listitem>\n";
+                $desc .= "<listitem>$field_descr</listitem>\n";
+                $desc .= "<entry role=\"struct_member_description\">$field_descr</entry>\n<entry role=\"struct_member_annotations\">$param_annotations</entry>\n";
                 delete $field_descrs{$field_name};
             } else {
                 &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
@@ -1607,11 +1733,11 @@
                 } else {
                     $missing_parameters = $field_name;
                 }
-                $desc .= "<listitem />\n";
+                $desc .= "<entry /><entry />\n";
             }
-            $desc .= "</varlistentry>\n";
+            $desc .= "</row>\n";
         }
-        $desc .= "</variablelist>";
+        $desc .= "</tbody></tgroup></informaltable>\n</refsect3>\n";
         foreach my $field_name (keys %field_descrs) {
             &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
                 "Field description for $symbol"."::"."$field_name is not used from source code comment block.");
@@ -1656,8 +1782,22 @@
 
 sub OutputUnion {
     my ($symbol, $declaration) = @_;
-    my $id = &CreateValidSGMLID ($symbol);
-    my $condition = &MakeConditionDescription ($symbol);
+
+    my $is_gtype = 0;
+    if (&CheckIsObject ($symbol)) {
+        @TRACE@("Found union gtype: $symbol\n");
+        $is_gtype = 1;
+    }
+
+    my $id;
+    my $condition;
+    if ($is_gtype) {
+        $id = &CreateValidSGMLID ($symbol . "_union");
+        $condition = &MakeConditionDescription ($symbol . "_union");
+    } else {
+        $id = &CreateValidSGMLID ($symbol);
+        $condition = &MakeConditionDescription ($symbol);
+    }
 
     # Determine if it is a simple struct or it also has a typedef.
     my $has_typedef = 0;
@@ -1665,29 +1805,25 @@
       $has_typedef = 1;
     }
 
-    my $synop;
+    my $type_output;
     my $desc;
     if ($has_typedef) {
         # For unions with typedefs we just output the union name.
-        $synop = &MakeReturnField("") . "<link linkend=\"$id\">$symbol</link>;\n";
+        $type_output = "";
         $desc = "<refsect2 id=\"$id\" role=\"union\"$condition>\n<title>$symbol</title>\n";
     } else {
-        $synop = &MakeReturnField("union") . "<link linkend=\"$id\">$symbol</link>;\n";
+        $type_output = "union";
         $desc = "<refsect2 id=\"$id\" role=\"union\"$condition>\n<title>union $symbol</title>\n";
     }
+    my $synop = "<row><entry role=\"datatype_keyword\">${type_output}</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link></entry></row>\n";
 
     $desc .= MakeIndexterms($symbol, $id);
     $desc .= "\n";
     $desc .= OutputSymbolExtraLinks($symbol);
-
-    # FIXME: we do more for structs
-    my $decl_out = &CreateValidSGML ($declaration);
-    $desc .= "<programlisting>$decl_out</programlisting>\n";
-
     $desc .= &MakeDeprecationNote($symbol);
 
     if (defined ($SymbolDocs{$symbol})) {
-        $desc .= &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
+        $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
     }
 
     # Create a table of fields and descriptions
@@ -1720,22 +1856,31 @@
         my $missing_parameters = "";
         my $unused_parameters = "";
 
-        $desc .= "<variablelist role=\"union\">\n";
+        $desc .= <<EOF;
+<refsect3 role="union_members">\n<title>Members</title>
+<informaltable role="union_members_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="union_members_name" colwidth="300px"/>
+<colspec colname="union_members_description"/>
+<colspec colname="union_members_annotations" colwidth="200px"/>
+<tbody>
+EOF
+
         while (@fields) {
             my $field_name = shift @fields;
             my $text = shift @fields;
             my $field_descr = $field_descrs{$field_name};
             my $param_annotations = "";
 
-            $desc .= "<varlistentry><term>$text</term>\n";
+            $desc .= "<row><entry role=\"union_member_name\"><para>$text</para></entry>\n";
             if (defined $field_descr) {
                 ($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr);
-                $field_descr = &ExpandAbbreviations($symbol, $field_descr);
-                $field_descr .= $param_annotations;
+                $field_descr = &ConvertMarkDown($symbol, $field_descr);
+
                 # trim
                 $field_descr =~ s/^(\s|\n)+//msg;
                 $field_descr =~ s/(\s|\n)+$//msg;
-                $desc .= "<listitem><simpara>$field_descr</simpara></listitem>\n";
+                $desc .= "<entry role=\"union_member_description\">$field_descr</entry>\n<entry role=\"union_member_annotations\">$param_annotations</entry>\n";
                 delete $field_descrs{$field_name};
             } else {
                 &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
@@ -1745,11 +1890,11 @@
                 } else {
                     $missing_parameters = $field_name;
                 }
-                $desc .= "<listitem />\n";
+                $desc .= "<entry /><entry />\n";
             }
-            $desc .= "</varlistentry>\n";
+            $desc .= "</row>\n";
         }
-        $desc .= "</variablelist>";
+        $desc .= "</tbody></tgroup></informaltable>\n</refsect3>";
         foreach my $field_name (keys %field_descrs) {
             &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
                 "Field description for $symbol"."::"."$field_name is not used from source code comment block.");
@@ -1811,56 +1956,16 @@
         $condition = &MakeConditionDescription ($symbol);
     }
 
-    my $synop = &MakeReturnField("enum") . "<link linkend=\"$id\">$symbol</link>;\n";
+    my $synop = "<row><entry role=\"datatype_keyword\">enum</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link></entry></row>\n";
     my $desc = "<refsect2 id=\"$id\" role=\"enum\"$condition>\n<title>enum $symbol</title>\n";
 
     $desc .= MakeIndexterms($symbol, $id);
     $desc .= "\n";
     $desc .= OutputSymbolExtraLinks($symbol);
-
-    my $decl_out = "";
-    my $public = 1;
-    my $new_declaration = "";
-    my $decl_line;
-    my $decl = $declaration;
-
-    if ($decl =~ m/^\s*(typedef\s+)?enum\s*\w*\s*(?:\/\*.*\*\/)?\s*{(.*)}\s*\w*\s*;\s*$/s) {
-        my $has_typedef = defined($1) ? 1 : 0;
-        my $enum_contents = $2;
-
-        foreach $decl_line (split (/\n/, $enum_contents)) {
-            #print "Enum line: $decl_line\n";
-            if ($decl_line =~ m%/\*\s*<\s*public\s*>\s*\*/%) {
-                $public = 1;
-            } elsif ($decl_line =~ m%/\*\s*<\s*(private|protected)\s*>\s*\*/%) {
-                $public = 0;
-            } elsif ($public) {
-                $new_declaration .= $decl_line . "\n";
-            }
-        }
-
-        if ($new_declaration) {
-            # Strip any blank lines off the ends.
-            $new_declaration =~ s/^\s*\n//;
-            $new_declaration =~ s/\n\s*$/\n/;
-
-            if ($has_typedef) {
-                $decl_out = "typedef enum {\n" . $new_declaration
-                  . "} $symbol;\n";
-            } else {
-                $decl_out = "enum $symbol {\n" . $new_declaration
-                  . "};\n";
-            }
-        }
-    }
-
-    $decl_out = &CreateValidSGML ($decl_out);
-    $desc .= "<programlisting>$decl_out</programlisting>\n";
-
     $desc .= &MakeDeprecationNote($symbol);
 
     if (defined ($SymbolDocs{$symbol})) {
-        $desc .= &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
+        $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
     }
 
     # Create a table of fields and descriptions
@@ -1885,18 +1990,27 @@
     my $missing_parameters = "";
     my $unused_parameters = "";
 
-    $desc .= "<variablelist role=\"enum\">\n";
+    $desc .= <<EOF;
+<refsect3 role="enum_members">\n<title>Members</title>
+<informaltable role="enum_members_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="enum_members_name" colwidth="300px"/>
+<colspec colname="enum_members_description"/>
+<colspec colname="enum_members_annotations" colwidth="200px"/>
+<tbody>
+EOF
+
     for my $field_name (@fields) {
         my $field_descr = $field_descrs{$field_name};
         my $param_annotations = "";
 
         $id = &CreateValidSGMLID ($field_name);
         $condition = &MakeConditionDescription ($field_name);
-        $desc .= "<varlistentry id=\"$id\" role=\"constant\"$condition>\n<term><literal>$field_name</literal></term>\n";
+        $desc .= "<row role=\"constant\"><entry role=\"enum_member_name\"><para id=\"$id\">$field_name</para></entry>\n";
         if (defined $field_descr) {
             ($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr);
-            $field_descr = &ExpandAbbreviations($symbol, $field_descr);
-            $desc .= "<listitem><simpara>$field_descr$param_annotations</simpara></listitem>\n";
+            $field_descr = &ConvertMarkDown($symbol, $field_descr);
+            $desc .= "<entry role=\"enum_member_description\">$field_descr</entry>\n<entry role=\"enum_member_annotations\">$param_annotations</entry>\n";
             delete $field_descrs{$field_name};
         } else {
             if ($found) {
@@ -1908,11 +2022,11 @@
                     $missing_parameters = $field_name;
                 }
             }
-            $desc .= "<listitem />\n";
+            $desc .= "<entry /><entry />\n";
         }
-        $desc .= "</varlistentry>\n";
+        $desc .= "</row>\n";
     }
-    $desc .= "</variablelist>";
+    $desc .= "</tbody></tgroup></informaltable>\n</refsect3>";
     foreach my $field_name (keys %field_descrs) {
         &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
             "Value description for $symbol"."::"."$field_name is not used from source code comment block.");
@@ -1961,23 +2075,23 @@
     
     @TRACE@("ouputing variable: '$symbol' '$declaration'");
 
-    my $synop;
+    my $type_output;
     if ($declaration =~ m/^\s*extern\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*;/) {
         my $mod1 = defined ($1) ? $1 : "";
         my $ptr = defined ($3) ? $3 : "";
         my $space = defined ($4) ? $4 : "";
         my $mod2 = defined ($5) ? $5 : "";
-        $synop = &MakeReturnField("extern $mod1$ptr$space$mod2") . "<link linkend=\"$id\">$symbol</link>;\n";
+        $type_output = "extern $mod1$ptr$space$mod2";
     } elsif ($declaration =~ m/^\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*=/) {
         my $mod1 = defined ($1) ? $1 : "";
         my $ptr = defined ($3) ? $3 : "";
         my $space = defined ($4) ? $4 : "";
         my $mod2 = defined ($5) ? $5 : "";
-        $synop = &MakeReturnField("$mod1$ptr$space$mod2") . "<link linkend=\"$id\">$symbol</link>;\n";
-
+        $type_output = "$mod1$ptr$space$mod2";
     } else {
-        $synop = &MakeReturnField("extern") . "<link linkend=\"$id\">$symbol</link>;\n";
+        $type_output = "extern";
     }
+    my $synop = "<row><entry role=\"variable_type\">${type_output}</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link></entry></row>\n";
 
     my $desc = "<refsect2 id=\"$id\" role=\"variable\"$condition>\n<title>$symbol</title>\n";
 
@@ -1986,12 +2100,12 @@
     $desc .= OutputSymbolExtraLinks($symbol);
 
     my $decl_out = &CreateValidSGML ($declaration);
-    $desc .= "<programlisting>$decl_out</programlisting>\n";
+    $desc .= "<programlisting language=\"C\">$decl_out</programlisting>\n";
 
     $desc .= &MakeDeprecationNote($symbol);
 
     if (defined ($SymbolDocs{$symbol})) {
-        $desc .= &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
+        $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
     }
     $desc .= OutputSymbolTraits ($symbol);
     $desc .= "</refsect2>\n";
@@ -2027,54 +2141,40 @@
     # We output const rather than G_CONST_RETURN.
     $type_modifier =~ s/G_CONST_RETURN/const/g;
     $pointer =~ s/G_CONST_RETURN/const/g;
-    $pointer =~ s/^\s+/ /g;
+    $pointer =~ s/^\s+/&#160;/g;
 
-    my $ret_type_len = length ($start) + length ($type_modifier)+ length ($type)
-        + length ($pointer);
     my $ret_type_output;
-    my $symbol_len;
-    if ($ret_type_len < $RETURN_TYPE_FIELD_WIDTH) {
-        $ret_type_output = "$start$type_modifier$xref$pointer"
-            . (' ' x ($RETURN_TYPE_FIELD_WIDTH - $ret_type_len));
-        $symbol_len = 0;
-    } else {
-        #$ret_type_output = "$start$type_modifier$xref$pointer\n" . (' ' x $RETURN_TYPE_FIELD_WIDTH);
-
-        $ret_type_output = "$start$type_modifier$xref$pointer ";
-        $symbol_len = $ret_type_len + 1 - $RETURN_TYPE_FIELD_WIDTH;
-    }
-    #@TRACE@("$symbol ret type output: [$ret_type_output], $ret_type_len");
-
-    $symbol_len += length ($symbol);
+    $ret_type_output = "$start$type_modifier$xref$pointer\n";
+
+    my $indent_len;
+    $indent_len = length ($symbol) + 2;
     my $char1 = my $char2 = my $char3 = "";
     if ($symbol_type eq 'USER_FUNCTION') {
-        $symbol_len += 3;
-        $char1 = "(";
+        $indent_len += 3;
+        $char1 = "<phrase role=\"c_punctuation\">(</phrase>";
         $char2 = "*";
-        $char3 = ")";
+        $char3 = "<phrase role=\"c_punctuation\">)</phrase>";
     }
 
     my ($symbol_output, $symbol_desc_output);
-    if ($symbol_len < $SYMBOL_FIELD_WIDTH) {
-        $symbol_output = "$char1<link linkend=\"$id\">$char2$symbol</link>$char3"
-            . (' ' x ($SYMBOL_FIELD_WIDTH - $symbol_len));
-        $symbol_desc_output = "$char1$char2$symbol$char3"
-            . (' ' x ($SYMBOL_FIELD_WIDTH - $symbol_len));
+    $symbol_output = "$char1<link linkend=\"$id\">$char2$symbol</link>$char3";
+    if ($indent_len < $MAX_SYMBOL_FIELD_WIDTH) {
+        $symbol_desc_output = "$char1$char2$symbol$char3 ";
     } else {
-        $symbol_output = "$char1<link linkend=\"$id\">$char2$symbol</link>$char3\n"
-            . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH));
+        $indent_len = $MAX_SYMBOL_FIELD_WIDTH - 8;
         $symbol_desc_output = "$char1$char2$symbol$char3\n"
-            . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH));
+          . (' ' x ($indent_len - 1));
     }
 
-    my $synop = $ret_type_output . $symbol_output . '(';
-    my $desc = "<refsect2 id=\"$id\" role=\"function\"$condition>\n<title>${symbol} ()</title>\n";
+    my $synop = "<row><entry role=\"function_type\">${ret_type_output}</entry><entry role=\"function_name\">${symbol_output}&#160;<phrase role=\"c_punctuation\">()</phrase></entry></row>\n";
+
+    my $desc = "<refsect2 id=\"$id\" role=\"function\"$condition>\n<title>${symbol}&#160;()</title>\n";
 
     $desc .= MakeIndexterms($symbol, $id);
     $desc .= "\n";
     $desc .= OutputSymbolExtraLinks($symbol);
 
-    $desc  .= "<programlisting>${ret_type_output}$symbol_desc_output(";
+    $desc  .= "<programlisting language=\"C\">${ret_type_output}$symbol_desc_output(";
 
     my @fields = ParseFunctionDeclaration($declaration, \&MakeXRef,
                                         sub {
@@ -2085,20 +2185,15 @@
         my $field_name = $fields[$i];
 
         if ($i == 1) {
-            $synop .= "$field_name";
             $desc  .= "$field_name";
         } else {
-            $synop .= ",\n"
-                . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH))
-                . " $field_name";
             $desc  .= ",\n"
-                . (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH))
-                . " $field_name";
+                . (' ' x $indent_len)
+                . "$field_name";
         }
 
     }
 
-    $synop .= ");\n";
     $desc  .= ");</programlisting>\n";
 
     $desc .= &MakeDeprecationNote($symbol);
@@ -2107,7 +2202,7 @@
     my $parameters_output = 0;
 
     if (defined ($SymbolDocs{$symbol})) {
-        my $symbol_docs = &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
+        my $symbol_docs = &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
 
         # Try to insert the parameter table at the author's desired position.
         # Otherwise we need to tag it onto the end.
@@ -2166,13 +2261,12 @@
             my $param_annotations = "";
 
             ($param_desc,$param_annotations) = & ExpandAnnotation($symbol, $param_desc);
-            $param_desc = &ExpandAbbreviations($symbol, $param_desc);
-            $param_desc .= $param_annotations;
+            $param_desc = &ConvertMarkDown($symbol, $param_desc);
             # trim
             $param_desc =~ s/^(\s|\n)+//msg;
             $param_desc =~ s/(\s|\n)+$//msg;
             if ($param_name eq "Returns") {
-                $returns = "$param_desc";
+                $returns = "$param_desc\n<para>$param_annotations</para>";
             } elsif ($param_name eq "void") {
                 #print "!!!! void in params for $symbol?\n";
             } else {
@@ -2190,7 +2284,7 @@
                     }
                 }
                 if($param_desc ne "") {
-                    $params_desc .= "<varlistentry><term><parameter>$param_name</parameter>&#160;:</term>\n<listitem><simpara>$param_desc</simpara></listitem></varlistentry>\n";
+                    $params_desc .= "<row><entry role=\"parameter_name\"><para>$param_name</para></entry>\n<entry role=\"parameter_description\">$param_desc</entry>\n<entry role=\"parameter_annotations\">$param_annotations</entry></row>\n";
                     $num_params++;
                 }
             }
@@ -2207,24 +2301,31 @@
 
         # Signals have an implicit user_data parameter which we describe.
         if ($symbol_type eq "SIGNAL") {
-            $params_desc .= "<varlistentry><term><parameter>user_data</parameter>&#160;:</term>\n<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>\n";
+            $params_desc .= "<row><entry role=\"parameter_name\"><simpara>user_data</simpara></entry>\n<entry role=\"parameter_description\"><simpara>user data set when the signal handler was connected.</simpara></entry>\n<entry role=\"parameter_annotations\"></entry></row>\n";
         }
 
         # Start a table if we need one.
-        if ($params_desc || $returns) {
-            $output .= "<variablelist role=\"params\">\n";
-            if ($params_desc ne "") {
-                #$output .= "<varlistentry><term>Parameters:</term><listitem></listitem></varlistentry>\n";
-                $output .= $params_desc;
-            }
-
-            # Output the returns info last
-            if ($returns) {
-                $output .= "<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>$returns</simpara></listitem></varlistentry>\n";
-            }
-
-            # Finish the table.
-            $output .= "</variablelist>";
+        if ($params_desc ne "") {
+          $output .= <<EOF;
+<refsect3 role="parameters">\n<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+EOF
+          $output .= $params_desc;
+          $output .= "</tbody></tgroup></informaltable>\n</refsect3>";
+        }
+
+        # Output the returns info last
+        if ($returns ne "") {
+          $output .= <<EOF;
+<refsect3 role=\"returns\">\n<title>Returns</title>
+EOF
+          $output .= $returns;
+          $output .= "\n</refsect3>";
         }
 
         # remember missing/unused parameters (needed in tmpl-free build)
@@ -2284,8 +2385,10 @@
 #               $section_id - the SGML id to use for the toplevel tag.
 #               $includes - comma-separates list of include files added at top of
 #                 synopsis, with '<' '>' around them (if not already enclosed in "").
-#               $synopsis - reference to the DocBook for the Synopsis part.
-#               $details - reference to the DocBook for the Details part.
+#               $functions_synop - reference to the DocBook for the Functions Synopsis part.
+#               $other_synop - reference to the DocBook for the Types and Values Synopsis part.
+#               $functions_details - reference to the DocBook for the Functions Details part.
+#               $other_details - reference to the DocBook for the Types and Values Details part.
 #               $signal_synop - reference to the DocBook for the Signal Synopsis part
 #               $signal_desc - reference to the DocBook for the Signal Description part
 #               $args_synop - reference to the DocBook for the Arg Synopsis part
@@ -2299,7 +2402,7 @@
 #############################################################################
 
 sub OutputSGMLFile {
-    my ($file, $title, $section_id, $includes, $synopsis, $details, $signals_synop, $signals_desc, $args_synop, $args_desc, $hierarchy, $interfaces, $implementations, $prerequisites, $derived, $file_objects) = @_;
+    my ($file, $title, $section_id, $includes, $functions_synop, $other_synop, $functions_details, $other_details, $signals_synop, $signals_desc, $args_synop, $args_desc, $hierarchy, $interfaces, $implementations, $prerequisites, $derived, $file_objects) = @_;
 
     #print "Output sgml for file $file with title '$title'\n";
 
@@ -2313,6 +2416,7 @@
     if (!defined ($short_desc) || $short_desc =~ m/^\s*$/) {
         $short_desc = "";
     } else {
+        # Don't use ConvertMarkDown here for now since we don't want blocks
         $short_desc = &ExpandAbbreviations("$title:Short_description",
                                            $short_desc);
         #print "Found short_desc: $short_desc";
@@ -2321,7 +2425,7 @@
     if (!defined ($long_desc) || $long_desc =~ m/^\s*$/) {
         $long_desc = "";
     } else {
-        $long_desc = &ExpandAbbreviations("$title:Long_description",
+        $long_desc = &ConvertMarkDown("$title:Long_description",
                                           $long_desc);
         #print "Found long_desc: $long_desc";
     }
@@ -2329,7 +2433,7 @@
     if (!defined ($see_also) || $see_also =~ m%^\s*(<para>)?\s*(</para>)?\s*$%) {
         $see_also = "";
     } else {
-        $see_also = &ExpandAbbreviations("$title:See_Also", $see_also);
+        $see_also = &ConvertMarkDown("$title:See_Also", $see_also);
         #print "Found see_also: $see_also";
     }
     if ($see_also) {
@@ -2376,18 +2480,19 @@
     $year += 1900;
 
     my $include_output = "";
-    my $include;
-    foreach $include (split (/,/, $includes)) {
+    if ($includes) {
+      $include_output .= "<refsect1 id=\"$section_id.includes\"><title>Includes</title><synopsis>";
+      my $include;
+      foreach $include (split (/,/, $includes)) {
         if ($include =~ m/^\".+\"$/) {
-            $include_output .= "#include ${include}\n";
+          $include_output .= "#include ${include}\n";
         }
         else {
-            $include =~ s/^\s+|\s+$//gs;
-            $include_output .= "#include &lt;${include}&gt;\n";
+          $include =~ s/^\s+|\s+$//gs;
+          $include_output .= "#include &lt;${include}&gt;\n";
         }
-    }
-    if ($include_output ne '') {
-        $include_output = "\n$include_output\n";
+      }
+      $include_output .= "</synopsis></refsect1>\n";
     }
 
     my $extralinks = OutputSectionExtraLinks($title,"Section:$file");
@@ -2428,19 +2533,19 @@
 <refpurpose>$short_desc</refpurpose>
 </refnamediv>
 $stability
-<refsynopsisdiv id="$section_id.synopsis" role="synopsis">
-<title role="synopsis.title">Synopsis</title>
-$object_anchors
-<synopsis>$include_output$${synopsis}</synopsis>
-</refsynopsisdiv>
-$$hierarchy$$prerequisites$$derived$$interfaces$$implementations$$args_synop$$signals_synop
+$$functions_synop$$args_synop$$signals_synop$object_anchors$$other_synop$$hierarchy$$prerequisites$$derived$$interfaces$$implementations
+$include_output
 <refsect1 id="$section_id.description" role="desc">
 <title role="desc.title">Description</title>
 $extralinks$long_desc
 </refsect1>
-<refsect1 id="$section_id.details" role="details">
-<title role="details.title">Details</title>
-$$details
+<refsect1 id="$section_id.functions_details" role="details">
+<title role="details.title">Functions</title>
+$$functions_details
+</refsect1>
+<refsect1 id="$section_id.other_details" role="details">
+<title role="details.title">Types and Values</title>
+$$other_details
 </refsect1>
 $$args_desc$$signals_desc$see_also
 </refentry>
@@ -2654,7 +2759,8 @@
     # If we're not in CDATA convert to entities.
     $text =~ s/&(?![a-zA-Z#]+;)/&amp;/g;        # Do this first, or the others get messed up.
     $text =~ s/<(?![a-zA-Z\/!])/&lt;/g;
-    $text =~ s/(?<![a-zA-Z0-9"'\/-])>/&gt;/g;
+    # Allow ">" at beginning of string for blockquote markdown
+    $text =~ s/(?<=[^\w\n"'\/-])>/&gt;/g;
 
     # Handle "#include <xxxxx>"
     $text =~ s/#include(\s+)<([^>]+)>/#include$1&lt;$2&gt;/g;
@@ -2747,12 +2853,13 @@
 sub ExpandAbbreviations {
   my ($symbol, $text) = @_;
 
+  # Note: This is a fallback and normally done in the markdown parser
+
   # Convert "|[" and "]|" into the start and end of program listing examples.
-  # FIXME: we like to have a way to specify parameters e.g. language="c"
-  $text =~ s%\|\[%<informalexample><programlisting>%g;
-  $text =~ s%\]\|%</programlisting></informalexample>%g;
-  # TODO: check for a xml comment after |[ and pick the language attribute from
-  # that
+  # Support \[<!-- language="C" --> modifiers
+  $text =~ s%\|\[<!-- language="([^"]+)" -->%<informalexample><programlisting language="$1"><![CDATA[%g;
+  $text =~ s%\|\[%<informalexample><programlisting><![CDATA[%g;
+  $text =~ s%\]\|%]]></programlisting></informalexample>%g;
 
   # keep CDATA unmodified, preserve ulink tags (ideally we preseve all tags
   # as such)
@@ -2787,6 +2894,8 @@
                                \&ExpandAbbreviationsEndTag,
                                \&ExpandAbbreviationsCallback2);
   } elsif ($tag eq "") {
+    # NOTE: this is a fallback. It is normally done by the Markdown parser.
+
     # We are outside any CDATA or <programlisting> sections, so we expand
     # any gtk-doc abbreviations.
 
@@ -2814,15 +2923,6 @@
     # Convert '#symbol', but not '\#symbol'.
     $text =~ s/(\A|[^\\])#([\w\-:\.]+[\w]+)/$1.&MakeHashXRef($2, "type");/eg;
     $text =~ s/\\#/#/g;
-
-    # Expand urls
-    # FIXME: should we skip urls that are already tagged? (e.g. <literal>http://...</literal>)
-    # this is apparently also called for markup and not just for plain text
-    # disable for now.
-    #$text =~ s%(http|https|ftp)://(.*?)((?:\s|,|\)|\]|\<|\.\s))%<ulink url="$1://$2">$2</ulink>$3%g;
-
-    # TODO: optionally check all words from $text against internal symbols and
-    # warn if those could be xreffed, but miss a %,# or ()
   }
 
   return $text;
@@ -2838,6 +2938,9 @@
     # FIXME: why is this different from &ExpandAbbreviationsCallback(),
     #        why not just call it
     $text =~ s/#(\w+)/&MakeHashXRef($1, "");/eg;
+  } elsif ($tag eq "<![CDATA[") {
+    # NOTE: this is a fallback. It is normally done by the Markdown parser.
+    $text = &ReplaceEntities ($text, $symbol);
   }
 
   return $text;
@@ -2859,13 +2962,13 @@
     # If the symbol is in the form "Object::signal", then change the symbol to
     # "Object-signal" and use "signal" as the text.
     if ($symbol =~ s/::/-/) {
-      $text = "\"$'\"";
+      $text = "“$'”";
     }
 
     # If the symbol is in the form "Object:property", then change the symbol to
     # "Object--property" and use "property" as the text.
     if ($symbol =~ s/:/--/) {
-      $text = "\"$'\"";
+      $text = "“$'”";
     }
 
     if ($tag ne "") {
@@ -3029,24 +3132,26 @@
 sub MakeDeprecationNote {
     my ($symbol) = $_[0];
     my $desc = "";
-    my $note = "";
     if (exists $Deprecated{$symbol}) {
-        $desc .= "<warning>";
-
-        if ($Deprecated{$symbol} =~ /^\s*([0-9\.]+)\s*:/) {
-                $desc .= "<para><literal>$symbol</literal> has been deprecated since version $1 and should not be used in newly-written code.";
+        my $note;
+
+        $desc .= "<warning><para><literal>$symbol</literal> ";
+
+        $note = $Deprecated{$symbol};
+
+        if ($note =~ /^\s*([0-9\.]+)\s*:?/) {
+                $desc .= "has been deprecated since version $1 and should not be used in newly-written code.</para>";
         } else {
-                $desc .= "<para><literal>$symbol</literal> is deprecated and should not be used in newly-written code.";
+                $desc .= "is deprecated and should not be used in newly-written code.</para>";
         }
-        if ($Deprecated{$symbol} ne "") {
-            $note = &ExpandAbbreviations($symbol, $Deprecated{$symbol});
-            $note =~ s/^\s*([0-9\.]+)\s*:\s*//;
-            $note =~ s/^\s+//;
-            $note =~ s/\s+$//;
-            $note =~ s%\n{2,}%\n</para>\n<para>\n%g;
+        $note =~ s/^\s*([0-9\.]+)\s*:?\s*//;
+        $note =~ s/^\s+//;
+        $note =~ s/\s+$//;
+        if ($note ne "") {
+            $note = &ConvertMarkDown($symbol, $note);
             $desc .= " " . $note;
         }
-        $desc .= "</para></warning>\n";
+        $desc .= "</warning>\n";
     }
     return $desc;
 }
@@ -3093,7 +3198,9 @@
     }
 
     if ($desc ne "") {
-        $desc=" condition=\"".$desc."\"";
+        my $cond = $desc;
+        $cond =~ s/\"/&quot;/g;
+        $desc=" condition=\"".$cond."\"";
         #print "condition for '$symbol' = '$desc'\n";
     }
     return $desc;
@@ -3104,12 +3211,15 @@
 # Description : Returns the DocBook output describing the ancestors and
 #               immediate children of a GObject subclass. It uses the
 #               global @Objects and @ObjectLevels arrays to walk the tree.
+#
 # Arguments   : $object - the GtkObject subclass.
+#               @hierarchy - previous hierarchy
 #############################################################################
 
 sub GetHierarchy {
-    my ($object) = @_;
-
+    my ($object,$hierarchy_ref) = @_;
+    my @hierarchy = @{$hierarchy_ref};
+    
     # Find object in the objects array.
     my $found = 0;
     my @children = ();
@@ -3132,7 +3242,7 @@
         }
     }
     if (!$found) {
-        return "";
+        return @hierarchy;
     }
 
     # Walk up the hierarchy, pushing ancestors onto the ancestors array.
@@ -3148,9 +3258,9 @@
         }
     }
 
-    # Output the ancestors list, indented and with links.
-    my $hierarchy = "<synopsis>\n";
-    $level = 0;
+    # Output the ancestors, indented and with links.
+    my $last_index = 0;
+    $level = 1;
     for ($i = $#ancestors; $i >= 0; $i--) {
         my $link_text;
         # Don't add a link to the current object, i.e. when i == 0.
@@ -3160,25 +3270,59 @@
         } else {
             $link_text = "$ancestors[$i]";
         }
-        if ($level == 0) {
-            $hierarchy .= "  $link_text\n";
+        my $indented_text = ' ' x ($level * 4) . $link_text;
+        # Check if we already have this object
+        my $index = -1;
+        for ($j = 0; $j <= $#hierarchy; $j++) {
+            if ($hierarchy[$j] eq $indented_text) {
+                $index = $j;
+                last;
+            }
+        }
+        if ($index == -1) {
+            # We have a new entry, find insert position in alphabetical order
+            my $indent = ' ' x ($level * 4);
+            my $found = 0;
+            for ($j = $last_index; $j <= $#hierarchy; $j++) {
+                if ($hierarchy[$j] !~ m/^${indent}/) {
+                    $last_index = $j;
+                    $found = 1;
+                    last;
+                } elsif ($hierarchy[$j] =~ m/^${indent}[^ ]/) {
+                    my $stripped_text = $hierarchy[$j];
+                    if ($indented_text !~ m/<link linkend/) {
+                        $stripped_text =~ s%<link linkend="[A-Za-z]*">%%;
+                        $stripped_text =~ s%</link>%%;
+                    }
+                    if ($indented_text lt $stripped_text) {
+                        $last_index = $j;
+                        $found = 1;
+                        last;
+                    } 
+                }
+            }
+            if (!$found) {
+              $last_index = 1 + $#hierarchy;
+            }
+            splice @hierarchy, $last_index, 0, ($indented_text);
+            $last_index++;
         } else {
-#            $hierarchy .= ' ' x ($level * 6 - 3) . "|\n";
-            $hierarchy .= ' ' x ($level * 6 - 3) . "+----$link_text\n";
+            # Already have this one, remmeber index as base insert point
+            $last_index = $index + 1;
         }
         $level++;
     }
+    # Output the children, indented and with links.
     for ($i = 0; $i <= $#children; $i++) {
-      my $id = &CreateValidSGMLID ($children[$i]);
-      my $link_text = "<link linkend=\"$id\">$children[$i]</link>";
-      $hierarchy .= ' ' x ($level * 6 - 3) . "+----$link_text\n";
-    }
-    $hierarchy .= "</synopsis>\n";
+        my $id = &CreateValidSGMLID ($children[$i]);
+        my $indented_text = ' ' x ($level * 4) . "<link linkend=\"$id\">$children[$i]</link>";
+        splice @hierarchy, $last_index, 0, ($indented_text);
+        $last_index++;
+    }    
 
-    return $hierarchy;
+    return @hierarchy; 
 }
 
-
 #############################################################################
 # Function    : GetInterfaces
 # Description : Returns the DocBook output describing the interfaces
@@ -3366,15 +3510,12 @@
             my $symbol = "${object}::${name}";
             my $id = &CreateValidSGMLID ("$object-$name");
 
-            my $pad = ' ' x (46 - length($name));
-            $synop .= "  &quot;<link linkend=\"$id\">$name</link>&quot;$pad ";
-
-            $desc .= "<refsect2 id=\"$id\" role=\"signal\"><title>The <literal>&quot;$name&quot;</literal> signal</title>\n";
+            $desc .= "<refsect2 id=\"$id\" role=\"signal\"><title>The <literal>“$name”</literal> signal</title>\n";
             $desc .= MakeIndexterms($symbol, $id);
             $desc .= "\n";
             $desc .= OutputSymbolExtraLinks($symbol);
 
-            $desc .= "<programlisting>";
+            $desc .= "<programlisting language=\"C\">";
 
             $SignalReturns[$i] =~ m/\s*(const\s+)?(\w+)\s*(\**)/;
             my $type_modifier = defined($1) ? $1 : "";
@@ -3382,12 +3523,12 @@
             my $pointer = $3;
             my $xref = &MakeXRef ($type, &tagify($type, "returnvalue"));
 
-            my $ret_type_len = length ($type_modifier) + length ($pointer)
-                + length ($type);
-            my $ret_type_output = "$type_modifier$xref$pointer"
-                . (' ' x ($RETURN_TYPE_FIELD_WIDTH - $ret_type_len));
+            my $ret_type_output = "$type_modifier$xref$pointer";
+            my $callback_name = "user_function";
+            $desc  .= "${ret_type_output}\n${callback_name} (";
 
-            $desc  .= "${ret_type_output}user_function " . &MakeReturnField("") . " (";
+            my $indentation = ' ' x (length($callback_name) + 2);
+            my $pad = $indentation;
 
             my $sourceparams = $SourceSymbolParams{$symbol};
             my @params = split ("\n", $SignalPrototypes[$i]);
@@ -3398,32 +3539,33 @@
             # do two passes, the first one is to calculate padding
             for ($l = 0; $l < 2; $l++) {
                 for ($j = 0; $j <= $#params; $j++) {
+                    my $param_name;
                     # allow alphanumerics, '_', '[' & ']' in param names
                     if ($params[$j] =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)\s*$/) {
                         $type = $1;
                         $pointer = $2;
                         if (defined($sourceparams)) {
-                            $name = $$sourceparams[$PARAM_FIELD_COUNT * $j];
+                            $param_name = $$sourceparams[$PARAM_FIELD_COUNT * $j];
                         }
                         else {
-                            $name = $3;
+                            $param_name = $3;
                         }
-                        if (!defined($name)) {
-                            $name = "arg$j";
+                        if (!defined($param_name)) {
+                            $param_name = "arg$j";
                         }
                         if ($l == 0) {
                             if (length($type) + length($pointer) > $type_len) {
                                 $type_len = length($type) + length($pointer);
                             }
-                            if (length($name) > $name_len) {
-                                $name_len = length($name);
+                            if (length($param_name) > $name_len) {
+                                $name_len = length($param_name);
                             }
                         }
                         else {
                             $xref = &MakeXRef ($type, &tagify($type, "type"));
                             $pad = ' ' x ($type_len - length($type) - length($pointer));
-                            $desc .= "$xref$pad $pointer$name,\n";
-                            $desc .= (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH));
+                            $desc .= "$xref$pad $pointer${param_name},\n";
+                            $desc .= $indentation;
                         }
                     } else {
                         &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
@@ -3434,60 +3576,48 @@
             $xref = &MakeXRef ("gpointer", &tagify("gpointer", "type"));
             $pad = ' ' x ($type_len - length("gpointer"));
             $desc  .= "$xref$pad user_data)";
+            $desc  .= "</programlisting>\n";
 
             my $flags = $SignalFlags[$i];
             my $flags_string = "";
 
             if (defined ($flags)) {
               if ($flags =~ m/f/) {
-                $flags_string = "<link linkend=\"G-SIGNAL-RUN-FIRST:CAPS\"><literal>Run First</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-RUN-FIRST:CAPS\">Run First</link>";
               }
               elsif ($flags =~ m/l/) {
-                $flags_string = "<link linkend=\"G-SIGNAL-RUN-LAST:CAPS\"><literal>Run Last</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-RUN-LAST:CAPS\">Run Last</link>";
               }
               elsif ($flags =~ m/c/) {
-                $flags_string = "<link linkend=\"G-SIGNAL-RUN-CLEANUP:CAPS\"><literal>Cleanup</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-RUN-CLEANUP:CAPS\">Cleanup</link>";
                 $flags_string = "Cleanup";
               }
               if ($flags =~ m/r/) {
                 if ($flags_string) { $flags_string .= " / "; }
-                $flags_string = "<link linkend=\"G-SIGNAL-NO-RECURSE:CAPS\"><literal>No Recursion</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-NO-RECURSE:CAPS\">No Recursion</link>";
               }
               if ($flags =~ m/d/) {
                 if ($flags_string) { $flags_string .= " / "; }
-                $flags_string = "<link linkend=\"G-SIGNAL-DETAILED:CAPS\"><literal>Has Details</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-DETAILED:CAPS\">Has Details</link>";
               }
               if ($flags =~ m/a/) {
                 if ($flags_string) { $flags_string .= " / "; }
-                $flags_string = "<link linkend=\"G-SIGNAL-ACTION:CAPS\"><literal>Action</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-ACTION:CAPS\">Action</link>";
               }
               if ($flags =~ m/h/) {
                 if ($flags_string) { $flags_string .= " / "; }
-                $flags_string = "<link linkend=\"G-SIGNAL-NO-HOOKS:CAPS\"><literal>No Hooks</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-NO-HOOKS:CAPS\">No Hooks</link>";
               }
             }
 
-            if ($flags_string)
-              {
-                $synop .= ": $flags_string\n";
-
-                $pad = ' ' x (5 + $name_len - length("user_data"));
-                $desc  .= "$pad : $flags_string</programlisting>\n";
-              }
-            else
-              {
-                $synop .= "\n";
-                $desc  .= "</programlisting>\n";
-              }
-
-            $desc .= &MakeDeprecationNote($symbol);
+            $synop .= "<row><entry role=\"signal_type\">${ret_type_output}</entry><entry role=\"signal_name\"><link linkend=\"$id\">${name}</link></entry><entry role=\"signal_flags\">${flags_string}</entry></row>\n";
 
             my $parameters = &OutputParamDescriptions ("SIGNAL", $symbol);
             my $parameters_output = 0;
 
             $AllSymbols{$symbol} = 1;
             if (defined ($SymbolDocs{$symbol})) {
-                my $symbol_docs = &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
+                my $symbol_docs = &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
 
                 # Try to insert the parameter table at the author's desired
                 # position. Otherwise we need to tag it onto the end.
@@ -3500,10 +3630,14 @@
                     $AllDocumentedSymbols{$symbol} = 1;
                 }
             }
+            $desc .= &MakeDeprecationNote($symbol);
 
             if ($parameters_output == 0) {
                 $desc .= $parameters;
-              }
+            }
+            if ($flags_string) {
+                $desc  .= "<para>Flags: $flags_string</para>\n";
+            }
             $desc .= OutputSymbolTraits ($symbol);
             $desc .= "</refsect2>";
         }
@@ -3563,14 +3697,14 @@
             my $default_output = CreateValidSGML ($default);
 
             if ($type eq "GtkString") {
-                $type = "char*";
+                $type = "char&#160;*";
             }
             if ($type eq "GtkSignal") {
                 $type = "GtkSignalFunc, gpointer";
                 $type_output = &MakeXRef ("GtkSignalFunc") . ", "
                     . &MakeXRef ("gpointer");
             } elsif ($type =~ m/^(\w+)\*$/) {
-                $type_output = &MakeXRef ($1, &tagify($1, "type")) . "*";
+                $type_output = &MakeXRef ($1, &tagify($1, "type")) . "&#160;*";
             } else {
                 $type_output = &MakeXRef ($type, &tagify($type, "type"));
             }
@@ -3595,7 +3729,7 @@
             my $blurb;
             if (defined($SymbolDocs{$symbol}) &&
                 !IsEmptyDoc($SymbolDocs{$symbol})) {
-                $blurb = &ExpandAbbreviations($symbol, $SymbolDocs{$symbol});
+                $blurb = &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
                 #print ".. [$SymbolDocs{$symbol}][$blurb]\n";
                 $AllDocumentedSymbols{$symbol} = 1;
             }
@@ -3610,17 +3744,20 @@
             }
 
             my $pad1 = " " x (24 - length ($name));
-            my $pad2 = " " x (20 - length ($type));
 
-             my $arg_synop = "  &quot;<link linkend=\"$id\">$name</link>&quot;$pad1 $type_output $pad2 : $flags_string\n";
-            my $arg_desc = "<refsect2 id=\"$id\" role=\"property\"><title>The <literal>&quot;$name&quot;</literal> $kind</title>\n";
+            my $arg_synop = "<row><entry role=\"property_type\">$type_output</entry><entry role=\"property_name\"><link linkend=\"$id\">$name</link></entry><entry role=\"property_flags\">$flags_string</entry></row>\n";
+            my $arg_desc = "<refsect2 id=\"$id\" role=\"property\"><title>The <literal>“$name”</literal> $kind</title>\n";
             $arg_desc .= MakeIndexterms($symbol, $id);
             $arg_desc .= "\n";
             $arg_desc .= OutputSymbolExtraLinks($symbol);
 
-            $arg_desc .= "<programlisting>  &quot;$name&quot;$pad1 $type_output $pad2 : $flags_string</programlisting>\n";
+            $arg_desc .= "<programlisting>  “$name”$pad1 $type_output</programlisting>\n";
+            $arg_desc .= $blurb;
             $arg_desc .= &MakeDeprecationNote($symbol);
-            $arg_desc .= $blurb;
+
+            if ($flags_string) {
+              $arg_desc  .= "<para>Flags: $flags_string</para>\n";
+            }
             if ($range ne "") {
                 $arg_desc .= "<para>Allowed values: $range_output</para>\n";
             }
@@ -3877,9 +4014,7 @@
                 }
 
                 if ($deprecated_desc) {
-                    if (exists $Deprecated{$symbol}) {
-                    }
-                    else {
+                    if (!exists $Deprecated{$symbol}) {
                          # don't warn for signals and properties
                          #if ($symbol !~ m/::?(.*)/) {
                          if (defined $DeclarationTypes{$symbol}) {
@@ -3910,7 +4045,7 @@
                 $symbol = $1;
                 #print "SECTION DOCS found in source for : '$symbol'\n";
                 $ignore_broken_returns = 1;
-            } elsif (m%^\s*([\w:-]*\w)\s*:?\s*(\([a-z ]+\)\s*)*$%) {
+            } elsif (m%^\s*([\w:-]*\w)\s*:?\s*(\([-a-z0-9_ ]+\)\s*)*$%) {
                 $symbol = $1;
                 #print "SYMBOL DOCS found in source for : '$symbol'\n";
             }
@@ -4340,14 +4475,7 @@
             # Do not add <para> to nothing, it breaks missing docs checks.
             my $src_doc_para = "";
             if ($src_doc ne "") {
-                # Expand markdown (and do paragraphs)
-                $src_doc_para = &ConvertMarkDown ($src_doc, $symbol);
-                ## fixup xml markup
-                # FIXME: this is questionable, as we can't make assumtions on the content really
-                #$src_doc_para =~ s%^<para>\n(<refsect[1-9])%$1%gms;
-                #$src_doc_para =~ s%^<para>\n<para>%<para>%gms;
-                #$src_doc_para =~ s%(</refsect[1-9]>)\n</para>$%$1%gms;
-                #print "$symbol : [$src_doc][$src_doc_para]\n";
+                $src_doc_para = $src_doc;
             }
 
             if ($symbol =~ m/$TMPL_DIR\/.+:Long_Description/) {
@@ -4526,109 +4654,742 @@
     return 0;
 }
 
-
 #############################################################################
 # Function    : ConvertMarkDown
-# Description : Converts mark down syntax to the respective docbook, but only
-#               outside CDATA and <programlisting> tags.
+# Description : Converts mark down syntax to the respective docbook.
 #               http://de.wikipedia.org/wiki/Markdown
-#               Code snippets have been takesn from
-#               http://daringfireball.net/projects/markdown/
-#                 Copyright (c) 2004 John Gruber
-# Arguments   : the doc-string, the symbol name
+#               Inspired by the design of ParseDown
+#               http://parsedown.org/
+#               Copyright (c) 2013 Emanuil Rusev, erusev.com
+# Arguments   : the symbol name, the doc-string
 #############################################################################
-my $md_in_refsect2;
+
 sub ConvertMarkDown {
-    my ($text, $symbol) = @_;
-
-    # reset state
-    $md_in_refsect2=0;
-
-    # convert
-    $text = &ModifyXMLElements ($text, $symbol,
-                               "<!\\[CDATA\\[|<programlisting[^>]*>|\\|\\[",
-                               \&ConvertMarkDownEndTag,
-                               \&ConvertMarkDownCallback);
-    # encapsulate and terminate
-    $text = "<para>\n$text\n</para>";
-    if ($md_in_refsect2==1) {
-        $text = "$text</refsect2>"
-    }
+    my ($symbol, $text) = @_;
+
+    $text = &MarkDownParse ($text, $symbol);
+
     return $text
 }
 
-sub ConvertMarkDownEndTag {
-  if ($_[0] eq "<!\[CDATA\[") {
-    return "]]>";
-  } elsif ($_[0] eq "|[") {
-    return "]\\|";
-  } else {
-    return "</programlisting>";
-  }
-}
-
-sub ConvertMarkDownCallback {
-  my ($text, $symbol, $tag) = @_;
-
-  # If we're not in CDATA or a <programlisting> we convert blank lines so
-  # they start a new <para>.
-  if ($tag eq "") {
-    my $end_of_para="";
-    my $end_of_section="";
-    my $have_list=0;
-
-    $end_of_para = "$end_of_para</para>";
-    $end_of_section = "$end_of_section</para>";
-    if ($md_in_refsect2==1) {
-        $end_of_section= "$end_of_section</refsect2>";
-    }
-
-    # TODO(ensonic): it would be nice to add id parameters to the refsect2 elements
-
-    # Setext-style headers:
-    #          Header 1
-    #          ========
-    #
-    #          Header 2
-    #          --------
-    #
-    if($text =~ s%^\n(.+)[ \t]*\n=+[ \t]*\n\n%$end_of_section<refsect2><title>$1</title><para>\n%gm) {
-        $md_in_refsect2=1;
-    }
-
-    # atx-style headers:
-    #        # Header 1
-    #        ## Header 2
-    #        ## Header 2 with closing hashes ##
-    #        ...
-    #        ###### Header 6
-    #
-    if($text =~ s%^\n\#[ \t]*(.+?)[ \t]*\#\n+%$end_of_section<refsect2><title>$1</title><para>\n%gm) {
-        $md_in_refsect2=1;
-    }
-
-    # Simple (unnested) lists:
-    #   Please select:
-    #   - item 1
-    #   - item 2 with loooong
-    #     description
-    #   - item 3
-    #
-    #   New paragraph.
-    $text.="\n"; # we need a new line to avoid too complicated matching rules below
-    if ($text =~ s%(?<=\n)-\s+(.+?)(?=(?:\n-\s+)|(?:\n\n)|(?:\n$))%<listitem><para>$1</para></listitem>%gs) {
-        $text =~ s%(?<!</listitem>)(\n<listitem>)%\n<itemizedlist>$1%g;
-        $text =~ s%(</listitem>\n)(?!<listitem>)%$1</itemizedlist>\n%g;
-    }
-    chomp $text;
-
-    # Make Paragraphs on blank lines
-    $text =~ s%\n{2,}%\n$end_of_para\n<para>\n%g;
-  }
-
-  return $text;
-}
-
+# SUPPORTED MARKDOWN
+# ==================
+#
+# Atx-style Headers
+# -----------------
+#
+# # Header 1
+#
+# ## Header 2 ##
+#
+# Setext-style Headers
+# --------------------
+#
+# Header 1
+# ========
+#
+# Header 2
+# --------
+#
+# Ordered (unnested) Lists
+# ------------------------
+#
+# 1. item 1
+#
+# 1. item 2 with loooong
+#    description
+#
+# 3. item 3
+#
+# Note: we require a blank line above the list items
+#
+
+# TODO(ensonic): it would be nice to add id parameters to the refsect2 elements
+
+sub MarkDownParseBlocks {
+  my ($linesref, $symbol, $context) = @_;
+  my $line;
+  my @md_blocks = ();
+  my $md_block = { type => "" };
+
+ OUTER: foreach $line (@$linesref) {
+    my $first_char = substr ($line, 0, 1);
+    my $deindented_line;
+
+    if ($md_block->{"type"} eq "markup") {
+      if (!$md_block->{"closed"}) {
+        if (index ($line, $md_block->{"start"}) != -1) {
+          $md_block->{"depth"}++;
+        }
+        if (index ($line, $md_block->{"end"}) != -1) {
+          if ($md_block->{"depth"} > 0) {
+            $md_block->{"depth"}--;
+          } else {
+            $md_block->{"closed"} = 1;
+          }
+        }
+        $md_block->{"text"} .= "\n" . $line;
+        next OUTER;
+      }
+    }
+
+    $deindented_line = $line;
+    $deindented_line =~ s/^\s+//;
+
+    if ($md_block->{"type"} eq "heading") {
+      # a heading is ended by any level less than or equal
+      if ($md_block->{"level"} == 1) {
+        if ($line =~ /^={4,}[ \t]*$/) {
+          my $text = pop $md_block->{"lines"};
+          $md_block->{"interrupted"} = 0;
+          push @md_blocks, $md_block;
+
+          $md_block = { type => "heading",
+                        text => $text,
+                        lines => [],
+                        level => 1 };
+          next OUTER;
+        } elsif ($line =~ /^[#][ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$/) {
+          $md_block->{"interrupted"} = 0;
+          push @md_blocks, $md_block;
+
+          $md_block = { type => "heading",
+                        text => $1,
+                        id => $2,
+                        lines => [],
+                        level => 1 };
+          next OUTER;
+        } else {
+          # push lines into the block until the end is reached
+          push $md_block->{"lines"}, $line;
+          next OUTER;
+        }
+      } else {
+        if ($line =~ /^[=]{4,}[ \t]*$/) {
+          my $text = pop $md_block->{"lines"};
+          $md_block->{"interrupted"} = 0;
+          push @md_blocks, $md_block;
+
+          $md_block = { type => "heading",
+                        text => $text,
+                        lines => [],
+                        level => 1 };
+          next OUTER;
+        } elsif ($line =~ /^[-]{4,}[ \t]*$/) {
+          my $text = pop $md_block->{"lines"};
+          $md_block->{"interrupted"} = 0;
+          push @md_blocks, $md_block;
+
+          $md_block = { type => "heading",
+                        text => $text,
+                        lines => [],
+                        level => 2 };
+          next OUTER;
+        } elsif ($line =~ /^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$/) {
+          $md_block->{"interrupted"} = 0;
+          push @md_blocks, $md_block;
+
+          $md_block = { type => "heading",
+                        text => $2,
+                        id => $3,
+                        lines => [],
+                        level => length($1) };
+          next OUTER;
+        } else {
+          # push lines into the block until the end is reached
+          push $md_block->{"lines"}, $line;
+          next OUTER;
+        }
+      }
+    } elsif ($md_block->{"type"} eq "code") {
+      if ($line =~ /^[ \t]*\]\|/) {
+        push @md_blocks, $md_block;
+        $md_block = { type => "paragraph",
+                      text => "",
+                      lines => [] };
+      } else {
+        push $md_block->{"lines"}, $line;
+      }
+      next OUTER;
+    }
+
+    if ($deindented_line eq "") {
+      $md_block->{"interrupted"} = 1;
+      next;
+    }
+
+    if ($md_block->{"type"} eq "quote") {
+      if (!$md_block->{"interrupted"}) {
+        $line =~ s/^[ ]*>[ ]?//;
+        push $md_block->{"lines"}, $line;
+        next OUTER;
+      }
+    } elsif ($md_block->{"type"} eq "li") {
+      my $marker = $md_block->{"marker"};
+      if ($line =~ /^([ ]{0,3})($marker)[ ](.*)/) {
+        my $indentation = $1;
+        if ($md_block->{"indentation"} ne $indentation) {
+          push $md_block->{"lines"}, $line;
+        } else {
+          my $lines = $3;
+          my $ordered = $md_block->{"ordered"};
+          $lines =~ s/^[ ]{0,4}//;
+          $md_block->{"last"} = 0;
+          push @md_blocks, $md_block;
+          $md_block = { type => "li",
+                        ordered => $ordered,
+                        indentation => $indentation,
+                        marker => $marker,
+                        first => 0,
+                        last => 1,
+                        lines => [ $lines ] };
+        }
+        next OUTER;
+      }
+
+      if ($md_block->{"interrupted"}) {
+        if ($first_char eq " ") {
+          push $md_block->{"lines"}, "";
+          $line =~ s/^[ ]{0,4}//;
+          push $md_block->{"lines"}, $line;
+          $md_block->{"interrupted"} = 0;
+          next OUTER;
+        }
+      } else {
+        $line =~ s/^[ ]{0,4}//;
+        push $md_block->{"lines"}, $line;
+        next OUTER;
+      }
+    }
+
+    # indentation sensitive types
+
+    if ($line =~ /^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$/) {
+      # atx heading (#)
+      push @md_blocks, $md_block;
+
+      $md_block = { type => "heading",
+                    text => $2,
+                    id => $3,
+                    lines => [],
+                    level => length($1) };
+
+      next OUTER;
+    } elsif ($line =~ /^={4,}[ \t]*$/) {
+      # setext heading (====)
+
+      if ($md_block->{"type"} eq "paragraph" && $md_block->{"interrupted"}) {
+        push @md_blocks, $md_block;
+        $md_block->{"type"} = "heading";
+        $md_block->{"lines"} = [];
+        $md_block->{"level"} = 1;
+      }
+
+      next OUTER;
+    } elsif ($line =~ /^-{4,}[ \t]*$/) {
+      # setext heading (-----)
+
+      if ($md_block->{"type"} eq "paragraph" && $md_block->{"interrupted"}) {
+        push @md_blocks, $md_block;
+        $md_block->{"type"} = "heading";
+        $md_block->{"lines"} = [];
+        $md_block->{"level"} = 2;
+      }
+
+      next OUTER;
+    } elsif ($line =~ /^[ \t]*\|\[[ ]*(?:<!-- language="([^"]+?)" -->)?/) {
+      # code
+      $md_block->{"interrupted"} = 1;
+      push @md_blocks, $md_block;
+      $md_block = { type => "code",
+                    language => $1,
+                    lines => [] };
+      next OUTER;
+    }
+
+    # indentation insensitive types
+
+    if ($line =~ /^[ ]*<!DOCTYPE/) {
+      push @md_blocks, $md_block;
+
+      $md_block = { type   => "markup",
+                    text   => $deindented_line,
+                    start  => "<",
+                    end    => ">",
+                    closed => 0,
+                    depth  => 0 };
+
+    } elsif ($line =~ /^[ ]*<\??(\w+)[^>]*([\/\?])?[ \t]*>/) {
+      # markup, including <?xml version="1.0"?>
+      my $tag = $1;
+      my $is_self_closing = defined($2);
+      # FIXME: why do we need to skip https? here, if we generalize this to all
+      # uri schemes we get parsing errors
+      if (! $MD_TEXT_LEVEL_ELEMENTS{$tag} && $tag !~ /^https?/) {
+        push @md_blocks, $md_block;
+
+        if ($is_self_closing) {
+          $md_block = { type => "self-closing tag",
+                        text => $deindented_line };
+          $is_self_closing = 0;
+          next OUTER;
+        }
+
+        $md_block = { type   => "markup",
+                      text   => $deindented_line,
+                      start  => "<" . $tag . ">",
+                      end    => "</" . $tag . ">",
+                      closed => 0,
+                      depth  => 0 };
+        if ($deindented_line =~ /<\/$tag>/) {
+          $md_block->{"closed"} = 1;
+        }
+        next OUTER;
+      }
+    } elsif ($line =~ /^([ ]*)[*+-][ ](.*)/) {
+      # li
+      push @md_blocks, $md_block;
+      my $lines = $2;
+      my $indentation = $1;
+      $lines =~ s/^[ ]{0,4}//;
+      $md_block = { type => "li",
+                    ordered => 0,
+                    indentation => $indentation,
+                    marker => "[*+-]",
+                    first => 1,
+                    last => 1,
+                    lines => [ $lines ] };
+      next OUTER;
+    } elsif ($line =~ /^[ ]*>[ ]?(.*)/) {
+      push @md_blocks, $md_block;
+      $md_block = { type => "quote",
+                    lines => [ $1 ] };
+      next OUTER;
+    }
+
+    # list item
+
+    if ($line =~ /^([ ]{0,4})\d+[.][ ]+(.*)/) {
+      push @md_blocks, $md_block;
+      my $lines = $2;
+      my $indentation = $1;
+      $lines =~ s/^[ ]{0,4}//;
+
+      $md_block = { type => "li",
+                    ordered => 1,
+                    indentation => $indentation,
+                    marker => "\\d+[.]",
+                    first => 1,
+                    last => 1,
+                    lines => [ $lines ] };
+
+      next;
+    }
+
+    # paragraph
+    if ($md_block->{"type"} eq "paragraph") {
+      if ($md_block->{"interrupted"}) {
+        push @md_blocks, $md_block;
+        $md_block = { type => "paragraph",
+                      interrupted => 0,
+                      text => $line };
+      } else {
+        $md_block->{"text"} .= "\n" . $line;
+      }
+    } else {
+      push @md_blocks, $md_block;
+      $md_block = { type => "paragraph",
+                    text => $line };
+    }
+  }
+
+  push @md_blocks, $md_block;
+
+  shift @md_blocks;
+
+  return @md_blocks;
+}
+
+sub MarkDownParseSpanElementsInner {
+  my ($text, $markersref) = @_;
+  my $markup = "";
+  my %markers = map { $_ => 1 } @$markersref;
+
+  while ($text ne "") {
+    my $closest_marker = "";
+    my $closest_marker_index = 0;
+    my $closest_marker_position = -1;
+    my $text_marker = "";
+    my $i = 0;
+    my $offset = 0;
+    my @markers_rest;
+    my $marker;
+    my $use;
+
+    while ( ($marker, $use) = each %markers ) {
+      my $marker_position;
+
+      if (!$use) {
+        next;
+      }
+
+      $marker_position = index ($text, $marker);
+
+      if ($marker_position < 0) {
+        $markers{$marker} = 0;
+        next;
+      }
+
+      if ($closest_marker eq "" || $marker_position < $closest_marker_position) {
+        $closest_marker = $marker;
+        $closest_marker_index = $i;
+        $closest_marker_position = $marker_position;
+      }
+    }
+
+    if ($closest_marker_position >= 0) {
+      $text_marker = substr ($text, $closest_marker_position);
+    }
+
+    if ($text_marker eq "") {
+      $markup .= $text;
+      $text = "";
+      next; # last
+    }
+
+    $markup .= substr ($text, 0, $closest_marker_position);
+    $text = substr ($text, $closest_marker_position);
+    @markers_rest = map { $markers{$_} ? ($_ eq $closest_marker ? () : $_) : () } keys %markers;
+
+    if ($closest_marker eq "![" || $closest_marker eq "[") {
+      my %element;
+
+      if (index ($text, "]") && $text =~ /\[((?:[^][]|(?R))*)\]/) {
+        my $remaining_text;
+
+        %element = ( "!" => (substr ($text, 0, 1) eq "!"),
+                     "a" => $1 );
+
+        $offset = length ($&);
+        if ($element{"!"}) {
+          $offset++;
+        }
+
+        $remaining_text = substr ($text, $offset);
+        if ($remaining_text =~ /^\([ ]*([^)'"]*?)(?:[ ]+['"](.+?)['"])?[ ]*\)/) {
+          $element{"»"} = $1;
+          if (defined ($2)) {
+            $element{"#"} = $2;
+          }
+          $offset += length ($&);
+        } elsif ($remaining_text =~ /^\s*\[([^\]<]*?)\]/) {
+          $element{"ref"} = $1;
+          $offset += length ($&);
+        } else {
+          undef %element;
+        }
+      }
+
+      if (%element) {
+        if ($element{"»"}) {
+          $element{"»"} =~ s/&/&amp;/g;
+          $element{"»"} =~ s/</&lt;/g;
+        }
+        if ($element{"!"}) {
+          $markup .= "<inlinemediaobject><imageobject><imagedata fileref=\"" . $element{"»"} . "\"></imagedata></imageobject>";
+
+          if (defined ($element{"a"})) {
+            $markup .= "<textobject><phrase>" . $element{"a"} . "</phrase></textobject>";
+          }
+
+          $markup .= "</inlinemediaobject>";
+        } elsif ($element{"ref"}) {
+          $element{"a"} = &MarkDownParseSpanElementsInner ($element{"a"}, \@markers_rest);
+          $markup .= "<link linkend=\"" . $element{"ref"} . "\"";
+
+          if (defined ($element{"#"})) {
+            # title attribute not supported
+          }
+
+          $markup .= ">" . $element{"a"} . "</link>";
+        } else {
+          $element{"a"} = &MarkDownParseSpanElementsInner ($element{"a"}, \@markers_rest);
+          $markup .= "<ulink url=\"" . $element{"»"} . "\"";
+
+          if (defined ($element{"#"})) {