gtk-doc r616 - in trunk: . tests/annotations/docs

[stefkost svn gnome org]

Author: stefkost
Date: Thu Nov  6 13:50:30 2008
New Revision: 616
URL: http://svn.gnome.org/viewvc/gtk-doc?rev=616&view=rev

Log:
	* gtkdoc-mkdb.in:
	  Get rid of german variable name. Generate glossary xml for
	  annotations. Improve initial master document.
	* tests/annotations/docs/tester-docs.xml:
	  Update example to include anotation glossary.



Modified:
   trunk/ChangeLog
   trunk/gtkdoc-mkdb.in
   trunk/tests/annotations/docs/tester-docs.xml

Modified: trunk/gtkdoc-mkdb.in
==============================================================================
--- trunk/gtkdoc-mkdb.in	(original)
+++ trunk/gtkdoc-mkdb.in	Thu Nov  6 13:50:30 2008
@@ -265,6 +265,24 @@
 $PreProcessorDirectives{"undef"} = 1;
 $PreProcessorDirectives{"warning"} = 1;
 
+# remember used annotation (to write minimal glossary)
+my %AnnotationsUsed;
+
+my %AnnotationDefinition = (
+    'array' => "Parameter points to an array of items.",
+    '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-domain' => "Typed errors. Similar to throws in Java.",
+    'in' => "Parameter for input. Default is <acronym>transfer-none</acronym>.",
+    'inout' => "Parameter for input and for returning results. Default is <acronym>transfer-full</acronym>.",
+    'not-error' => "A GError parameter is not to be handled like a normal GError.",
+    'null-ok' => "NULL is ok, both for passing and for returning.",
+    'out' => "Parameter for returning results. Default is <acronym>transfer-full</acronym>.",
+    'transfer-container' => "Free data container after the code is done.",
+    'transfer-full' => "Free data after the code is done.",
+    'transfer-none' => "Don't free data after the code is done."
+);
+
 # Create the root DocBook output directory if it doens't exist.
 if (! -e $SGML_OUTPUT_DIR) {
     mkdir ("$SGML_OUTPUT_DIR", 0777)
@@ -302,6 +320,7 @@
     &OutputIndexFull;
     &OutputDeprecatedIndex;
     &OutputSinceIndexes;
+    &OutputAnnotationGlossary;
 
     open (TIMESTAMP, ">$ROOT_DIR/sgml.stamp")
 	|| die "Can't create $ROOT_DIR/sgml.stamp: $!";
@@ -793,8 +812,8 @@
     
     # do a case insensitive sort while chopping off the prefix
     foreach my $hash (
-        sort { $$a{kriterium} cmp $$b{kriterium} }
-        map { my $x = uc($_); $x =~ s/^$NAME_SPACE\_?(.*)/$1/i; { kriterium => $x, original => $_, short => $1 } } 
+        sort { $$a{criteria} cmp $$b{criteria} }
+        map { my $x = uc($_); $x =~ s/^$NAME_SPACE\_?(.*)/$1/i; { criteria => $x, original => $_, short => $1 } } 
         keys %apiindex) {
 
         $symbol = $$hash{original};
@@ -876,6 +895,64 @@
     }
 }
 
+#############################################################################
+# Function    : OutputSinceIndexes
+# Description : This writes the 'since' api indexlists that can be included into
+#               the main document into an <index> tag.
+#############################################################################
+
+sub OutputAnnotationGlossary {
+    my $old_glossary = "$SGML_OUTPUT_DIR/annotation-glossary.xml";
+    my $new_glossary = "$SGML_OUTPUT_DIR/annotation-glossary.new";
+    my $lastletter = " ";
+    my $divopen = 0;
+
+    # TODO: if there are no annotations used return
+    return if (! keys(%AnnotationsUsed));
+
+    open (OUTPUT, ">$new_glossary")
+	|| die "Can't create $new_glossary";
+
+    my $header = $doctype_header;
+    $header =~ s/<!DOCTYPE \w+/<!DOCTYPE glossary/;
+
+    print (OUTPUT  <<EOF);
+$header
+<glossary id="annotation-glossary">
+  <title>Annotation Glossary</title>
+EOF
+
+    foreach my $annotation (keys(%AnnotationsUsed)) {
+        my $def = $AnnotationDefinition{$annotation};
+        my $curletter = uc(substr($annotation,0,1));
+
+        if ($curletter ne $lastletter) {
+            $lastletter = $curletter;
+      
+            if ($divopen == 1) {
+                print (OUTPUT "</glossdiv>\n");
+            }
+            print (OUTPUT "<glossdiv><title>$curletter</title>\n");
+            $divopen = 1;
+        }
+        print (OUTPUT <<EOF);
+    <glossentry>
+      <glossterm><anchor id="annotation-glossterm-$annotation"/>$annotation</glossterm>
+      <glossdef>
+        <para>$def</para>
+      </glossdef>
+    </glossentry>
+EOF
+    }
+
+    if ($divopen == 1) {
+        print (OUTPUT "</glossdiv>\n");
+    }
+    print (OUTPUT "</glossary>\n");
+    close (OUTPUT);
+
+    &UpdateFileIfChanged ($old_glossary, $new_glossary, 0);
+}
 
 #############################################################################
 # Function    : ReadKnownSymbols
@@ -1662,6 +1739,7 @@
                         $annotation_extra = " $2";
                     }
                     $param_annotations .= "<acronym>$annotation</acronym>$annotation_extra. ";
+                    $AnnotationsUsed{$annotation} = 1;
                 }
                 chomp($param_desc);
                 $param_desc =~ m/^(.*)\.*\s*$/;
@@ -1988,9 +2066,7 @@
       } else {
 	print OUTPUT <<EOF;
 <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
-EOF
-        print OUTPUT $book_top;
-        print OUTPUT <<EOF;
+$book_top
 ]>
 <book id="index">
 EOF
@@ -2008,11 +2084,25 @@
 
   <chapter>
     <title>[Insert title here]</title>
+    $book_bottom
+  </chapter>
 EOF
-      print OUTPUT $book_bottom;
-
-      print OUTPUT <<EOF;
+  if (-e $OBJECT_TREE_FILE) {
+    print OUTPUT <<EOF;
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+     <xi:include href="xml/tree_index.sgml"/>
   </chapter>
+EOF
+  }
+
+print OUTPUT <<EOF;
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
 </book>
 EOF
 

Modified: trunk/tests/annotations/docs/tester-docs.xml
==============================================================================
--- trunk/tests/annotations/docs/tester-docs.xml	(original)
+++ trunk/tests/annotations/docs/tester-docs.xml	Thu Nov  6 13:50:30 2008
@@ -46,95 +46,6 @@
       </glossentry>
     </glossdiv>
   </glossary>
-
-  <glossary id="annotation-glossary">
-    <title>Annotation Glossary</title>
-    <glossdiv id="annotation-glossary-A"><title>A</title>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-array"/>array</glossterm>
-        <glossdef>
-          <para>Parameter points to an array of items.</para>
-        </glossdef>
-      </glossentry>
-    </glossdiv>
-    <glossdiv id="annotation-glossary-D"><title>D</title>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-default"/>default</glossterm>
-        <glossdef>
-          <para>Default parameter value (for in case the <acronym>shadows</acronym>-to function has less parameters).</para>
-        </glossdef>
-      </glossentry>
-    </glossdiv>
-    <glossdiv id="annotation-glossary-E"><title>E</title>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-element-type"/>element-type</glossterm>
-        <glossdef>
-          <para>Generics and defining elements of containers and arrays.</para>
-        </glossdef>
-      </glossentry>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-error-domain"/>error-domain</glossterm>
-        <glossdef>
-          <para>Typed errors. Similar to throws in Java.</para>
-        </glossdef>
-      </glossentry>
-    </glossdiv>
-    <glossdiv id="annotation-glossary-I"><title>I</title>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-in"/>in</glossterm>
-        <glossdef>
-          <para>Parameter for input. Default is <acronym>transfer-none</acronym>.</para>
-        </glossdef>
-      </glossentry>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-inout"/>inout</glossterm>
-        <glossdef>
-          <para>Parameter for input and for returning results. Default is <acronym>transfer-full</acronym>.</para>
-        </glossdef>
-      </glossentry>
-    </glossdiv>
-    <glossdiv id="annotation-glossary-N"><title>N</title>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-not-error"/>not-error</glossterm>
-        <glossdef>
-          <para>A GError parameter is not to be handled like a normal GError.</para>
-        </glossdef>
-      </glossentry>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-null-ok"/>null-ok</glossterm>
-        <glossdef>
-          <para>NULL is ok, both for passing and for returning.</para>
-        </glossdef>
-      </glossentry>
-    </glossdiv>
-    <glossdiv id="annotation-glossary-O"><title>O</title>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-out"/>out</glossterm>
-        <glossdef>
-          <para>Parameter for returning results. Default is <acronym>transfer-full</acronym>.</para>
-        </glossdef>
-      </glossentry>
-    </glossdiv>
-    <glossdiv id="annotation-glossary-T"><title>T</title>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-transfer-container"/>transfer-container</glossterm>
-        <glossdef>
-          <para>Free data container after the code is done.</para>
-        </glossdef>
-      </glossentry>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-transfer-full"/>transfer-full</glossterm>
-        <glossdef>
-          <para>Free data after the code is done.</para>
-        </glossdef>
-      </glossentry>
-      <glossentry>
-        <glossterm><anchor id="annotation-glossterm-transfer-none"/>transfer-none</glossterm>
-        <glossdef>
-          <para>Don't free data after the code is done.</para>
-        </glossdef>
-      </glossentry>
-    </glossdiv>
-  </glossary>
-
+  
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
 </book>