#--
# Copyright protects this work.
# See LICENSE file for details.
#++

desc: web page for the Internet

code: |
  ICONS_DIR  = File.join(ERBook::FORMATS_DIR, 'xhtml', 'icons')
  JQUERY_DIR = File.join(ERBook::FORMATS_DIR, 'xhtml', 'jquery')

  # load the String#to_xhtml and String#to_inline_xhtml methods
  require 'erbook/to_xhtml'

  class String
    ##
    # Transforms this UTF-8 string into XML entities.
    #
    def to_xml_entities
      unpack('U*').map! {|c| "&##{c};"}.join
    end

    ##
    # Transforms this string into a valid URI fragment.
    # See http://www.nmt.edu/tcc/help/pubs/xhtml/id-type.html
    #
    def to_uri_fragment
      # remove XML tags from the input
      buf = gsub(/<.*?>/, '')

      # The first or only character must be a letter.
      buf.insert(0, 'a') unless buf[0,1] =~ /[[:alpha:]]/

      # The remaining characters must be letters, digits, hyphens (-),
      # underscores (_), colons (:), or periods (.) or Unicode characters
      #
      # However, colons (:) and periods (.) are special characters
      # in jQuery CSS selector syntax, so we sanitize them as well.
      #
      buf.unpack('U*').map! do |code|
        if code > 0xFF or code.chr =~ /[[:alnum:]\-_]/
          code
        else
          32 # ASCII character code for a single space
        end
      end.pack('U*').strip.gsub(/[[:space:]-]+/, '-')
    end
  end

  class Hash
    ##
    # Transforms this hash into a string of XML attribute key="value" pairs.
    #
    def to_xml_atts
      inject([]) {|s,(k,v)| s << %( #{k}="#{v}") }.join
    end
  end

  require 'erb'

  module ERBook
    ##
    # Encodes the given input in base64 format.
    #
    def ERBook.base_64_encode input #:nodoc:
      [input].pack('m')
    end

    ##
    # Encodes the contents of the given file in base64 format.
    #
    def ERBook.base_64_encode_file path #:nodoc:
      base_64_encode open(path, 'rb') {|f| f.read }
    end

    ##
    # Returns a string denoting embedded, base64 encoded data.
    #
    def ERBook.base_64_embed data, mime #:nodoc:
      "data:#{mime.to_s.downcase};base64,#{data.tr("\n", '')}"
    end

    def ERBook.base_64_embed_file path # :nodoc:
      data = base_64_encode_file(path)

      require 'mime/types'
      mime = MIME::Types.of(path)

      base_64_embed data, mime
    end

    ##
    # Returns a string denoting embedded, base64 encoded image data.
    #
    # [format]
    #   type of image data (e.g. PNG, JPEG, GIF, etc.)
    #
    def ERBook.base_64_embed_image_data data, format #:nodoc:
      base_64_embed data, "image/#{format}"
    end

    # admonition icons

      ICON_DEFS = YAML.load_file File.join(ICONS_DIR, 'index.yaml')

      class Icon < Struct.new(:origin, :path, :name, :format, :data) #:nodoc:
        ##
        # Returns a data URI containing embedded image data.
        #
        def data_uri
          ERBook.base_64_embed_image_data self.data, self.format
        end

        ##
        # Returns a CSS url() containing embedded image data.
        #
        def data_css
          %{url("#{data_uri}")}
        end

        ##
        # Returns a XML entity reference (to this icon's
        # embedded image data) ready for insertion into XML.
        #
        def entity_xml
          "&#{entity_name};"
        end

        ##
        # Returns the name of the XML entity whose
        # value contains embedded image data.
        #
        def entity_name
          "icon_#{name}"
        end

        ##
        # Returns an <img/> tag that renders the image
        # data embedded as an ENTITY in the html DOCTYPE.
        #
        def to_xhtml atts = {}
          atts[:alt] ||= name
          atts[:src] = entity_xml
          atts[:class] = :icon
          "<img#{atts.to_xml_atts}/>"
        end
      end

      ICON_BY_NAME = {}

      ICON_DEFS.each_pair do |name, path|
        format = File.extname(path).sub('.', '')
        origin = path[/^\w+/]

        path = File.join(ICONS_DIR, path) # make the path absolute
        data = base_64_encode_file(path)

        ICON_BY_NAME[name] = Icon.new(origin, path, name, format, data)
      end

      ICONS = ICON_BY_NAME.values

    class Template::Sandbox
      ##
      # Protects the given content from the text-to-XHTML conversion process.
      #
      def verbatim content
        ::ERB::Util.html_escape content
      end

      ##
      # Returns XHTML for a hyperlink to the given
      # URL of the given label and mouse-hover title.
      #
      def hyperlink url, label = url, title = nil
        %{<a href="#{url}"#{%{ title="#{title}"} if title}>#{label}</a>}
      end

      ##
      # Returns an <img/> tag that embeds the given image file.
      #
      # [path]
      #   path to the image file
      #
      # [format]
      #   format of the image file (e.g. PNG, JPEG, GIF, etc.)
      #
      # [atts]
      #   additional attributes for the <img> tag
      #
      def embed_image_file path, format = path[/\w+/], atts = {}
        data = ERBook.base_64_encode File.read(path)
        embed_image_data data, format, atts
      end

      ##
      # Returns an <img/> tag that embeds the given raw image data.
      #
      # [data]
      #   raw image data
      #
      # [format]
      #   format of the image file (e.g. PNG, JPEG, GIF, etc.)
      #
      # [atts]
      #   additional attributes for the <img> tag
      #
      def embed_image_data data, format, atts = {}
        atts[:src] = ERBook.base_64_embed_image_data(data, format)
        "<img#{atts.to_xml_atts}/>"
      end
    end

    class Document::Node
      ##
      # Returns the user-defined title for this node's content.
      #
      def title
        @title ||= args[0]
      end

      ##
      # Returns the user-defined indentifer for this node.
      #
      def id
        @id ||= args[1]
      end

      # utility methods

        def type_frag #:nodoc:
          "__#{type}__"
        end

        def type_label #:nodoc:
          ERBook::PHRASES[type.to_s.capitalize]
        end

        ##
        # Returns the title of this node as XHTML.
        #
        def title_xhtml
          title.to_s.to_inline_xhtml
        end

        ##
        # Returns the content of this node as XHTML.
        #
        def content_xhtml
          content.join.to_xhtml
        end

        ##
        # Returns the content of this node as XHTML inside a <div/>.
        #
        def content_xhtml_div #:nodoc:
          %{<div class="content">#{content_xhtml}</div>}
        end

        ##
        # Returns a hyperlink to this node containing its title.
        #
        def title_link title = nil
          title || title_xhtml
        end

        ##
        # Returns a hyperlink to this node
        # containing its LaTeX-style index number.
        #
        def index_link
          index
        end

        ##
        # Returns a hyperlink to this node containing its occurrence number.
        #
        def number_link
          [type_label, number].compact.join(' ')
        end

        ##
        # Returns a hyperlink to this node containing
        # its ocurrence number and its title.
        #
        def number_and_title_link #:nodoc:
          "#{number_link}.&nbsp;&nbsp;#{title_link}"
        end

        ##
        # Returns a hyperlink to this node containing
        # its LaTeX-style index number and its title.
        #
        def index_and_title_link #:nodoc:
          "#{index_link}&nbsp;&nbsp;#{title_link}"
        end

        ##
        # Returns a navigation menu for this node.
        #
        def navigation
          self.class.navigation(
            here_frag,
            (list_frag if defn['toc'] || defn['lof']),
            (prev_node.here_frag if prev_node),
            (next_node.here_frag if next_node)
          )
        end

        def parent_tabs_begin #:nodoc:
          if p = parent and pc = p.toc_children and self == pc.first
            %{<div class="tabs"><ul>} +

            pc.map do |c|
              %{<li><a href="##{c.here_frag}">#{c.title.to_s.to_inline_xhtml}</a></li>}
            end.join +

            %{</ul>}
          end
        end

        def parent_tabs_end #:nodoc:
          if p = parent and self == p.toc_children.last
            '</div>'
          end
        end

        ##
        # Returns all children of this node which are
        # configured to appear in the table of contents.
        #
        def toc_children
          children.select {|c| c.defn['toc'] }
        end

        HERE_TEXT = ERBook::PHRASES['Focus this segment']
        PREV_TEXT = ERBook::PHRASES['Focus previous segment']
        NEXT_TEXT = ERBook::PHRASES['Focus next segment']
        LIST_TEXT = ERBook::PHRASES['Return to listing']

        HERE_SIGN = ICON_BY_NAME['nav_here'].to_xhtml(:alt => '&lowast;')
        PREV_SIGN = ICON_BY_NAME['nav_prev'].to_xhtml(:alt => '&larr;')
        NEXT_SIGN = ICON_BY_NAME['nav_next'].to_xhtml(:alt => '&rarr;')
        LIST_SIGN = ICON_BY_NAME['nav_list'].to_xhtml(:alt => '&equiv;')

        ##
        # Calculates a local navigation menu containing links
        # to the given URI fragments (which can be nil).
        #
        def self.navigation here_frag, list_frag, prev_frag, next_frag
          here_link = %{<a title="#{HERE_TEXT}" href="##{here_frag}">#{HERE_SIGN}</a>} if here_frag
          prev_link = %{<a title="#{PREV_TEXT}" href="##{prev_frag}">#{PREV_SIGN}</a>} if prev_frag
          next_link = %{<a title="#{NEXT_TEXT}" href="##{next_frag}">#{NEXT_SIGN}</a>} if next_frag
          list_link = %{<a title="#{LIST_TEXT}" href="##{list_frag}">#{LIST_SIGN}</a>} if list_frag

          %{<a name="#{here_frag}"/><div class="nav">#{here_link} #{prev_link} #{next_link} #{list_link}</div>}
        end

        ##
        # Returns a hyperlink to this node.
        #
        # [label]
        #   Optional label (may contain XHTML) for the hyperlink.
        #
        #   If not specified, the title and designation of
        #   this node will be used as the label instead.
        #
        def xref_link label = nil
          prefix = [type_label, index || number].compact.join(' ')

          caption =
            if type == 'reference'
              prefix
            else
              [prefix, (%{"#{title}"} if label && title)].compact.join('. ')
            end

          label_xhtml = (label || title).to_s.to_inline_xhtml

          %{<a class="xref" href="##{here_frag}" title="#{::ERB::Util.h caption}">#{label_xhtml}</a>}
        end

      # URI fragments

        @@frags = []

        ##
        # Returns a unique URI fragment for this node.
        #
        def here_frag #:nodoc:
          unless defined? @here_frag
            salt = object_id.abs
            frag = (id || title || salt).to_s.to_uri_fragment

            # make it unique
            while @@frags.include? frag
              frag = "#{frag} #{index || number || salt}".to_uri_fragment
            end

            @@frags << frag
            @here_frag = frag
          end

          @here_frag
        end

        ##
        # Returns the URI fragment for the location in the table
        # of contents / list of figures that points this node.
        #
        def list_frag #:nodoc:
          @list_frag ||= "__toc__#{here_frag}".to_uri_fragment
        end
    end
  end


nodes:
  # object model
    node:
      toc: false
      lof: false
      depth: false
      index: false
      number: false
      silent: false
      inline: true
      bypass: true
      output: <%= @node.content_xhtml %>

  # Structure
    header: &header
      toc: false
      lof: false
      depth: false
      index: false
      number: false
      silent: true
      inline: true
      output: <%= @node.content_xhtml %>

    header_outside_above: &header_insert
      toc: false
      lof: false
      depth: false
      index: false
      number: false
      silent: true
      inline: true
      output: |
        <%= @node.parent_tabs_begin %>
        <div class="<%= @node.type %>" id="<%= @node.here_frag %>"><%= @node.content_xhtml %></div>
        <%= @node.parent_tabs_end %>

    header_inside_above:  *header_insert
    header_inside_below:  *header_insert
    header_outside_below: *header_insert

    footer:               *header
    footer_outside_above: *header_insert
    footer_inside_above:  *header_insert
    footer_inside_below:  *header_insert
    footer_outside_below: *header_insert

    abstract:
      toc: false
      lof: false
      depth: false
      index: false
      number: false
      silent: true
      bypass: true
      output: |
        <div id="<%= @node.type_frag %>">
          <%= @node.navigation %>
          <h1 class="title"><%= @node.type_label %></h1>
          <%= @node.content_xhtml_div %>
        </div>

  # Organization
    part: &latex
      toc: true
      lof: false
      depth: true
      index: true
      number: true
      silent: false
      output: |
        <%= @node.parent_tabs_begin %>
        <div class="<%= @node.type %>" id="<%= @node.here_frag %>">
          <%= @node.navigation %>
          <h1 class="title">
            <%= @node.type_label %>&nbsp;<%= @node.index_link %>
            <br/>
            <big><%= @node.title_link %></big>
          </h1>
          <%= @node.content_xhtml_div %>
        </div>
        <%= @node.parent_tabs_end %>

    chapter: *latex

    section:
      toc: true
      lof: false
      depth: true
      index: true
      number: true
      silent: false
      output: |
        <% depth = [6, @node.depth + 1].min %>
        <%= @node.parent_tabs_begin %>
        <div class="<%= @node.type %>" id="<%= @node.here_frag %>">
          <%= @node.navigation %>
          <h<%= depth %> class="title">
            <%= @node.index_and_title_link %>
          </h<%= depth %>>
          <%= @node.content_xhtml_div %>
        </div>
        <%= @node.parent_tabs_end %>

    paragraph:
      toc: true
      lof: false
      depth: false
      index: false
      number: false
      silent: false
      output: |
        <%= @node.parent_tabs_begin %>
        <div class="<%= @node.type %>" id="<%= @node.here_frag %>">
          <%= @node.navigation %>
          <p class="title"><%= @node.title_link %></p>
          <%= @node.content_xhtml_div %>
        </div>
        <%= @node.parent_tabs_end %>

  # Admonitions
    tip: &admonition
      toc: false
      lof: true
      depth: true
      index: false
      number: true
      silent: false
      output: |
        <%= @node.parent_tabs_begin %>
        <div class="<%= @node.type %>" id="<%= @node.here_frag %>">
          <%= @node.navigation %>
          <p class="title"><%= @node.number_and_title_link %></p>
          <div class="content">
            <%= ICON_BY_NAME[@node.type].to_xhtml %>
            <%= @node.content_xhtml %>
          </div>
        </div>
        <%= @node.parent_tabs_end %>

    note: *admonition
    caution: *admonition
    warning: *admonition
    important: *admonition

  # Auxilary materials (formal blocks)
  # see http://www.sagehill.net/docbookxsl/FormalTitles.html
    figure: &formal
      toc: false
      lof: true
      depth: true
      index: false
      number: true
      silent: false
      output: |
        <%= @node.parent_tabs_begin %>
        <div class="<%= @node.type %>" id="<%= @node.here_frag %>">
          <%= @node.navigation %>
          <p class="title"><%= @node.number_and_title_link %></p>
          <%= @node.content_xhtml_div %>
        </div>
        <%= @node.parent_tabs_end %>

    table: *formal
    example: *formal
    equation: *formal
    procedure: *formal

  # cross-references
    xref:
      toc: false
      lof: false
      depth: true
      index: false
      number: false
      silent: false
      inline: true
      output: |
        <%=
          query, label = @node.args

          scope  = @nodes.select {|n| n.content }
          target = scope.find {|n| n.id == query } || # id has 1st priority
                   scope.find {|n| n.title == query }

          if target
            target.xref_link label
          else
            raise ArgumentError, "invalid cross-reference to #{@node.title.inspect}", @node.trace
          end
        %>

  # Bibliography
    reference:
      toc: false
      lof: false
      depth: false
      index: false
      number: true
      silent: true
      bypass: true

    cite:
      toc: false
      lof: false
      depth: false
      index: false
      number: false
      silent: false
      inline: true
      output: |
        <%=
          target = @nodes_by_type['reference'].find {|n| n.title == @node.title }

          if target
            '<sup>[%s]</sup>' % [
              target.xref_link(target.number),
              *@node.args[1..-1]
            ].join(', ')
          else
            raise ArgumentError, "invalid citation for #{@node.title.inspect}", @node.trace
          end
        %>

output: |
  <%
    # set default parameter values
    $title    = '$title' unless defined? $title
    $subtitle = '$subtitle' unless defined? $subtitle
    $authors  = {'$authors' => nil} unless defined? $authors
    $date     = Time.now.strftime("%d %B %Y") unless defined? $date

    abstract = @nodes_by_type['abstract'].first

    references = @nodes_by_type['reference']
    if references.empty?
      references = nil
    end

    # compute table of contents
      toc_builder = lambda do |n|
        nested = n.children.inject('') {|s,c| s << toc_builder[c] }
        nested = nil if nested.empty?

        if n.defn['toc']
          entry = '%s<a id="%s" href="#%s">%s</a>' % [
            (n.index.to_s + '&nbsp;&nbsp;' if n.index),
            n.list_frag,
            n.here_frag,
            n.title.to_s.to_inline_xhtml
          ]

          %{<li>#{entry}#{"<ul>#{nested}</ul>" if nested}</li>}
        else
          nested
        end.to_s
      end

      toc = @roots.inject('') {|s,n| s << toc_builder[n] }

    # compute list of figures
      lof_enums = {} # type => nodes

      @format['nodes'].each_pair do |name, info|
        if info['lof']
          nodes = @nodes_by_type[name]
          lof_enums[name] = nodes unless nodes.empty?
        end
      end

      lof_sections_frag_and_label = []

      lof = lof_enums.sort.map do |type, nodes|
        nested = nodes.map do |n|
          %{<li><a id="#{n.list_frag}" href="##{n.here_frag}">#{n.title.to_s.to_inline_xhtml}</a></li>}
        end

        label = ERBook::PHRASES[type.capitalize << 's']
        frag = nodes.first.type_frag
        lof_sections_frag_and_label << [frag, label]

        %{<div id="#{frag}"><h2 class="title">#{label}</h2> <ol>#{nested}</ol></div>}
      end
  %><?xml version="1.0" encoding="utf-8"?>
  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
    %|ICONS.each |icon|
      <!ENTITY <%= icon.entity_name %> "<%= icon.data_uri %>">
  ]>
  <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
      <meta http-equiv="content-type" content="application/xhtml+xml; charset=utf-8"/>
      <meta name="generator" content="<%= ERBook::DISPLAY %>"/>

      % if $title || $subtitle
        <title><%=
          [$title, $subtitle].compact.map do |t|
            t.to_s.to_inline_xhtml
          end.join(' &mdash; ')
        %></title>

      % if $authors
        <meta name="author" content="<%= $authors.keys.join(', ') %>"/>

      % if $date
        <meta name="date" content="<%= $date %>"/>

      % if $feeds
        % $feeds.each_pair do |url, fmt|
          <link rel="alternate" type="application/<%= fmt %>+xml" href="<%= url %>"/>

      <style type="text/css" media="screen">
      /*<![CDATA[*/
        <%=
          css = File.read(File.join(JQUERY_DIR, 'jquery-ui-1.7.2.custom.css'))

          # embed images used by jQuery UI as data URIs
          css.gsub! %r{\bimages/.*?\.png\b} do |path|
            # XXX: using inspect to put quotes around the value
            #      because jQuery did not put them in their CSS
            ERBook.base_64_embed_file(File.join(JQUERY_DIR, path)).inspect
          end

          css
        %>

        .ui-widget
        {
            /* prevent nested widgets from having larger fonts */
            font-size: 1em;
        }

        .ui-tabs .ui-tabs-nav li.ui-tabs-selected a
        {
            cursor: pointer;
        }

        /* decorate external hyperlinks with a visual indicator */
        a[href]:not([href^="#"])
        {
            background          : <%= ICON_BY_NAME['hyperlink'].data_css %>;
            background-position : center right;
            background-repeat   : no-repeat;
            padding-right       : 13px;
        }

        /* display icon for blockquote elements */
        blockquote
        {
            background-image    : <%= ICON_BY_NAME['quote'].data_css %>;
            background-repeat   : no-repeat;
            margin-left         : 0;
            padding-left        : 65px;
            min-height          : 50px;
        }
      /*]]>*/
      </style>

      % require 'rainpress'
      % @format['styles'].each do |style|
        % style.each_pair do |media, sass|
          <style type="text/css" media="<%= media %>">
          /*<![CDATA[*/<%=

            # expand eRuby directives in SASS templates
            sass = ::Ember::Template.new(sass).render(binding)

            # compile SASS into CSS
            require 'sass'
            css = ::Sass::Engine.new(sass).render

            # minify the CSS
            css = Rainpress.compress(css)

          %>/*]]>*/
          </style>

      <script type="text/javascript">
      //<![CDATA[
        %< File.join(JQUERY_DIR, 'jquery-1.3.2.min.js')
        %< File.join(JQUERY_DIR, 'jquery-ui-1.7.2.custom.min.js')

        $(function() {
          //
          // respond to changes in window location
          //
          var $last_hash = null;

          function on_hash_change() {
            var curr_hash = window.location.hash;

            if (curr_hash && curr_hash != $last_hash) {
              $last_hash = curr_hash;
              reveal_hash(curr_hash);
            }

            setTimeout(on_hash_change, 300);
          }

          //
          // Sets the location bar hash to the given value.
          //
          // [prevent_jump]
          //  If true, prevents the browser from jumping to
          //  the element corresponding to the given hash.
          //
          function set_hash(hash, prevent_jump) {
            var set_the_hash = function() {
              //
              // XXX: bypass on_hash_change() by setting $last_hash
              //
              window.location.hash = $last_hash = hash;
            }

            if (prevent_jump) {
              var target = $(hash);

              if (target.length) {
                //
                // This particular approach to solving the browser
                // jumping problem comes from the jQuery.LocalScroll
                // plugin, which is dual licensed under MIT and GPL:
                //
                //   Copyright (c) 2007-2009 Ariel Flesler - aflesler(at)gmail(dot)com | http://flesler.blogspot.com
                //
                //   Permission is hereby granted, free of charge, to any person obtaining a copy
                //   of this software and associated documentation files (the "Software"), to deal
                //   in the Software without restriction, including without limitation the rights
                //   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
                //   copies of the Software, and to permit persons to whom the Software is
                //   furnished to do so, subject to the following conditions:
                //
                //   The above copyright notice and this permission notice shall be included in
                //   all copies or substantial portions of the Software.
                //
                //   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
                //   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
                //   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
                //   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
                //   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
                //   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
                //   THE SOFTWARE.
                //
                // This plugin is documented at:
                //
                //   http://flesler.blogspot.com/2007/10/jquerylocalscroll-10.html
                //
                // And its source is available at:
                //
                //   http://flesler-plugins.googlecode.com/svn/trunk/jquery.localScroll/jquery.localScroll.js
                //
                var target_id = target.attr('id');

                //
                // temporarily place a dummy element at the current
                // screen position and give it the ID of the target
                //
                var dummy = $('<span/>').attr('id', target_id).css({
                  position: 'absolute',
                  top:      $(window).scrollTop()
                });

                target.removeAttr('id').before(dummy);

                //
                // when we set the hash, the browser will jump to the
                // dummy, which is where the browser screen currently
                // is, and therefore the jump will not be visualized!
                //
                set_the_hash();

                //
                // undo the temporary changes
                //
                dummy.remove();
                target.attr('id', target_id);

                return;
              }
            }

            set_the_hash();
          }

          //
          // Returns the tab corresponding to the
          // given panel in the given tabs widget.
          //
          function tab_by_panel(panel, tabs_widget) {
            if (!tabs_widget) {
              tabs_widget = panel.parent('.ui-tabs');
            }

            return tabs_widget.find(
              '.ui-tabs-nav > li > a[href=#'+ panel.attr('id') +']'
            ).parent('li');
          }

          //
          // Reveals the element at the given hash by (1) activating all
          // tabs that contain it, (2) smoothly scrolling to it, and (3)
          // updating the hash in the browser's location bar accordingly.
          //
          function reveal_hash(hash) {
            var target = $(hash);

            if (target.length) {
              var target_is_panel = target.is('div') &&
                target.parent('.ui-tabs').length;

              var target_initially_hidden = target.is(':hidden');

              //
              // reveal all tabs which contain the target
              //
              if (target_initially_hidden) {
                var panels = target.parents('.ui-tabs > div:hidden').get().reverse();

                if (target_is_panel) {
                  panels.push(target);
                }

                for (var i in panels) {
                  var panel = $(panels[i]);
                  var tabs_widget = panel.parent('.ui-tabs');
                  var selected_index = tabs_widget.tabs('option', 'selected');

                  //
                  // map the panel to its tab because tabs do not
                  // have to be in the same order as their panels
                  //
                  var tab = tab_by_panel(panel, tabs_widget);
                  var wanted_index = tab.prevAll('li').length;

                  if (wanted_index != selected_index) {
                    tabs_widget.tabs('select', wanted_index);
                  }
                }
              }

              function scroll_to_target_and_set_hash() {
                if (target.is(':hidden')) {
                  //
                  // wait before scrolling because the
                  // tabs.select() calls above may not
                  // have fully taken effect yet and
                  // so the target may still be hidden
                  //
                  setTimeout(scroll_to_target_and_set_hash, 0);
                }
                else {
                  //
                  // scroll to the tab bar instead of the target
                  // because it contains the title for the target
                  //
                  var scroll_target = target_is_panel ?
                    target.parent('.ui-tabs') : target;

                  var screen_before_scroll = $(window).scrollTop();

                  $('html').animate({
                    scrollTop: Math.floor(scroll_target.offset().top)
                  }, 'slow', 'swing', function() {
                    set_hash(hash, target_is_panel);

                    if (
                      !target_initially_hidden &&
                      $(window).scrollTop() == screen_before_scroll
                    ) {
                      //
                      // nothing changed on the screen.
                      // the target was already visible.
                      // highlight it to notify the user.
                      //
                      target.effect('highlight', 'slow');
                    }
                  });
                }
              }

              scroll_to_target_and_set_hash();
            }
          }

          //
          // create jQuery UI tabs
          //
          $('.tabs').tabs();

          //
          // make internal hyperlinks reveal their targets when clicked
          //
          $('a[href^=#]').click(function() {
            var link = $(this);
            var hash = link.attr('href');

            if (link.parent('li').parent('.ui-tabs-nav').length) {
              // tab clicks should not cause the screen to scroll
              set_hash(hash, true);
            }
            else {
              reveal_hash(hash);
            }

            return false;
          });

          //
          // checkbox for printer friendly stylesheet
          //
          $('#__header__ > .authors_and_date').append(
            $('<span/>').append(
              $('<input/>').attr('type', 'checkbox').click(function() {
                if ($(this).is(':checked')) {
                  $('style[media=screen]').attr('media', 'neercs');
                  $('style[media=print]').attr('media', 'screen');
                }
                else {
                  $('style[media=screen]').attr('media', 'print');
                  $('style[media=neercs]').attr('media', 'screen');
                }
                return true;
              })
            ).append(" <%= ERBook::PHRASES['Printer friendly'] %>")
          );

          //
          // ready for action!
          //
          $('#__loading__').append("<%= ERBook::PHRASES['Ready!'] %>").
          fadeOut('slow', function() {
            $('#__body__').show();
            on_hash_change();
          });
        });
      //]]>
      </script>
    </head>
    <body>
      <%
        text_only_browser_divider = %{
          <div style="display: none"><br/><hr/><br/></div>
        }.strip
      %>

      <div id="__loading__">
        <%= ERBook::PHRASES['Loading...'] %> <noscript><%= ERBook::PHRASES['Failed!'] %>
          <p><%= ERBook::PHRASES['Please enable JavaScript in your Web browser.'] %></p>

          %= text_only_browser_divider
        </noscript>
      </div>

      <div id="__body__">
        %= node.output if node = @nodes_by_type['header_outside_above'].first

        <div id="__header__">
          %= node.output if node = @nodes_by_type['header_inside_above'].first

          % if header = @nodes_by_type['header'].first
            <%= header.output %>
          % else
            % if $logo
              <div class="logo"><%= $logo %></div>

            <div class="title_and_subtitle">
              % if $title
                <h1 class="title"><%= $title.to_s.to_inline_xhtml %></h1>

              % if $subtitle
                <h2 class="subtitle"><%= $subtitle.to_s.to_inline_xhtml %></h2>
            </div>

            <div class="authors_and_date">
              % if $authors
                <h3 class="authors"><%=
                  $authors.map do |name, url|
                    if url
                      %{<a href="#{url}">#{name}</a>}
                    else
                      name
                    end
                  end.join(', ')
                %></h3>

              % if $date
                <h3 class="date"><%= $date %></h3>
            </div>

          %= node.output if node = @nodes_by_type['header_inside_below'].first
        </div>

        %= node.output if node = @nodes_by_type['header_outside_below'].first

        <div class="tabs">
          <ul>
            % if abstract
              <li><a href="#__abstract__"><%= ERBook::PHRASES['Abstract'] %></a></li>

            <li><a href="#__doc__"><%= ERBook::PHRASES['Document'] %></a></li>

            % unless toc.empty?
              <li><a href="#__toc__"><%= ERBook::PHRASES['Contents'] %></a></li>

            % if references
              <li><a href="#__bib__"><%= ERBook::PHRASES['References'] %></a></li>

            <li><a href="#__nfo__"><%= ERBook::PHRASES['About'] %></a></li>
          </ul>

          %= abstract.output if abstract

          % unless toc.empty?
            <div id="__toc__">
              <h1 class="title"><%= ERBook::PHRASES['Contents'] %></h1>
              <ul><%= toc %></ul>

              % unless lof.empty?
                <div id="__lof__"><%= lof %></div>
            </div>

          <div id="__doc__" class="tabs">
            <h1 style="display: none"><%= ERBook::PHRASES['Document'] %></h1>
            <ul>
              % @roots.select {|n| n.defn['toc'] }.each do |n|
                <li><a href="#<%= n.here_frag %>"><%= n.title.to_s.to_inline_xhtml %></a></li>
            </ul>

            %= @content
          </div>

          % if references
            <div id="__bib__">
              <h1 class="title"><%= ERBook::PHRASES['References'] %></h1>
              <ol>
              % references.each do |n|
                <li id="<%= n.here_frag %>"><%= n.content_xhtml %></li>
              </ol>
            </div>

          %= text_only_browser_divider

          <div id="__nfo__">
            <p><%=
              ERBook::PHRASES[
                'This document was generated by %s on %s using the following resources.',
                %{<a href="#{ERBook::WEBSITE}">#{ERBook::DISPLAY}</a>},
                %{<b>#{Time.now}</b>}
              ]
            %></p>

            <table border="1">
              <thead>
                <tr>
                  <th><%= ERBook::PHRASES['Resource'] %></th>
                  <th><%= ERBook::PHRASES['Origin'] %></th>
                  <th><%= ERBook::PHRASES['License'] %></th>
                </tr>
              </thead>
              <tbody>
                <tr>
                  <td>
                    % ICONS.select {|i| i.origin == 'tango' }.each do |icon|
                      %= icon.to_xhtml
                  </td>
                  <td>
                    <a href="http://tango.freedesktop.org/Tango_Icon_Library">Tango Icon Theme</a>

                    <p>&copy; 2005 <a href="http://tango.freedesktop.org">Tango Desktop Project</a></p>
                  </td>
                  <td>
                    <a href="http://creativecommons.org/licenses/by-sa/2.5/">Creative Commons Attribution-ShareAlike 2.5 License Agreement</a>
                  </td>
                </tr>

                <tr>
                  <td>
                    % ICONS.select {|i| i.origin == 'mediawiki' }.each do |icon|
                      %= icon.to_xhtml
                  </td>
                  <td>
                    <a href="http://www.mediawiki.org/skins-1.5/monobook/external.png">MediaWiki Monobook Skin</a>

                    <p>&copy; 2007 <a href="https://www.ohloh.net/projects/mediawiki/contributors">MediaWiki contributors</a></p>
                  </td>
                  <td>
                    <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General Public License, version 2</a>
                  </td>
                </tr>
              </tbody>
            </table>

            <p class="validations">
              <a href="http://validator.w3.org/check?uri=referer"><img
                  src="http://www.w3.org/Icons/valid-xhtml10-blue"
                  alt="Valid XHTML 1.0 Transitional" height="31" width="88" /></a>

              <a href="http://jigsaw.w3.org/css-validator/check/referer?profile=css3"><img
                src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
                alt="Valid CSS!" height="31" width="88" /></a>
            </p>
          </div>
        </div>


        %= node.output if node = @nodes_by_type['footer_outside_above'].first

        <div id="__footer__">
          %= node.output if node = @nodes_by_type['footer_inside_above'].first

          % if footer = @nodes_by_type['footer'].first
            %= footer.content.to_s.to_xhtml

          %= node.output if node = @nodes_by_type['footer_inside_below'].first
        </div>

        %= node.output if node = @nodes_by_type['footer_outside_below'].first

      </div>
    </body>
  </html>

# definition of font families for use in the CSS styles
fonts:
  serif:      Constantia, "Book Antiqua", "URW Bookman L", serif
  sans-serif: Calibri, Verdana, sans-serif
  monospace:  Monaco, Consolas, "Lucida Console", monospace

styles: # these are SASS templates
- all: |
    body
      color: #000000
      background-color: #FFFFFF
      line-height: 1.5em
      font-family: <%= @format['fonts']['sans-serif'] %>


    blockquote
      color: #333
      font-style: italic


    em, strong, dt
      font-family: <%= @format['fonts']['serif'] %>


    hr
      height: 0
      border: 0
      border-top: thin dashed #000000


    tt, code, pre
      font-family: <%= @format['fonts']['monospace'] %>
      // appears like "size: small" otherwise
      font-size: 100%


    // output of the syntax coloring library
    code.para
      white-space: pre


    a > img
      border: none


    dt
      margin-top: 1.5em
      font-weight: bolder


    h1, h2, h3, h4, h5, h6, .title
      font-weight: lighter
      font-family: <%= @format['fonts']['serif'] %>


    #__lof__
      h1, h2, h3, h4, h5, h6
        margin-top: 1.25em


    #__doc__
      h1, h2, h3, h4, h5, h6
        margin-top: 2.5em
        line-height: 1.25em

      h1
        font-size: 2.0em

      h2
        font-size: 1.8em

      h3
        font-size: 1.6em

      h4
        font-size: 1.4em

      h5
        font-size: 1.2em

      h6
        font-size: 1.0em


    table
      border: none
      // no spacing between cell borders
      border-collapse: collapse
      margin: auto
      margin-top: 1em
      margin-bottom: 1em


    th, td
      padding: 1em
      border: 1px solid #bbb
      vertical-align: top
      background-color: #FFFFFF


    th
      background-color: #F5F5F5


    #__header__ > .title
      font-size: 2.25em


    #__abstract__
      margin-bottom: 5em


    #__toc__
      ul > li
        list-style-type: none

      li ul
        padding-bottom: 1em
        border-left: thick solid #F5F5F5

        &:hover
          border-color: #DCDCDC

      > ul
        padding-left: 1em


    #__footer__
      padding-top: 1em
      text-align: center
      margin: auto


    .part > .title, .chapter > .title
      padding-bottom: 0.5em


    .part > .title > big, .chapter > .title > big
      display: block
      margin-top: 0.25em


    .paragraph > .title, .tip > .title, .note > .title, .caution > .title, .warning > .title, .important > .title, .figure > .title, .table > .title, .example > .title, .equation > .title, .procedure > .title
      font-size: large
      margin-top: 2em


    .tip, .note, .caution, .warning, .important, .figure, .table, .example, .equation, .procedure
      margin: 3em


    .tip .nav, .note .nav, .caution .nav, .warning .nav, .important .nav, .figure .nav, .table .nav, .example .nav, .equation .nav, .procedure .nav
      margin-right: -3em


    .tip > .content, .note > .content, .caution > .content, .warning > .content, .important > .content, .figure > .content, .table > .content, .example > .content, .equation > .content, .procedure > .content
      // height of icon
      min-height: 48px


    .tip > .content > .icon, .note > .content > .icon, .caution > .content > .icon, .warning > .content > .icon, .important > .content > .icon
      float: left
      margin:
        top: 0
        right: 1em
        bottom: 1em
        left: 0


    .figure >
      .title
        text-align: center

      .content img
        display: block
        margin: auto


- screen: |
    body
      margin: 0
      padding: 0.5em
      background-color: #FFFFFF


    #__body__, #__abstract__ > .title, #__toc__ > .title, .part > .title, .chapter > .title, .section > .title, .paragraph > .title, #__bib__ > .title
      display: none


    .tabs
      // otherwise .nav becomes obscured by the tabs
      clear: both


    tt
      background-color: #F0F8FF


    pre
      cursor: text
      line-height: normal
      border: 1px solid #b1d827
      background-color: #F5FFDF
      padding: 1em

      // fit container to content; no overflow!
      display: inline-block
      margin: 0
      min-width: 92.5%


    // output of the syntax coloring library
    code.para
      cursor: text
      line-height: normal
      border: 1px solid #b1d827
      background-color: #F5FFDF
      padding: 1em
      display: inline-block
      margin: 0
      min-width: 92.5%
      background-color: #FFFFE8
      border-color: #EEDD88


    pre.para
      background-color: #FFFFE8
      border-color: #EEDD88


    a
      text-decoration: none

      &:hover
        text-decoration: underline

      &:link
        // maximum saturation of RoyalBlue
        color: #0038E1

      &:visited
        color: #800080


    #__toc__ a:target, #__lof__ a:target
      background: <%= ICON_BY_NAME['here_frag'].data_css %>
      background-position: center right
      background-repeat: no-repeat
      padding-right: 20px


    #__header__ >
      .logo
        float: left
        margin-right: 1em
        margin-top: 0.25em

        img
          max-height: 4em
          max-width: 4em

      .title_and_subtitle
        float: left
        margin-right: 1.5em

        .title
          margin-top: 0.25em

      .authors_and_date
        text-align: right

        .authors, .date
          margin-top: 0
          margin-bottom: 0.25em

        .date
          font-weight: lighter


    .nav
      float: right

      > a > img
        border-top: thick solid #FFFFFF

        &:hover
          border-top: thick solid #FA8072


    #__nfo__ > table td:first-child, #__nfo__ > .validations
      text-align: center


- print: |
    tt
      font-weight: normal


    pre
      border: none


    h1, h2, h3, h4, h5, h6
      font-weight: normal
      clear: both


    =emphasize_hyperlinks
      color: #0000FF
      text-decoration: underline
      font-weight: bolder

    a
      // blend all hyperlinks with normal text
      &:link, &:visited
        color: #000000
        text-decoration: none

      // emphasize external hyperlinks
      &[href]:not([href^="#"])
        &:link, &:visited
          +emphasize_hyperlinks

      // emphasize cross-reference hyperlinks
      &.xref[title]
        &:link, &:visited
          +emphasize_hyperlinks

      // show URL of destination for external hyperlinks
      &[href]:not([href^="#"]):after
        content: " " attr(href)
        font-family: <%= @format['fonts']['monospace'] %>

      // show name of destination for cross-references
      &.xref[title]:after
        content: " " attr(title)

      &:after
        font-weight: normal
        font-size: smaller


    .tabs > ul, .nav, #__lof__, #__nfo__ > .validations
      display: none


    #__toc__, .part, .chapter, #__bib__
      page-break-before: always


    #__header__, #__footer__
      text-align: center


    #__header__ > .authors
      margin-top: 1.625em
      margin-bottom: -0.25em


    .header_outside_above, #__header__, .header_outside_below, .logo
      margin-bottom: 5em


    .footer_outside_above, #__footer__, .footer_outside_below, #__bib__, #__nfo__
      margin-top: 5em


    #__header__ .header_inside_above, #__footer__ .footer_inside_above
      margin-bottom: 4em


    #__header__ .header_inside_below, #__footer__ .footer_inside_below
      margin-top: 4em


    .part > .title > big, .chapter > .title > big
      padding-bottom: 0.5em