[gtk-doc] add '@Image' attribute to sections

[Ryan Lortie <ryanl src gnome org>]

commit b784c5fec02da0baa91e685e9c3adecdbe3f403b
Author: Ryan Lortie <desrt desrt ca>
Date:   Sat Oct 24 16:07:55 2009 -0700

    add '@Image' attribute to sections
    
    - set to an image file to have that image placed in the top-right corner
      of the section documentation
     - fall back to looking in the 'gallery' file (as used by Gtk+)
     - fixes Bug 599514 - sane support for per-page images

 gtk-doc.xsl                          |   21 ++++++++++++++-------
 gtkdoc-mkdb.in                       |   33 ++++++++++++++++++++++++++++++---
 gtkdoc-mktmpl.in                     |   14 ++++++++++++--
 help/manual/C/gtk-doc-manual.xml     |   12 ++++++++++++
 tests/gobject/docs/Makefile.am       |    4 +++-
 tests/gobject/docs/images/object.png |  Bin 0 -> 4101 bytes
 tests/gobject/src/gobject.c          |    1 +
 7 files changed, 72 insertions(+), 13 deletions(-)
---
diff --git a/gtk-doc.xsl b/gtk-doc.xsl
index 8a69e00..c533b81 100644
--- a/gtk-doc.xsl
+++ b/gtk-doc.xsl
@@ -655,13 +655,20 @@ Get a newer version at http://docbook.sourceforge.net/projects/xsl/
           </p>
         </td>
         <td valign="top" align="right">
-           <!-- find the gallery image to use here
-                - determine the id of the enclosing refentry
-                - look for an inlinegraphic inside a link with linkend == refentryid inside a para with role == gallery
-                - use it here
-             -->
-           <xsl:variable name="refentryid" select="../@id"/>
-           <xsl:apply-templates select="//para[ role = 'gallery']/link[ linkend = $refentryid]/inlinegraphic"/>
+          <xsl:choose>
+            <xsl:when test="../refmeta/refmiscinfo/inlinegraphic">
+              <xsl:apply-templates select="../refmeta/refmiscinfo/inlinegraphic"/>
+            </xsl:when>
+            <xsl:otherwise>
+              <!-- find the gallery image to use here
+                   - determine the id of the enclosing refentry
+                   - look for an inlinegraphic inside a link with linkend == refentryid inside a para with role == gallery
+                   - use it here
+                -->
+              <xsl:variable name="refentryid" select="../@id"/>
+              <xsl:apply-templates select="//para[ role = 'gallery']/link[ linkend = $refentryid]/inlinegraphic"/>
+            </xsl:otherwise>
+          </xsl:choose>
         </td></tr>
        </table>
      </div>
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index 32ad234..3c8d4a7 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -2252,6 +2252,28 @@ sub OutputSGMLFile {
 	$stability = "<refsect1 id=\"$section_id.stability-level\">\n<title>Stability Level</title>\n$DEFAULT_STABILITY, unless otherwise indicated\n</refsect1>\n";
     }
 
+    my $image = $SymbolDocs{"$TMPL_DIR/$file:Image"};
+    if (!defined ($image)) {
+      $image = "";
+    } else {
+      $image =~ s/^\s*//;
+      $image =~ s/\s*$//;
+
+      my $format;
+
+      if ($image =~ /jpe?g$/i) {
+        $format = "format='JPEG'";
+      } elsif ($image =~ /png$/i) {
+        $format = "format='PNG'";
+      } elsif ($image =~ /svg$/i) {
+        $format = "format='SVG'";
+      } else {
+        $format = "";
+      }
+
+      $image = "  <inlinegraphic fileref='$image' $format/>\n"
+    }
+
     my ($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) =
 	gmtime (time);
     my $month = (qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec))[$mon];
@@ -2301,7 +2323,9 @@ sub OutputSGMLFile {
 <refmeta>
 <refentrytitle role="top_of_page" id="$section_id.top_of_page">$title</refentrytitle>
 <manvolnum>3</manvolnum>
-<refmiscinfo>\U$MODULE\E Library</refmiscinfo>
+<refmiscinfo>
+  \U$MODULE\E Library
+$image</refmiscinfo>
 </refmeta>
 <refnamediv>
 <refname>$title</refname>
@@ -3681,6 +3705,8 @@ sub ScanSourceFile {
                             $key = "$TMPL_DIR/$real_symbol:Section_Id";
                         } elsif ($params[$k] eq "include") {
                             $key = "$TMPL_DIR/$real_symbol:Include";
+                        } elsif ($params[$k] eq "image") {
+                            $key = "$TMPL_DIR/$real_symbol:Image";
                         }
                         if (defined($key)) {
                             $SourceSymbolDocs{$key}=$params[$k+1];
@@ -4012,7 +4038,7 @@ sub OutputMissingDocumentation {
         #my $ssline = &GetSymbolSourceLine($symbol);
         #my $location = "defined at " . (defined($ssfile)?$ssfile:"?") . ":" . (defined($ssline)?$ssline:"0") . "\n";
         # DEBUG
-        if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also|Stability_Level|Include|Section_Id)/) {
+        if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also|Stability_Level|Include|Section_Id|Image)/) {
             $total++;
             if (exists ($AllDocumentedSymbols{$symbol})) {
                 $n_documented++;
@@ -4780,7 +4806,8 @@ sub ReadTemplateFile {
 		|| $symbol eq "Long_Description"
 		|| $symbol eq "See_Also"
 		|| $symbol eq "Stability_Level"
-		|| $symbol eq "Include") {
+		|| $symbol eq "Include"
+		|| $symbol eq "Image") {
 
 		$symbol = $docsfile . ":" . $symbol;
 	    }
diff --git a/gtkdoc-mktmpl.in b/gtkdoc-mktmpl.in
index e7d63bf..961b062 100755
--- a/gtkdoc-mktmpl.in
+++ b/gtkdoc-mktmpl.in
@@ -556,7 +556,7 @@ sub OutputOldParams {
 sub OutputTemplateFile {
     my ($file, $title, $output) = @_;
 
-    my ($short_desc, $long_desc, $see_also, $stability);
+    my ($short_desc, $long_desc, $see_also, $stability, $image);
 
     if (defined ($SymbolDocs{"$TMPL_DIR/$file:Title"})) {
 	$title = $SymbolDocs{"$TMPL_DIR/$file:Title"};
@@ -586,6 +586,12 @@ sub OutputTemplateFile {
     } else {
 	$stability = "";
     }
+    if (defined ($SymbolDocs{"$TMPL_DIR/$file:Image"})) {
+	$image = $SymbolDocs{"$TMPL_DIR/$file:Image"};
+	delete $SymbolDocs{"$TMPL_DIR/$file:Image"};
+    } else {
+	$image = "";
+    }
 
 
     my $old_tmpl_file = "$TMPL_DIR/$file";
@@ -610,6 +616,9 @@ $see_also
 <!-- ##### SECTION Stability_Level ##### -->
 $stability
 
+<!-- ##### SECTION Image #### -->
+$image
+
 EOF
 
     print (OUTPUT $$output) unless $ONLY_SECTION_TMPL;
@@ -1017,7 +1026,8 @@ sub ReadTemplateFile {
 		|| $symbol eq "Short_Description"
 		|| $symbol eq "Long_Description"
 		|| $symbol eq "See_Also"
-		|| $symbol eq "Stability_Level") {
+		|| $symbol eq "Stability_Level"
+		|| $symbol eq "Image") {
 		$symbol = $docsfile . ":" . $symbol;
 	    }
 
diff --git a/help/manual/C/gtk-doc-manual.xml b/help/manual/C/gtk-doc-manual.xml
index a69f987..79dacef 100644
--- a/help/manual/C/gtk-doc-manual.xml
+++ b/help/manual/C/gtk-doc-manual.xml
@@ -735,6 +735,7 @@ make
  * @see_also: #MeepSettings
  * @stability: Stable
  * @include: meep/app.h
+ * @Image: application.png
  *
  * The application class handles ...
  */
@@ -854,6 +855,17 @@ make
             </para>
           </listitem>
         </varlistentry>
+        <varlistentry>
+          <term>@image</term>
+          <listitem>
+            <para>
+              The image to display at the top of the reference page for this
+              section.  This will often be some sort of a diagram to illustrate
+              the visual appearance of a class or a diagram of its relationship
+              to other classes.  This item is optional.
+            </para>
+          </listitem>
+        </varlistentry>
       </variablelist>
 
       <tip>
diff --git a/tests/gobject/docs/Makefile.am b/tests/gobject/docs/Makefile.am
index 68e489b..1f4267b 100644
--- a/tests/gobject/docs/Makefile.am
+++ b/tests/gobject/docs/Makefile.am
@@ -44,7 +44,9 @@ CFILE_GLOB=$(top_srcdir)/tests/gobject/src/*.c
 IGNORE_HFILES=config.h
 
 # Images to copy into HTML directory.
-HTML_IMAGES = $(top_srcdir)/home.png
+HTML_IMAGES = \
+	$(top_srcdir)/home.png			\
+	$(srcdir)/images/object.png
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
diff --git a/tests/gobject/docs/images/object.png b/tests/gobject/docs/images/object.png
new file mode 100644
index 0000000..b7f4535
Binary files /dev/null and b/tests/gobject/docs/images/object.png differ
diff --git a/tests/gobject/src/gobject.c b/tests/gobject/src/gobject.c
index f004d6d..7e80e12 100644
--- a/tests/gobject/src/gobject.c
+++ b/tests/gobject/src/gobject.c
@@ -3,6 +3,7 @@
  * @title: GtkdocObject
  * @short_description: class for gtk-doc unit test
  * @see_also: #GtkdocIface
+ * @Image: object.png
  *
  * This file contains non-sense code for the sole purpose of testing the docs.
  * We can link to the #GtkdocObject:otest property and the #GtkdocObject::otest