erbook 8.0.0 → 9.0.0

data/doc/intro.erb

@@ -23,12 +23,13 @@
   * [Project home](<%= $website %>) --- the <%= $project %> project home page.
 
   To get help or provide feedback, simply
-  <%= xref "License", "contact the author(s)" %>.
+  %= xref "License", "contact the author(s)."
 
 
   %|section "Features"
 
     <%= $project %> is exciting because:
+
     * Its documents are scriptable [eRuby templates](<%= eruby_url %>).
     * It lets you <%= xref "HelloWorld", "define your own document formats" %>.
     * It emits beautiful <%= xref "xhtml", "XHTML (web page)" %> documents.
@@ -47,11 +48,12 @@
 
   %|section "Credits" |n|
 
-    %= $logo = n.xref_link("![#{$project} logo](#{$program}.png)".to_inline_xhtml)
+    %= $logo = n.xref_link("![#{$project} logo](#{$program}.png)".to_xhtml)
 
     %< "README"
 
-    <%= $project %> is made possible by
+    %= $project
+    is made possible by
     %= xref "History", "contributions"
     from users like you:
 

data/doc/setup.erb

@@ -26,14 +26,14 @@
           %|td
             Ruby language interpreter
           %|td
-            Version 1.8.7 or newer is required.
+            Version 1.8.7 and 1.9.1 have been tested successfully.
         %|tr
           %|td
             [RubyGems](http://rubygems.org)
           %|td
             Ruby packaging system
           %|td
-            Version 1.0.0 or newer is required.
+            Version 1.3.5 or newer is required.
 
 
   %|section "Installation"
@@ -44,20 +44,24 @@
 
     To check whether the installation was sucessful, run this command:
 
-        <%= $program %> -v
+        <%= $program %> --version
 
     If the installation was successful, you will see output like this:
 
-    <pre><%= verbatim `ruby bin/#{$program} -v` %></pre>
+    %|text
+      %= verbatim `ruby bin/#{$program} --version`
 
-    Otherwise, you can <%= xref "License", "contact the author" %> for help.
+    If you do not see such output, you may
+    %= xref "License", "ask the author(s)"
+    for help.
 
 
   %|section "Package contents"
 
-    You will see the following items inside <%= $project %>'s installation directory, whose path you can determine by running this command:
+    You will see the following items inside <%= $project %>'s installation
+    directory, whose path you can determine by running this command:
 
-        <%= $program %> -v
+        <%= $program %> --version
 
     * <tt>bin/</tt>
 
@@ -78,15 +82,17 @@
 
         * <tt>rdoc.rb</tt> --- provides RDoc parse trees to Ruby code.
 
-    * <tt>doc/</tt> --- contains this manual and other documentation.
+    * <tt>doc/</tt>
+
+      * <tt>api/</tt> --- API reference documentation.
 
       * <tt><%= $program %>.svg</tt> --- source file of the <%= $project %> logo.
 
       * <tt>index.erb</tt> --- source file of this manual.
 
-      * <tt>api/</tt> --- API reference documentation.
+    * <tt>LICENSE</tt> --- copyright notice and legal conditions.
 
-    * <tt>LICENSE</tt> --- project license and copyright notice.
+    * <tt>CREDITS</tt> --- attribution of project contributors.
 
 
   %|section "Version numbers"

data/doc/theory.erb

@@ -367,7 +367,6 @@
                   `String`
                 %|td
                   Path of the current format specification file.
-              %|tr
 
         % output_template_table_builder.call lambda {
           %|tr
@@ -419,14 +418,16 @@
 
       %|example! "HelloWorld format specification file", "HelloWorld.spec"
 
-        <code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.spec') %></code>
+        %|code :rhtml
+          %= verbatim File.read('doc/HelloWorld.spec')
 
 
       %|example! "Input document for HelloWorld format", "HelloWorld.input"
 
         Note that this input document uses the [*shorthand* eRuby directive syntax](<%= Ember::WEBSITE %>#Directives) and the [implicit <tt><%% end %></tt> inference](<%= Ember::WEBSITE %>#Infer-block-endings) features of the [<%= Ember::PROJECT %>](<%= Ember::WEBSITE %>) <%= Ember::TAGLINE %>.
 
-        <code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.input') %></code>
+        %|code :rhtml
+          %= verbatim File.read('doc/HelloWorld.input')
 
 
       %|example! "Output of HelloWorld format", "HelloWorld.output"

data/doc/usage.erb

@@ -8,7 +8,14 @@
 
   %|section "Command-line interface"
 
-    <pre><%= `ruby bin/#{$program} -h` %></pre>
+    When you run this command:
+
+        <%= $program %> --help
+
+    You will see this output:
+
+    %|text
+      %= verbatim `ruby bin/#{$program} --help`
 
     The first command-line argument to <%= $project %> is either the name of a predefined format (FormatName) or the path to a <%= xref "SpecFile", "format specification file" %> (FormatFile).
 
@@ -33,9 +40,9 @@
         Otherwise, Microsoft web browsers _will not display_ your XHTML document and will instead prompt the reader to save your XHTML document as a file on their computer.  See [this detailed explanation](http://www.howtocreate.co.uk/wrongWithIE/?chapter=XHTML) for details.
 
 
-  %|section "Unindenting nodes hierarchically"
+    %|section "Unindenting nodes hierarchically"
 
-    When writing <%= $project %> documents, I prefer to indent the content of nodes according to their depth because my [text editor of choice](http://jedit.org) automatically folds blocks of text based on indentation.
+      When writing <%= $project %> documents, I prefer to indent the content of nodes according to their depth because my [text editor of choice](http://jedit.org) automatically folds blocks of text based on indentation.
 
-    If you also prefer to write documents in this way, be sure to pass the <tt>--unindent</tt> option to <%= $project %> so that the indentation will not affect the resulting output.
+      If you also prefer to write documents in this way, be sure to pass the <tt>--unindent</tt> option to <%= $project %> so that the indentation will not affect the resulting output.
 

data/fmt/xhtml.yaml

@@ -9,7 +9,7 @@ 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
+  # load the String#to_xhtml methods
   require 'erbook/to_xhtml'
 
   class String
@@ -93,7 +93,7 @@ code: |
       data = base_64_encode_file(path)
 
       require 'mime/types'
-      mime = MIME::Types.of(path)
+      mime = MIME::Types.of(path).to_a.join(',')
 
       base_64_embed data, mime
     end
@@ -124,15 +124,21 @@ code: |
         # Returns a CSS url() containing embedded image data.
         #
         def data_css
-          %{url("#{data_uri}")}
+          %{url(#{embed_uri})}
         end
 
         ##
-        # Returns an <img/> tag that renders an embedded data URI.
+        # Returns a temporary data URI that will be replaced
+        # with the actual data URI at runtime by javascript.
+        #
+        alias embed_uri object_id
+
+        ##
+        # Returns an image tag that renders an embedded data URI.
         #
         def to_xhtml atts = {}
           atts[:alt] ||= name
-          atts[:src] = data_uri
+          atts[:src] = embed_uri
           atts[:class] = :icon
           "<img#{atts.to_xml_atts}/>"
         end
@@ -169,7 +175,7 @@ code: |
       end
 
       ##
-      # Returns an <img/> tag that embeds the given image file.
+      # Returns an image tag that embeds the given image file.
       #
       # [path]
       #   path to the image file
@@ -178,7 +184,7 @@ code: |
       #   format of the image file (e.g. PNG, JPEG, GIF, etc.)
       #
       # [atts]
-      #   additional attributes for the <img> tag
+      #   additional attributes for the image tag
       #
       def embed_image_file path, format = path[/\w+/], atts = {}
         data = ERBook.base_64_encode File.read(path)
@@ -186,7 +192,7 @@ code: |
       end
 
       ##
-      # Returns an <img/> tag that embeds the given raw image data.
+      # Returns an image tag that embeds the given raw image data.
       #
       # [data]
       #   raw image data
@@ -195,7 +201,7 @@ code: |
       #   format of the image file (e.g. PNG, JPEG, GIF, etc.)
       #
       # [atts]
-      #   additional attributes for the <img> tag
+      #   additional attributes for the image tag
       #
       def embed_image_data data, format, atts = {}
         atts[:src] = ERBook.base_64_embed_image_data(data, format)
@@ -242,7 +248,7 @@ code: |
         # Returns the title of this node as XHTML.
         #
         def title_xhtml
-          title.to_s.to_inline_xhtml
+          title.to_s.to_xhtml
         end
 
         ##
@@ -253,10 +259,12 @@ code: |
         end
 
         ##
-        # Returns the content of this node as inline XHTML.
+        # Returns the result of wrapping
+        # this node's content in the given
+        # tag and converting it into XHTML.
         #
-        def content_inline_xhtml
-          content.join.to_inline_xhtml
+        def wrap_content_xhtml tag, atts = {}
+          %{<#{tag}#{atts.to_xml_atts}>#{content.join}</#{tag}>}.to_xhtml
         end
 
         ##
@@ -321,7 +329,7 @@ code: |
             %{<div class="tabs"><ul>} +
 
             pc.map do |c|
-              %{<li><a href="##{c.here_frag}">#{c.title.to_s.to_inline_xhtml}</a></li>}
+              %{<li><a href="##{c.here_frag}">#{c.title.to_s.to_xhtml}</a></li>}
             end.join +
 
             %{</ul>}
@@ -385,7 +393,7 @@ code: |
               [prefix, (%{"#{title}"} if label && title)].compact.join('. ')
             end
 
-          label_xhtml = (label || title).to_s.to_inline_xhtml
+          label_xhtml = (label || title).to_s.to_xhtml
 
           %{<a class="xref" href="##{here_frag}" title="#{::ERB::Util.h caption}">#{label_xhtml}</a>}
         end
@@ -429,17 +437,28 @@ code: |
 nodes:
   # theory
 
-    node: &wrapper
+    node: &node
       index:  false
+      chain:  false
       number: false
-      inline: true
       silent: false
+      inline: true
       output: <%= @node.content_xhtml %>
 
+    text: &text
+      <<: *node
+      inline: false
+      output: <%= @node.wrap_content_xhtml :pre %>
+
+    code:
+      <<: *text
+      params: language
+      output: <%= @node.wrap_content_xhtml :code, :lang => @node.language %>
+
   # structure
 
     header: &header
-      <<: *wrapper
+      <<: *node
       silent: true
 
     header_outside_above: &header_insert
@@ -460,7 +479,7 @@ nodes:
     footer_outside_below: *header_insert
 
     abstract:
-      <<: *wrapper
+      <<: *node
       output: |
         <div id="<%= @node.type_frag %>">
           <h1 class="title"><%= @node.type_label %></h1>
@@ -471,9 +490,10 @@ nodes:
 
     part: &latex
       index:  tree
+      chain:  true
       number: section
-      inline: false
       silent: false
+      inline: false
       params: [title, id]
       output: |
         <%= @node.parent_tabs_begin %>
@@ -521,11 +541,17 @@ nodes:
 
     float:
       index:  list
+      chain:  true
       number: ordinal
-      inline: false
       silent: false
+      inline: false
       params: [title, id, type]
       output: |
+        <%
+          if @node.type == 'command' and @node.title
+            @node.title = "<tt>#{verbatim @node.title}</tt>"
+          end
+        %>
         <%= @node.parent_tabs_begin %>
         <div class="<%= @node.type %>" id="<%= @node.here_frag %>">
           <%= @node.navigation %>
@@ -544,22 +570,20 @@ nodes:
   # tables
 
     table: &table
-      index: false
-      number: false
-      inline: true
-      silent: false
+      <<: *node
+      inline: false
       params: [xml_atts]
       output: |
-        <table border="1"<%=
+        <ins><table border="1"<%=
           (@node.xml_atts || {}).to_xml_atts
-        %>><%= @node.content_xhtml %></table>
+        %>><%= @node.content_xhtml %></table></ins>
 
     thead: &table_child
       <<: *table
       output: |
         <<%= @node.type %><%=
           (@node.xml_atts || {}).to_xml_atts
-        %>><%= @node.content_inline_xhtml %></<%= @node.type %>>
+        %>><%= @node.content_xhtml %></<%= @node.type %>>
 
     tbody:  *table_child
     tfoot:  *table_child
@@ -569,10 +593,7 @@ nodes:
 
   # cross-references
     xref:
-      index:  false
-      number: false
-      inline: true
-      silent: false
+      <<: *node
       params: [query, label]
       output: |
         <%=
@@ -591,16 +612,14 @@ nodes:
 
     reference: &reference
       index:  false
+      chain:  false
       number: ordinal
-      inline: false
       silent: true
+      inline: false
       params: [title, id]
 
     cite:
-      index:  false
-      number: false
-      inline: true
-      silent: false
+      <<: *node
       params: [target]
       output: |
         <%=
@@ -644,7 +663,7 @@ output: |
             (n.section_number.to_s + '&nbsp;&nbsp;' if n.section_number),
             n.list_frag,
             n.here_frag,
-            n.title.to_s.to_inline_xhtml
+            n.title.to_s.to_xhtml
           ]
 
           %{<li>#{entry}#{"<ul>#{nested}</ul>" if nested}</li>}
@@ -671,7 +690,7 @@ output: |
       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>}
+          %{<li><a id="#{n.list_frag}" href="##{n.here_frag}">#{n.title.to_s.to_xhtml}</a></li>}
         end.join
 
         label = ERBook::PHRASES[type.capitalize << 's']
@@ -681,8 +700,8 @@ output: |
         %{<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">
+  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml">
     <head>
       <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
@@ -694,7 +713,7 @@ output: |
       % if $title || $subtitle
         <title><%=
           [$title, $subtitle].compact.map do |t|
-            t.to_s.to_inline_xhtml
+            t.to_s.to_xhtml
           end.join(' &mdash; ')
         %></title>
 
@@ -722,36 +741,6 @@ output: |
 
           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>
 
@@ -789,11 +778,13 @@ output: |
       %>
 
       <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>
+        <%= ERBook::PHRASES['Loading...'] %> <noscript><%=
+          "<ins>%s</ins> <p>%s</p> %s" % [
+            ERBook::PHRASES['Failed!'],
+            ERBook::PHRASES['Please enable JavaScript in your Web browser.'],
+            text_only_browser_divider
+          ]
+        %></noscript>
       </div>
 
       <div id="__body__">
@@ -810,10 +801,10 @@ output: |
 
             <div class="title_and_subtitle">
               % if $title
-                <h1 class="title"><%= $title.to_s.to_inline_xhtml %></h1>
+                <h1 class="title"><%= $title.to_s.to_xhtml %></h1>
 
               % if $subtitle
-                <h2 class="subtitle"><%= $subtitle.to_s.to_inline_xhtml %></h2>
+                <h2 class="subtitle"><%= $subtitle.to_s.to_xhtml %></h2>
             </div>
 
             <div class="authors_and_date">
@@ -868,7 +859,7 @@ output: |
             <h1 style="display: none"><%= ERBook::PHRASES['Document'] %></h1>
             <ul>
               % @roots.select {|n| n.index_toc? }.each do |n|
-                <li><a href="#<%= n.here_frag %>"><%= n.title.to_s.to_inline_xhtml %></a></li>
+                <li><a href="#<%= n.here_frag %>"><%= n.title.to_s.to_xhtml %></a></li>
             </ul>
 
             %= @content
@@ -938,7 +929,7 @@ output: |
             <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>
+                  alt="Valid XHTML 1.0 Strict" 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"
@@ -1110,12 +1101,10 @@ javascript: |
         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) {
+        if (target.is(':hidden')) {
           var panels = target.parents('.ui-tabs > div:hidden').get().reverse();
 
           if (target_is_panel) {
@@ -1154,26 +1143,21 @@ javascript: |
           }
         }
 
-        var screen_before_scroll = $(window).scrollTop();
+        var scroll_offset = scroll_target.offset().top;
 
-        $('html, body').animate(
-          { scrollTop: Math.floor(scroll_target.offset().top) },
-          'slow', 'swing', function() {
-            var screen_after_scroll = $(window).scrollTop();
+        //
+        // set body height so that any element can be
+        // brought to the top of the screen via scrolling
+        //
+        var document_height = $(document).height();
+        var window_height   = $(window).height();
+        if (document_height - scroll_offset <= window_height) {
+          $('body').css('min-height', document_height + window_height);
+        }
 
+        $('html, body').animate(
+          { scrollTop: scroll_offset }, 'slow', 'swing', function() {
             set_hash(hash, target_is_panel);
-
-            if (
-              !target_initially_hidden &&
-              screen_after_scroll == screen_before_scroll
-            ) {
-              //
-              // nothing changed on the screen.
-              // the target was already visible.
-              // highlight it to notify the user.
-              //
-              target.effect('highlight', 'slow');
-            }
           }
         );
       }
@@ -1251,6 +1235,44 @@ javascript: |
       ).append(" <%= ERBook::PHRASES['Printer friendly'] %>")
     );
 
+    //
+    // activate embedded data URIs
+    //
+    var data_uri_by_embed_uri = <%=
+      result = {}
+      ICONS.each do |icon|
+        result[icon.embed_uri] = icon.data_uri
+      end
+
+      require 'json'
+      result.to_json
+    %>;
+
+    $('img[src]').each(function() {
+      var image = $(this);
+      var data_uri = data_uri_by_embed_uri[image.attr('src')];
+
+      if (data_uri) {
+        image.attr('src', data_uri);
+      }
+    });
+
+    $('style').each(function() {
+      var style = $(this);
+      var css = style.text();
+
+      if (css) {
+        for (var embed_uri in data_uri_by_embed_uri) {
+          var src = new RegExp('\\burl\\(' + embed_uri + '\\)', 'g');
+          var dst = 'url("' + data_uri_by_embed_uri[embed_uri] + '")';
+
+          css = css.replace(src, dst);
+        }
+
+        style.text(css);
+      }
+    });
+
     //
     // ready for action!
     //
@@ -1283,6 +1305,11 @@ styles: # these are SASS templates
     blockquote
       color: #333
       font-style: italic
+      background-image: <%= ICON_BY_NAME['quote'].data_css %>
+      background-repeat: no-repeat
+      margin-left: 0
+      padding-left: 65px
+      min-height: 50px
 
 
     hr
@@ -1301,12 +1328,11 @@ styles: # these are SASS templates
     code.para
       white-space: pre
 
-    ins > pre
-      text-decoration: none
 
+    // proper container (according to XHTML validation) for
+    // inserting block-level elements in arbitrary locations
     ins
-      // for IE only, because the above "ins > pre" does not work
-      .text-decoration: none
+      text-decoration: none
 
 
     a > img
@@ -1468,6 +1494,15 @@ styles: # these are SASS templates
       clear: both
 
 
+    .ui-widget
+      // prevent nested widgets from having larger fonts
+      font-size: 1em
+
+
+    .ui-tabs .ui-tabs-nav li.ui-tabs-selected a
+      cursor: pointer
+
+
     tt
       background-color: #F0F8FF
 
@@ -1517,16 +1552,17 @@ styles: # these are SASS templates
       &:visited
         color: #800080
 
+      // decorate external hyperlinks with a visual indicator
+      &[href]:not([href^="#"])
+        background: <%= ICON_BY_NAME['hyperlink'].data_css %>
+        background-position: center right
+        background-repeat: no-repeat
+        padding-right: 13px
+
 
     #__header__ >
       .logo
-        float: left
-        margin-right: 1em
-        margin-top: 0.25em
-
-        img
-          max-height: 4em
-          max-width: 4em
+        text-align: center
 
       .title_and_subtitle
         float: left
@@ -1565,12 +1601,22 @@ styles: # these are SASS templates
 
     .nav
       float: right
+      clear: right
 
-      > a > img
-        border-top: thick solid #FFFFFF
+      > a > img:hover
+        background-color: yellow
 
-        &:hover
-          border-top: thick solid #FA8072
+
+    // make navigation menu appear on the tab bar
+    .ui-tabs > .ui-tabs-panel > .nav
+      position: relative
+      margin-top: -3.375em
+      margin-right: -1em
+
+
+    // prevent tabs on tab bar from ovelapping with the above navigation menu
+    .ui-tabs > .ui-tabs-nav > li:last-child
+      margin-right: 9em
 
 
     #__nfo__ > table td:first-child, #__nfo__ > .validations