<?xml version="1.0" encoding="UTF-8"?>
<chapter id="using-plugins">
    <title>Installing and Using Plugins</title>
    <!-- jEdit buffer-local properties: -->
    <!-- :tabSize=1:indentSize=1:noTabs=true:wrap=hard:maxLineLen=80: -->
    <!-- :xml.root=users-guide.xml: -->
    <para>A <firstterm>plugin</firstterm> is an application which is loaded and
    runs as part of another, host application. Plugins respond to user commands
    and perform tasks that supplement the host application's features.</para>

    <para>This chapter covers installing, updating and removing plugins.
    Documentation for the plugins themselves can be found in
    <guimenu>Help</guimenu>&gt;<guimenuitem>jEdit Help</guimenuitem>, and
    information about writing plugins can be found in <xref
    linkend="writing-plugins-part" />.</para>

    <section id="plugin-manager">
        <title>The Plugin Manager</title>

        <para><guimenu>Plugins</guimenu>&gt;<guimenuitem>Plugin
        Manager</guimenuitem> displays the plugin manager window. It consists of
        three tabs: Manage, Update and Install. The Manage tab lists all
        installed plugins; clicking on a plugin in the list will display
        information about it.</para>

        <para>To remove plugins, select them (multiple plugins can be selected
        by holding down <keycap>Control</keycap>) and click
        <guibutton>Remove</guibutton>. This will display a confirmation dialog
        box first.</para>

        <para>To view plugin documentation, select a plugin and click
        <guibutton>Help</guibutton>. Note that plugin documentation can also be
        accessed by invoking <guimenu>Help</guimenu>&gt;<guimenuitem>jEdit
        Help</guimenuitem>.</para>

        <para> After you have tuned jEdit to your liking and want to install the
        same set of plugins onto another host, or another user's profile, you
        can export your currently installed plugin list as an xml file, known as
        a <emphasis role="bold">PluginSet</emphasis>. The
        <guibutton>Save</guibutton> rollover button allows you to save the list
        of installed and loaded plugins to an XML file.  See <xref
        linkend="plugin-sets" /> for more information. </para>


        <para><guimenu>Plugins</guimenu>&gt;<guimenuitem>Plugin
        Options</guimenuitem> displays a dialog box for changing plugin
        settings.</para>
    </section>

    <section id="installing-plugins">
        <title>Installing and Updating Plugins</title>

        <para>Plugins can be installed in two ways; manually, and from the
        plugin manager. In most cases, plugins should be installed from the
        plugin manager. It is easier and more convenient.</para>

        <para>To install plugins manually, go to <ulink
        url="http://plugins.jedit.org">http://plugins.jedit.org</ulink> in a web
        browser and follow the directions on that page.</para>

        <para>To install plugins from the plugin manager, make sure you are
        connected to the Internet and click the <guibutton>Install</guibutton>
        tab in the plugin manager window. The plugin manager will then download
        information about available plugins from the jEdit web site, and present
        a list of plugins compatible with your jEdit release.</para>

        <para>Click on a plugin in the list to see some information about it. To
        select plugins for installation, click the check box next to their names
        in the list.</para>

        <para>The <guibutton>Total size</guibutton> field shows the total size
        of all plugins chosen for installation, along with any plugins that will
        be automatically downloaded in order to fulfill dependencies.</para>

        <para>If a previously saved PluginSet was selected, it will
        automatically be loaded whenever the Install tab is created, and you
        will see the filename in the hovertip of the
        <guibutton>choose</guibutton> rolloverbutton, as well as all of the
        plugins in that set already checked for you. </para>

        <para> You can clear the active PluginSet with the
        <guibutton>clear</guibutton> button next to it, or choose a different
        PluginSet xml file with the <guibutton>choose</guibutton> button. See
        <xref linkend="plugin-sets" /> for more information. </para>

        <para>Once you have specified plugins to install, click
        <guibutton>Install</guibutton> to begin the download process.</para>

        <para>By default, the plugin manager does not download plugin source
        code, and installs the downloaded plugins in the
        <filename>jars</filename> subdirectory of the user-specific settings
        directory. These settings can be changed in <guilabel>Plugin
        Manager</guilabel> pane of the
        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
        Options</guimenuitem> dialog box; see <xref
        linkend="pluginmgr-pane" />.</para>

        <para>The <guibutton>Update</guibutton> tab of the plugin manager is
        very similar to the <guibutton>Install</guibutton> tab. It lists plugins
        for which updated versions are available. It will also offer to delete
        any obsolete plugins.</para>

        <sidebar>
            <title>Proxy Servers and Firewalls</title>

            <para>If you are connected to the Internet through an HTTP proxy or
            SOCKS firewall, you will need to specify the relevant details in the
            <guibutton>Proxy Servers</guibutton> pane of the
            <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
            Options</guimenuitem> dialog box; see <xref
            linkend="firewall-pane" />.</para>
        </sidebar>
    </section>

    <section id="plugin-sets">
    <title>Plugin Sets</title>

    <para> A <emphasis role="bold">PluginSet</emphasis> is a collection of
    plugins, represented as an XML file. These XML files can be created from the
    <guibutton>save</guibutton> button of the Manage tab of the Plugin Manager.
    Saving a PluginSet remembers all of the currently loaded plugins. </para>

    <para> When a PluginSet has been saved, it becomes the "default pluginset",
    which means that if you unload/uninstall plugins from that set and go back to the
    Install tab, you should see them selected for download again. To clear this
    setting, click on the <guibutton>clear</guibutton> button in the
    Install tab.
    </para>

    <para> It is posisble to Choose/Open a PluginSet from the Manage or the
    Install tab. The behavior of choosing a PluginSet depends on which tab
    you are on when you choose it. From the Manage tab, it unloads plugins that
    are loaded but not in the list. From the Install tab, it selects plugins
    from that list that are not loaded, marking them for download from Plugin
    Central. </para>

    <para> When choosing a PluginSet, the path can be given as a remote URL.
    This helps teachers and sysadmins direct the students/slaves to a standard
    set of plugins that are required for the course/job. </para>

    </section>

</chapter>