inochi 1.0.0 → 1.1.0

data/doc/intro.erb

@@ -1,103 +1,67 @@
 %#--
-%# Copyright 2009 Suraj N. Kurapati
-%# See the LICENSE file for details.
+%# Copyright protects this work.
+%# See LICENSE file for details.
 %#++
 
 % 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)'
+% test_libs = Dir[Inochi::INSTALL + '/lib/inochi/test/*.rb']
+
 
 %|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:
+    <%= $project %> is an infrastructure for [RubyGems](http://www.rubygems.org)-based software that encourages good documentation, reduces programming effort, and automates common tasks.
+
+
+  * <%= 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"
 
-  * It encourages good documentation:
+    <%= $project %> is exciting because:
 
-    * Provides a comprehensive user manual that integrates release notes, setup and usage instructions, and more.
+    * 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.
 
-    * 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).
 
-  * 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).
+    * It automates common tasks:
+      * Generates project scaffolds while merging changes from previous ones.
+      * Provides Rake tasks for packaging, publishing, and announcing your project.
+      * Integrates with <%= xref "Test execution", "#{test_libs.length} different unit testing libraries" %> for your convenience.
 
-  * It automates common tasks:
-    * 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:
-  * [hoe](http://seattlerb.rubyforge.org/hoe/)
-  * [newgem](http://newgem.rubyforge.org)
-  * [Mr Bones](http://codeforpeople.rubyforge.org/bones/)
-  * [Gemify](http://gitorious.org/projects/gemify/)
-  * [Jeweler](http://technicalpickles.github.com/jeweler/)
-  * [GemMake](https://simonmenke.github.com/gm/)
-  * [SimpleGem](http://github.com/reagent/simple-gem/tree/master)
+  %|section "Etymology"
 
-  %|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!
 
-  %|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 author(s)" %>.
-
-    %|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>
 
   %|section "License"
+
     %< "../LICENSE"
 
-  %|section "Credits"  |n|
+
+  %|section "Credits" |n|
+
     %= $logo = n.xref_link("![#{$project} logo](#{$program}.png)".to_inline_xhtml)
 
     %< "README"
@@ -107,3 +71,17 @@
     from users like you:
 
     %< "../CREDITS"
+
+
+  %|section "Related works"
+
+    * [GemMake](https://simonmenke.github.com/gm/)
+    * [Gemify](http://gitorious.org/projects/gemify/)
+    * [Jeweler](http://technicalpickles.github.com/jeweler/)
+    * [Mr Bones](http://codeforpeople.rubyforge.org/bones/)
+    * [Reap](http://reap.rubyforge.org)
+    * [echoe](http://blog.evanweaver.com/files/doc/fauna/echoe/)
+    * [hoe](http://seattlerb.rubyforge.org/hoe/)
+    * [newgem](http://newgem.rubyforge.org)
+    * [simple-gem](http://sneaq.net/gems-simple)
+

data/doc/setup.erb

@@ -1,10 +1,14 @@
 %#--
-%# Copyright 2009 Suraj N. Kurapati
-%# See the LICENSE file for details.
+%# Copyright protects this work.
+%# See LICENSE file for details.
 %#++
 
+
 %|chapter "Setup"
+
+
   %|section "Requirements"
+
     Your system needs the following software to run <%= $project %>.
 
     | Software                        | Description               | Notes                                                               |
@@ -13,7 +17,9 @@
     | [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. |
 
+
   %|section "Installation"
+
     You can install <%= $project %> by running this command:
 
         gem install <%= $program %> --development
@@ -29,7 +35,9 @@
     If you do not see such output, you may
     <%= xref "License", "ask the author(s)" %> for help.
 
+
   %|section "Manifest"
+
     You will see the following items inside <%= $project %>'s installation
     directory, whose path you can determine by running this command:
 
@@ -52,3 +60,46 @@
     * <tt>lang/</tt> --- translations of language phrases.
 
     * <tt>LICENSE</tt> --- copyright notice and legal conditions.
+
+
+  %|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>
+

data/doc/usage.erb

@@ -1,13 +1,17 @@
 %#--
-%# Copyright 2009 Suraj N. Kurapati
-%# See the LICENSE file for details.
+%# Copyright protects this work.
+%# See LICENSE file for details.
 %#++
 
 % require 'inochi/util/tempdir'
 % yaml_addr = "http://yaml.kwiki.org/?YamlInFiveMinutes"
 
+
 %|part "Usage"
+
+
   %|section "Command-line interface"
+
     When you run this command:
 
         <%= $program %> --help
@@ -16,7 +20,9 @@
 
     <pre><%= verbatim `ruby bin/#{$program} --help` %></pre>
 
+
     %|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:
@@ -46,17 +52,23 @@
 
           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.
 
+
   %|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"
+
+  %|section "General walkthrough", "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"
+
       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!
@@ -97,60 +109,72 @@
 
       *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.
 
+
     %|cd TempDir.new.path
+
       % main_executable = 'bin/word_count'
 
+
       %|section "Generate your project"
+
         Give life to your new project:
 
         <pre>
         # inochi WordCount
-        <%= verbatim `ruby #{$install}/bin/inochi WordCount` %>
+        %= verbatim `ruby #{$install}/bin/inochi WordCount`
         </pre>
 
         Enter the <tt>word_count</tt> directory:
 
         <pre>
         # cd word_count
-        <% cd "word_count" %>
+        % cd "word_count"
         </pre>
 
+
         %|paragraph "View Rake tasks"
+
           <pre>
           # rake -T
-          <%= verbatim `rake -T` %>
+          %= verbatim `rake -T`
           </pre>
 
+
         %|paragraph "Run unit tests"
+
           <pre>
           # rake test
-          <%= verbatim `rake test` %>
+          %= verbatim `rake test`
           </pre>
 
+
         %|paragraph "Run project executable"
+
           <pre>
-          <% command = main_executable %>
+          % command = main_executable
           # ruby <%= command %>
-          <%= verbatim `ruby #{command}` %>
+          %= verbatim `ruby #{command}`
           </pre>
 
           See usage information:
 
           <pre>
-          <% command = "#{main_executable} --help" %>
+          % command = "#{main_executable} --help"
           # ruby <%= command %>
-          <%= verbatim `ruby #{command}` %>
+          %= verbatim `ruby #{command}`
           </pre>
 
           See project & version information:
 
           <pre>
-          <% command = "#{main_executable} --version" %>
+          % command = "#{main_executable} --version"
           # ruby <%= command %>
-          <%= verbatim `ruby #{command}` %>
+          %= verbatim `ruby #{command}`
           </pre>
 
+
         %|paragraph "Show user manual"
+
           Build the user manual (please disregard any "unclosed span" warnings):
 
           <pre>
@@ -160,49 +184,59 @@
           Launch the user manual:
 
           <pre>
-          <% command = "#{main_executable} --manual" %>
+          % command = "#{main_executable} --manual"
           # ruby <%= command %>
           </pre>
 
           The manual will now appear in your default web browser.
 
+
       %|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"
-          <% license_file = 'LICENSE' %>
+
+          % 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:
 
           <pre>
-          <%= verbatim File.read(license_file) %>
+          %= verbatim File.read(license_file)
           </pre>
 
-          <% main_library = 'lib/word_count.rb' %>
+          % main_library = 'lib/word_count.rb'
 
           Open the main project library file <tt><%= main_library %></tt> and fill in the blanks:
 
           <code>
-          <%= verbatim File.read(main_library) %>
+          %= verbatim File.read(main_library)
           </code>
 
+
         %|section "Project executable"
+
           Open the <tt><%= main_executable %></tt> file and fill in the blanks:
 
           <code>
-          <%= verbatim File.read(main_executable) %>
+          %= verbatim File.read(main_executable)
           </code>
 
+
         %|section "Rake tasks"
-          <% rake_file = 'rakefile' %>
+
+          % rake_file = 'rakefile'
 
           Open the <tt><%= rake_file %></tt> and fill in the blanks:
 
           <code>
-          <%= verbatim File.read(rake_file) %>
+          %= verbatim File.read(rake_file)
           </code>
 
+
         %|section "User manual"
+
           <%
             whole = 'doc/index.erb'
             parts = File.read(whole).
@@ -212,15 +246,18 @@
             files = [whole, *parts]
           %>
 
-          The user manual's source file <tt><%= whole %></tt> subdivides its content into several smaller files, according to topic, for easier editing and maintenance.  These files are processed by the [<%= ERBook::PROJECT %>](<%= ERBook::WEBSITE %>) program's [XHTML format](<%= ERBook::DOCSITE %>#xhtml) to produce the <tt>doc/index.xhtml</tt> file.
+          The user manual's source file <tt><%= whole %></tt> subdivides its content into several smaller files, according to topic, for easier editing and maintenance.  These files are processed by the [<%= ERBook::PROJECT %>](<%= ERBook::WEBSITE %>) program's [XHTML format](<%= ERBook::DOCSITE %>#xhtml) to produce the <tt>doc/index.html</tt> file.
 
           Open these source files and fill in the blanks:
 
+
           %|files.each |f|
             %|paragraph "<tt>#{f}</tt>"
               <code lang="rhtml"><%= verbatim File.read(f) %></code>
 
+
       %|section "Implement your project"
+
         Add the following code to the bottom of <tt>lib/word_count.rb</tt>, the main project library:
 
         <code>
@@ -273,12 +310,14 @@
         end
         </code>
 
+
         %|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.
 
-          <% sub_library = 'word_count/odf/text' %>
+          % sub_library = 'word_count/odf/text'
 
           For example, if your project has a sub-library, say, <tt>lib/<%= sub_library %>.rb</tt> that counts the number of words in an [OpenDocument Text](http://en.wikipedia.org/wiki/OpenDocument) document, then it would be loaded into the main project executable like this:
 
@@ -288,15 +327,21 @@
 
           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.
 
+
       %|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"
+
           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.
 
+
         %|paragraph "Test execution"
+
           <pre>rake test</pre>
 
           The above command begins the testing process, during which:
@@ -307,11 +352,13 @@
 
           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:
 
-          % Dir[Inochi::INSTALL + '/lib/inochi/test/*.rb'].sort.each do |f|
+          % test_libs.sort.each do |f|
             * <tt><%= File.basename(f, '.rb') %></tt> ---
-              <%= File.read(f).scan(/^#(.*)/).join %>
+              %= File.read(f).scan(/^#(.*)/).join
+
 
         %|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:
@@ -320,12 +367,16 @@
           require 'test/foo/qux'
           </code>
 
+
       %|section "Translate your project"
-        <% phrases_file = "<tt>lang/phrases.yaml</tt>" %>
+
+        % 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.
 
+
         %|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 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" %>:
@@ -341,7 +392,9 @@
           #=> 'No translation for this'
           </code>
 
+
           %|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>
@@ -349,7 +402,9 @@
             your_project::PHRASES['You are %d years old.', user_age]
             </code>
 
+
           %|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>
@@ -360,7 +415,9 @@
             your_project::PHRASES.fr('Farewell %s!', user_name)
             </code>
 
+
         %|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:
@@ -382,15 +439,19 @@
 
           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.
 
+
         %|section "Extracting language phrases"
+
           <pre>
           # rake lang:dump
-          <%= verbatim `rake lang:dump` %>
+          %= verbatim `rake lang:dump`
           </pre>
 
           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"
+
             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.
@@ -399,44 +460,89 @@
 
             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.
 
+
           %|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! :-)
 
+
         %|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` %>
+          %= 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.
 
+
       %|section "Publish your project"
+
         <pre>
         # rake pub
         </pre>
 
         The above command performs all automated steps described in the following sections.
 
+
         %|section "Build a RubyGem"
+
           Build a RubyGem by running:
 
           <pre>
           # rake gem
-          <%= `rake gem` %>
+          <%=
+            # prevent Maruku errors about blanks (__________) in the
+            # scaffold-generated documentation for this dummy project
+            Dir['doc/*.erb'].each do |doc|
+              File.open(doc, 'r+') do |f|
+                old = f.read
+                new = old.gsub('__________', '')
+
+                f.rewind
+                f.write new
+              end
+            end
+
+            # remove TODO and FIXME words (which come
+            # from the scaffold-generated output for
+            # this dummy project)from the gem spec
+            # that RubyGems does not reject it
+            File.open('rakefile', 'r+') do |f|
+              old = f.read
+              new = old.sub(/^Inochi.rake.*$/) do |header|
+                header + %q{
+                  [:summary, :description].each do |field|
+                    old = gem.send(field)
+                    new = old.gsub(/\b(TODO|FIXME)\b/o, '')
+
+                    gem.send("#{field}=", new)
+                  end
+                }
+              end
+
+              f.rewind
+              f.write new
+            end
+
+            `rake gem`
+          %>
           </pre>
 
           See the RubyGem contents:
 
-          <pre>
+          <code lang="yaml">
           # gem spec pkg/*.gem
-          <code lang="yaml"><%= `gem spec pkg/*.gem`.rstrip %></code>
-          </pre>
+          %= `gem spec pkg/*.gem`.rstrip
+          </code>
+
 
         %|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:
@@ -445,7 +551,9 @@
           # rake pub:gem
           </pre>
 
+
         %|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:
@@ -454,10 +562,12 @@
           # rake pub:ann
           </pre>
 
+
           %|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" %>
+            % 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), where <tt>~</tt> denotes the path to your home directory.  This file is a [YAML document](<%= yaml_addr %>) containing the following parameters:
 
@@ -474,12 +584,14 @@
 
                 # chmod 0600 <%= logins_file %>
 
+
           %|section "Manual release announcement"
+
             Build release announcements by running:
 
             <pre>
             # rake ann
-            <%= `rake ann` %>
+            %= `rake ann`
             </pre>
 
             This produces the following files in your project directory:
@@ -489,7 +601,9 @@
 
             Now you can manually announce your release using these files.
 
+
         %|section "Publish the documentation"
+
           Publish the user manual and API documentation by running:
 
           <pre>
@@ -497,3 +611,31 @@
           </pre>
 
           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.
+
+
+  %|section "Specific topics"
+
+
+    %|section "Build a RubyGem without #{$project} as runtime dependency"
+
+      <%= $project %> adds itself as a runtime dependency to your project's gem, by default, because it assumes that you want to use its runtime convenience facilities in your project.
+
+      However, if you only wish to use <%= $project %>'s gem building facilities and your project has no use for its runtime convenience facilities, then you can build your project's gem without <%= $project %> as a runtime dependency as follows.
+
+      1.  Create your project's <tt>rakefile</tt> with the following structure and fill in the blanks:
+
+          <code>
+      require 'rubygems'
+      require 'inochi'
+
+      Inochi.init __________
+
+      Inochi.rake __________, :inochi_consumer => false
+      </code>
+
+          Notice the `:inochi_consumer => false` parameter being passed to  `Inochi.rake()`.  This is what tells <%= $project %> not to add itself as a runtime dependency to your project's gem.
+
+      2.  Build your project's gem <%= xref "Build a RubyGem", "as you normally would" %>.
+
+      Now your project uses <%= $project %> *only* when building its gem and contains <%= $project %>-related code *only* in its <tt>rakefile</tt>.  The remainder of your project is isolated from, and has no knowledge of, <%= $project %>.
+