erbook 7.1.0 → 7.1.1

data/doc/intro.erb

@@ -5,8 +5,8 @@
 
 % eruby_url = "http://en.wikipedia.org/wiki/ERuby"
 % api_url = './api/index.html'
-% repo_url = 'http://github.com/sunaku/' + $program
-% repo_scm = '[Git](http://git-scm.com)'
+% src_url = 'http://github.com/sunaku/' + $program
+% src_scm = '[Git](http://git-scm.com)'
 
 
 %|chapter "Introduction"
@@ -14,9 +14,16 @@
 
   %|project
 
-    <%= $project %> is an extensible document processor that emits <%= xref "HelloWorld", "any document you can imagine" %> from [eRuby templates](<%= eruby_url %>) which allow scripting and dynamic content generation.
+    <%= $project %> is an extensible document processor that emits <%= xref "HelloWorld", "any document you can imagine" %> from [eRuby templates](<%= eruby_url %>), which allow scripting and dynamic content generation.
 
-    A working <%= xref "xhtml", "XHTML (web page)" %> format is provided, while <%= xref "latex", "LaTeX (PDF)" %>, <%= xref "man", "UNIX manual page" %>, and <%= xref "text", "plain text" %> formats are planned... <%= xref "License", "patches are welcome" %>!
+
+  * <%= xref "History", "What's new?" %> --- history of project releases.
+  * [Source code](<%= src_url %>) --- obtain via <%= src_scm %> or browse online.
+  * [API reference](<%= api_url %>) --- documentation for source code.
+  * [Project home](<%= $website %>) --- the <%= $project %> project home page.
+
+  To get help or provide feedback, simply
+  <%= xref "License", "contact the author(s)" %>.
 
 
   %|section "Features"
@@ -24,68 +31,13 @@
     <%= $project %> is exciting because:
     * Its documents are scriptable [eRuby templates](<%= eruby_url %>).
     * It lets you <%= xref "HelloWorld", "define your own document formats" %>.
-    * Its core contains less than 400 lines of code.
+    * It emits beautiful <%= xref "xhtml", "XHTML (web page)" %> documents.
+    * It consists of a mere <%= `sloccount .`[/^Total.+=\s*(\d+)$/, 1] %> lines of code.
 
-    These features distinguish <%= $project %> from the competition, who offer neither scriptable documents nor definable document formats:
-    * [DocBook](http://www.docbook.org)
-    * [Deplate](http://deplate.sourceforge.net)
-    * [SiSU](http://www.jus.uio.no/sisu/SiSU/)
-    * [AsciiDoc](http://www.methods.co.nz/asciidoc/)
-    * [txt2tags](http://txt2tags.sourceforge.net)
-    * [Grutatxt](http://www.triptico.com/software/grutatxt.html)
 
+    %|note "More document formats are planned"
 
-  %|section "Logistics"
-
-    * <%= xref "History", "What's new?" %> --- history of project releases.
-    * [Source code](<%= repo_url %>) --- obtain via <%= repo_scm %> or browse online.
-    * [API reference](<%= api_url %>) --- documentation for source code.
-    * [Project home](<%= $website %>) --- the <%= $project %> project home page.
-
-    To get help or provide feedback, simply
-    <%= xref "License", "contact the authors" %>.
-
-
-    %|paragraph "Version numbers"
-
-      <%= $project %> releases are numbered in *major.minor.patch*
-      form according to the [RubyGems rational versioning
-      policy](http://www.rubygems.org/read/chapter/7), which
-      can be summarized thus:
-
-      <table markdown="1">
-        <thead>
-          <tr>
-            <td rowspan="2">What increased in the version number?</td>
-            <td colspan="3">The increase indicates that the release:</td>
-          </tr>
-          <tr>
-            <th>Is backward compatible?</th>
-            <th>Has new features?</th>
-            <th>Has bug fixes?</th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr>
-            <th>major</th>
-            <td style="background-color: #FFE4E1;">No</td>
-            <td>Yes</td>
-            <td>Yes</td>
-          </tr>
-          <tr>
-            <th>minor</th>
-            <td>Yes</td>
-            <td>Yes</td>
-            <td>Yes</td>
-          </tr>
-          <tr>
-            <th>patch</th>
-            <td>Yes</td>
-            <td style="background-color: #FFE4E1;">No</td>
-            <td>Yes</td>
-          </tr>
-        </tbody>
-      </table>
+      <%= xref "latex", "LaTeX (PDF)" %>, <%= xref "man", "UNIX manual page" %>, and <%= xref "text", "plain text" %> document formats are planned for future releases... <%= xref "License", "patches are welcome" %>!
 
 
   %|section "License"
@@ -100,7 +52,7 @@
     %< "README"
 
     <%= $project %> is made possible by
-    <%= xref "History", "contributions" %>
+    %= xref "History", "contributions"
     from users like you:
 
     %< "../CREDITS"
@@ -126,3 +78,16 @@
     Martin DeMello in [ruby-talk](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/283304):
 
     > Very nice work indeed!
+
+
+  %|section "Related works"
+
+    Note that, unlike <%= $project %>, these related works offer *neither* scriptable documents nor definable document formats.  I have yet to encounter another project that does.  If you happen to know, please enlighten me.
+
+    * [DocBook](http://www.docbook.org)
+    * [Deplate](http://deplate.sourceforge.net)
+    * [SiSU](http://www.jus.uio.no/sisu/SiSU/)
+    * [AsciiDoc](http://www.methods.co.nz/asciidoc/)
+    * [txt2tags](http://txt2tags.sourceforge.net)
+    * [Grutatxt](http://www.triptico.com/software/grutatxt.html)
+

data/doc/setup.erb

@@ -33,7 +33,7 @@
     Otherwise, you can <%= xref "License", "contact the author" %> for help.
 
 
-  %|section "Manifest"
+  %|section "Package contents"
 
     You will see the following items inside <%= $project %>'s installation directory, whose path you can determine by running this command:
 
@@ -46,7 +46,7 @@
     * <tt>fmt/</tt> --- contains the predefined set of <%= xref "SpecFile", "format specification files" %>. If you ever need to install your custom format specification file globally, then put it inside this directory.
 
       %|ERBook::FORMAT_FILES.each do |file|
-        <%='  '%>* <tt><%= File.basename(file) %></tt> --- <%= YAML.load_file(file)['desc'] %>
+        %= '  * <tt>%s</tt> --- %s' % [File.basename(file), YAML.load_file(file)['desc']]
 
     * <tt>lib/</tt>
 
@@ -67,3 +67,46 @@
       * <tt>api/</tt> --- API reference documentation.
 
     * <tt>LICENSE</tt> --- project license and copyright notice.
+
+
+  %|section "Version numbers"
+
+    <%= $project %> releases are numbered in *major.minor.patch*
+    form according to the [RubyGems rational versioning
+    policy](http://www.rubygems.org/read/chapter/7), which
+    can be summarized as follows:
+
+    <table markdown="1">
+      <thead>
+        <tr>
+          <td rowspan="2">What increased in the version number?</td>
+          <td colspan="3">The increase indicates that the release:</td>
+        </tr>
+        <tr>
+          <th>Is backward compatible?</th>
+          <th>Has new features?</th>
+          <th>Has bug fixes?</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <th>major</th>
+          <td style="background-color: #FFE4E1;">No</td>
+          <td>Yes</td>
+          <td>Yes</td>
+        </tr>
+        <tr>
+          <th>minor</th>
+          <td>Yes</td>
+          <td>Yes</td>
+          <td>Yes</td>
+        </tr>
+        <tr>
+          <th>patch</th>
+          <td>Yes</td>
+          <td style="background-color: #FFE4E1;">No</td>
+          <td>Yes</td>
+        </tr>
+      </tbody>
+    </table>
+

data/doc/usage.erb

@@ -12,7 +12,7 @@
 
     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).
 
-    Predefined formats are simply short-hand names of format specification files located in the <tt>fmt/</tt> subdirectory of the <%= $project %> installation directory (see <%= xref "Manifest" %>).
+    Predefined formats are simply short-hand names of format specification files located in the <tt>fmt/</tt> subdirectory of the <%= $project %> installation directory (see <%= xref "Package contents" %>).
 
 
     %|section "Saving the output to a file"
@@ -24,11 +24,13 @@
       In the above example, *YOUR\_PATH\_HERE* is the path of the file in which the output should be saved.
 
 
-      %|important "Save XHTML output as <tt>.xhtml</tt>"
+      %|important "Serve XHTML as HTML for Microsoft web browsers"
 
-        When you use the XHTML format, ensure that the file extension of your saved output document is either <tt>.xhtml</tt> or <tt>.xml</tt>. Alternatively, ensure that your saved output document is served to web browsers under the <tt>application/xhtml+xml</tt> mime type.
+        If you do not care whether people can read your XHTML documents using Microsoft web browsers, please disregard this message.  Otherwise, please heed the following instructions.
 
-        Otherwise, most web browsers _will not display_ the icons and graphics embedded in the saved XHTML output document because they will treat it as HTML instead of as XML.  See [this QuirksMode.org bug report](http://www.quirksmode.org/bugreports/archives/2005/02/custom_dtds_int_1.html) for details.
+        When you use the XHTML format, ensure that either (1) your saved output document is served to web browsers under the <tt>text/html</tt> mime type, or (2) the file extension of your saved output document is either <tt>.html</tt> or <tt>.htm</tt>.
+
+        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"
@@ -36,3 +38,4 @@
     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.
+

data/fmt/xhtml.yaml

@@ -119,28 +119,11 @@ code: |
         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.
+        # Returns an <img/> tag that renders an embedded data URI.
         #
         def to_xhtml atts = {}
           atts[:alt] ||= name
-          atts[:src] = entity_xml
+          atts[:src] = data_uri
           atts[:class] = :icon
           "<img#{atts.to_xml_atts}/>"
         end
@@ -338,10 +321,10 @@ code: |
         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;')
+        HERE_SIGN = ICON_BY_NAME['nav_here'].to_xhtml(:alt => HERE_TEXT)
+        PREV_SIGN = ICON_BY_NAME['nav_prev'].to_xhtml(:alt => PREV_TEXT)
+        NEXT_SIGN = ICON_BY_NAME['nav_next'].to_xhtml(:alt => NEXT_TEXT)
+        LIST_SIGN = ICON_BY_NAME['nav_list'].to_xhtml(:alt => LIST_TEXT)
 
         ##
         # Calculates a local navigation menu containing links
@@ -469,7 +452,7 @@ nodes:
       index: false
       number: false
       silent: true
-      bypass: true
+      bypass: false
       output: |
         <div id="<%= @node.type_frag %>">
           <%= @node.navigation %>
@@ -646,6 +629,8 @@ output: |
     $subtitle = '$subtitle' unless defined? $subtitle
     $authors  = {'$authors' => nil} unless defined? $authors
     $date     = Time.now.strftime("%d %B %Y") unless defined? $date
+    $logo     = nil unless defined? $logo
+    $feeds    = nil unless defined? $feeds
 
     abstract = @nodes_by_type['abstract'].first
 
@@ -700,14 +685,14 @@ output: |
       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 %>">
-  ]>
+  "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="application/xhtml+xml; charset=utf-8"/>
-      <meta name="generator" content="<%= ERBook::DISPLAY %>"/>
+      <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
+
+      <meta name="generator" content="<%=
+        [ERBook::DISPLAY, ERBook::WEBSITE].join(' &mdash; ')
+      %>"/>
 
       % if $title || $subtitle
         <title><%=
@@ -798,6 +783,10 @@ output: |
         %< File.join(JQUERY_DIR, 'jquery-ui-1.7.2.custom.min.js')
 
         $(function() {
+          /*
+          %< File.join(ERBook::INSTALL, 'LICENSE')
+          */
+
           //
           // respond to changes in window location
           //
@@ -822,6 +811,10 @@ output: |
           //  the element corresponding to the given hash.
           //
           function set_hash(hash, prevent_jump) {
+            if ($last_hash == hash) {
+              return;
+            }
+
             var set_the_hash = function() {
               //
               // XXX: bypass on_hash_change() by setting $last_hash
@@ -872,9 +865,11 @@ output: |
                 // temporarily place a dummy element at the current
                 // screen position and give it the ID of the target
                 //
+                var original_screen_position = $(window).scrollTop();
+
                 var dummy = $('<span/>').attr('id', target_id).css({
                   position: 'absolute',
-                  top:      $(window).scrollTop()
+                  top:      original_screen_position
                 });
 
                 target.removeAttr('id').before(dummy);
@@ -892,6 +887,12 @@ output: |
                 dummy.remove();
                 target.attr('id', target_id);
 
+                //
+                // the above approach does not work for Opera and IE.
+                // they ignore the dummy and jump to the actual target
+                //
+                $(window).scrollTop(original_screen_position);
+
                 return;
               }
             }
@@ -955,47 +956,35 @@ output: |
                 }
               }
 
-              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 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, body').animate(
+                { scrollTop: Math.floor(scroll_target.offset().top) },
+                'slow', 'swing', function() {
+                  var screen_after_scroll = $(window).scrollTop();
+
+                  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');
+                  }
                 }
-              }
-
-              scroll_to_target_and_set_hash();
+              );
             }
           }
 
@@ -1277,6 +1266,13 @@ styles: # these are SASS templates
     code.para
       white-space: pre
 
+    ins > pre
+      text-decoration: none
+
+    ins
+      // for IE only, because the above "ins > pre" does not work
+      .text-decoration: none
+
 
     a > img
       border: none

data/lib/erbook.rb

@@ -9,10 +9,10 @@ require 'inochi'
 
 Inochi.init :ERBook,
   :program => 'erbook',
-  :version => '7.1.0',
-  :release => '2009-08-30',
+  :version => '7.1.1',
+  :release => '2009-09-06',
   :website => 'http://snk.tuxfamily.org/lib/erbook/',
-  :tagline => 'Extensible document processor based on eRuby',
+  :tagline => 'Write books, manuals, and documents in eRuby',
   :require => {
     'ember'      => '~> 0',     # for eRuby template processing
     'maruku'     => '~> 0.5',   # for Markdown to XHTML conversion