rumai 2.0.2 → 2.1.0

data/doc/intro.erb

@@ -1,41 +1,47 @@
-<% chapter "Introduction" do %>
-  <% project_summary do %>
-    **<%= $project %>** is a [Ruby](<%= ruby_url %>) interface to the [wmii](<%= wmii_url %>) window manager.
-  <% end %>
+%#--
+%# Copyright 2008 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
 
-  **<%= $project %>** is exciting because:
-  * It excels at *dynamic arrangement* of clients, columns, views, and tags.
-  * It provides an <%= xref 'shell', 'interactive shell' %> for live entertainment.
-  * It contains a *pure Ruby client* for the [9P2000 protocol](<%= p9p_url %>) on which wmii's [IXP file-system interface](<%= wmii_ixp_url %>) is built.
+% api_url = './api/index.html'
+% repo_url = 'http://github.com/sunaku/' + $program
+% repo_scm = '[Git](http://git-scm.com)'
 
-  These features distinguish **<%= $project %>** from the competition:
+%|chapter "Introduction"
+  %|project
+    <%= $project %> is a [Ruby](<%= ruby_url %>) interface to the [wmii](<%= wmii_url %>) window manager.
+    * It excels at dynamic arrangement of clients, columns, views, and tags.
+    * It provides an <%= xref 'shell', 'interactive shell' %> for live entertainment.
+    * It contains a pure Ruby client for the [9P2000 protocol](<%= p9p_url %>) on which wmii's [IXP file-system interface](<%= wmii_ixp_url %>) is built.
+
+  These features distinguish <%= $project %> from the competition:
+  * [r9p](http://libs.suckless.org/r9p)
+  * [Rii](http://rubyforge.org/projects/rii/)
+  * [Ruby-IXP](http://home.gna.org/rubyixp/)
   * [ruby-wmii](http://eigenclass.org/hiki.rb?wmii+ruby)
-  * [Rii](http://)
-  * [Ruby-IXP](http://)
 
-  <% paragraph "Etymology" do %>
+  %|paragraph "Etymology"
     The word "wmii" is incredibly difficult to pronounce because it is an abbreviation, not an acronym.  If we were to treat it as an acronym, the closest pronounciation would be, in my mind, something like "vim-eye".
 
     Since this is a Ruby library, I added a "roo" and worked it through:
 
-        vim-eye
-        roo-vim-eye
-        roovm-eye
-        roo-mai
+    * vim-eye
+    * roo-vim-eye
+    * roovm-eye
 
     And thus we get "Rumai".
-  <% 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.
+    * [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:
@@ -73,18 +79,13 @@
           </tr>
         </tbody>
       </table>
-    <% end %>
-  <% end %>
 
-  <% section "License" do %>
-    <%# include ../LICENSE #%>
-  <% end %>
+  %|section "License"
+    %< "../LICENSE"
 
-  <% section "Credits" do %>
-    **<%= $project %>** is made possible by
+  %|section "Credits"
+    <%= $project %> is made possible by
     <%= xref "History", "contributions" %>
     from users like you:
 
-    * [Simon Hafner](http://github.com/Tass)
-  <% end %>
-<% end %>
+    %< "../CREDITS"

data/doc/setup.erb

@@ -1,16 +1,20 @@
-<% chapter "Setup" do %>
-  <% section "Requirements" do %>
-    Your system needs the following software to run **<%= $project %>**.
+%#--
+%# Copyright 2008 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 newer is required. |
     | [RubyGems](http://rubygems.org) | Ruby packaging system     | Version 1.3.1 or newer is required. |
     | [wmii](<%= wmii_url %>)         | Window manager            | Version 3.6 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 %>
 
@@ -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><%= $program %>/</tt>
 
@@ -51,5 +54,3 @@
       * <tt>index.erb</tt> --- source of this user manual.
 
     * <tt>LICENSE</tt> --- copyright notice and legal conditions.
-  <% end %>
-<% end %>

data/doc/usage.erb

@@ -1,21 +1,32 @@
-<% chapter "Usage" do %>
-  <% section "Concepts" do %>
-    If you wish to wield the power of **<%= $project %>** more effectively, you should understand the following basic concepts:
+%#--
+%# Copyright 2008 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
 
-    * A *client* is any graphical program that is running in your X session.  In other words, any *window* in your wmii session is a *client*.
+%|chapter "Usage"
+  %|section "Concepts"
+    Client
+    : Any graphical program (a "window") that is running in your X session.
 
-    * A *tag* is an arbitrary string (a label) that can be associated with one or more clients.
+    Tag
+    : An arbitrary label that can be associated with one or more clients.
 
-    * A *view* is a graphical representation of a *tag*.  It shows all clients associated with a particular tag.
+    View
+    : A visualization of a particular tag.  A "workspace".
 
-    * An *area* is a region inside a *view*. It contains clients.
+    Area
+    : A region inside a view.  It can contain clients.
 
-      * A *managed area* or *column* is a region where clients cannot overlap each other.
+    Managed area, column
+    : An area whose clients cannot overlap each other.
 
-      * The *floating area* is an area whose clients (1) can overlap each other and (2) _float above_ the managed areas.
-  <% end %>
+    Floating area
+    : An area whose clients:
 
-  <% section "Command-line interface" do %>
+        * can overlap each other
+        * float above clients in the managed areas
+
+  %|section "Command-line interface"
     When you run this command:
 
         <%= $program %> --help
@@ -24,7 +35,7 @@
 
     <pre><%= verbatim `ruby bin/#{$program} --help` %></pre>
 
-    <% paragraph "Interactive shell", "shell" do %>
+    %|paragraph "Interactive shell", "shell"
       When you run this command:
 
           <%= $program %>
@@ -38,15 +49,14 @@
       For example, to get the current client object, you can type `curr_client` instead of having to type `Rumai.curr_client` at the prompt.  Both commands achieve the same effect.
 
       The next thing to note is that **tab completion** is enabled by default. So you can type part of a command and press the TAB key to see a list of possible completions.
-    <% end %>
-  <% end %>
 
-  <% section "Tutorial" do %>
-    Now that you know <%= xref "shell", "how to start the interactive shell" %>, let us walk through a quick demonstration that highlights the main features of **<%= $project %>**.  You can follow along by copying & pasting the presented commands into the interactive shell.
+  %|section "Tutorial"
+    Now that you know <%= xref "shell", "how to start the interactive shell" %>, let us walk through a quick demonstration that highlights the main features of <%= $project %>.  You can follow along by copying & pasting the presented commands into the interactive shell.
 
     <%
       open_terms = %q{
         Launch a few terminals so that we have something to work with:
+
         <code>
         colors = %w[ red green blue black orange brown gray navy gold ]
         colors.each {|c| system "xterm -bg #{c} -title #{c} -e read &" }
@@ -55,6 +65,7 @@
 
       close_terms = %q{
         Close the terminals we launched earlier:
+
         <code>
         terms = curr_view.clients.select {|c| colors.include? c.label.read }
         terms.each {|c| c.kill }
@@ -62,37 +73,41 @@
       }.gsub(/^\s+/, '')
     %>
 
-    <% section "Automated client arrangement" do %>
+    %|section "Automated client arrangement"
       <%= open_terms %>
 
       Arrange all clients in a grid:
+
       <code>
       curr_view.arrange_in_grid
       </code>
 
       Arrange all clients in a diamond shape:
+
       <code>
       curr_view.arrange_in_diamond
       </code>
 
       Arrange all clients like LarsWM does:
+
       <code>
       curr_view.arrange_as_larswm
       </code>
 
       <%= close_terms %>
-    <% end %>
 
-    <% section "Multiple client grouping" do %>
+    %|section "Multiple client grouping"
       <%= open_terms %>
 
       Add the red, green, and blue terminals into the "grouping":
+
       <code>
       terms = curr_view.clients.select {|c| %w[red green blue].include? c.label.read }
       terms.each {|c| c.group }
       </code>
 
-      You should now see a new button labelled as "<notextile>@</notextile>" on the left-hand side of wmii's bar, indicating that there is now a new view labelled "<notextile>@</notextile>" in wmii. Let us inspect what clients this mysterious view contains:
+      You should now see a new button labelled as "@" on the left-hand side of wmii's bar, indicating that there is now a new view labelled "@" in wmii. Let us inspect what clients this mysterious view contains:
+
       <code>
       v = View.new "@"
       puts v.clients.map {|c| c.label.read }
@@ -101,11 +116,13 @@
       Aha! The mysterious view contains the red, green, and blue clients we recently "grouped". Thus, by adding a client to the "grouping", we are simply tagging the client with the "@" token.
 
       Now that we have put some clients into the "grouping", let us move all clients in the grouping to the floating area in the current view:
+
       <code>
       grouping.each {|c| c.send "toggle" }
       </code>
 
       Neat! Let us bring them back into the managed area:
+
       <code>
       grouping.each {|c| c.send "toggle" }
       </code>
@@ -115,24 +132,26 @@
       In summary, you can select multiple clients (by adding them to the "grouping") and perform operations on them. This is useful when you want to do something with a group of clients but do not want to manually focus one, perform the action, focus the next one, and so on.
 
       Another important aspect is that selected clients stay selected until they are unselected. This allows you to continue performing tasks on the selection without having to reselect the same clients after every operation.
-    <% end %>
 
-    <% section "Easy column manipulation" do %>
+    %|section "Easy column manipulation"
       <%= open_terms %>
 
       You can insert a group of clients to the top, bottom, or after the currently focused client of _any_ column using Array-like methods.
 
       Give each client its own column (one client per column):
+
       <code>
       curr_view.each_column {|c| c.length = 1 }
       </code>
 
       Put (at most) three clients in every column:
+
       <code>
       curr_view.each_column {|c| c.length = 3 }
       </code>
 
       Move the red, green, and blue clients into the floating area:
+
       <code>
       rgb = %w[red green blue]
       terms = curr_view.clients.select {|c| rgb.include? c.label.read }
@@ -140,6 +159,7 @@
       </code>
 
       Slurp all floating clients into the last column:
+
       <code>
       list = curr_view.areas
       a, b = list.first, list.last
@@ -147,59 +167,69 @@
       </code>
 
       Set the last column's layout to stacking mode:
+
       <code>
       b.layout = 'stack'
       </code>
 
       Move the red, green, and blue clients to the top of the second column:
+
       <code>
       curr_view.areas[2].unshift terms
       </code>
 
       Move the red, green, and blue clients to the bottom of the third column:
+
       <code>
       curr_view.areas[3].push terms
       </code>
 
       <%= close_terms %>
-    <% end %>
 
-    <% section "Easy client manipulation" do %>
+    %|section "Easy client manipulation"
       <%= open_terms %>
 
       Obtain a reference to the red client:
+
       <code>
       red = curr_view.clients.find {|c| c.label.read == "red" }
       </code>
 
       Show the red client's current tags:
+
       <code>
       red.tags
       </code>
 
       Add the "foo" and "bar" tags to the red client:
+
       <code>
       red.tag "foo", "bar"
       </code>
 
       Remove the "bar" tag from the red client:
+
       <code>
       red.untag "bar"
       </code>
 
       Do complex operations on the red client's tags:
+
       <code>
       red.with_tags { concat %w[a b c]; push 'z'; delete 'c' }
       </code>
 
       Focus the next client after the red client:
+
       <code>
-      red.next.focus ; curr_client == red.next #=> true
+      red.next.focus
+      curr_client == red.next #=> true
       </code>
 
       Notice that by focusing a client, we make it the current client.
 
       Focus the red client on a different view:
+
       <code>
       orig = curr_view
       v = red.views.last
@@ -207,40 +237,46 @@
       </code>
 
       Return to the original view:
+
       <code>
       orig.focus
       </code>
 
       Send the red client to the last column:
+
       <code>
       red.send curr_view.areas.last
       </code>
 
       <%= close_terms %>
-    <% end %>
 
-    <% section "Traversing the file system" do %>
+    %|section "Traversing the file system"
       Show the root node of wmii's IXP file system:
+
       <code>
       fs
       </code>
 
       Show the names of all files at the root level:
+
       <code>
       fs.entries
       </code>
 
       Show the parent of the root node:
+
       <code>
       fs.parent
       </code>
 
       Show the children of the root node:
+
       <code>
       fs.children
       </code>
 
       Navigate into to the <tt>/lbar/</tt> directory:
+
       <code>
       n1 = fs.lbar
       n2 = fs['lbar']
@@ -251,6 +287,7 @@
       Notice that you can traverse the file system hierarchy by simply calling methods on node objects.  Alternatively, you can traverse by specifying an arbitrary sub-path (relative path) using the `[]` operator on a node.
 
       Create a new temporary button:
+
       <code>
       b = left_bar.rumai_example # path of new button
       b.exist? #=> false
@@ -261,6 +298,7 @@
       You should now see an empty button on the left-hand side of the wmii bar.
 
       Color the button black-on-white and label it as "hello world":
+
       <code>
       content = "#000000 #ffffff #000000 hello world"
       b.write content
@@ -268,18 +306,14 @@
       </code>
 
       Remove the temporary button:
+
       <code>
       b.remove
       b.exist? #=> false
       </code>
-    <% end %>
 
-    <% section "Available commands" do %>
+    %|section "Available commands"
       Refer to the `Rumai` module in the [API documentation](api/index.html) for a complete list of commands (method calls, really) and their documentation.
-    <% end %>
-  <% end %>
 
-  <% section "Scripting your wmiirc", 'wmiirc' do %>
-    One important application of **<%= $project %>** is the support of Ruby-based <tt>wmiirc</tt> configuration files.  For a solid example of such application, take a look at [my personal <tt>wmiirc</tt>](http://github.com/sunaku/wmiirc/tree/master).
-  <% end %>
-<% end %>
+  %|section "Scripting your wmiirc", 'wmiirc'
+    One important application of <%= $project %> is the support of Ruby-based <tt>wmiirc</tt> configuration files.  For a solid example of such application, take a look at [my personal <tt>wmiirc</tt>](http://github.com/sunaku/wmiirc/).