%#                                                                          #%
%#             You can read this document in its full glory by              #%
%#          opening ./doc/index.html in your favorite Web browser.          #%
%#                                                                          #%

%#----------------------------------------------------------------------------
%| section "Interactive shell", "shell"
%#----------------------------------------------------------------------------

  %|command! "rumai"

    This command starts an IRB (Interactive Ruby Shell) session, which places
    you a command prompt like this:

        irb(Rumai):001:0>

    The <tt>irb(Rumai)</tt> token in the command prompt indicates that
    commands will be evaluated _inside_ the `Rumai` module.  As a result, you
    can omit the "Rumai" prefix from your commands if you wish.

    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.

%#----------------------------------------------------------------------------
%| section "Live demonstration", "Tutorial"
%#----------------------------------------------------------------------------

  Now that you know <%= xref "shell", "how to start the interactive shell" %>,
  let us walk through a (hopefully) quick demonstration that highlights the
  main features of Rumai.  You can follow along by copying & pasting the
  presented commands into the interactive shell.

  %|open_terms = lambda do
    Launch a few terminals so that we have something to work with:

    %|code :ruby
      colors = %w[ red green blue black orange brown gray navy gold ]
      colors.each {|c| system "xterm -bg #{c} -title #{c} -e sh -c read &" }

  %|close_terms = lambda do
    Close the terminals we launched earlier:

    %|code :ruby
      terms = curr_view.clients.select {|c| colors.include? c.label.read }
      terms.each {|c| c.kill }

  %#--------------------------------------------------------------------------
  %| section "Automated client arrangement"
  %#--------------------------------------------------------------------------

    % open_terms.call

    Arrange all clients in a grid:

    %|code :ruby
      curr_view.arrange_in_grid

    Arrange all clients in a diamond shape:

    %|code :ruby
      curr_view.arrange_in_diamond

    Arrange all clients like LarsWM does:

    %|code :ruby
      curr_view.arrange_as_larswm

    % close_terms.call

  %#--------------------------------------------------------------------------
  %| section "Multiple client grouping"
  %#--------------------------------------------------------------------------

    % open_terms.call

    Add the red, green, and blue terminals into the "grouping":

    %|code :ruby
      terms = curr_view.clients.select do |c|
        %%w[red green blue].include? c.label.read
      end
      terms.each {|c| c.group }

    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 :ruby
      v = View.new "@"
      puts v.clients.map {|c| c.label.read }

    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 :ruby
      grouping.each {|c| c.send "toggle" }

    Neat! Let us bring them back into the managed area:

    %|code :ruby
      grouping.each {|c| c.send "toggle" }

    % close_terms.call

    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.

  %#--------------------------------------------------------------------------
  %| section "Easy column manipulation"
  %#--------------------------------------------------------------------------

    % open_terms.call

    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 :ruby
      curr_view.each_column {|c| c.length = 1 }

    Put (at most) three clients in every column:

    %|code :ruby
      curr_view.each_column {|c| c.length = 3 }

    Move the red, green, and blue clients into the floating area:

    %|code :ruby
      rgb = %w[red green blue]
      terms = curr_view.clients.select {|c| rgb.include? c.label.read }
      curr_view.areas[0].push terms

    Slurp all floating clients into the last column:

    %|code :ruby
      list = curr_view.areas
      a, b = list.first, list.last
      b.concat a

    Set the last column's layout to stacking mode:

    %|code :ruby
      b.layout = 'stack'

    Move the red, green, and blue clients to the top of the second column:

    %|code :ruby
      curr_view.areas[2].unshift terms

    Move the red, green, and blue clients to the bottom of the third column:

    %|code :ruby
      curr_view.areas[3].push terms

    % close_terms.call

  %#--------------------------------------------------------------------------
  %| section "Easy client manipulation"
  %#--------------------------------------------------------------------------

    % open_terms.call

    Obtain a reference to the red client:

    %|code :ruby
      red = curr_view.clients.find {|c| c.label.read == "red" }

    Show the red client's current tags:

    %|code :ruby
      red.tags

    Add the "foo" and "bar" tags to the red client:

    %|code :ruby
      red.tag "foo", "bar"

    Remove the "bar" tag from the red client:

    %|code :ruby
      red.untag "bar"

    Do complex operations on the red client's tags:

    %|code :ruby
      red.with_tags { concat %w[a b c]; push 'z'; delete 'c' }

    Focus the next client after the red client:

    %|code :ruby
      red.next.focus
      curr_client == red.next #=> true

    Notice that by focusing a client, we make it the current client.

    Focus the red client on a different view:

    %|code :ruby
      orig = curr_view
      v = red.views.last
      red.focus v

    Return to the original view:

    %|code :ruby
      orig.focus

    Send the red client to the last column:

    %|code :ruby
      red.send curr_view.areas.last

    % close_terms.call

  %#--------------------------------------------------------------------------
  %| section "Traversing the file system"
  %#--------------------------------------------------------------------------

    Show the root node of wmii's IXP file system:

    %|code :ruby
      fs

    Show the names of all files at the root level:

    %|code :ruby
      fs.entries

    Show the parent of the root node:

    %|code :ruby
      fs.parent

    Show the children of the root node:

    %|code :ruby
      fs.children

    Navigate into to the <tt>/lbar/</tt> directory:

    %|code :ruby
      n1 = fs.lbar
      n2 = fs['lbar']
      n1 == n2 #=> true
      left_bar = n1

    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 :ruby
      b = left_bar.rumai_example # path of new button
      b.exist? #=> false
      b.create
      b.exist? #=> true

    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 :ruby
      content = "#000000 #ffffff #000000 hello world"
      b.write content
      b.read == content #=> true

    Remove the temporary button:

    %|code :ruby
      b.remove
      b.exist? #=> false

  %#--------------------------------------------------------------------------
  %| section "More commands"
  %#--------------------------------------------------------------------------

    See the `Rumai` module in the [API documentation](api/index.html) for a
    complete list of commands (method calls really) and their documentation.