inochi 0.3.0 → 1.0.0

data/doc/intro.erb

@@ -1,15 +1,26 @@
-<% chapter "Introduction" do %>
-  <% project_summary do %>
-    **<%= $project %>** is an infrastructure for [RubyGems](http://www.rubygems.org)-based software projects that encourages good documentation and reduces programming effort by automating common tasks.
-  <% end %>
+%#--
+%# Copyright 2009 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
 
-  **<%= $project %>** is exciting because:
+% 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 infrastructure for [RubyGems](http://www.rubygems.org)-based software projects that encourages good documentation and reduces programming effort by automating common tasks.
+
+  <%= $project %> is exciting because:
 
   * It encourages good documentation:
+
     * Provides a comprehensive user manual that integrates release notes, setup and usage instructions, and more.
+
     * Automates the display of help, version, and usage information for your project's main executable.
 
   * It reduces programming effort:
+    * Makes it easy to <%= xref "Translate your project", "translate your project" %> into many languages.
     * Provides a single point of entry to your project's libraries.
     * Keeps your project's configuration in one place.
     * Parses command-line options using [the Trollop library](http://trollop.rubyforge.org).
@@ -18,7 +29,7 @@
     * Generates project scaffolds while merging changes from previous ones.
     * Provides Rake tasks for packaging, publishing, and announcing your project.
 
-  These features distinguish **<%= $project %>** from the competition:
+  These features distinguish <%= $project %> from the competition:
   * [hoe](http://seattlerb.rubyforge.org/hoe/)
   * [newgem](http://newgem.rubyforge.org)
   * [Mr Bones](http://codeforpeople.rubyforge.org/bones/)
@@ -27,25 +38,24 @@
   * [GemMake](https://simonmenke.github.com/gm/)
   * [SimpleGem](http://github.com/reagent/simple-gem/tree/master)
 
-  <% paragraph "Etymology" do %>
+  %|paragraph "Etymology"
     In the past, software development was thought to be like mathematical modeling or building construction:  the assembly of inanimate objects.  Nowadays, it is thought to be more like gardening: the cultivation of life!
 
     In this manner, I consider this project not as a generator of skeletons or as a builder of scaffolds, but as a *giver of life*.  That is why I named this project "inochi", the Japanese word for *life*.
 
     Happy cultivation!
-  <% end %>
 
-  <% section "Logistics" do %>
+  %|section "Logistics"
     * <%= 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 home](<%= $website %>) --- the **<%= $project %>** project home page.
+    * [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 author(s)" %>.
 
-    <% 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:
@@ -83,21 +93,17 @@
           </tr>
         </tbody>
       </table>
-    <% end %>
-  <% end %>
 
-  <% section "License" do %>
-    <%# include ../LICENSE #%>
-  <% end %>
+  %|section "License"
+    %< "../LICENSE"
+
+  %|section "Credits"  |n|
+    %= $logo = n.xref_link("![#{$project} logo](#{$program}.png)".to_inline_xhtml)
 
-  <% section "Credits" do %>
-    <%= $logo = "![project logo](#{$program}.png)".to_inline_xhtml %>
-    <%# include README #%>
+    %< "README"
 
-    **<%= $project %>** is made possible by
-    <%= xref "History", "contributions" %>
+    <%= $project %> is made possible by
+    %= xref "History", "contributions"
     from users like you:
 
-    * Florian Gilcher
-  <% end %>
-<% end %>
+    %< "../CREDITS"

data/doc/setup.erb

@@ -1,18 +1,22 @@
-<% chapter "Setup" do %>
-  <% section "Requirements" do %>
-    Your system needs the following software to run **<%= $project %>**.
+%#--
+%# Copyright 2009 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.6 or 1.8.7 is required.                                 |
-    | [RubyGems](http://rubygems.org) | Ruby packaging system     | Version 1.x.x is required.                                          |
+    | [RubyGems](http://rubygems.org) | Ruby packaging system     | Version 1.3.1 or newer is required.                                 |
     | [Lynx](http://lynx.isc.org)     | Text-mode web browser     | Version 2.8.6 or newer is required to convert HTML into plain text. |
-  <% end %>
 
-  <% section "Installation" do %>
-    You can install **<%= $project %>** by running this command:
+  %|section "Installation"
+    You can install <%= $project %> by running this command:
 
-        gem install -f <%= $program %>
+        gem install <%= $program %> --development
 
     To check whether the installation was sucessful, run this command:
 
@@ -24,21 +28,20 @@
 
     If you do not see such output, you may
     <%= xref "License", "ask the author(s)" %> for help.
-  <% end %>
 
-  <% section "Manifest" do %>
-    You will see the following items inside **<%= $project %>**'s installation
+  %|section "Manifest"
+    You will see the following items inside <%= $project %>'s installation
     directory, whose path you can determine by running this command:
 
         <%= $program %> --version
 
     * <tt>bin/</tt>
 
-      * <tt><%= $program %></tt> --- the main **<%= $project %>** executable.
+      * <tt><%= $program %></tt> --- the main <%= $project %> executable.
 
     * <tt>lib/</tt>
 
-      * <tt><%= $program %>.rb</tt> --- the main **<%= $project %>** library.
+      * <tt><%= $program %>.rb</tt> --- the main <%= $project %> library.
 
     * <tt>doc/</tt>
 
@@ -49,5 +52,3 @@
     * <tt>lang/</tt> --- translations of language phrases.
 
     * <tt>LICENSE</tt> --- copyright notice and legal conditions.
-  <% end %>
-<% end %>

data/doc/usage.erb

@@ -1,7 +1,13 @@
-<% yaml_addr = "http://yaml.kwiki.org/?YamlInFiveMinutes" %>
+%#--
+%# Copyright 2009 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
 
-<% part "Usage" do %>
-  <% section "Command-line interface" do %>
+% require 'inochi/util/tempdir'
+% yaml_addr = "http://yaml.kwiki.org/?YamlInFiveMinutes"
+
+%|part "Usage"
+  %|section "Command-line interface"
     When you run this command:
 
         <%= $program %> --help
@@ -10,7 +16,7 @@
 
     <pre><%= verbatim `ruby bin/#{$program} --help` %></pre>
 
-    <% tip "Merging files with **kdiff3**" do %>
+    %|tip "Merging files with **kdiff3**"
       Instead of merging files by hand, you can transfer wanted changes between files semi-automatically using [kdiff3](http://kdiff3.sourceforge.net).  Simply follow these instructions:
 
       1.  Create a file named <tt>merge2</tt> with the following content:
@@ -34,26 +40,23 @@
 
       3.  Place the file in a directory that is listed in your `PATH` environment variable.
 
-      4.  Run **<%= $project %>** like this:
+      4.  Run <%= $project %> like this:
 
               <%= $program %> -m merge2
 
           Now **kdiff3** will be invoked to help you transfer your changes.  When you are finished transferring changes, save the file and quit **kdiff3**.  If you do not want to transfer any changes, simply quit **kdiff3** _without_ saving the file.
-    <% end %>
-  <% end %>
 
-  <% section "Ruby library interface" do %>
-    The [`Inochi` module](api/Inochi.html) has several class methods which provide a common configuration for various aspects of your project.  These aspects, and their interactions with the `Inochi` module, are as follows:
-    * Your project's main library invokes the [`Inochi.init()` method](api/Inochi.html#init-class_method).
-    * Your project's main executable invokes the [`Inochi.main()` method](api/Inochi.html#main-class_method).
-    * Your project's <tt>Rakefile</tt> invokes the [`Inochi.rake()` method](api/Inochi.html#rake-class_method).
-    * Your project's user manual invokes the [`Inochi.book()` method](api/Inochi.html#book-class_method).
-  <% end %>
+  %|section "Ruby library interface"
+    The `Inochi` module has several class methods which provide a common configuration for various aspects of your project.  These aspects, and their interactions with the `Inochi` module, are as follows:
+    * Your project's main library invokes the `Inochi.init()` method.
+    * Your project's main executable invokes the `Inochi.main()` method.
+    * Your project's <tt>rakefile</tt> invokes the `Inochi.rake()` method.
+    * Your project's user manual invokes the `Inochi.book()` method.
 
-  <% section "Tutorial" do %>
-    This tutorial shows how **<%= $project %>** is used to manage a hypothetical `WordCount` project throughout the various stages of its life.
+  %|section "Tutorial"
+    This tutorial shows how <%= $project %> is used to manage a hypothetical `WordCount` project throughout the various stages of its life.
 
-    <% section "Have a brilliant idea" do %>
+    %|section "Have a brilliant idea"
       It is 4am on Sunday morning.  Unwilling to sleep, you have spent the past few hours programming obsessively..  Though your eyes grow heavy and your stomach churns from hunger, your mind charges forth with haste.
 
       > Push on! Keep on!
@@ -92,22 +95,12 @@
 
       You awaken that evening relaxed and refreshed.  A brilliant idea for a new project enters your mind:  the project will be a tool that counts the number of words in text file.  And, the project can be accessed from Ruby via the `WordCount` module.
 
-      *However*, you must go to work the next morning, so there isn't much time.  What can you do?  Let's see how **<%= $project %>** can help us meet this challenge.
-    <% end %>
-
-    <%
-      require 'tempfile'
-      tmp = Tempfile.new($project).path
-      File.delete tmp
-      mkdir_p tmp
+      *However*, you must go to work the next morning, so there isn't much time.  What can you do?  Let's see how <%= $project %> can help us meet this challenge.
 
-      begin
-        old = Dir.pwd
-        cd tmp
+    %|cd TempDir.new.path
+      % main_executable = 'bin/word_count'
 
-        main_executable = 'bin/word_count'
-    %>
-      <% section "Generate your project" do %>
+      %|section "Generate your project"
         Give life to your new project:
 
         <pre>
@@ -122,21 +115,19 @@
         <% cd "word_count" %>
         </pre>
 
-        <% paragraph "View Rake tasks" do %>
+        %|paragraph "View Rake tasks"
           <pre>
           # rake -T
           <%= verbatim `rake -T` %>
           </pre>
-        <% end %>
 
-        <% paragraph "Run unit tests" do %>
+        %|paragraph "Run unit tests"
           <pre>
           # rake test
           <%= verbatim `rake test` %>
           </pre>
-        <% end %>
 
-        <% paragraph "Run project executable" do %>
+        %|paragraph "Run project executable"
           <pre>
           <% command = main_executable %>
           # ruby <%= command %>
@@ -158,9 +149,8 @@
           # ruby <%= command %>
           <%= verbatim `ruby #{command}` %>
           </pre>
-        <% end %>
 
-        <% paragraph "Show user manual" do %>
+        %|paragraph "Show user manual"
           Build the user manual (please disregard any "unclosed span" warnings):
 
           <pre>
@@ -175,13 +165,11 @@
           </pre>
 
           The manual will now appear in your default web browser.
-        <% end %>
-      <% end %>
 
-      <% section "Configure your project" do %>
-        <%= xref "Ruby library interface" %> lists and documents the interactions between your project and **<%= $project %>**.  These points of interaction are illustrated in the following sections.
+      %|section "Configure your project"
+        <%= xref "Ruby library interface" %> lists and documents the interactions between your project and <%= $project %>.  These points of interaction are illustrated in the following sections.
 
-        <% section "Project information" do %>
+        %|section "Project information"
           <% license_file = 'LICENSE' %>
 
           Open the <tt><%= license_file %></tt> file, which contains the open source [ISC license](http://www.opensource.org/licenses/isc-license.txt) by default, and add a copyright notice with your name and (optional) email address:
@@ -197,31 +185,29 @@
           <code>
           <%= verbatim File.read(main_library) %>
           </code>
-        <% end %>
 
-        <% section "Project executable" do %>
+        %|section "Project executable"
           Open the <tt><%= main_executable %></tt> file and fill in the blanks:
 
           <code>
           <%= verbatim File.read(main_executable) %>
           </code>
-        <% end %>
 
-        <% section "Rake tasks" do %>
-          <% rake_file = 'Rakefile' %>
+        %|section "Rake tasks"
+          <% rake_file = 'rakefile' %>
 
           Open the <tt><%= rake_file %></tt> and fill in the blanks:
 
           <code>
           <%= verbatim File.read(rake_file) %>
           </code>
-        <% end %>
 
-        <% section "User manual" do %>
+        %|section "User manual"
           <%
             whole = 'doc/index.erb'
             parts = File.read(whole).
-              scan(/<%#\s*include\s+(\S+)/).flatten.map {|s| "doc/#{s}" }
+              scan(/^[[:blank:]]*%\+[[:blank:]]*(.*)\s*/).
+              flatten.map {|s| "doc/" + eval(s) }
 
             files = [whole, *parts]
           %>
@@ -230,15 +216,11 @@
 
           Open these source files and fill in the blanks:
 
-          <% files.each do |f| %>
-            <% paragraph "<tt>#{f}</tt>" do %>
+          %|files.each |f|
+            %|paragraph "<tt>#{f}</tt>"
               <code lang="rhtml"><%= verbatim File.read(f) %></code>
-            <% end %>
-          <% end %>
-        <% end %>
-      <% end %>
 
-      <% section "Implement your project" do %>
+      %|section "Implement your project"
         Add the following code to the bottom of <tt>lib/word_count.rb</tt>, the main project library:
 
         <code>
@@ -291,10 +273,10 @@
         end
         </code>
 
-        <% paragraph "Goodbye `$LOAD_PATH`, hello `require()`" do %>
-          Notice that, in the Ruby files that you modified so far, there were no `$LOAD_PATH` manipulations and no explicit `require()` statements to pull in the various parts of your project.  That is because **<%= $project %>** does this for you automatically.
+        %|paragraph "Goodbye `$LOAD_PATH`, hello `require()`"
+          Notice that, in the Ruby files that you modified so far, there were no `$LOAD_PATH` manipulations and no explicit `require()` statements to pull in the various parts of your project.  That is because <%= $project %> does this for you automatically.
 
-          Furthermore, you can always `require()` a sub-library anywhere in your project using its canonical path because **<%= $project %>** puts your main project libraries on the Ruby load path.
+          Furthermore, you can always `require()` a sub-library anywhere in your project using its canonical path because <%= $project %> puts your main project libraries on the Ruby load path.
 
           <% sub_library = 'word_count/odf/text' %>
 
@@ -305,19 +287,16 @@
           </code>
 
           Regardless of whether a sub-library is used within your project itself or from within an external application, we always `require()` the sub-library using the same canonical path.
-        <% end %>
-      <% end %>
 
-      <% section "Test your project" do %>
-        To reduce the amount of code you have to write, **<%= $project %>** defines the following convention for unit tests.
+      %|section "Test your project"
+        To reduce the amount of code you have to write, <%= $project %> defines the following convention for unit tests.
 
-        <% paragraph "Units and tests" do %>
+        %|paragraph "Units and tests"
           Every Ruby source file in your project's <tt>lib/</tt> directory is considered to be a **unit**.  Likewise, every Ruby source file in your project's <tt>test/</tt> is considered to be a **test**.
 
           As a result, your project's <tt>test/</tt> directory structure *mirrors* the structure of your project's <tt>lib/</tt> directory.  For example, if your project has a <tt>lib/foo/bar.rb</tt> unit, then <tt>test/foo/bar.rb</tt> would be its corresponding test.
-        <% end %>
 
-        <% paragraph "Test execution" do %>
+        %|paragraph "Test execution"
           <pre>rake test</pre>
 
           The above command begins the testing process, during which:
@@ -326,16 +305,13 @@
 
           * Before a test is executed, its corresponding unit is automatically loaded into the Ruby environment using `require()`.
 
-          As for the details of test execution:
-
-          * Tests are executed by the [minitest] library, which allows you to write unit tests in a combination of styles: traditional xUnit TDD, alternative rSpec BDD, and mock-based validation styles.
+          The details of test execution are left to the integration libraries specified by the `:test_with` parameter of the `Inochi.rake()` method.  Possible values for this parameter are:
 
-          * Within each test, test cases are executed in random order.  This is the default behavior of the [minitest] library.
+          % Dir[Inochi::INSTALL + '/lib/inochi/test/*.rb'].sort.each do |f|
+            * <tt><%= File.basename(f, '.rb') %></tt> ---
+              <%= File.read(f).scan(/^#(.*)/).join %>
 
-          [minitest]: http://rubyforge.org/projects/bfts/
-        <% end %>
-
-        <% paragraph "Helper libraries" do %>
+        %|paragraph "Helper libraries"
           Your project's main directory is added to Ruby's load path.  So if your tests have helper libraries stored in your project's <tt>test/</tt> directory, you can load them into your tests by adding a "test/" prefix.
 
           For example, if your <tt>test/foo/bar.rb</tt> test has a <tt>test/foo/qux.rb</tt> helper library, then you would write the following code inside the test to load the helper library:
@@ -343,18 +319,16 @@
           <code>
           require 'test/foo/qux'
           </code>
-        <% end %>
-      <% end %>
 
-      <% section "Translate your project" do %>
+      %|section "Translate your project"
         <% phrases_file = "<tt>lang/phrases.yaml</tt>" %>
 
-        Although English is the *lingua franca* of today, your project's users may prefer to interact with it in their native language.  **<%= $project %>** makes it easy to translate your project and also makes it easy for users to correct and contribute translations to your project.
+        Although English is the *lingua franca* of today, your project's users may prefer to interact with it in their native language.  <%= $project %> makes it easy to translate your project and also makes it easy for users to correct and contribute translations to your project.
 
-        <% section "Language phrases" do %>
-          **<%= $project %>** equips your project module with a `PHRASES` constant (see the [`Inochi::Phrases` class](api/Inochi/Phrases.html)) which provides access to translations of language phrases used in your project.
+        %|section "Language phrases"
+          <%= $project %> equips your project module with a `PHRASES` constant (see the `Inochi::Phrases` class) which provides access to translations of language phrases used in your project.
 
-          The [`Inochi::Phrases#[]` method](api/Inochi/Phrases.html#[]-instance_method) translates a given language phrase into the user's preferred language, which is automatically inferred from their environment, but may be explictly overridden by the user via the <tt>--locale</tt> option of <%= xref "Run project executable", "your project's main executable" %>:
+          The `Inochi::Phrases#[]` method translates a given language phrase into the user's preferred language, which is automatically inferred from their environment, but may be explictly overridden by the user via the <tt>--locale</tt> option of <%= xref "Run project executable", "your project's main executable" %>:
 
           <code>
           your_project::PHRASES['Have a nice day!']
@@ -367,16 +341,15 @@
           #=> 'No translation for this'
           </code>
 
-          <% paragraph "Parameterizing language phrases" do %>
+          %|paragraph "Parameterizing language phrases"
             Language phrases can be parameterized using [`printf` format placeholders](http://en.wikipedia.org/wiki/Printf#printf_format_placeholders) to ease translation:
 
             <code>
             your_project::PHRASES['Good afternoon, %s.', user_name]
             your_project::PHRASES['You are %d years old.', user_age]
             </code>
-          <% end %>
 
-          <% paragraph "Explicit translation into a language" do %>
+          %|paragraph "Explicit translation into a language"
             If a language phrase must be translated into a specific language, regardless of the user's preference, you can invoke the respective method (whose name is the same as the [ISO-639 language code](http://en.wikipedia.org/wiki/ISO_639) of the language into which you wish to translate) on your `PHRASES` object:
 
             <code>
@@ -386,10 +359,8 @@
             # explictly translate into French (fr)
             your_project::PHRASES.fr('Farewell %s!', user_name)
             </code>
-          <% end %>
-        <% end %>
 
-        <% section "Translation files" do %>
+        %|section "Translation files"
           Translation files are [YAML documents](<%= yaml_addr %>) that reside in your project's <tt>lang/</tt> directory.  They provide translations for <%= xref "Language phrases", "language phrases" %> used in your project.
 
           For example, suppose that your language phrases are written in English, the <tt>lang/es.yaml</tt> (Spanish) translation file would appear like this:
@@ -410,9 +381,8 @@
           On each line, the original language phrase (as used in your project) appears first, then a single semicolon (:), followed by the translation.
 
           Also, notice that if a language phrase contains a semicolon, then the entire phrase must be enclosed in quotation marks.  The same rule applies to its corresponding translation.
-        <% end %>
 
-        <% section "Extracting language phrases" do %>
+        %|section "Extracting language phrases"
           <pre>
           # rake lang:dump
           <%= verbatim `rake lang:dump` %>
@@ -420,48 +390,43 @@
 
           The above command exercises your project's code and extracts all *utilized* language phrases into the <%= phrases_file %> file.  Continue reading to learn how this is accomplished.
 
-          <% paragraph "Dynamic analysis" do %>
+          %|paragraph "Dynamic analysis"
             Because Ruby is a dynamically interpreted language, the easiest way to extract language phrases is to evaluate the code that defines them and keep track of which phrases are defined.
 
-            But how can **<%= $project %>** exercise all Ruby code in your project?  The answer is through *unit tests*.  Because unit tests already exercise your project's code, **<%= $project %>** can use them to reach and extract all language phrases from your project.
+            But how can <%= $project %> exercise all Ruby code in your project?  The answer is through *unit tests*.  Because unit tests already exercise your project's code, <%= $project %> can use them to reach and extract all language phrases from your project.
 
-            However, note that if your unit tests *do not* exercise a part of your project that defines language phrases, then those phrases *will not* be extracted by **<%= $project %>**.
+            However, note that if your unit tests *do not* exercise a part of your project that defines language phrases, then those phrases *will not* be extracted by <%= $project %>.
 
             This gives you extra motivation to improve the coverage of your test suite---at least to the point where all code that defines language phrases is covered.
-          <% end %>
 
-          <% paragraph "Static analysis" do %>
+          %|paragraph "Static analysis"
             In a future release, I plan to extract language phrases through static analysis of Ruby code.  This approach will supplement the current practice of reaching language phrases through unit tests.
 
             Patches are welcome! :-)
-          <% end %>
-        <% end %>
 
-        <% section "Translating language phrases" do %>
-          After you have extracted all language phrases from your project (either manually or via <%= xref "Extracting language phrases" %>) into the <%= phrases_file %> file, **<%= $project %>** can automatically translate them into various languages using the [Yahoo! BabelFish translation service](http://babelfish.yahoo.com):
+        %|section "Translating language phrases"
+          After you have extracted all language phrases from your project (either manually or via <%= xref "Extracting language phrases" %>) into the <%= phrases_file %> file, <%= $project %> can automatically translate them into various languages using the [Yahoo! BabelFish translation service](http://babelfish.yahoo.com):
 
           <pre>
           # rake lang:conv from=LANGUAGE_CODE
           <%= verbatim `rake lang:conv from=LANGUAGE_CODE 2>&1` %>
           </pre>
 
-          Notice that you must specify the language in which your phrases are written, via the <tt>from=</tt> parameter.  **<%= $project %>** cannot determine this automatically.
-        <% end %>
-      <% end %>
+          Notice that you must specify the language in which your phrases are written, via the <tt>from=</tt> parameter.  <%= $project %> cannot determine this automatically.
 
-      <% section "Publish your project" do %>
+      %|section "Publish your project"
         <pre>
         # rake pub
         </pre>
 
         The above command performs all automated steps described in the following sections.
 
-        <% section "Build a RubyGem" do %>
+        %|section "Build a RubyGem"
           Build a RubyGem by running:
 
           <pre>
-          # rake pak
-          <%= `rake pak` %>
+          # rake gem
+          <%= `rake gem` %>
           </pre>
 
           See the RubyGem contents:
@@ -470,20 +435,18 @@
           # gem spec pkg/*.gem
           <code lang="yaml"><%= `gem spec pkg/*.gem`.rstrip %></code>
           </pre>
-        <% end %>
 
-        <% section "Publish a RubyGem" do %>
-          You must first register your project on [RubyForge](http://rubyforge.org) before you can publish a RubyGem.  If your RubyForge project name is different from your actual project name, then you should pass the `:rubyforge_project` and `:rubyforge_section` options to the [`Inochi.rake()` method](api/Inochi.html#rake-class_method)).
+        %|section "Publish a RubyGem"
+          You must first register your project on [RubyForge](http://rubyforge.org) before you can publish a RubyGem.  If your RubyForge project name is different from your actual project name, then you should pass the `:rubyforge_project` and `:rubyforge_section` options to the `Inochi.rake()` method.
 
           Publish a RubyGem by running:
 
           <pre>
-          # rake pub:pak
+          # rake pub:gem
           </pre>
-        <% end %>
 
-        <% section "Announce a release" do %>
-          You must first provide your <%= xref "Login information" %> to **<%= $project %>**.  If you do not want to do this, then see <%= xref "Manual release announcement" %>.
+        %|section "Announce a release"
+          You must first provide your <%= xref "Login information" %> to <%= $project %>.  If you do not want to do this, then see <%= xref "Manual release announcement" %>.
 
           Announce a release by running:
 
@@ -491,12 +454,12 @@
           # rake pub:ann
           </pre>
 
-          <% paragraph "Login information" do %>
-            In order to automate the announcement of releases, **<%= $project %>** needs to know your login information for the [RAA (Ruby Application Archive)](http://raa.ruby-lang.org) and [RubyForum](http://www.ruby-forum.com/forum/4), which serves as a gateway to the [ruby-talk mailing list](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/).
+          %|paragraph "Login information"
+            In order to automate the announcement of releases, <%= $project %> needs to know your login information for the [RAA (Ruby Application Archive)](http://raa.ruby-lang.org) and [RubyForum](http://www.ruby-forum.com/forum/4), which serves as a gateway to the [ruby-talk mailing list](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/).
 
             <% logins_file = "~/.config/inochi/logins.yaml" %>
 
-            This information is expected to be stored in a <tt><%= logins_file %></tt> file (this location can be overridden by passing the `:logins_file` option to the [`Inochi.rake()` method](api/Inochi.html#rake-class_method)), where <tt>~</tt> denotes the path to your home directory.  This file is a [YAML document](<%= yaml_addr %>) containing the following parameters:
+            This information is expected to be stored in a <tt><%= logins_file %></tt> file (this location can be overridden by passing the `:logins_file` option to the `Inochi.rake()` method), where <tt>~</tt> denotes the path to your home directory.  This file is a [YAML document](<%= yaml_addr %>) containing the following parameters:
 
             <code lang="yaml">
             www.ruby-forum.com:
@@ -511,9 +474,7 @@
 
                 # chmod 0600 <%= logins_file %>
 
-          <% end %>
-
-          <% section "Manual release announcement" do %>
+          %|section "Manual release announcement"
             Build release announcements by running:
 
             <pre>
@@ -522,29 +483,17 @@
             </pre>
 
             This produces the following files in your project directory:
-            <% Dir['ANN*'].each do |f| %>
-            * <tt><%= f %></tt>
-            <% end %>
+
+            %|Dir['ANN*'].each |f|
+              * <tt><%= f %></tt>
 
             Now you can manually announce your release using these files.
-          <% end %>
-        <% end %>
 
-        <% section "Publish the documentation" do %>
+        %|section "Publish the documentation"
           Publish the user manual and API documentation by running:
 
           <pre>
           # rake pub:doc
           </pre>
 
-          If your documentation website (see the `:docsite` option for the [`Inochi.init()` method](api/Inochi.html#init-class_method)) is hosted on RubyForge, then the above command will automatically upload your project's documentation to the correct place.
-        <% end %>
-      <% end %>
-    <%
-      ensure
-        cd old
-        rm_rf tmp
-      end
-    %>
-  <% end %>
-<% end %>
+          If your documentation website (see the `:docsite` option for the `Inochi.init()` method) is hosted on RubyForge, then the above command will automatically upload your project's documentation to the correct place.