<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>

