erbook 6.1.0 → 7.0.0

data/doc/intro.erb

@@ -1,35 +1,43 @@
-<% chapter "Introduction" do %>
-  <% eruby_url = "http://en.wikipedia.org/wiki/ERuby" %>
+%#--
+%# Copyright 2007 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
 
-  <% project_summary do %>
-    **<%= $project %>** is an extensible document processor that emits <%= xref "HelloWorld", "any document you can imagine" %> from [eRuby templates](<%= eruby_url %>) that allow scripting and dynamic content generation.
+% 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)'
+
+%|chapter "Introduction"
+  %|project
+    <%= $project %> is an extensible document processor that emits <%= xref "HelloWorld", "any document you can imagine" %> from [eRuby templates](<%= eruby_url %>) that 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" %>!
-  <% end %>
-
-  **<%= $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 300 lines of code.
-
-  These features distinguish **<%= $project %>** from the competition, which offers 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)
-
-  <% section "Logistics" do %>
-    * <%= xref "History", "Release notes" %> --- history of project releases.
-    * [Source code](http://github.com/sunaku/<%= $program %>) --- obtain via [Git](http://git.or.cz) or browse online.
-    * [API reference](api/index.html) --- documentation for source code.
+
+    <%= $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 300 lines of code.
+
+    These features distinguish <%= $project %> from the competition, which offers 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)
+
+    %|section "Logistics"
+      * <%= xref "History", "Release notes" %> --- 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" do %>
-      **<%= $project %>** releases are numbered in *major.minor.patch*
+    %|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:
@@ -67,27 +75,23 @@
           </tr>
         </tbody>
       </table>
-    <% end %>
-  <% end %>
 
-  <% section "License" do %>
-    <%# include ../LICENSE #%>
-  <% end %>
+  %|section "License"
+    %< "../LICENSE"
 
-  <% section "Credits" do |n| %>
-    <%= $logo = n.xref_link("![#{$project} logo](#{$program}.png)".to_inline_xhtml) %>
-    <%# include README #%>
+  %|section "Credits" |n|
+    %= $logo = n.xref_link("![#{$project} logo](#{$program}.png)".to_inline_xhtml)
+    %< "README"
 
-    **<%= $project %>** is made possible by
+    <%= $project %> is made possible by
     <%= xref "History", "contributions" %>
     from users like you:
 
     * Jens Vierbuchen
     * Maunika Gosike
     * [Zhang Chiyuan](http://lifegoo.pluskid.org)
-  <% end %>
 
-  <% section "Reviews" do %>
+  %|section "Reviews"
     Tom Cloyd in [ruby-talk](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/327499):
 
     > This documentation is simply gorgeous!
@@ -95,16 +99,14 @@
 
     Vitor Peres in [ruby-talk](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/283052):
 
-    > I actually felt like printing \[this manual], because it's just so well-thought typographically... Even if \[**<%= $project %>**] weren't great by itself, I'd feel good just looking at the manual.
+    > I actually felt like printing \[this manual], because it's just so well-thought typographically... Even if \[<%= $project %>] weren't great by itself, I'd feel good just looking at the manual.
 
 
     Ara T. Howard in [ruby-talk](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/282949):
 
-    > \[This manual is] a insanely complete and nice looking bit of documentation \[... **<%= $project %>**] looks like a great project
+    > \[This manual is] a insanely complete and nice looking bit of documentation \[... <%= $project %>] looks like a great project
 
 
     Martin DeMello in [ruby-talk](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/283304):
 
     > Very nice work indeed!
-  <% end %>
-<% end %>

data/doc/setup.erb

@@ -1,15 +1,19 @@
-<% chapter "Setup" do %>
-  <% section "Requirements" do %>
-    Your system needs the following software to run **<%= $project %>**.
+%#--
+%# Copyright 2007 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
+
+%|chapter "Setup"
+  %|section "Requirements"
+    Your system needs the following software to run <%= $project %>.
 
     | Software                        | Description               | Notes                               |
     | --------                        | -----------               | -----                               |
     | [Ruby](http://ruby-lang.org)    | Ruby language interpreter | Version 1.8.7 or newer is required. |
     | [RubyGems](http://rubygems.org) | Ruby packaging system     | Version 1.0.0 or newer is required. |
-  <% end %>
 
-  <% section "Installation" do %>
-    You can install **<%= $project %>** by running this command:
+  %|section "Installation"
+    You can install <%= $project %> by running this command:
 
         gem install <%= $program %>
 
@@ -22,41 +26,37 @@
     <pre><%= verbatim `ruby bin/#{$program} -v` %></pre>
 
     Otherwise, you can <%= xref "License", "contact the author" %> for help.
-  <% end %>
 
-  <% section "Manifest" do %>
-    You will see the following items inside **<%= $project %>**'s installation directory, whose path you can determine by running this command:
+  %|section "Manifest"
+    You will see the following items inside <%= $project %>'s installation directory, whose path you can determine by running this command:
 
         <%= $program %> -v
 
     * <tt>bin/</tt>
 
-      * <tt><%= $program %></tt> --- the main **<%= $project %>** executable.
+      * <tt><%= $program %></tt> --- the main <%= $project %> executable.
 
     * <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'] %>
-    <% end %>
+      %|ERBook::FORMAT_FILES.each do |file|
+        <%='  '%>* <tt><%= File.basename(file) %></tt> --- <%= YAML.load_file(file)['desc'] %>
 
     * <tt>lib/</tt>
 
-      * <tt><%= $program %>.rb</tt> --- the main **<%= $project %>** library.
+      * <tt><%= $program %>.rb</tt> --- the main <%= $project %> library.
 
       * <tt><%= $program %>/</tt>
 
-        * <tt>to_xhtml.rb</tt> --- provides methods (see <%= xref "Text to XHTML conversion" %>) for the <%= xref "xhtml" %> format.
+        * <tt>to_xhtml.rb</tt> --- implements <%= xref "Text to XHTML conversion" %> methods for the <%= xref "xhtml" %> format.
 
         * <tt>rdoc.rb</tt> --- provides RDoc parse trees to Ruby code.
 
     * <tt>doc/</tt> --- contains this manual and other documentation.
 
-      * <tt><%= $program %>.svg</tt> --- source file of the **<%= $project %>** logo.
+      * <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> --- project license and copyright notice.
-  <% end %>
-<% end %>

data/doc/theory.erb

@@ -1,27 +1,30 @@
-<% chapter "Theory of operation" do %>
+%#--
+%# Copyright 2007 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
+
+%|chapter "Theory of operation"
   When you run <%= $project %>, it does the following:
 
   1.  Loads the <%= xref "SpecFile", "format specification file" %>.
 
-  2.  Creates an **input document** by:
+  2.  Creates an *input document* by:
 
       * Reading the input (the content of either the input file or the standard input stream) into memory.
 
-      * Evaluating <%= xref "include", "include directives" %> in the input.
-
-  3.  Transforms the input document into a **processed document** by:
+  3.  Transforms the input document into a *processed document* by:
 
-      * Building a **document tree** data structure from <%= xref "Nodes", "nodes" %> present in the input document.
+      * Building a *document tree* data structure from <%= xref "Nodes", "nodes" %> present in the input document.
 
       * Replacing every node in the input document with the result of its <%= xref "SpecFile.nodes.output", "node output template" %>.
 
-  4.  Transforms the processed document into an **output document** according to the <%= xref "SpecFile.output", "document output template" %>.
+  4.  Transforms the processed document into an *output document* according to the <%= xref "SpecFile.output", "document output template" %>.
 
   5.  Prints the output document to the standard output stream.
 
-  Although there is only one document being processed here, we refer to it using three distinct terms: **input**, **processed**, and **output**; because the content of the document changes radically with every transformation.
+  Although there is only one document being processed here, we refer to it using three distinct terms: *input*, *processed*, and *output*; because the content of the document changes radically with every transformation.
 
-  <% section "Nodes" do %>
+  %|section "Nodes"
     A node is a block of text that appears like this:
 
         <%% node_type node_argument1, node_argument2, ... do |node_object| %>
@@ -65,7 +68,7 @@
 
     A <%= xref "SpecFile", "format specification file" %> defines what types of nodes an input document may use.
 
-    <% section "The `ERBook::Document::Node` class", "Node.class" do %>
+    %|section "The `ERBook::Document::Node` class", "Node.class"
       When <%= $project %> builds a document tree from the nodes in an input document, it stores information about these nodes into `ERBook::Document::Node` objects.  A `ERBook::Document::Node` object has the following properties (methods):
 
       | Property | Type                                | Description                                                                                                                                                |
@@ -83,10 +86,8 @@
       | children | `Array` of `ERBook::Document::Node` | List of child nodes from the document tree.                                                                                                                |
 
       Furthermore, the `ERBook::Document::Node` class is derived from [Ruby's `OpenStruct` class](http://www.ruby-doc.org/stdlib/libdoc/ostruct/rdoc/classes/OpenStruct.html), so you can define new properties for `ERBook::Document::Node` objects dynamically.
-    <% end %>
-  <% end %>
 
-  <% section "Format specification file", "SpecFile" do %>
+  %|section "Format specification file", "SpecFile"
     A format specification file is a plain-text file marked up in [YAML syntax](http://yaml4r.sourceforge.net/cookbook/). Through the following parameters, it defines (1) what types of nodes an input document may contain, (2) how the content of those nodes is transformed into output, and (3) how the processed document is transformed into the output document.
 
     | Parameter | Type     | Description                                                                                                                                                                                                                                        |
@@ -103,7 +104,7 @@
       common_template_vars = nil
     %>
 
-    <% section "Node definition", "SpecFile.nodes" do %>
+    %|section "Node definition", "SpecFile.nodes"
       A node definition is a mapping from a name (the "node type") to the following set of parameters:
 
       | Parameter | Type     | Description                                                                               |
@@ -113,10 +114,11 @@
       | silent    | Boolean  | Suppress the output of this node?                                                         |
       | output    | `String` | An eRuby template for the content of this node. See <%= xref "SpecFile.nodes.output" %>.  |
       | inline    | Boolean  | Is node's output an in-line string of text that can be embedded anywhere in the document? |
+      | bypass    | Boolean  | Is node simply a wrapper (of negligible depth) for content?                               |
 
       You may define additional parameters in a node definition if you want.
 
-      <% section "Node output template", "SpecFile.nodes.output" do %>
+      %|section "Node output template", "SpecFile.nodes.output"
         A node output template (the **output** parameter in a node definition) is an eRuby template that transforms a node's content into output.  During the processing stage, <%= $project %> replaces all nodes in the input document with the result of this template _unless_ the **silent** parameter is enabled in this node's definition.
 
         The following variables are available for use in this template:
@@ -138,10 +140,8 @@
         | `@format[:file]` | `String` | Path of the current format specification file. |
         }.lstrip.gsub(/^ +/, '')
         %>
-      <% end %>
-    <% end %>
 
-    <% section "Document output template", "SpecFile.output" do %>
+    %|section "Document output template", "SpecFile.output"
       A document output template (the **output** parameter in a format specification file) is an eRuby template that transforms a processed document into the final output document.
 
       The following variables are available for use in this template:
@@ -150,9 +150,8 @@
       | --------   | ----     | -----------                        |
       | `@content` | `String` | Content of the processed document. |
       <%= common_template_vars %>
-    <% end %>
 
-    <% section "Creating your own document format", "HelloWorld" do %>
+    %|section "Creating your own document format", "HelloWorld"
       Here is a working example to help you digest all that you've learned so far about format specification files. A few things to notice in this example are:
 
       * We define a `generate_name()` method in <%= xref "HelloWorld.spec" %> and make use of it in the <%= xref "HelloWorld.input" %>. This shows how to provide format-specific functionality to an input document.
@@ -171,17 +170,11 @@
 
       4.  Examine the <tt>HelloWorld.output</tt> file to your satisfaction!
 
-      <% example "HelloWorld format specification file", "HelloWorld.spec" do %>
+      %|example "HelloWorld format specification file", "HelloWorld.spec"
         <code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.spec') %></code>
-      <% end %>
 
-      <% example "Input document for HelloWorld format", "HelloWorld.input" do %>
+      %|example "Input document for HelloWorld format", "HelloWorld.input"
         <code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.input') %></code>
-      <% end %>
-
-      <% example "Output of HelloWorld format", "HelloWorld.output" do %>
-        <%= `ruby bin/#{PROGRAM} -u doc/HelloWorld.spec doc/HelloWorld.input` %>
-      <% end %>
-    <% end %>
-  <% end %>
-<% end %>
+
+      %|example "Output of HelloWorld format", "HelloWorld.output"
+        %= `ruby bin/#{PROGRAM} -u doc/HelloWorld.spec doc/HelloWorld.input`

data/doc/usage.erb

@@ -1,39 +1,29 @@
-<% chapter "Usage" do %>
-  <% section "Command-line interface" do %>
+%#--
+%# Copyright 2007 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
+
+%|chapter "Usage"
+  %|section "Command-line interface"
     <pre><%= `ruby bin/#{$program} -h` %></pre>
 
-    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).
+    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 "Manifest" %>).
 
-    <% section "Saving the output to a file" do %>
+    %|section "Saving the output to a file"
       Simply redirect the standard ouput stream (STDOUT) to a file like this:
 
           <%= $program %> > YOUR_PATH_HERE
 
       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>" do %>
+      %|important "Save XHTML output as <tt>.xhtml</tt>"
         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.
 
         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.
-      <% end %>
-    <% end %>
-  <% end %>
-
-  <% section "Including external documents", "include" do %>
-    The **include** directive allows you to insert the content of an arbitrary file at a certain place in the input document.  It is written like this:
-
-        <%%# include YOUR_PATH_HERE #%>
-
-    In the above example, *YOUR\_PATH\_HERE* is the path of the file whose content you wish to insert into the input document.
-
-    You can divide a large document into separate files for easier editing and stitch them together, dynamically, into a single document using the **include** directive.
-  <% end %>
 
-  <% section "Unindenting nodes hierarchically" do %>
-    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.
+  %|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.
 
-    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.
-  <% end %>
-<% end %>
+    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.icons/index.yaml

@@ -4,17 +4,19 @@
 # icon_name: relative path to the image file
 #
 
-important: tango-icon-theme-0.8.1/48x48/emblems/emblem-important.png
-
-warning: tango-icon-theme-0.8.1/48x48/status/dialog-error.png
-
-caution: tango-icon-theme-0.8.1/48x48/status/dialog-warning.png
-
-note: tango-icon-theme-0.8.1/48x48/apps/accessories-text-editor.png
-
-tip: tango-icon-theme-0.8.1/48x48/status/dialog-information.png
-
-quote: tango-icon-theme-0.8.1/48x48/apps/internet-group-chat.png
-
-link: mediawiki-1.13.2/skins/simple/external.png
-
+hyperlink:  mediawiki-1.13.2/skins/simple/external.png
+here_frag:  tango-icon-theme-0.8.90/16x16/places/start-here.png
+
+# admonitions
+important:  tango-icon-theme-0.8.90/48x48/emblems/emblem-important.png
+warning:    tango-icon-theme-0.8.90/48x48/status/dialog-error.png
+caution:    tango-icon-theme-0.8.90/48x48/status/dialog-warning.png
+note:       tango-icon-theme-0.8.90/48x48/apps/accessories-text-editor.png
+tip:        tango-icon-theme-0.8.90/48x48/status/dialog-information.png
+quote:      tango-icon-theme-0.8.90/48x48/apps/internet-group-chat.png
+
+# navigation menu on every heading
+nav_here:   tango-icon-theme-0.8.90/32x32/status/software-update-available.png
+nav_prev:   tango-icon-theme-0.8.90/32x32/actions/go-up.png
+nav_next:   tango-icon-theme-0.8.90/32x32/actions/go-down.png
+nav_list:   tango-icon-theme-0.8.90/32x32/places/start-here.png

data/fmt/xhtml.icons/rakefile

@@ -0,0 +1,33 @@
+#--
+# Copyright 2009 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
+require 'rake/clean'
+
+require 'yaml'
+INDEX = YAML.load_file('index.yaml')
+
+desc 'generate PNGs for tango icons from SVG sources'
+task :default
+
+INDEX.values.grep(/tango-icon-theme/).each do |dst|
+  sh 'git', 'add', dst
+
+  if dst =~ /(\d+)x\1/
+    size = $1
+    src = $` + 'scalable' + $'.ext('.svg')
+
+    file dst do
+      mkdir_p File.dirname(dst)
+      sh 'inkscape', '-e', dst, '-h', size, src
+
+      # ensure sources are in repository so everything
+      # works the next time this rake task is run
+      sh 'git', 'add', src
+    end
+    CLOBBER.include dst
+
+    task :default => dst
+  end
+end