updates and ssh plugin docs

git-svn-id: svn+ssh://svn.internal.sanger.ac.uk/repos/svn/pathsoft/artemis/trunk@4124 ee4ac58c-ac51-4696-9907-e4b3aa274f04

docs/act_manual.sgml

@@ -31,7 +31,7 @@
 <!ENTITY lt CDATA "&#60;">
 <!ENTITY gt CDATA "&#62;">
 ]>
-<!-- $Header: //tmp/pathsoft/artemis/docs/act_manual.sgml,v 1.5 2005-02-22 11:52:29 tjc Exp $ -->
+<!-- $Header: //tmp/pathsoft/artemis/docs/act_manual.sgml,v 1.6 2006-03-01 11:32:37 tjc Exp $ -->
 <BOOK ID="index">
   <TITLE> The &prog; Manual </TITLE>
   <BOOKINFO>
@@ -40,7 +40,7 @@
     </PRODUCTNAME>
     <PUBDATE>16 May 2000</PUBDATE>
     <COPYRIGHT>
-      <YEAR>2000-2005</YEAR>
+      <YEAR>2000-2006</YEAR>
       <HOLDER>Genome Research Limited</HOLDER>
     </COPYRIGHT>
     <LEGALNOTICE>

docs/intro_chapter.sgml

@@ -75,9 +75,7 @@ is unpacked see <XREF LINKEND="RUNNINGUNIX">.
       <PARA>
 For MacOSX users a disk image is provided. This should be downloaded and
 double clicked on and the 'Readme.txt' opened and followed.
-          </SYNOPSIS>
         </PARA>
-      </SECT3>
     </SECT2>
 
     <SECT2 ID="DOSINSTALLATION">

docs/manual.sgml

@@ -2,6 +2,7 @@
 <!ENTITY intro SYSTEM "intro_chapter.sgml">
 <!ENTITY start SYSTEM "start_chapter.sgml">
 <!ENTITY mainwindow SYSTEM "main_window_chapter.sgml">
+<!ENTITY ssh SYSTEM "ssh_chapter.sgml">
 <!ENTITY options SYSTEM "options.sgml">
 <!ENTITY filemenu SYSTEM "file_menu.sgml">
 <!ENTITY menus SYSTEM "menus.sgml">
@@ -34,7 +35,7 @@
 ]>
 <!-- see: http://www.pcmedia.co.nz/~michaelh/intro-to-sgml/html/c04.htm-->
 <!-- and: http://www.pcmedia.co.nz/~michaelh/intro-to-sgml/html/template.sgml-->
-<!-- $Header: //tmp/pathsoft/artemis/docs/manual.sgml,v 1.5 2004-12-07 11:12:19 tjc Exp $ -->
+<!-- $Header: //tmp/pathsoft/artemis/docs/manual.sgml,v 1.6 2006-03-01 11:32:37 tjc Exp $ -->
 <BOOK ID="index">
   <TITLE> The &art; Manual </TITLE>
   <BOOKINFO>
@@ -43,7 +44,7 @@
     </PRODUCTNAME>
     <PUBDATE>22 February 1999</PUBDATE>
     <COPYRIGHT>
-      <YEAR>1999-2005</YEAR>
+      <YEAR>1999-2006</YEAR>
       <HOLDER>Genome Research Limited</HOLDER>
     </COPYRIGHT>
     <LEGALNOTICE>
@@ -79,5 +80,6 @@ sequence annotation tool.
   &intro;
   &start;
   &mainwindow;
+  &ssh;
   &options;
 </BOOK>

docs/ssh_chapter.sgml

+<CHAPTER ID="SSH-CHAPTER">
+  <TITLE>Secure Shell (SSH) Plugin To &prog</TITLE>
+
+  <SECT1 ID="SSH-OVERVIEW">
+    <TITLE>Overview of the SSH Plugin</TITLE>
+    <PARA>
+This is a plug-in to &prog that enables you to view and transfer
+files from a local machine (e.g. PC/MacOSX/deskpro) to another remote
+file system (i.e. any other file system that you have ssh access to).
+The main areas where this is useful are:
+   </PARA>
+   <ITEMIZEDLIST SPACING="compact">
+   <LISTITEM>
+   <PARA>
+file management for both local and remote files. Files can be transferred
+by dragging and droping between file systems. Multiple files can be
+selected and transferred in this way.
+   </PARA>
+   </LISTITEM>
+
+   <LISTITEM>
+   <PARA>
+launching Artemis and ACT with sequences and tab files from files
+on the remote machines.
+   </PARA>
+   </LISTITEM>
+
+   <LISTITEM>
+   <PARA>
+running BLAST and Fasta searches can be sent from the local machine that
+is running &prog and run on the remote machine. To do this the software
+(BLAST and Fasta) need to be set up on the remote side (see 
+<XREF LINKEND="SSH-CONFIG-SSH-SEARCHES">).
+   </PARA>
+   </LISTITEM>
+   </ITEMIZEDLIST>
+
+   </SECT1>
+
+   <SECT1 ID="SSH-LOGIN">
+    <TITLE>Loggin In</TITLE>
+    <PARA>
+From the &prog launch window go to the 'File' menu and select
+'Open SSH File Manager'. A file manager window will then open with a
+local file manager at the top. Underneath this is a remote file manager
+with a section to enter login details.
+
+<MEDIAOBJECT>
+<IMAGEOBJECT>
+   <IMAGEDATA FORMAT="gif" FILEREF="fm_login.gif">
+            </IMAGEOBJECT>
+</MEDIAOBJECT>
+
+   </PARA>
+
+   <PARA>
+If you can connect directly to the remote machine give the hostname, username
+and password. Alternatively if you are using a SSH tunnel (see <XREF
+LINKEND="SSH-TUNNEL-LOGIN">) then use localhost and the appropriate
+port number.
+   </PARA>
+
+  </SECT1>
+
+  <SECT1 ID="SSH-TUNNEL-LOGIN">
+    <TITLE>Setting up a SSH tunnel</TITLE>
+    <PARA>
+The tunneling capability of SSH Secure Shell allows people to access
+their email, intraweb pages and files securely even when working away
+from the office. This can be used with &prog and this section provides
+some examples of setting up tunnelling. It may be necessary to consult your
+friendly system administrator about the details on how best to do this.
+    </PARA>
+
+    <PARA>
+On <EMPHASIS>UNIX</EMPHASIS> the ssh configuration can be set in the file 
+<ComputerOutput>~/.ssh/config</ComputerOutput>. This
+contains the information to set up a tunnel that looks like this:
+    </PARA>
+
+    <PARA>
+    <SCREEN>
+Host *.sanger.ac.uk
+   LocalForward 2222 machine.sanger.ac.uk:22
+   User tjc
+    </SCREEN>
+    </PARA>
+
+    <PARA>
+Once this configuration file is in place you can login from a UNIX 
+window to set up a tunnel.
+    </PARA>
+
+    <PARA>
+On <EMPHASIS>Windows</EMPHASIS> you can use <XREF LINKEND="PUTTY">.
+    </PARA>
+
+    <PARA>
+When the tunnel has been established you can start artemis and enter
+'localhost' into the Hostname field in the login window and the port
+number (e.g. 2222 in the above example).
+    </PARA>
+
+<MEDIAOBJECT>
+<IMAGEOBJECT>
+   <IMAGEDATA FORMAT="gif" FILEREF="fm.gif">
+            </IMAGEOBJECT>
+</MEDIAOBJECT>
+
+  <PARA>
+The file manager can be used to drag and drop files between each file system.
+If you right click on a selected file this will provide you with a pop-up menu (see below)
+enabling you to delete, rename and open files.
+    </PARA>
+
+<MEDIAOBJECT>
+<IMAGEOBJECT>
+   <IMAGEDATA FORMAT="gif" FILEREF="fm_popup.gif">
+            </IMAGEOBJECT>
+</MEDIAOBJECT>
+
+    <PARA>
+Files on the remote file system can be double clicked on and opened
+in Artemis (in the same way they can be opened from the local file
+manager). Tab files can be read in by dragging them from the remote
+file manager and dropping them into the Artemis window.
+    </PARA>
+
+    <PARA>
+Note for ACT the sequence filename can be dragged from the file manager into
+the file selection box (if the files are not found locally the are then
+located on the server). The tab files in ACT can be dragged from the
+file manager and dropped on the relevant sequence display.
+    </PARA>
+
+    <PARA>
+When files are saved, if the entry orginated from the remote file system
+then this is saved locally in the current working directory and to the 
+remote file as well.
+    </PARA>
+  </SECT1>
+
+  <SECT1 ID="PUTTY">
+    <TITLE>Using Putty to Set Up A Tunnel</TITLE>
+    <PARA>
+On <EMPHASIS>Windows</EMPHASIS> you can use  
+<ULINK
+URL="http://www.chiark.greenend.org.uk/~sgtatham/putty/" TYPE="external">
+Putty</ULINK> to set up a ssh tunnel. Below are settings that can be used 
+in Putty to set up a SSH tunnel.
+    </PARA>
+
+<MEDIAOBJECT>
+<IMAGEOBJECT>
+   <IMAGEDATA FORMAT="gif" FILEREF="putty1.gif">
+            </IMAGEOBJECT>
+</MEDIAOBJECT>
+
+    <PARA>
+    </PARA>
+
+<MEDIAOBJECT>
+<IMAGEOBJECT>
+   <IMAGEDATA FORMAT="gif" FILEREF="putty2.gif">
+            </IMAGEOBJECT>
+</MEDIAOBJECT>
+
+    <PARA>
+SSH 2 only is probably recommended here.
+    </PARA>
+<MEDIAOBJECT>
+<IMAGEOBJECT>
+   <IMAGEDATA FORMAT="gif" FILEREF="putty3.gif">
+            </IMAGEOBJECT>
+</MEDIAOBJECT>
+
+    <PARA>
+X11 forwarding is not necessary.
+    </PARA>
+<MEDIAOBJECT>
+<IMAGEOBJECT>
+   <IMAGEDATA FORMAT="gif" FILEREF="putty4.gif">
+            </IMAGEOBJECT>
+</MEDIAOBJECT>
+
+    <PARA>
+Set the source port to 2222 and set the destination to
+hostname:port (e.g. pcs2.internal.sanger.ac.uk:22).
+    </PARA>
+<MEDIAOBJECT>
+<IMAGEOBJECT>
+   <IMAGEDATA FORMAT="gif" FILEREF="putty5.gif">
+            </IMAGEOBJECT>
+</MEDIAOBJECT>
+
+    <PARA>
+Click 'Add' to add this to the list of forwarded ports.
+    </PARA>
+
+<MEDIAOBJECT>
+<IMAGEOBJECT>
+   <IMAGEDATA FORMAT="gif" FILEREF="putty6.gif">
+            </IMAGEOBJECT>
+</MEDIAOBJECT>
+
+    <PARA>
+Run Artemis and select the 'SSH File Manager' from the 'File'
+menu. At the bottom fill in login details and click on the
+'Connect' button.
+Logging in may take a minute (depending on the connection).
+    </PARA>
+
+<MEDIAOBJECT>
+<IMAGEOBJECT>
+   <IMAGEDATA FORMAT="gif" FILEREF="putty7.gif">
+            </IMAGEOBJECT>
+</MEDIAOBJECT>
+
+  </SECT1>
+
+  <SECT1 ID="SSH-RUNNING-DB-SEARCHES">
+    <TITLE>Using the SSH connection to run Fasta and BLAST</TITLE>
+    <PARA>
+Using the SSH connection you can send Fasta and BLAST searches to be run 
+on the remote machine. If you have not already be prompted to login
+(i.e. when opening up the SSH file manager), you will then be asked
+for your login details. The sequence files that are to be searched against the
+database are then sent to the remote machine.
+Once the search has finished the results are transferred back afterwards.
+If &prog detects that you have opened up an entry from the remote file system
+the analysis will be run in the directory you open the entry from. The results
+in this case are stored on both the local and remote machines.
+    </PARA>
+
+    <PARA>
+To keep Fasta and BLAST searches on your local machine and the remote file system
+<EMPHASIS>in-sync</EMPHASIS>:
+    </PARA>
+
+   <ITEMIZEDLIST SPACING="compact">
+   <LISTITEM>
+   <PARA>
+copy any previously run fasta and blast directories from the remote machine to your
+local file system. This can be done by making a tar ball of the directory:
+e.g. creating a tar file of a 'fasta' directory
+   </PARA>
+   <PARA>
+<SCREEN>
+tar cvf tar_ball_name.tar fasta
+</SCREEN>
+   </PARA>
+   </LISTITEM>
+   <LISTITEM>
+   <PARA>
+Then transfer this file to the local project directory and extract with:
+   </PARA>
+   <PARA>
+<SCREEN>
+tar xvf tar_ball_name.tar
+</SCREEN>
+   </PARA>
+   </LISTITEM>
+   <LISTITEM>
+   <PARA>
+when launching Artemis, make sure you first change directory to the directory above
+the 'fasta' directory that has been unpacked.
+   </PARA>
+   </LISTITEM>
+   <LISTITEM>
+   <PARA>
+open the files from the remote file system in the file manager. It then knows where 
+to save it back to.
+   </PARA>
+   </LISTITEM>
+   </ITEMIZEDLIST>
+  </SECT1>
+
+  <SECT1 ID="SSH-CONFIG-SSH-SEARCHES">
+    <TITLE>Configuring Searches to be run via SSH</TITLE>
+    <PARA>
+This would most likely be done by a systems administrator. The databases and
+fasta and BLAST software need to be set up on the remote machine. Once this is
+done the commands that are sent from the Artemis/ACT client to the remote
+machine are controlled by a 'j2ssh.properties' file, see below for example of
+this file. This needs to be put in the CLASSPATH for Artemis/ACT or the one in
+the distribution (lib/j2ssh/j2ssh.properties) modified.
+   </PARA>
+
+    <PARA>
+The j2ssh.properties file also hold default information. For example default
+parameters can be set for the login prompt, the working directory (for searches
+when sequences are opened on the local side) and any extra directories (other
+than the users home directory) to display in the file manager.
+   </PARA>
+
+   <PARA>
+   <SCREEN>
+#
+#
+# Configuration file for using SSH file management and
+# database searches. 
+#
+#
+# default login options
+port=2222
+host=localhost
+#
+#
+# Generic default options
+#
+blastp=blastall -p blastp
+blastx=blastall -p blastx
+tblastx=blastall -p tblastx
+blastn=blastall -p blastn
+fasta=fasta33_t -B -S -q -b 100 -H -l /data/fasta/pubseqgbs
+fastx=fastx33_t -B -S -q -b 40 -H -l /data/fasta/pubseqgbs
+#
+#
+# default working directory
+wdir=/scratch
+#
+#
+# aliases used for fasta
+%uniprot=%U
+%uniprot_archaea=%A
+%uniprot_bacteria=%B
+%uniprot_eukaryota=%E
+%uniprot_viruses=%V
+%uniprot_rest=%R
+%malaria=%M
+%kineto_aa=%K
+default_db=%uniprot_bacteria
+#
+#
+# remote directories to use as roots in the file manager
+remotedir.PD=/nfs/pathdata
+remotedir.YP=/nfs/disk222/yeastpub
+# local directories to use as roots in the file manager
+localdir.PD=/nfs/pathdata
+localdir.YP=/nfs/disk222/yeastpub
+   </SCREEN>
+   </PARA>
+
+  </SECT1>
+
+</CHAPTER>