[kupfer] Big user help update: General and Plugin Help Documents
- From: Ulrik Sverdrup <usverdrup src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [kupfer] Big user help update: General and Plugin Help Documents
- Date: Tue, 8 Mar 2011 20:15:23 +0000 (UTC)
commit fc8a04efb4944f6dcf94a3f066fbd24e63178973
Author: Ulrik Sverdrup <ulrik sverdrup gmail com>
Date: Tue Mar 8 21:05:33 2011 +0100
Big user help update: General and Plugin Help Documents
This integrates most of the `Kupfer Tips`__ information as well as
starting per-plugin documentation.
__ http://live.gnome.org/Kupfer/Tips
Starting out with simple documentation for five active-by-default
plugins but we can expect to expand it to more and more plugins.
help/C/Makefile | 4 +-
help/C/{tips.page => generalusage.page} | 97 +++++++-----------
help/C/index.page | 5 +-
help/C/introduction.page | 27 ++---
help/C/keyboard.page | 171 +++++++++++++++++++++++++++++++
help/C/license.page | 2 +-
help/C/managing-plugins.page | 100 ++++++++++++++++++
help/C/{plugins.page => moreusage.page} | 136 ++++++++++---------------
help/C/plugin-calculator.page | 67 ++++++++++++
help/C/plugin-favorites.page | 61 +++++++++++
help/C/plugin-selected-file.page | 36 +++++++
help/C/plugin-triggers.page | 95 +++++++++++++++++
help/C/plugin-websearch.page | 44 ++++++++
help/Makefile.am | 13 ++-
14 files changed, 691 insertions(+), 167 deletions(-)
---
diff --git a/help/C/Makefile b/help/C/Makefile
index 9712bf1..cb91461 100644
--- a/help/C/Makefile
+++ b/help/C/Makefile
@@ -1,4 +1,4 @@
-pages=$(wildcard *.page)
+pages=$(wildcard *.page plugin/*.page)
htmls=$(patsubst %.page,%.html,$(pages))
all: $(htmls) index.cache
@@ -22,4 +22,4 @@ $(htmls) : %.html : %.page
.PHONY: clean
clean:
- rm index.cache *.html
+ rm -fv index.cache *.html
diff --git a/help/C/tips.page b/help/C/generalusage.page
similarity index 62%
rename from help/C/tips.page
rename to help/C/generalusage.page
index ac5ea50..0245bba 100644
--- a/help/C/tips.page
+++ b/help/C/generalusage.page
@@ -1,36 +1,13 @@
<page xmlns="http://projectmallard.org/1.0/";
type="topic"
- id="tips">
+ id="generalusage">
<info>
<link type="guide" xref="index#usage"/>
- <desc>Using <app>Kupfer</app> more conveniently.</desc>
+ <desc>How to start using <app>Kupfer</app>.</desc>
</info>
<title>Basic Usage</title>
-
- <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 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>
@@ -83,50 +60,52 @@
</tr>
</table>
<p>
- Additionally, the key <key>Return</key> activates the current
- selection: the command is executed. <key>Escape</key> clears the
- current selection.
+ Additionally:
</p>
+ <list>
+ <item><p><key>Return</key> activates the current selection: the command is executed.
+ </p></item>
+ <item><p><key>Escape</key> clears the current selection.</p></item>
+ <item><p><key>Tab</key> switches between the object and the action pane. </p></item>
+ </list>
+ <p> By default you show <app>Kupfer</app> using the global keyboard shortcut
+ <keyseq><key>Ctrl</key><key>Space</key></keyseq>.
+ </p>
+ <p> See <link xref="keyboard" /> for more information. </p>
+ </section>
+
<section>
- <title>Global Keyboard Shortcuts</title>
+ <title>Learning Habits</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 which by
- default is <keyseq><key>Ctrl</key><key>Space</key></keyseq>.
+ <app>Kupfer</app> remembers which objects and actions are used the
+ most. When beginning to use it, you have to use the arrow keys at
+ times to make it precise which object you want to find. After a few
+ uses of that object, Kupfer will rank it higher. Objects marked as
+ <link xref="plugin-favorites">favorites</link> are also ranked higher.
</p>
+ </section>
+
+
+ <section>
+ <title>The Catalog</title>
<p>
- Global Keyboard Shortcuts are configured in Kupfer's preferences.
+ The Catalog is the collection of objects you can
+ access in Kupfer, such as documents and programs.
</p>
+
<p>
- The Triggers plugin allows to configure actions to be activated by
- global shortcuts, but triggers can only be configured in that
- plugin.
+ 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>
- </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.
+ Most subcatalogs update their content automatically. For example,
+ the Desktop folder source is always up-to-date.
</p>
</section>
- </section>
-
-
-
- <section>
- <title>Configuration files and paths</title>
- <p>
- Install custom plugins in the folder
- <file>~/.local/share/kupfer/plugins/</file>
- </p>
- <p>
- 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>
diff --git a/help/C/index.page b/help/C/index.page
index 6d0bf77..1ba0d0c 100644
--- a/help/C/index.page
+++ b/help/C/index.page
@@ -18,10 +18,13 @@
<include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
</info>
- <title>Kupfer manual</title>
+ <title>Kupfer Manual</title>
<section id="usage" style="2column">
<title>Using Kupfer</title>
</section>
+ <section id="plugins" style="2column">
+ <title>About Specific Plugins</title>
+ </section>
</page>
diff --git a/help/C/introduction.page b/help/C/introduction.page
index 6868749..e774bd6 100644
--- a/help/C/introduction.page
+++ b/help/C/introduction.page
@@ -1,6 +1,6 @@
<page xmlns="http://projectmallard.org/1.0/";
type="topic"
- id="intro">
+ id="introduction">
<info>
<link type="guide" xref="index"/>
@@ -10,28 +10,21 @@
<title>Introduction</title>
<p>
- <app>Kupfer</app> is a program to change, speed up and make everything
- about files and programs more fun on your computer.
-
- <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.
+ <app>Kupfer</app> is an interface for quick and convenient access to
+ applications and their documents.
</p>
-
<p>
- <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.
+ The most typical use is to find a specific application and launch it. We have
+ tried to make <app>Kupfer</app> easy to extend with plugins so that
+ this quick-access paradigm can be extended to many more objects than just
+ applications.
</p>
<p>
- The program is very inspired by
- <link href="http://www.blacktree.com/";>Quicksilver</link>.
+ We hope that using <app>Kupfer</app> feels both <em>very fun</em> and
+ <em>different</em>.
</p>
-
<p>
- For more information about <app>Kupfer</app>, visit its
+ For up-to-date information about <app>Kupfer</app>, visit its
<link href="http://kaizer.se/wiki/kupfer/";>homepage</link>.
</p>
</page>
diff --git a/help/C/keyboard.page b/help/C/keyboard.page
new file mode 100644
index 0000000..ca20d33
--- /dev/null
+++ b/help/C/keyboard.page
@@ -0,0 +1,171 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ type="topic"
+ id="keyboard">
+
+ <info>
+ <link type="guide" xref="index#usage"/>
+ <desc>Complete keyboard reference.</desc>
+ </info>
+
+ <title>Command Keys and Accelerator Keys</title>
+
+ <section>
+ <title>Keyboard Interface</title>
+ <p>
+ In command mode, the following keystrokes have special meanings:
+ </p>
+ <table>
+ <tr>
+ <td><p><key>â??</key> or <key>Space</key></p></td>
+ <td><p> Go to the next match </p></td>
+ </tr>
+ <tr>
+ <td><p>
+ <key>â??</key> or <keyseq><key>Shift</key><key>Space</key></keyseq>
+ </p></td>
+ <td><p> Go to the previous match </p></td>
+ </tr>
+ <tr>
+ <td><p> <key>â??</key> or <key>/</key> </p></td>
+ <td><p> Descend into an object with content </p></td>
+ </tr>
+ <tr>
+ <td><p> <key>Backspace</key></p></td>
+ <td><p> Erase a character from the query. If the
+ query is empty, go up a level
+ </p></td>
+ </tr>
+ <tr>
+ <td><p> <key>.</key></p></td>
+ <td><p> Activate free-text mode </p></td>
+ </tr>
+ <tr>
+ <td><p> <key>,</key></p></td>
+ <td><p> Put selected object on the stack ("Comma Trick") </p></td>
+ </tr>
+ </table>
+ <p>
+ Quick access keys:
+ </p>
+ <table>
+ <tr>
+ <td><p>
+ <key>=</key>
+ </p></td>
+ <td><p> Activate free-text mode with =
+ prefix (for <link xref="plugin-calculator" />)
+ </p></td>
+ </tr>
+ <tr>
+ <td><p>
+ <key>/</key>
+ </p></td>
+ <td><p> Activate free-text mode (when nothing is selected) with
+ <code>/</code> prefix (to input a rooted path)
+ </p></td>
+ </tr>
+ </table>
+ <p>
+ Additionally:
+ </p>
+ <list>
+ <item><p><key>Return</key> activates the current selection: the command is executed.
+ </p></item>
+ <item><p><key>Escape</key> clears the current selection.</p></item>
+ <item><p><key>Tab</key> switches between the object and the action pane. </p></item>
+ </list>
+ <p>
+ The meaning of the keys <key>Space</key>, <key>.</key>, <key>,</key>,
+ <key>/</key> and <key>=</key> can not be changed, but you can deactivate
+ their special meaning with the checkbox <app>Use single keystroke
+ commands</app> in <app>Kupfer Preferences</app>.
+ </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.
+ They have the following meanings and default shortcuts:
+ </p>
+ <table>
+ <tr>
+ <td><p><keyseq><key>Ctrl</key><key>.</key></keyseq></p></td>
+ <td><p> Toggle text mode </p></td>
+ </tr>
+ <tr>
+ <td><p><keyseq><key>Ctrl</key><key>,</key></keyseq></p></td>
+ <td><p> The comma trick </p></td>
+ </tr>
+ <tr>
+ <td><p><keyseq><key>Ctrl</key><key>;</key></keyseq></p></td>
+ <td><p> Show preferences window </p></td>
+ </tr>
+ <tr>
+ <td><p><keyseq><key>Ctrl</key><key>R</key></keyseq></p></td>
+ <td><p> Reset all </p></td>
+ </tr>
+ <tr>
+ <td><p><keyseq><key>Alt</key><key>A</key></keyseq></p></td>
+ <td><p> Alternate activate </p></td>
+ </tr>
+ <tr>
+ <td><p><keyseq><key>Ctrl</key><key>Return</key></keyseq></p></td>
+ <td><p> Compose command </p></td>
+ </tr>
+ <tr>
+ <td><p><keyseq><key>Ctrl</key><key>S</key></keyseq></p></td>
+ <td><p> Switch to first pane </p></td>
+ </tr>
+ <tr>
+ <td><p><keyseq><key>Ctrl</key><key>Q</key></keyseq></p></td>
+ <td><p> Select 'Quit' </p></td>
+ </tr>
+ <tr>
+ <td><p><keyseq><key>Ctrl</key><key>G</key></keyseq></p></td>
+ <td><p> Select 'Selected File' </p></td>
+ </tr>
+ <tr>
+ <td><p><keyseq><key>Ctrl</key><key>T</key></keyseq></p></td>
+ <td><p> Select 'Selected Text' </p></td>
+ </tr>
+ <tr>
+ <td><p><keyseq><key>F1</key></keyseq></p></td>
+ <td><p> Show Help </p></td>
+ </tr>
+
+ </table>
+ </section>
+
+ <section>
+ <title>Global Keyboard Shortcuts</title>
+ <p>
+ <app>Kupfer</app> always listens to global shortcuts, even if it is not
+ currently in the foreground.
+ </p>
+ <p>
+ They have the following meanings and default shortcuts:
+ </p>
+ <table>
+ <tr>
+ <td><p><keyseq><key>Ctrl</key><key>Space</key></keyseq></p></td>
+ <td><p> Show/hide <app>Kupfer</app></p></td>
+ </tr>
+ <tr>
+ <td><p>(not configured by default)</p></td>
+ <td><p> Show <app>Kupfer</app> with 'Selection' object focused</p></td>
+ </tr>
+ </table>
+
+ </section>
+ <section>
+ <title>Triggers</title>
+ <p>
+ The plugin <link xref="plugin-triggers">Triggers</link> allows to
+ configure actions to be activated by global shortcuts, but triggers can
+ only be configured in that plugin.
+ </p>
+ </section>
+
+</page>
diff --git a/help/C/license.page b/help/C/license.page
index 1a13a51..8fff621 100644
--- a/help/C/license.page
+++ b/help/C/license.page
@@ -4,7 +4,7 @@
<info>
<link type="seealso" xref="index"/>
- <desc>Legal Information.</desc>
+ <desc>You can copy, modify and share Kupfer.</desc>
</info>
<title>License</title>
diff --git a/help/C/managing-plugins.page b/help/C/managing-plugins.page
new file mode 100644
index 0000000..e2fa141
--- /dev/null
+++ b/help/C/managing-plugins.page
@@ -0,0 +1,100 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ type="topic"
+ id="managing-plugins">
+
+ <info>
+ <link type="guide" xref="index#usage"/>
+ <desc>Using plugins with <app>Kupfer</app>.</desc>
+ </info>
+
+ <title>How to configure plugins</title>
+
+ <p>
+ Functionality in Kupfer is organized by extentsion modules called
+ "plugins". Each plugin provides additional functionality, for example
+ integration with an external application.
+ </p>
+
+ <section>
+ <title>Configuring Plugins</title>
+ <p>
+ You can enable, disable and configure plugins if you open Kupfer's
+ preferences window using one of these methods:
+ </p>
+ <list>
+ <item><p>Click the Kupfer icon in the notification area and select
+ the item Preferences</p>
+ </item>
+ <item><p>Search for the object <app>Kupfer Preferences</app> in Kupfer itself.
+ Press <key>Return</key> to open it.</p>
+ </item>
+ <item><p>Use the keyboard shortcut
+ <keyseq><key>Control</key><key>;</key></keyseq></p>
+ </item>
+ </list>
+ <p>
+ Select the tab "Plugins" to reach the plugin list in the
+ preferences window.
+ </p>
+
+ <p>
+ Select plugins in the list to read about them, and tick the box
+ next its name to load the plugin.
+ </p>
+
+ <p>
+ If the plugin has any configurable parameters, they will be
+ visible below the plugin information.
+ </p>
+ <p>The plugin <app>Kupfer Plugins</app> allows fast access to each plugin's
+ information page as well as the action "Show Source Code" which
+ reveals the implementation.
+ </p>
+ </section>
+
+ <section>
+ <title>Installing more Plugins</title>
+ <p>
+ You can install custom plugins into the folder
+ <code>~/.local/share/kupfer/plugins</code>. Each plugin is either a
+ single <code>.py</code> file or a python package (a folder directly
+ containing a file called <code>__init__.py</code>). Plugins
+ in the package format can include icon files. Python packages can even
+ be installed as <code>.zip</code> files.
+ </p>
+ </section>
+
+ <section>
+ <title>Creating Plugins</title>
+ <p>
+ Adding to <app>Kupfer</app>'s object knowledge can be surprisingly
+ easy, just look at the default plugins if you want to create new.
+ Documentation for plugin creators is available in the file
+ Documentation/Manual.rst in the source distribution on the webpage at
+ <link href="http://kaizer.se/wiki/kupfer/Manual/";>Kupfer Manual</link>.
+ </p>
+ </section>
+ <section>
+ <title>The <em>Catalog</em> tab in preferences</title>
+ <p>
+ Each plugin can export a number of sources which contain objects.
+ Normally, all their contents are directly accessible from a top-level
+ search.
+ Some plugins export so specialized or so many objects that their
+ catalogs should better not have their objects exported to the top
+ level. To reach those objects, you have to first find the catalog by
+ name, then enter the catalog using the action <em>Search
+ Contents</em>.
+ </p>
+ <p>
+ In the tab <em>Catalog</em> in <app>Kupfer Preferences</app>,
+ a ticked box next to each source means that its objects are exported.
+ An unticked box means that its contents are hidden from the top level.
+ </p>
+ <p>
+ <em>Note:</em> Kupfer may become slow if large enough subcatalogs are exported
+ to the top level.
+ </p>
+ </section>
+</page>
+
diff --git a/help/C/plugins.page b/help/C/moreusage.page
similarity index 60%
rename from help/C/plugins.page
rename to help/C/moreusage.page
index c2ba5b7..8e99432 100644
--- a/help/C/plugins.page
+++ b/help/C/moreusage.page
@@ -1,35 +1,14 @@
<page xmlns="http://projectmallard.org/1.0/";
type="topic"
- id="plugins">
+ id="moreusage">
<info>
<link type="guide" xref="index#usage"/>
- <desc>Using <app>Kupfer</app> plugins.</desc>
+ <desc>More advanced usage information.</desc>
</info>
- <title>Plugins</title>
+ <title>Using <app>Kupfer</app> in depth.</title>
- <p>
- You can install custom plugins into ~/.local/share/kupfer/plugins;
- adding to <app>Kupfer</app>'s object knowledge can be surprisingly
- easy, just look at the default plugins if you want to create new.
- </p>
-
- <section>
- <title>Search the Web Search Engines</title>
- <p>
- The Search the Web plugin uses <app>Firefox'</app> search engines,
- so you can add Search Engines directly in <app>Firefox</app> and
- <app>Kupfer</app> will find them later.
- </p>
- <p>
- You can also install custom search plugins directly, only for
- <app>Kupfer</app>, in the folder:
- </p>
- <code>~/.local/share/kupfer/searchplugins/</code>
-
- </section>
-
<section>
<title>Open Terminal Here</title>
<p>
@@ -42,31 +21,14 @@
<section>
<title>Grab current selection</title>
- <p>
- To use <app>Kupfer</app> like a pro, you can configure a "Magic Keybinding"
- for <app>Kupfer</app>. GUI configuration is not yet supported, but edit the
- configuration file <file>~/.config/kupfer/kupfer.cfg</file> to include the
- following:
+ <p> To use the current selected text, from any application, with
+ <app>Kupfer</app>, you can configure a global keyboard shortcut for the
+ action Show with Selection in the preferences window.
</p>
- <code>
-[Kupfer]
-keybinding = <Control>space
-magickeybinding = <Ctrl><Alt>space
- </code>
-
<p>
- Now, pressing <keyseq><key>Ctrl</key><key>Alt</key><key>Space</key></keyseq>
- will summon <app>Kupfer</app> with the current selection in focus. Make sure
- you have installed <app>Kupfer</app>'s nautilus plugin, then both the currently
- selected file in Nautilus, or the currently selected text in the front application
- will be selected.
- </p>
- <p>
- Now you can select a word in, say, a web browser, use
- <keyseq><key>Ctrl</key><key>Alt</key><key>Space</key></keyseq>, and select action
- <gui>Look Up</gui> to look up the selected word. Or select an image file, use
- <keyseq><key>Ctrl</key><key>Alt</key><key>Space</key></keyseq>, select action
- <gui>Scale</gui> with object <gui>1000</gui> to scale the image to 1000 pixels wide!
+ If configured, pressing the global keyboard shortcut
+ will summon <app>Kupfer</app> with the current selection as the focused
+ object.
</p>
</section>
@@ -94,42 +56,6 @@ magickeybinding = <Ctrl><Alt>space
</section>
<section>
- <title>Calculator Plugin</title>
- <p>
- The calculator plugin lets you calculate expressions quickly. It can evaluate
- expressions entered as text starting with "=". Entering = from command mode will
- start text mode directly with = prefixed for quick access.
- </p>
- <p>
- The Calculator uses python's math and complex math modules,
- and parses expressions as Python expressions. You may use common
- mathematical functions, such as sqrt, sin, exp and log; the command
- <cmd>=help</cmd> will show a list of all defined functions and constants.
- </p>
- <list>
- <item>
- <p>
- Notice that the power operator in Python is double stars, for example
- =3**3 will evaluate to 27.
- </p>
- </item>
- <item>
- <p>
- To calculate trig functions for angles, convert to radians first:
- </p>
- <code>sin(radians(30)) -> 0.5</code>
- </item>
- <item>
- <p>
- The last result is stored as the name _ (an underscore, just like in
- the Python console).
- </p>
- </item>
- </list>
-
- </section>
-
- <section>
<title>Command line connection</title>
<p>
<app>Kupfer</app> is its own remote control. When <app>Kupfer</app> is
@@ -181,5 +107,47 @@ magickeybinding = <Ctrl><Alt>space
around where you were, deep in that folder (press space, then type a query).
</p>
</section>
-
+
+ <section>
+ <title>The "Comma Trick"</title>
+ <p> The "comma trick" allows the user to use actions on many objects at
+ the same time.
+ </p>
+
+ <p>Simply press comma <key>,</key> when an object is selected. The object
+ is put on a "stack", and you can find yet another file or object, press
+ comma to put it on the stack. When you subsequently invoke an action, the
+ action is carried out on all of the objects at the same time.
+ </p>
+
+ <p>Some actions are only "multiplied" when used with many objects, other
+ are smarter than that:</p>
+ <list>
+ <item><p> Selecting many files and using the Create Archive action, all
+ files will be packed into the same archive.</p></item>
+ <item><p>If you select multiple contacts and use a Send Email action, it
+ creates one email directed at all the contacts.</p></item>
+ <item><p>If you select multiple subcatalogs (For example Firefox
+ Bookmarks and Epiphany Bookmarks) and use Search Contents.., you get
+ a subcatalog search restricted to the objects of those two catalogs!
+ You can even bind a trigger to this command(!)
+ </p></item>
+ </list>
+ <p>The "comma trick" is
+ <link href="http://www.43folders.com/2005/06/13/quicksilver-the-comma-trick";>
+ directly taken from Quicksilver</link>
+ (the example given in the external article should work identically in Kupfer).
+ </p>
+ </section>
+ <section>
+ <title>Save Commands as Files</title>
+ <p>You can use keyboard shortcut for "Compose Command" (by default it is
+ <keyseq><key>Control</key><key>Return</key></keyseq>) to create a
+ command object out of the currently focused command in Kupfer.
+ This object can be saved as a runnable file if you use the "Save As.." action.
+ The resulting file will can be executed when opened from the file manager
+ (to run it requires that Kupfer is already running).
+ </p>
+ </section>
+
</page>
diff --git a/help/C/plugin-calculator.page b/help/C/plugin-calculator.page
new file mode 100644
index 0000000..fd67c56
--- /dev/null
+++ b/help/C/plugin-calculator.page
@@ -0,0 +1,67 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ type="topic"
+ id="plugin-calculator">
+
+ <info>
+ <link type="guide" xref="index#plugins"/>
+ <desc>Using the calculator plugin.</desc>
+ </info>
+
+ <title><app>Calculator</app></title>
+
+ <section>
+ <title>Calculator Plugin</title>
+ <p>
+ The calculator plugin lets you calculate expressions quickly. It can evaluate
+ expressions entered as text starting with "=". Entering = from command mode will
+ start text mode directly with = prefixed for quick access.
+ </p>
+ </section>
+ <section>
+ <title>Basic Usage</title>
+ <steps>
+ <item><p>
+ Activate Kupfer and type <key>=</key>
+ </p></item>
+ <item><p>Type in a mathematical expression using
+ <key>+</key>,<key>-</key>,<key>/</key>,<key>*</key> (and
+ <key>**</key> for exponentiation)
+ </p></item>
+ <item><p>
+ Press <key>Return</key> to get the result.
+ </p></item>
+ </steps>
+
+ </section>
+ <section>
+ <title>Notes</title>
+ <p>
+ The Calculator uses python's math and complex math modules,
+ and parses expressions as Python expressions. You may use common
+ mathematical functions, such as <cmd>sqrt</cmd>, <cmd>sin</cmd>,
+ <cmd>exp</cmd> and <cmd>log</cmd>; the command <cmd>=help</cmd> will
+ show a list of all defined functions and constants.
+ </p>
+ <list>
+ <item>
+ <p>
+ Notice that the power operator in Python is double stars, for example
+ <code>=3**3</code> will evaluate to 27.
+ </p>
+ </item>
+ <item>
+ <p>
+ To calculate trig functions for angles, convert to radians first:
+ </p>
+ <code>sin(radians(30)) -> 0.5</code>
+ </item>
+ <item>
+ <p>
+ The last result is stored as the name _ (an underscore, just like in
+ the Python console).
+ </p>
+ </item>
+ </list>
+ </section>
+
+</page>
diff --git a/help/C/plugin-favorites.page b/help/C/plugin-favorites.page
new file mode 100644
index 0000000..c7a374f
--- /dev/null
+++ b/help/C/plugin-favorites.page
@@ -0,0 +1,61 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ type="topic"
+ id="plugin-favorites">
+
+ <info>
+ <link type="guide" xref="index#plugins"/>
+ <desc>Using the favorites plugin.</desc>
+ </info>
+
+ <title><app>Favorites</app></title>
+
+ <section>
+ <title>Favorites Plugin</title>
+ <p>
+ With <app>Favorites</app> you mark objects, for example files,
+ for quicker access. It is a sort of shelf on which you can store objects
+ in Kupfer. Objects marked as favorites will also be ranked higher and
+ are adorned with a star symbol.
+ </p>
+ </section>
+ <section>
+ <title>Basic Usage</title>
+ <steps>
+ <item>
+ <p>
+ Find an object in <app>Kupfer</app>
+ </p>
+ </item>
+ <item>
+ <p>
+ Type <key>Tab</key> and select either the action <em>Add to
+ Favorites</em> or <em>Remove from Favorites</em>.
+ </p>
+ </item>
+ </steps>
+ </section>
+ <section>
+ <title>Power user tips</title>
+ <p>
+ If you favorite an object, you can access it in more places. Not only in
+ the "Favorites" subcatalog, but also as the indirect (secondary) object
+ for some actions. For example:
+ </p>
+ <list>
+ <item><p> Command-lines from favorites are quick to access. </p></item>
+ <item><p>When scaling images with the <em>Scale...</em> action from the
+ <app>Image Tools</app> plugin. This action needs a size description
+ as the third object, like "1024" or "1200x800". If you often scale
+ to the same size, say "1200x800", add this to favorites, and it
+ will always appear as a suggestion for the action.
+ </p>
+ </item>
+ <item>
+ <p>
+ Actions needing an email address as the indirect object will pick
+ up email addresses from favorites as well as well.
+ </p>
+ </item>
+ </list>
+ </section>
+</page>
diff --git a/help/C/plugin-selected-file.page b/help/C/plugin-selected-file.page
new file mode 100644
index 0000000..da90769
--- /dev/null
+++ b/help/C/plugin-selected-file.page
@@ -0,0 +1,36 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ type="topic"
+ id="plugin-nautilusselection">
+
+ <info>
+ <link type="guide" xref="index#plugins"/>
+ <desc>Using the selected file plugin.</desc>
+ </info>
+
+ <title><app>Selected File</app></title>
+
+ <section>
+ <title>Basic Usage</title>
+ <p>
+ Select a file in the file manager. Open <app>Kupfer</app> and search for the
+ object <app>Selected File</app>, which represents the file or files that
+ are selected.
+ </p>
+ <p>
+ Instead of searching, you can press
+ <keyseq><key>Ctrl</key><key>G</key></keyseq> to directly focus the
+ selected file. See <link xref="keyboard" /> for more information.
+ </p>
+</section>
+ <section>
+ <title><app>Selected File</app> requires <app>Nautilus</app></title>
+ <p>
+ The selected file plugin works with the <app>Nautilus</app> file browser and
+ requires that the extension <cmd>kupfer_provider.py</cmd> is installed
+ (it is normally installed together with <app>Kupfer</app>). After
+ installing it for the first time, <app>Nautilus</app> must start anew before it is
+ active.
+ </p>
+ </section>
+
+</page>
diff --git a/help/C/plugin-triggers.page b/help/C/plugin-triggers.page
new file mode 100644
index 0000000..b85089e
--- /dev/null
+++ b/help/C/plugin-triggers.page
@@ -0,0 +1,95 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ type="topic"
+ id="plugin-triggers">
+
+ <info>
+ <link type="guide" xref="index#plugins"/>
+ <desc>Using the triggers plugin.</desc>
+ </info>
+
+ <title><app>Triggers</app></title>
+
+ <section>
+ <title>Triggers Plugin</title>
+ <p>
+ With <app>Triggers</app> you can take a command you would normally
+ perform in Kupfer, such as launching an application or opening a
+ document, and bind a global key combination to run this command. As long
+ as Kupfer is running, any application can have the current focus.
+ </p>
+ </section>
+ <section>
+ <title>Basic Usage</title>
+ <steps>
+ <item>
+ <p>
+ Set up a command in Kupfer that you want to run,
+ </p>
+ </item>
+ <item>
+ <p>
+ Press <keyseq><key>Ctrl</key><key>Return</key></keyseq> (or the
+ shortcut you have configured in preferences) to create a composed
+ command.
+ </p>
+ </item>
+ <item>
+ <p>
+ Type <key>Tab</key> and select the action <em>Add Trigger...</em>
+ and press <key>Return</key>
+ </p>
+ </item>
+ <item>
+ <p>
+ Using the window that appears, press modifier keys and a letter or
+ number key to set a global shortcut. An example is pressing and
+ holding <key>Ctrl</key><key>Alt</key> and then typing <key>R</key>
+ to bind <keyseq><key>Ctrl</key><key>Alt</key><key>R</key></keyseq>.
+ </p>
+ </item>
+ </steps>
+ <p> Since trigger keyboard shortcuts are global, they can be used from
+ any application. You must select shortcuts with care so that they do
+ not conflict with other functions.
+ </p>
+ </section>
+ <section>
+ <title>Power user tips</title>
+ <p> <em>Proxy objects</em> such as <em>Selected Text</em>, <em>Selected File</em>,
+ <em>Frontmost Window</em>, <em>Last Command</em> et cetera allow very
+ powerful triggers.
+ </p>
+ <p> The application action <em>Launch</em> is special; if you bind a
+ trigger using <em>Launch</em>, it will start the application if it is
+ not running, but focus the application when it is already running. By
+ contrast, <em>Start Again</em> will start the application if it is
+ running or not.
+ </p>
+ </section>
+ <section>
+ <title>Example Triggers</title>
+ <terms>
+ <item>
+ <title><em>Firefox â?? Launch</em></title>
+ <p> Start a program if it is already running,
+ else focus its window.
+ </p></item>
+ <item>
+ <title><em>Selected Text â?? Search With â?? Google</em></title>
+ <p>Search the web using the currently selected text. </p></item>
+ <item>
+ <title><em>Selected File â?? Move To â?? (Downloads Folder)</em></title>
+ <p> Move the currently selected file to a specific folder
+ </p>
+ </item>
+ <item>
+ <title><em>Songs â?? Search Contents</em></title>
+ <p>
+ You may even add a trigger to open a specific subcatalog in Kupfer,
+ for example Rhythmbox's songs.
+ </p>
+ </item>
+ </terms>
+ </section>
+
+</page>
diff --git a/help/C/plugin-websearch.page b/help/C/plugin-websearch.page
new file mode 100644
index 0000000..9938022
--- /dev/null
+++ b/help/C/plugin-websearch.page
@@ -0,0 +1,44 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ type="topic"
+ id="plugin-websearch">
+
+ <info>
+ <link type="guide" xref="index#plugins"/>
+ <desc>Using the search the web plugin.</desc>
+ </info>
+
+ <title><app>Search the Web</app></title>
+
+ <section>
+ <title>Basic Usage</title>
+ <steps>
+ <item><p>Activate Kupfer and make sure it is in free-text mode (press period)
+ </p></item>
+ <item><p>Type in a search query and tap <key>Tab</key> to switch to the
+ action pane.</p></item>
+ <item><p> Type "Search With" to find Search the Web's action and tap
+ <key>Tab</key> again to switch to the third pane (indirect object).
+ </p></item>
+ <item><p>Select search engine with the arrow keys and type <key>Return</key>
+ to open the search in a web browser.</p></item>
+ </steps>
+
+ </section>
+
+ <section>
+ <title>Search Engines</title>
+ <p>
+ The Search the Web plugin uses <app>Firefox'</app> search engines,
+ so you can add Search Engines directly in <app>Firefox</app> and
+ <app>Kupfer</app> will find them later.
+ </p>
+ <p>
+ You can also install custom search plugins directly, only for
+ <app>Kupfer</app>, in the folder:
+ </p>
+ <code>~/.local/share/kupfer/searchplugins/</code>
+ <p>The search engine descriptions must written in OpenSearch format.
+ </p>
+
+ </section>
+</page>
diff --git a/help/Makefile.am b/help/Makefile.am
index 0b46ea8..05438b0 100644
--- a/help/Makefile.am
+++ b/help/Makefile.am
@@ -16,12 +16,19 @@ DOC_INCLUDES =
DOC_FIGURES =
DOC_PAGES = \
+ generalusage.page \
index.page \
introduction.page \
+ keyboard.page \
license.page \
- plugins.page \
- tips.page
-
+ managing-plugins.page \
+ moreusage.page \
+ plugin-calculator.page \
+ plugin-favorites.page \
+ plugin-selected-file.page \
+ plugin-triggers.page \
+ plugin-websearch.page \
+#
DOC_LINGUAS = cs de es it pl sl
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
