1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
<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>
<steps>
<title>Open <app>Kupfer Preferences</app> to the Plugins tab</title>
<item>
<p> Use one of the following methods:</p>
<list>
<item><p>Click the Kupfer icon in the notification area and select
the item <em>Preferences</em></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>Ctrl</key><key>;</key></keyseq></p>
</item>
</list>
</item>
<item>
<p>
Select the tab <em>Plugins</em>
</p>
</item>
</steps>
<p>
Select plugins in the list to read about them, and tick the box
next to its name to activate the plugin, or untick to deactivate.
</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>If a Plugin can not be Activated</title>
<p>
If a plugin fails to activate because it requires a software
module that is not available, its plugin information will display a
message like this:
</p>
<p><em>Plugin could not be read due to an error:</em>
</p><p><em>Python module 'gdata' is needed</em></p>
<p>
This means that you need to install a needed python module
from your distribution—and possibly the plugin documentation can
tell you how.
</p>
<p>The plugin may also unexpectedly fail to load, and display a
different error message. It may then be a program error in either
the plugin or <app>Kupfer</app>.
</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>
<note style="warning">
<p>
<em>Caution:</em> Treat a plugin as a computer program.
Do not install untrusted plugins.
</p>
</note>
</section>
<section>
<title>Creating Plugins</title>
<p>
Documentation for plugin creators is available in the file
<code>Documentation/Manual.rst</code> in the source distribution on
the webpage at
<link href="http://kaizer.se/wiki/kupfer/Manual/">Kupfer Manual</link>.
An easy way to start is to copy an existing plugin and experimenting
with it.
</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 these objects 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>
|
