[kupfer] help: Update Introduction and Basic Usage

[Ulrik Sverdrup <usverdrup src gnome org>]

commit 6b0c9fbf92dd765c7954fb3acbaa8574d2849eba
Author: Ulrik Sverdrup <ulrik sverdrup gmail com>
Date:   Tue Mar 30 01:19:43 2010 +0200

    help: Update Introduction and Basic Usage
    
    Update texts to correspond better to the website and to Kupfer/Tips

 help/C/introduction.page |   27 ++++------
 help/C/tips.page         |  125 +++++++++++++++++++++++++++++++++++++---------
 2 files changed, 113 insertions(+), 39 deletions(-)
---
diff --git a/help/C/introduction.page b/help/C/introduction.page
index 6ecaa61..6868749 100644
--- a/help/C/introduction.page
+++ b/help/C/introduction.page
@@ -10,27 +10,24 @@
   <title>Introduction</title>
 
   <p>
-    <app>Kupfer</app> is a command tool heavily inspired by 
-    <link href="http://www.blacktree.com/";>Quicksilver</link>; you do not use 
-    it to search your files, you use it to summon an application or document 
-    quickly by typing the first parts of its name.
-  </p>
+    <app>Kupfer</app> is a program to change, speed up and make everything
+    about files and programs more fun on your computer.
 
-  <p>
-    <app>Kupfer</app> is written using Python and has a flexible architecture. 
-    Objects that it can access are implemented in plugins, and new plugins can 
-    be written quickly.
+    <app>Kupfer</app> is a launcher; you typically use it to summon an
+    application or a document quickly by typing parts of its name. It can also
+    do more than getting at something quickly: there are different plugins for
+    accessing more objects and running custom commands.
   </p>
 
   <p>
-    The philosophy of <app>Kupfer</app> is simplicity. The implementation is simple, 
-    makes the easy things work first, and does not overdesign unnecessary parts 
-    of the program.
+    <app>Kupfer</app> is written using Python and has a flexible architecture;
+    the implementation is simple and makes the easy things work first. One
+    goal is that new plugins can be written quickly without too much
+    programming.
   </p>
-
   <p>
-    When you run <app>Kupfer</app>, it launches, then anytime you type <app>Kupfer's</app> 
-    keybinding -- immediately its window is presented ready for a new query.
+    The program is very inspired by
+    <link href="http://www.blacktree.com/";>Quicksilver</link>.
   </p>
 
   <p>
diff --git a/help/C/tips.page b/help/C/tips.page
index c27c1da..f65b146 100644
--- a/help/C/tips.page
+++ b/help/C/tips.page
@@ -4,65 +4,142 @@
 
   <info>
    <link type="guide" xref="index#usage"/>
-   <desc>Using <app>Kupfer</app> more convenient.</desc>
+   <desc>Using <app>Kupfer</app> more conveniently.</desc>
   </info>
 
   <title>Basic Usage</title>
 
   <p>
-    By default, with the keybinder module installed, <keyseq><key>Ctrl</key><key>Space</key></keyseq> 
-    will summon the Kupfer window.
+    By default, with the keybinder module installed,
+    <keyseq><key>Ctrl</key><key>Space</key></keyseq> 
+    will summon the Kupfer window. This and other global keybinding can be
+    configured in the preferences.
   </p>
 
-  <p>
-    Included toplevel directories (by default home an desktop) are monitored 
-    so new files will be found immediately. Most plugins in <app>Kupfer</app> 
-    try to use the change notifications that are available from the system, to 
-    keep up to date with the instant.
-  </p>
+  <section>
+    <title>The Catalog</title>
+    <p>
+      The Catalog is the collection of objects you can
+      access in Kupfer, such as documents and programs. 
+    </p>
 
-  <p>
-    Objects that have content, like folders, are marked with an arrow. Pressing 
-    <key>right-arrow</key> will enter these objects.
-  </p>
+    <p>
+      Objects in the catalog that have content, like folders, are marked
+      with an arrow. Pressing <key>right-arrow</key> will enter these
+      objects. Much of the catalog is composed of subcatalogs; plugin
+      subcatalogs do in general list objects that are also available
+      directly from the top level.  Subcatalogs can be used for a
+      narrower view or search scope, when using Kupfer.
+    </p>
+
+    <p>
+      Most subcatalogs update their content automatically. For example,
+      the Desktop folder catalog  is always uptodate.
+    </p>
+  </section>
+
+  <section>
+    <title>Keyboard Interface</title>
+
+    <p>
+      <app>Kupfer</app> is to the largest part a keyboard-managed
+      interface to applications and documents.
+    </p>
+    <p>
+      Kupfer's default mode is the command mode: If you type a query,
+      kupfer will search for a match in its catalog.
+    </p>
+      
+    <p>
+      The arrow keys allow you to browse query matches quite naturally,
+      going to the previous or next match, and going up and down in the
+      subcatalogs.
+    </p>
 
   <p>
-    In command mode, some keybindings are:
+    In command mode, some keystrokes have special meanings: 
   </p>
-   <list>
+   <terms>
     <item>
+      <title><key>Space</key> or <key>â??</key></title>
+      <p> Go to the next match </p>
+    </item>
+    <item>
+     <title> <key>Shift+Space</key> or <key>â??</key></title>
      <p>
-      <key>space</key> to go to the next match
+       Go to the previous match
      </p>
     </item>
     <item>
+     <title> <key>.</key></title>
      <p>
-     <key>.</key> to activate free-text mode
+       Activate free-text mode
      </p>
     </item>
     <item>
+     <title> <key>/</key>  or <key>â??</key></title>
      <p>
-      <key>/</key> to descend into an object with content
+       Descend into an object with content
      </p>
     </item>
     <item>
+     <title> <key>Backspace</key></title>
      <p>
-     <key>Backspace</key> to go back upspace to go to the next match
+       Erase a character from the query. If the
+       query is empty, go up a level 
      </p>
     </item>
-   </list>
+    <item>
+     <title> <key>,</key></title>
+     <p>
+       Put selected object on the stack ("Comma Trick") 
+     </p>
+    </item>
+   </terms>
+  <p>
+    Additionally, the key <key>Return</key> activates the current
+    selection: the command is executed. <key>Escape</key> clears the
+    current selection.
+  </p>
+  <section>
+    <title>Global Keyboard Shortcuts</title>
+    <p>
+      Kupfer listens to global shortcuts, even if Kupfer is not
+      currently in the foreground. The most important global shortcut is
+      the shortcut to show and hide Kupfer's command window.
+    </p>
+    <p>
+      Global Keyboard Shortcuts are configured in Kupfer's preferences.
+    </p>
+    <p>
+      The Triggers plugin allows to configure actions to be activated by
+      global shortcuts, but triggers can only be configured in that
+      plugin.
+    </p>
+  </section>
+  <section>
+    <title>Additional Keyboard Shortcuts</title>
+    <p>
+      Additional keyboard shortcuts that work with Kupfer when it is in
+      the foreground can be configured in Kupfer's preferences.
+    </p>
+  </section>
+ </section>
+
   
 
  <section>
   <title>Configuration files and paths</title>
   <p>
-    Kupfer cache, config and data are in <file>~/.cache/kupfer</file>, 
-    <file>~/.config/kupfer</file> and <file>~/.local/share/kupfer</file>.
+    Install custom plugins in the folder
+    <file>~/.local/share/kupfer/plugins/</file>
   </p>
-  
   <p>
-    Install custom plugins in <file>~/.local/share/kupfer/plugins/</file>
+    Kupfer cache, config and data are located in the directories
+    <file>~/.cache/kupfer</file>, <file>~/.config/kupfer</file> and
+    <file>~/.local/share/kupfer</file>.
   </p>
+  
  </section>
 
 </page>