gerbil 3.0.2 → 3.1.0

data/fmt/html.yaml

@@ -34,6 +34,13 @@ code: |
     end
   end
 
+  class Hash
+    # Transforms this hash into a string of HTML attribute key=value pairs.
+    def to_html_atts
+      inject([]) {|s,(k,v)| s << %( #{k}="#{v}") }.join
+    end
+  end
+
   class Node
     # Returns the user-defined title for this node's content.
     def title
@@ -84,9 +91,9 @@ code: |
   # aFormat:: format of the image data (e.g. PNG, JPG, GIF, etc.)
   # aAttrs:: additional attributes for the <img> tag
   #
-  def embed_image_data aData, aFormat, aAttrs
-    atts = aAttrs.inject('') {|s,(k,v)| s << %( #{k}="#{v}") }
-    %{<img src="data:image/#{aFormat};base64,#{aData}"#{atts}/>}
+  def embed_image_data aData, aFormat, aAtts = {}
+    aAtts['src'] = "data:image/#{aFormat};base64,#{aData}"
+    "<img#{aAtts.to_html_atts}/>"
   end
 
   # Returns a HTML <img> tag that embeds the given image file.
@@ -104,10 +111,9 @@ code: |
     Icon = Struct.new(:path, :name, :format, :data)
 
     class Icon
-      # Returns a HTML image tag containing embedded image data.  The given
-      # attributes (name => value) are applied to the HTML tag declaration.
-      def to_html aAttributes = {}
-        embed_image_data data, format, aAttributes
+      # Returns the CSS class for this icon.
+      def css_class
+        @css_class ||= "icon-#{name}"
       end
     end
 
@@ -159,8 +165,9 @@ nodes:
     number: false
     silent: true
     output: |
-      <div id="<%= @node.type %>">
-        <h1 class="title"><%= @node.type.capitalize %></h1>
+      <% label = @node.type.capitalize %>
+      <div id="<%= label %>">
+        <h1 class="title"><a class="here" href="#<%= label %>"><%= label %></a></h1>
         <div class="content"><%= @node.content.to_s.to_html %></div>
       </div>
 
@@ -177,11 +184,11 @@ nodes:
       <div class="<%= @node.type %>">
         <h1 class="title">
           <%= @node.type.capitalize %>
-          <a class="toc" id="<%= @node.url %>" href="#<%= @node.list_url %>"><%= @node.index %></a>
+          <a class="list" id="<%= @node.url %>" href="#<%= @node.list_url %>"><%= @node.index %></a>
 
           <br/>
 
-          <big><%= @node.title.to_s.to_html %></big>
+          <a class="here" href="#<%= @node.url %>"><big><%= @node.title.to_s.to_html %></big></a>
         </h1>
 
         <div class="content"><%= @node.content.to_s.to_html %></div>
@@ -198,7 +205,7 @@ nodes:
       <% level = [6, @node.depth + 1].min %>
       <div class="<%= @node.type %>">
         <h<%= level %> class="title">
-          <a class="toc" id="<%= @node.url %>" href="#<%= @node.list_url %>"><%= @node.index %></a>&nbsp;&nbsp;<%= @node.title.to_s.to_html %>
+          <a class="list" id="<%= @node.url %>" href="#<%= @node.list_url %>"><%= @node.index %></a>&nbsp;&nbsp;<a class="here" href="#<%= @node.url %>"><%= @node.title.to_s.to_html %></a>
         </h<%= level %>>
         <div class="content"><%= @node.content.to_s.to_html %></div>
       </div>
@@ -210,7 +217,7 @@ nodes:
     number: false
     output: |
       <div class="<%= @node.type %>">
-        <p class="title"><%= @node.title.to_s.to_html %></p>
+        <p class="title" id="<%= @node.url %>"><a class="here" href="#<%= @node.url %>"><%= @node.title.to_s.to_html %></a></p>
         <div class="content"><%= @node.content.to_s.to_html %></div>
       </div>
 
@@ -225,18 +232,16 @@ nodes:
     number: true
     output: |
       <div class="<%= @node.type %>">
-        <p class="title"><a class="toc" id="<%= @node.url %>" href="#<%= @node.list_url %>"><%= @node.type.capitalize %> <%= @node.number %></a>.&nbsp;&nbsp;<%= @node.title.to_s.to_html %></p>
+        <p class="title"><a class="list" id="<%= @node.url %>" href="#<%= @node.list_url %>"><%= @node.type.capitalize %> <%= @node.number %></a>.&nbsp;&nbsp;<a class="here" href="#<%= @node.url %>"><%= @node.title.to_s.to_html %></a></p>
 
-        <%
+        <div class="content <%=
           $use_icons = true unless defined? $use_icons
 
-          if $use_icons && icon = ICONS[@node.type]
+          if $use_icons and icon = ICONS[@node.type]
             ($icons_used ||= []) << icon
-            %><%= icon.to_html :class => :icon %><%
+            icon.css_class
           end
-        %>
-
-        <div class="content"><%= @node.content.to_s.to_html %></div>
+        %>"><%= @node.content.to_s.to_html %></div>
       </div>
 
   note: *admonition
@@ -256,7 +261,7 @@ nodes:
     number: true
     output: |
       <div class="<%= @node.type %>">
-        <p class="title"><a class="toc" id="<%= @node.url %>" href="#<%= @node.list_url %>"><%= @node.type.capitalize %> <%= @node.number %></a>.&nbsp;&nbsp;<%= @node.title.to_s.to_html %></p>
+        <p class="title"><a class="list" id="<%= @node.url %>" href="#<%= @node.list_url %>"><%= @node.type.capitalize %> <%= @node.number %></a>.&nbsp;&nbsp;<a class="here" href="#<%= @node.url %>"><%= @node.title.to_s.to_html %></a></p>
         <div class="content"><%= @node.content.to_s.to_html %></div>
       </div>
 
@@ -287,19 +292,25 @@ nodes:
             target.index || target.number
           ]
 
-          unless target.type == 'reference'
-            title = "<em>#{target.title.to_s.to_html}</em>"
-          end
+          title_text =
+            if target.type == 'reference'
+              prefix
+            else
+              [prefix, target.title].compact.join('. ')
+            end
 
-          '<a class="%s" href="#%s">%s</a>' % [
-            @node.type,
-            target.url,
-            if @node.args.length > 1
-              @node.args[1].to_s.to_html
+          title_auto = @node.args.length < 2
+
+          title_html =
+            if title_auto
+              title_text.to_html
             else
-              [prefix, title].compact.join(': ')
+              @node.args[1].to_s.to_html
             end
-          ]
+
+          %{<a class="#{@node.type}" href="##{target.url}"#{
+            %{ title="#{title_text}"} unless title_auto
+          }>#{title_html}</a>}
         else
           raise ArgumentError, "invalid cross-reference to #{@node.title.inspect}", @node.trace
         end
@@ -345,9 +356,60 @@ output: |
     $title   = '$title' unless defined? $title
     $authors = {'$authors' => nil} unless defined? $authors
     $date    = Time.now.strftime("%d %B %Y") unless defined? $date
+
+    # get a list of all icons used in the document, if any
+    icons_used = $icons_used if defined? $icons_used and not $icons_used.empty?
+
+    abstract = @types['abstract'].first
+
+    references = @types['reference']
+    references = nil if references.empty?
+
+    # compute table of contents
+      tocBuilder = lambda do |n|
+        if @spec['nodes'][n.type]['toc']
+          entry = '%s<a id="%s" href="#%s">%s</a>' % [
+            (n.index.to_s + '&nbsp;&nbsp;' if n.index),
+            n.list_url,
+            n.url,
+            n.title.to_s.to_html
+          ]
+          nested = n.children.inject('') {|s,c| s << tocBuilder[c] }
+
+          %{<li>#{entry}#{ "<ul>#{nested}</ul>" unless nested.empty? }</li>}
+        else
+          ''
+        end
+      end
+
+      toc = @roots.inject('') {|s,n| s << tocBuilder[n] }
+
+    # compute list of figures
+      lofEnums = {} # type => nodes
+
+      @spec['nodes'].each_pair do |name, info|
+        if info['lof']
+          nodes = @types[name]
+          lofEnums[name] = nodes unless nodes.empty?
+        end
+      end
+
+      lofSections = []
+
+      lof = lofEnums.sort.map do |(type, nodes)|
+        nested = nodes.map do |n|
+          %{<li><a id="#{n.list_url}" href="##{n.url}">#{n.title.to_s.to_html}</a></li>}
+        end
+
+        label = type.capitalize << 's'
+        lofSections << label
+
+        %{<h1 id="#{label}" class="title"><a class="here" href="##{label}">#{label}</a></h1> <ol>#{nested}</ol>}
+      end
   %>
-  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-  <html>
+  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+  <html xmlns="http://www.w3.org/1999/xhtml">
     <head>
       <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
       <meta name="date" content="<%= $date %>"/>
@@ -358,17 +420,57 @@ output: |
       <% end if $feeds %>
       <title><%= $title.to_s.to_html %></title>
 
+      <% if icons_used %>
+      <style type="text/css" media="all">
+      <!--
+        <% icons_used.each do |icon| %>
+        .<%= icon.css_class %> {
+          <%
+            # we use list-style-image instead of background-image because the
+            # latter is neither printable nor shown in print preview by default
+            # in most browsers
+            #
+            # see http://www.web-graphics.com/mtarchive/001703.php
+          %>
+          display: list-item;
+          list-style-image: url(data:image/<%= icon.format %>;base64,<%= icon.data.tr("\n", '') %>);
+          list-style-position: inside;
+        }
+        <% end %>
+      -->
+      </style>
+      <% end %>
+
       <%
         styles = @spec['styles']
-        %w[screen print].each do |media|
+        (styles.keys - %w[common]).each do |media|
       %>
       <style type="text/css" media="<%= media %>">
+      <!--
         <%= styles['common'] %>
         <%= styles[media] %>
+      -->
       </style>
       <% end %>
     </head>
     <body>
+      <div class="nav">
+        <%=
+          [
+            ('Abstract' if abstract),
+            'Contents',
+            lofSections,
+            ('References' if references)
+          ].flatten.compact.map do |section|
+            %{<a href="##{section}">#{section}</a>}
+          end.join(' &middot; ')
+        %>
+      </div>
+
+      <br style="display: none"/>
+      <hr style="display: none"/>
+      <br style="display: none"/>
+
       <%= node = @types['header_outside_above'].first and node.output %>
       <div id="header">
       <%= node = @types['header_inside_above'].first and node.output %>
@@ -376,7 +478,7 @@ output: |
         <%= header.output %>
       <% else %>
         <%= $logo if defined? $logo %>
-        <h1 class="title"><%= $title.to_s.to_html %></h1>
+        <h1 class="title"><a class="here" href="#"><%= $title.to_s.to_html %></a></h1>
         <h2 class="authors"><%=
           $authors.map do |(name, url)|
             if url
@@ -392,62 +494,40 @@ output: |
       </div>
       <%= node = @types['header_outside_below'].first and node.output %>
 
-      <%= node = @types['abstract'].first and node.output %>
-
-      <% # table of contents
-        builder = lambda do |n|
-          if @spec['nodes'][n.type]['toc']
-            entry = '%s<a id="%s" href="#%s">%s</a>' % [
-              (n.index.to_s + '&nbsp;&nbsp;' if n.index),
-              n.list_url,
-              n.url,
-              n.title.to_s.to_html
-            ]
-            nested = n.children.inject('') {|s,c| s << builder[c] }
-
-            %{<li>#{entry}#{ "<ul>#{nested}</ul>" unless nested.empty? }</li>}
-          else
-            ''
-          end
-        end
-
-        toc = @roots.inject('') {|s,n| s << builder[n] }
+      <%= abstract.output if abstract %>
 
-        unless toc.empty?
-          %><div id="toc"><h1>Contents</h1> <ul><%= toc %></ul></div><%
-        end
-      %>
-
-      <% # list of figures
-        enums = {} # type => nodes
-
-        @spec['nodes'].each_pair do |name, info|
-          if info['lof']
-            nodes = @types[name]
-            enums[name] = nodes unless nodes.empty?
-          end
-        end
+      <br style="display: none"/>
+      <hr style="display: none"/>
+      <br style="display: none"/>
 
-        lof = enums.sort.map do |(type, nodes)|
-          nested = nodes.map do |n|
-            %{<li><a id="#{n.list_url}" href="##{n.url}">#{n.title.to_s.to_html}</a></li>}
-          end
+      <% unless toc.empty? %>
+        <div id="<%= label = 'Contents' %>">
+          <h1 class="title"><a class="here" href="#<%= label %>"><%= label %></a></h1>
+          <ul>
+            <%= toc %>
+
+            <% if references %>
+            <li><a href="#References">References</a></li>
+            <% end %>
+          </ul>
+        </div>
+      <% end %>
 
-          %{<h1>#{type.capitalize}s</h1> <ol>#{nested}</ol>}
-        end
+      <% unless lof.empty? %>
+        <div id="lof"><%= lof %></div>
+      <% end %>
 
-        unless lof.empty?
-          %><div id="lof"><%= lof %></div><%
-        end
-      %>
+      <br style="display: none"/>
+      <hr style="display: none"/>
+      <br style="display: none"/>
 
       <div id="content"><%= @content %></div>
 
-      <% unless (refs = @types['reference']).empty? %>
-      <div id="references">
-        <h1 class="title">References</h1>
+      <% if references %>
+      <div id="References">
+        <h1 class="title"><a class="here" href="#References">References</a></h1>
         <ol>
-        <% refs.each do |n| %>
+        <% references.each do |n| %>
           <li id="<%= n.url %>"><%= n.content.to_s.to_html %></li>
         <% end %>
         </ol>
@@ -467,8 +547,14 @@ output: |
         Generated on <%= Time.now %> by <a href="<%= Gerbil[:website] %>"><%= Gerbil[:name] %></a> <%= Gerbil[:version] %>.
       <% end %>
 
-      <% if defined? $icons_used and $icons_used and not $icons_used.empty? %>
-        <p>The admonition icons (<%= $icons_used.uniq.map {|icon| icon.to_html}.join(' ') %>) used in this document are Copyright &copy; 2005 <a href="http://tango.freedesktop.org">Tango Desktop Project</a>. They are part of the <a href="http://tango.freedesktop.org/Tango_Icon_Library">Tango Icon Theme</a> set, which is distributed under the <a href="http://creativecommons.org/licenses/by-sa/2.5/">Creative Commons Attribution-ShareAlike 2.5 License Agreement</a>.</p>
+      <% if icons_used %>
+        <div id="footer-credits">
+          <% icons_used.uniq.each do |icon| %>
+          <span class="<%= icon.css_class %>" style="float: right">&nbsp;</span>
+          <% end %>
+
+          <p>The admonition graphics used in this document are Copyright &copy; 2005 <a href="http://tango.freedesktop.org">Tango Desktop Project</a>. They are part of the <a href="http://tango.freedesktop.org/Tango_Icon_Library">Tango Icon Theme</a> set, which is distributed under the <a href="http://creativecommons.org/licenses/by-sa/2.5/">Creative Commons Attribution-ShareAlike 2.5 License Agreement</a>.</p>
+        </div>
       <% end %>
       <%= node = @types['footer_inside_below'].first and node.output %>
       </div>
@@ -494,6 +580,70 @@ styles:
         font-family      : Cambria, Georgia, serif;
       }
 
+      blockquote
+      {
+        margin           : 1em;
+        border           : 5px dotted #ddd;
+        padding          : 1em;
+      }
+
+      hr
+      {
+        height           : 0;
+        border           : 0;
+        border-top       : 2px solid #FF0000;
+      }
+
+    /* source code */
+
+      tt,
+      code,
+      pre
+      {
+        font-family      : Consolas, "Lucida Console", monospace;
+      }
+
+      tt
+      {
+        font-weight      : bold;
+        color            : #A52A2A;
+        background-color : #FFFAF0;
+      }
+
+      /* output of the syntax coloring library */
+      .code
+      {
+        background-color : #FFFFF0;
+      }
+
+      pre
+      {
+        cursor           : text;
+        line-height      : normal;
+        border           : 1px dashed #C0C0C0;
+        background-color : #F5FFDF;
+        padding          : 1em;
+        overflow         : auto;
+      }
+
+    /* hyperlinks */
+
+      a > img
+      {
+        border           : none;
+      }
+
+      a img
+      {
+        _border          : none; /* for IE6 */
+      }
+
+      a.here:link,
+      a.here:visited
+      {
+        color            : #000000;
+      }
+
     /* lists */
 
       #content li:first-child
@@ -575,7 +725,7 @@ styles:
 
       table
       {
-        border           : none;
+        border-collapse  : collapse; /* no spacing between cell borders */
         margin           : auto; /* center horizontally */
         margin-top       : 1em;
       }
@@ -584,7 +734,7 @@ styles:
       td
       {
         padding          : 1em;
-        border           : 1px solid #C0C0C0;
+        border           : 1px solid #bbb;
         vertical-align   : top;
         background-color : inherit;
       }
@@ -596,6 +746,14 @@ styles:
 
     /* document structure */
 
+      .nav
+      {
+        text-align       : center;
+        border-bottom    : thick dotted #DCDCDC;
+        padding-bottom   : 1em;
+        margin-bottom    : 4em;
+      }
+
       #header
       {
         text-align       : center;
@@ -627,34 +785,34 @@ styles:
         margin-top       : 4em;
       }
 
-      #abstract
+      #Abstract
       {
         margin-bottom    : 5em;
       }
 
-      #toc li
+      #Contents li
       {
         list-style-type  : none;
       }
 
-      #toc li ul
+      #Contents li ul
       {
         padding-bottom   : 1em;
         border-left      : thick solid #F5F5F5;
         _border-left     : none; /* for IE6 */
       }
 
-      #toc li ul:hover
+      #Contents li ul:hover
       {
         border-color     : #DCDCDC;
       }
 
-      #toc > ul
+      #Contents > ul
       {
         padding-left     : 1em;
       }
 
-      #references
+      #References
       {
         margin-top       : 5em;
       }
@@ -666,6 +824,11 @@ styles:
         text-align       : center;
       }
 
+      #footer-credits
+      {
+        margin-top       : 2em;
+      }
+
     /* document nodes */
 
       .part    > .title,
@@ -780,112 +943,35 @@ styles:
   screen: |
     body
     {
-      margin             : auto;
-      padding            : 0.5em;
-      max-width          : 36em;
+      margin            : auto;
+      padding           : 0.5em;
+      max-width         : 36em;
     }
 
-    /* emphasis */
-
-      blockquote
-      {
-        margin           : 1em;
-        border           : 5px dotted #C0C0C0;
-        padding          : 1em;
-        color            : #444;
-      }
-
-      hr
-      {
-        height           : 0;
-        border           : 0;
-        border-top       : 2px solid #FF0000;
-      }
-
-    /* source code */
-
-      tt,
-      code,
-      pre
-      {
-        font-family      : Consolas, "Lucida Console", monospace;
-      }
-
-      tt
-      {
-        font-weight      : bold;
-        color            : #A52A2A;
-        background-color : #FFFAF0;
-      }
-
-      /* output of the syntax coloring library */
-      .code
-      {
-        background-color : #FFFFF0;
-      }
-
-      pre
-      {
-        cursor           : text;
-        line-height      : normal;
-        border           : 1px dashed #C0C0C0;
-        background-color : #F5FFDF;
-        padding          : 1em;
-        overflow         : auto;
-      }
-
-      /*
-      pre:hover
-      {
-        border           : none;
-        position         : fixed;
-        z-index          : 1;
-        margin           : 0;
-        top              : 0;
-        left             : 0;
-        right            : 0;
-        bottom           : 0;
-        overflow         : auto;
-        cursor           : text;
-      }
-      */
-
     /* hyperlinks */
 
-      a > img
-      {
-        border           : none;
-      }
-
       a:link
       {
-        color            : #0000FF;
-        text-decoration  : none;
+        color           : #0000FF;
+        text-decoration : none;
       }
 
       a:visited
       {
-        color            : #9400D3;
-        text-decoration  : none;
+        color           : #800080;
+        text-decoration : none;
       }
 
       a:hover
       {
-        color            : #FF0000;
-        text-decoration  : underline;
+        color           : #FF0000;
+        text-decoration : underline;
       }
 
       a:target
       {
-        color            : #FF0000;
-        font-weight      : bold;
-      }
-
-      a.toc:link,
-      a.toc:visited
-      {
-        text-decoration  : none;
-        z-index          : 1;
+        color           : #FF0000;
+        font-weight     : bold;
       }
 
   print: |
@@ -893,17 +979,15 @@ styles:
 
       tt
       {
-        color            : inherit;
-        background-color : inherit;
-        font-weight      : normal;
+        background-color  : inherit;
+        font-weight       : normal;
       }
 
       pre,
       .code
       {
-        border           : none;
-        overflow         : visible;
-        background-color : inherit;
+        border            : none;
+        background-color  : inherit;
       }
 
     /* headings */
@@ -915,56 +999,63 @@ styles:
       h5,
       h6
       {
-        font-weight      : normal;
+        font-weight       : normal;
       }
 
     /* hyperlinks */
 
+      /* blend all hyperlinks with normal text */
       a:link,
-      a:visited,
-      a:active
+      a:visited
       {
-        color            : #0000FF;
-        font-weight      : bold;
-        text-decoration  : underline;
+        color             : #000000;
+        text-decoration   : none;
       }
 
-      a:after
+      /* emphasize external and cross-reference hyperlinks */
+      a:not([href^="#"]):link,
+      a:not([href^="#"]):visited,
+      a.xref[title]:link,
+      a.xref[title]:visited
       {
-        content          : " " attr(href);
-        font-family      : Consolas, "Lucida Console", monospace;
-        font-weight      : normal;
-        font-size        : 90%;
+        color             : #0000FF;
+        text-decoration   : underline;
+        font-weight       : bolder;
       }
 
-      a[href^="#"]:after
+      /* show URL of destination for external hyperlinks */
+      a:not([href^="#"]):after
       {
-        content          : "";
+        content           : " " attr(href);
+        font-family       : Consolas, "Lucida Console", monospace;
       }
 
-      a[href^="#"]
+      /* show name of destination for cross-references */
+      a.xref[title]:after
       {
-        color            : #A52A2A;
-        font-weight      : lighter;
-        text-decoration  : none;
-        font-style       : italic;
+        content           : " " attr(title);
       }
 
-      a.toc:link,
-      a.toc:visited
+      a:after
       {
-        color            : inherit;
-        .color           : #000000; /* for IE6 and IE7 */
-        font-weight      : inherit;
-        text-decoration  : none;
-        font-style       : normal;
+        font-weight       : normal;
+        font-size         : smaller;
       }
 
     /* document structure */
 
+      .nav,
       #lof
       {
-        display          : none;
+        display           : none;
+      }
+
+      #Contents,
+      .part,
+      .chapter,
+      #References
+      {
+        page-break-before : always;
       }
 
     /* document nodes */
@@ -972,13 +1063,12 @@ styles:
       .part    > .title > big,
       .chapter > .title > big
       {
-        padding-bottom   : 0.5em;
+        padding-bottom    : 0.5em;
       }
 
       .part    .title big,
       .chapter .title big
       {
-        _padding-bottom  : 0.5em; /* for IE6 */
+        _padding-bottom   : 0.5em; /* for IE6 */
       }
 
-