<?xml version="1.0"?>

<!-- FTP plugin user's guide -->
<!-- (C) 2001, 2003 Slava Pestov -->

<!-- jEdit buffer-local properties: -->
<!-- :indentSize=1:noTabs=true:folding=sidekick: -->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<book>

<bookinfo><title>FTP plugin user's guide</title>

 <authorgroup>
  <author><firstname>Slava</firstname><surname>Pestov</surname></author>
 </authorgroup>

 <legalnotice><title>Legal Notice</title>
  <para>
   Permission is granted to copy, distribute and/or modify this document
   under the terms of the GNU Free Documentation License, Version 1.1 or
   any later version published by the Free Software Foundation; with no
   <quote>Invariant Sections</quote>, <quote>Front-Cover Texts</quote> or
   <quote>Back-Cover Texts</quote>, each as defined in the license. A copy of
   the license can be found in the file <filename>COPYING.DOC.txt</filename>
   included with jEdit.
  </para>
 </legalnotice>
</bookinfo>

<chapter id="ftp"><title>Connecting to FTP servers</title>

<para>

The FTP plugin lets you browse directories and edit files on remote servers
using FTP, the File Transfer Protocol. Note that FTP is insecure since it
sends everything (including passwords) as clear-text over the network. If you
can, consider using SFTP, documented in the next section.

</para>

<para>

To connect to an FTP server, either select
<guimenuitem>Connect to FTP Server</guimenuitem> from the file system
browser's <guimenu>Plugins</guimenu> menu, or use the
<guimenuitem>Open from FTP Server</guimenuitem> and
<guimenuitem>Save to FTP Server</guimenuitem> commands in the
<guimenu>Plugins</guimenu>&gt;<guisubmenu>FTP</guisubmenu> menu.

</para>

</chapter>

<chapter id="sftp"><title>Connecting to SFTP servers</title>

<para>

The FTP plugin also supports the SSH File Transfer Protocol, or SFTP.
SFTP is much more secure than FTP because it encrypts all network traffic.
However not all FTP servers support SFTP. SFTP support requires Java 1.4.

</para>

<para>

To connect to an SFTP server, either select
<guimenuitem>Connect to Secure FTP Server</guimenuitem> from the file system
browser's <guimenu>Plugins</guimenu> menu, or use the
<guimenuitem>Open from Secure FTP Server</guimenuitem> and
<guimenuitem>Save to Secure FTP Server</guimenuitem> commands in the
<guimenu>Plugins</guimenu>&gt;<guisubmenu>FTP</guisubmenu> menu.

</para>

<para>

SFTP support is provided using the
<ulink url="http://www.sshtools.com">sshtools</ulink>
library.

</para>

</chapter>

<chapter id="misc"><title>Miscellaneous features</title>

<para>
The FTP plugin includes a number of time-saving and performance-improving
features:
</para>

<itemizedlist>

<listitem><para>
Remote directory listings are cached. Changing files
from within jEdit will automatically update the cache as necessary. However, if
changes are made from another program, you will need to clear the cache
manually using the <guimenuitem>Clear Remote Directory Cache</guimenuitem>
command in the
<guimenu>Plugins</guimenu>&gt;<guisubmenu>FTP</guisubmenu> menu.
</para></listitem>

<listitem><para>
Passwords are remembered while jEdit is running so you don't have to re-type
them. Passwords are not saved to disk and therefore are forgotten when jEdit
exits. To force jEdit to forget all passwords while it is running, use the
<guimenuitem>Forget Remote Passwords</guimenuitem> command in the
<guimenu>Plugins</guimenu>&gt;<guisubmenu>FTP</guisubmenu> menu.
</para></listitem>

<listitem><para>
FTP and SFTP connections are kept open for 2 minutes before being closed.
Performing another operation while a connection is still open resets the 2
minute timer. This improves performance by reducing network traffic.
</para>

<para>
You can close unused connections at any other time using the
<guimenuitem>Close Unused Connections</guimenuitem> command in the
<guimenu>Plugins</guimenu>&gt;<guisubmenu>FTP</guisubmenu> menu.
</para></listitem>

</itemizedlist>

</chapter>

<appendix id="changes"><title>Change log</title>

 <itemizedlist>

  <listitem><para><emphasis role="bold">Version 0.6</emphasis>
   requires jEdit 4.2pre2 and JakartaCommons 0.3.</para>
  
  <itemizedlist>
   <listitem><para>Updated to SSHTools 0.1.7 beta.</para></listitem>
   <listitem><para>Permissions are now preserved on SFTP servers.
   </para></listitem>
   <listitem><para>Incomplete support for VMS FTP servers.</para></listitem>
   <listitem><para>Support for AS/400 FTP servers (Nagy Gabor).</para></listitem>
   <listitem><para>Moved Log4J to JakartaCommons plugin.</para></listitem>
  </itemizedlist>

  </listitem>

  <listitem><para><emphasis role="bold">Version 0.5</emphasis>
   requires jEdit 4.1pre8.</para>

   <itemizedlist>
    <listitem><para>Connections to servers using the SSH File Transfer Protocol
    (SFTP) are now supported. This uses the <command>sshtools</command> library,
    version 0.0.5, and requires Java 2 version 1.4.</para></listitem>
    <listitem><para>Fixed various problems in the connection pooling code.
    </para></listitem>
    <listitem><para>Fixed problem with FTP servers localized for non-English
    languages.</para></listitem>
    <listitem><para>Fixed problem with AIX FTP servers.</para></listitem>
    <listitem><para>Permissions were not preserved properly
    (Brian Hardy).</para></listitem>
    <listitem><para>Login dialog box host and user name fields now remember
    previously entered values.
    </para></listitem>
    <listitem><para>Using the <guimenuitem>Save a Copy As</guimenuitem> command
    to save a buffer located on a non-FTP filesystem would result in an exception
    being thrown (but the file is still saved).
    </para></listitem>
   </itemizedlist>
  </listitem>

  <listitem><para><emphasis role="bold">Version 0.4.1</emphasis>
   requires jEdit 4.0pre3.</para>

  <itemizedlist>
    <listitem><para>Fixed problems if the remote server drops the connection
    before the keep-alive timeout expires.
    </para></listitem>
    <listitem><para>If passive mode could not be established or if the
    response to the <command>PASV</command> command could not be parsed, the
    client switches to data port mode instead of failing.
    </para></listitem>
    <listitem><para>Directory listing no longer fails if there was a problem
    while attempting to resolve a symbolic link.
    </para></listitem>
    <listitem><para>FTP operations now use a 45-second timeout by default.
    </para></listitem>
   </itemizedlist>
  </listitem>
 </itemizedlist>

 <itemizedlist>

  <listitem><para><emphasis role="bold">Version 0.4</emphasis>
   requires jEdit 4.0pre3.</para>

   <itemizedlist>
    <listitem><para>Connections are now kept open for 2 minutes after last
    use. This improves performance by reducing network traffic.
    </para></listitem>

    <listitem><para>Fixed a possible ArrayIndexOutOfBoundsException if the
    server output an empty line in a file listing.</para></listitem>

    <listitem><para>First attempt at supporting VMS FTP servers.
    </para></listitem>
   </itemizedlist>
  </listitem>
 
  <listitem><para><emphasis role="bold">Version 0.3.4</emphasis>
   requires jEdit 4.0pre3.</para>

   <itemizedlist>

    <listitem><para>
     Hidden files were not listed, even if <guimenuitem>Show Hidden
     Files</guimenuitem> was selected in the file system browser.
    </para></listitem>

    <listitem><para>
     <guimenuitem>Open from FTP Server</guimenuitem> and <guimenuitem>Save to
     FTP Server</guimenuitem> commands opened the wrong directory on the remote
     server.
    </para></listitem>

    <listitem><para>
     The directory cache would sometimes only be invalidated after the file
     system browser reloaded the directory, resulting in an outdated directory
     listing.
    </para></listitem>

   </itemizedlist>

 </listitem>

<listitem><para><emphasis role="bold">Version 0.3.3</emphasis>
   requires jEdit 4.0pre3.</para>

   <itemizedlist>

    <listitem><para>
     Now uses jEdit 4.0pre3 I/O error reporting API.
    </para></listitem>

    <listitem><para>
     <guibutton>Reload</guibutton> button in file system browser did not
     flush subdirectories of the current directory from the cache.
    </para></listitem>

    <listitem><para>
     You can now use @ in user names (some ISPs require this).
    </para></listitem>

    <listitem><para>
     File listings from Microsoft FTP servers in DOS listing mode are now
     parsed.
    </para></listitem>

  </itemizedlist>
 </listitem>

  <listitem><para><emphasis role="bold">Version 0.3.2</emphasis>
   requires jEdit 4.0pre2.</para>

   <itemizedlist>
    <listitem><para>
     Plugin is now compiled using Ant.
    </para></listitem>

    <listitem><para>
     Fixed another file rename problem with the Microsoft FTP server.
    </para></listitem>

    <listitem><para>
     Updated for jEdit 4.0pre2 API changes.
    </para></listitem>

    <listitem><para>
     After connecting to an FTP server, the home directory is now shown by
     default, which is much more intuitive than starting at the root directory
    </para></listitem>

    <listitem><para>
     File names with leading spaces should now work correctly.
    </para></listitem>

    <listitem><para>
     When running on jEdit 4.0pre3 or later, the <guibutton>Reload</guibutton>
     button in the file system browser should actually work now.
    </para></listitem>
   </itemizedlist>
  </listitem>

  <listitem><para><emphasis role="bold">Version 0.3.1</emphasis>
   requires jEdit 2.7pre2.</para>

   <itemizedlist>
    <listitem><para>
     Renaming and saving files didn't work with the Microsoft FTP server.
    </para></listitem>

    <listitem><para>
     Another minor tweak to the file list patterns.
    </para></listitem>

    <listitem><para>
     Connecting to a different port (by appending
     <filename>:<replaceable>port</replaceable></filename>
     to the host name) didn't work properly
    </para></listitem>
   </itemizedlist>
  </listitem>

  <listitem><para><emphasis role="bold">Version 0.3</emphasis>
   requires jEdit 2.7pre2.</para>

   <itemizedlist>
    <listitem><para>
     Soft links were not resolved properly.
    </para></listitem>

    <listitem><para>
     File names with spaces didn't work.
    </para></listitem>

    <listitem><para>
     Made listing parsing code more compatible with different servers.
    </para></listitem>

    <listitem><para>
     <guimenuitem>Open from FTP Server</guimenuitem> command didn't select
     the newly opened buffer.
    </para></listitem>

    <listitem><para>
     File permissions are now preserved when a file is being saved.
    </para></listitem>

    <listitem><para>
     Code cleanups
    </para></listitem>

    <listitem><para>
     Documentation is now in DocBook-XML format.
    </para></listitem>

  </itemizedlist>

  </listitem>

 </itemizedlist>

</appendix>

</book>