GNOME.org
 

gtk-doc r692 - trunk

Author: stefkost
Date: Thu Feb 26 13:22:11 2009
New Revision: 692
URL: http://svn.gnome.org/viewvc/gtk-doc?rev=692&view=rev

Log:
	* gtk-doc.xsl:
	* style.css:
	* gtkdoc-mkdb.in:
	  Fix annotation more. Refactor the extra-link feature. Still disabled
	  by default. Needs configure stuff next.



Modified:
   trunk/ChangeLog
   trunk/gtk-doc.xsl
   trunk/gtkdoc-mkdb.in
   trunk/style.css

Modified: trunk/gtk-doc.xsl
==============================================================================
--- trunk/gtk-doc.xsl	(original)
+++ trunk/gtk-doc.xsl	Thu Feb 26 13:22:11 2009
@@ -138,35 +138,34 @@
 
   <xsl:template name="user.head.content">
     <xsl:if test="$gtkdoc.version">
-      <meta name="generator"
-            content="GTK-Doc V{$gtkdoc.version} (XML mode)"/>
+      <meta name="generator" content="GTK-Doc V{$gtkdoc.version} (XML mode)"/>
     </xsl:if>
     <link rel="stylesheet" href="style.css" type="text/css"/>
 
-      <!-- copied from the html.head template in the docbook stylesheets
-           we don't want links for all refentrys, thats just too much
-        -->
-      <xsl:variable name="this" select="."/>
-      <xsl:for-each select="//part
-                            |//reference
-                            |//preface
-                            |//chapter
-                            |//article
-                            |//appendix[not(parent::article)]|appendix
-                            |//glossary[not(parent::article)]|glossary
-                            |//index[not(parent::article)]|index">
-        <link rel="{local-name(.)}">
-          <xsl:attribute name="href">
-            <xsl:call-template name="href.target">
-              <xsl:with-param name="context" select="$this"/>
-              <xsl:with-param name="object" select="."/>
-            </xsl:call-template>
-          </xsl:attribute>
-          <xsl:attribute name="title">
-            <xsl:apply-templates select="." mode="object.title.markup.textonly"/>
-          </xsl:attribute>
-        </link>
-      </xsl:for-each>
+    <!-- copied from the html.head template in the docbook stylesheets
+         we don't want links for all refentrys, thats just too much
+      -->
+    <xsl:variable name="this" select="."/>
+    <xsl:for-each select="//part
+                          |//reference
+                          |//preface
+                          |//chapter
+                          |//article
+                          |//appendix[not(parent::article)]|appendix
+                          |//glossary[not(parent::article)]|glossary
+                          |//index[not(parent::article)]|index">
+      <link rel="{local-name(.)}">
+        <xsl:attribute name="href">
+          <xsl:call-template name="href.target">
+            <xsl:with-param name="context" select="$this"/>
+            <xsl:with-param name="object" select="."/>
+          </xsl:call-template>
+        </xsl:attribute>
+        <xsl:attribute name="title">
+          <xsl:apply-templates select="." mode="object.title.markup.textonly"/>
+        </xsl:attribute>
+      </link>
+    </xsl:for-each>
   </xsl:template>
   
   <xsl:template name="user.footer.content">
@@ -561,11 +560,13 @@
      </div>
   </xsl:template>
 
+  <!-- add anchors for index sections -->
   <xsl:template match="indexdiv">
     <a><xsl:attribute name="name">idx<xsl:value-of select="./title"/></xsl:attribute></a>
     <xsl:apply-templates/>
   </xsl:template>
 
+  <!-- add anchors for glossary sections -->
   <xsl:template match="glossdiv">
     <a><xsl:attribute name="name">gls<xsl:value-of select="./title"/></xsl:attribute></a>
     <xsl:apply-templates/>
@@ -574,7 +575,37 @@
   <!-- Exterminate any trace of indexterms in the main flow -->
   <xsl:template match="indexterm">
   </xsl:template>
+
+  <!-- Extra link on the right side of doc-blobs -->
+  <xsl:template name="user.format.extralinks">
+    <xsl:if test="../ulink[ role='extralinks']">
+      <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>
+          <a>
+            <xsl:attribute name="href"><xsl:value-of select="@url"/></xsl:attribute>
+            <xsl:copy-of select="text()" />
+          </a>
+          <xsl:if test="position() = last()">&#160;]</xsl:if>
+        </xsl:for-each>
+      </span>
+    </xsl:if>
+    <!--xsl:copy-of select="text()" /-->
+    <xsl:apply-templates/>
+  </xsl:template>
+
+  <xsl:template match="//refsect2/ulink[ role='extralinks']"/>
+  <xsl:template match="//refsect1/ulink[ role='extralinks']"/>
+
+  <xsl:template match="//refsect2/title">
+    <h3><xsl:call-template name="user.format.extralinks"/></h3>
+  </xsl:template>
   
+  <xsl:template match="//refsect1/title">
+    <h2><xsl:call-template name="user.format.extralinks"/></h2>
+  </xsl:template>
+
   <!-- ==================================================================== -->
 
   <xsl:template match="acronym">

Modified: trunk/gtkdoc-mkdb.in
==============================================================================
--- trunk/gtkdoc-mkdb.in	(original)
+++ trunk/gtkdoc-mkdb.in	Thu Feb 26 13:22:11 2009
@@ -1123,6 +1123,59 @@
     return $desc;
 }
 
+#############################################################################
+# Function    : Outpu{Symbol,Section}ExtraLinks
+# Description : Returns extralinks for the symbol (if enabled).
+# Arguments   : $symbol - the name of the function/macro begin described.
+#############################################################################
+
+sub uri_escape {
+    my $text = $_[0];
+    return undef unless defined $text;
+
+    # Build a char to hex map
+    my %escapes = ();
+    for (0..255) {
+            $escapes{chr($_)} = sprintf("%%%02X", $_);
+    }
+
+    # Default unsafe characters.  RFC 2732 ^(uric - reserved)
+    $text =~ s/([^A-Za-z0-9\-_.!~*'()])/$escapes{$1}/g;
+
+    return $text;
+}
+
+sub OutputSymbolExtraLinks {
+    my ($symbol) = @_;
+    my $desc = "";
+
+    if (0) { # NEW FEATURE: needs configurability
+    my $sstr = &uri_escape($symbol);
+    my $mstr = &uri_escape($MODULE);
+    $desc .= <<EOF;
+<ulink role="extralinks" url="http://www.google.com/codesearch?q=$sstr";>code search</ulink>
+<ulink role="extralinks" url="http://library.gnome.org/edit?module=$mstr&amp;symbol=$sstr";>edit documentation</ulink>
+EOF
+    }
+    return $desc;
+}
+
+sub OutputSectionExtraLinks {
+    my ($symbol,$docsymbol) = @_;
+    my $desc = "";
+
+    if (0) { # NEW FEATURE: needs configurability
+    my $sstr = &uri_escape($symbol);
+    my $mstr = &uri_escape($MODULE);
+    my $dsstr = &uri_escape($docsymbol);
+    $desc .= <<EOF;
+<ulink role="extralinks" url="http://www.google.com/codesearch?q=$sstr";>code search</ulink>
+<ulink role="extralinks" url="http://library.gnome.org/edit?module=$mstr&amp;symbol=$dsstr";>edit documentation</ulink>
+EOF
+    }
+    return $desc;
+}
+
 
 #############################################################################
 # Function    : OutputMacro
@@ -1161,13 +1214,7 @@
     $desc = "<refsect2 id=\"$id\" role=\"macro\"$condition>\n<title>$title</title>\n";
     $desc .= MakeIndexterms($symbol, $id);
     $desc .= "\n";
-    
-    # NEW FEATURE
-    #my $qstr=$symbol;
-    #$qstr =~ s/([^A-Za-z0-9])/sprintf("%%%02X", ord($1))/seg;
-    #$desc .= "<ulink role=\"extralinks\" url=\"http://www.google.com/codesearch?q=$qstr\";>code search</ulink>";
-    #$desc .= "\n";
-    # NEW FEATURE
+    $desc .= OutputSymbolExtraLinks($symbol);
 
     # 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
@@ -1228,6 +1275,8 @@
     my $desc = "<refsect2 id=\"$id\" role=\"typedef\"$condition>\n<title>$symbol</title>\n";
 
     $desc .= MakeIndexterms($symbol, $id);
+    $desc .= "\n";
+    $desc .= OutputSymbolExtraLinks($symbol);
 
     if (!defined ($DeclarationConditional{$symbol})) {
 	$declaration = &CreateValidSGML ($declaration);
@@ -1295,6 +1344,8 @@
     }
 
     $desc .= MakeIndexterms($symbol, $id);
+    $desc .= "\n";
+    $desc .= OutputSymbolExtraLinks($symbol);
 
     # Form a pretty-printed, private-data-removed form of the declaration
 
@@ -1431,6 +1482,8 @@
     my $desc = "<refsect2 id=\"$id\" role=\"enum\"$condition>\n<title>enum $symbol</title>\n";
 
     $desc .= MakeIndexterms($symbol, $id);
+    $desc .= "\n";
+    $desc .= OutputSymbolExtraLinks($symbol);
 
     $declaration = &CreateValidSGML ($declaration);
     $desc .= "<programlisting>$declaration</programlisting>\n";
@@ -1503,6 +1556,8 @@
     my $desc = "<refsect2 id=\"$id\" role=\"union\"$condition>\n<title>union $symbol</title>\n";
 
     $desc .= MakeIndexterms($symbol, $id);
+    $desc .= "\n";
+    $desc .= OutputSymbolExtraLinks($symbol);
 
     $declaration = &CreateValidSGML ($declaration);
     $desc .= "<programlisting>$declaration</programlisting>\n";
@@ -1544,6 +1599,8 @@
     my $desc = "<refsect2 id=\"$id\" role=\"variable\"$condition>\n<title>$symbol</title>\n";
 
     $desc .= MakeIndexterms($symbol, $id);
+    $desc .= "\n";
+    $desc .= OutputSymbolExtraLinks($symbol);
 
     $declaration = &CreateValidSGML ($declaration);
     $desc .= "<programlisting>$declaration</programlisting>\n";
@@ -1630,6 +1687,8 @@
     my $desc = "<refsect2 id=\"$id\" role=\"function\"$condition>\n<title>${symbol} ()</title>\n";
 
     $desc .= MakeIndexterms($symbol, $id);
+    $desc .= "\n";
+    $desc .= OutputSymbolExtraLinks($symbol);
 
     $desc  .= "<programlisting>${ret_type_output}$symbol_desc_output(";
 
@@ -1799,18 +1858,12 @@
                 $param_desc = $';
                 @annotations = split(/\)\s*\(/,$1);
                 foreach $annotation (@annotations) {
-                    if ($annotation =~ m%(.*)\s+(.*)%) {
-                        $annotation = $1;
-                        $annotation_extra = " $2";
-                    }
-                    $param_annotations .= "<acronym>$annotation</acronym>$annotation_extra. ";
-
                     # need to search for the longest key-match in %AnnotationDefinition
                     my $match_length=0;
                     my $match_annotation="";
                     my $annotationdef;
                     foreach $annotationdef (keys %AnnotationDefinition) {
-                        if ($annotationdef =~ m/^$annotation/) {
+                        if ($annotation =~ m/^$annotationdef/) {
                             if (length($annotationdef)>$match_length) {
                                 $match_length=length($annotationdef);
                                 $match_annotation=$annotationdef;
@@ -1818,11 +1871,16 @@
                         }
                     }
                     if ($match_annotation ne "") {
-                      $AnnotationsUsed{$match_annotation} = 1;
+                        if ($annotation =~ m%$match_annotation\s+(.*)%) {
+                            $annotation_extra = " $1";
+                        }
+                        $AnnotationsUsed{$match_annotation} = 1;
+                        $param_annotations .= "<acronym>$match_annotation</acronym>$annotation_extra. ";
                     }
                     else {
-                      &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
-                          "unknown annotation \"$annotation\" in documentation for $symbol.");
+                        &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
+                            "unknown annotation \"$annotation\" in documentation for $symbol.");
+                        $param_annotations=$annotation;
                     }
                 }
                 chomp($param_desc);
@@ -1991,6 +2049,8 @@
     if ($include_output ne '') {
         $include_output = "\n$include_output\n";
     }
+    
+    my $extralinks = OutputSectionExtraLinks($title,"Section:$file");
 
     my $old_sgml_file = "$SGML_OUTPUT_DIR/$file.$OUTPUT_FORMAT";
     my $new_sgml_file = "$SGML_OUTPUT_DIR/$file.$OUTPUT_FORMAT.new";
@@ -2044,6 +2104,7 @@
 
 <refsect1 id="$section_id.description" role="desc">
 <title role="desc.title">Description</title>
+$extralinks
 $long_desc
 </refsect1>
 
@@ -2934,6 +2995,9 @@
 
 	    $desc .= "<refsect2 id=\"$id\" role=\"signal\"><title>The <literal>&quot;$name&quot;</literal> signal</title>\n";
 	    $desc .= MakeIndexterms($symbol, $id);
+	    $desc .= "\n";
+	    $desc .= OutputSymbolExtraLinks($symbol);
+
 	    $desc .= "<programlisting>";
 
 	    $SignalReturns[$i] =~ m/\s*(const\s+)?(\w+)\s*(\**)/;
@@ -3170,6 +3234,9 @@
  	    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";
 	    $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 .= &MakeDeprecationNote($symbol);
 	    $arg_desc .= $blurb;

Modified: trunk/style.css
==============================================================================
--- trunk/style.css	(original)
+++ trunk/style.css	Thu Feb 26 13:22:11 2009
@@ -180,10 +180,9 @@
 }
 .note
 {
-  /* FIXME: use a different color */
-  /* tango:orange 0/1 r<->g */
-  background: #eeffd9;
-  border-color: #b0ff4f;
+  /* tango:chameleon 0/0.5 */
+  background: #d8ffb2;
+  border-color: #abf562;
 }
 .note, .warning
 {
@@ -200,6 +199,16 @@
   margin-bottom: 0.0em
 }
 
+/* blob links */
+h2 .extralinks, h3 .extralinks
+{
+  float: right;
+  /* tango:aluminium 3 */
+  color: #babdb6;
+  font-size: 80%;
+  font-weight: normal;
+}
+
 /* code listings */
 
 .programlisting .cbracket   { color: #a40000; } /* tango: scarlet red 3 */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]