/jEdit/tags/jedit-4-0-pre5/doc/FAQ/faq-items2.xml

<!-- jEdit buffer-local properties:                     -->
<!-- :indentSize=1:noTabs=true:maxLineLen=72:tab Size=2: -->

<!-- jEdit FAQ									        -->
<!-- Copyright (C) 2002 John Gellene                    -->

<!-- $Id: faq-items2.xml 3997 2002-01-26 13:40:00Z jgellene $
-->

<sect1 id="installing-jedit"><title>Installing and Starting jEdit</title>
<para>
  This section deals with installing jEdit using the Java-based
  installation program, as well as installation issues that are specific
  to particular operating systems. It also deals with problems
  encountered in starting up jEdit.
</para>

<qandaset defaultlabel="qanda">

  <qandadiv id="install-general">
    <title>General installation questions</title>
    <qandaentry>
      <question id="easy-howto-install"><para>
        What is the easiest way to install jEdit?
      </para></question>
      <answer><para>
        First, make sure you have a working installation of the Java platform.
        You will need to know the path of the Java application launcher, which is
        called <filename>java.exe</filename> on Windows systems and simply
        <filename>java</filename> on others.
      </para>
      <para>
        Next, decide whether you want the current stable version or the latest
        development version. The stable version is a good choice for first-time
        users. Download the Java installer for the version you have chosen from
        the jEdit web site; it consists of a single file with a name in the
        style <filename>jeditXXXinstall.jar</filename>.
        This file is a compressed archive containing all of the files you need
        for jEdit to run as well as an installer application written in Java.
        You can put this file anywhere on your hard disk that is convenient.
      </para>
      <para>
        To run the installer, do whatever you normally do to run a Java jar
        archive. If this is your first time, follow these steps:
      </para>
      <procedure>
        <step><para>Open a terminal or command interpreter window.</para></step>
        <step><para>Change the current directory to the directory in which you
        have stored the jEdit installer file.</para></step>
        <step><para>Run this command:
          <userinput>[full path to java application launcher] -jar
          jeditXXXinstall.jar</userinput></para>
        </step>
      </procedure>
      <para>
        The installer will load and display a series of dialogs for selecting a
        few simple options, including the directory in which you wish jEdit
        installed. It will also tell you how much disk space you need for
        the main program and various installation options.
      </para>
      <para>
        If this is your first download of jEdit, you should definitely install
        the set of macros that come with the application. Many of them are
        useful for all programmers, and even the ones you don't use can
        serve as models for when you eventually begin writing your own macros.
      </para>
      <para>
        The installation process is very short. If you are installing the
        program on Windows and you select the jEditLauncher option, you should
        be able to start jEdit by clicking on any of the icons that the
        installation program provides. On other systems, you can enter
        <userinput>jedit</userinput> in a terminal window or create your own
        desktop or menu shortcut.
      </para></answer>
    </qandaentry>
    <qandaentry>
      <question id="install-no-such-file"><para>
        What should I do when the installer displays the message,
        <screen>No such file or directory</screen>?
      </para></question>
      <answer><para>
        The full message that you may receive from the Java application launcher
        begins as follows:
        <screen>Exception in thread "main" java.util.zip.ZipException: No such file or directory
...</screen>
        This means that the Java application launcher cannot read the
        jar archive file that you specified on the command line. If your Java
        runtime environment otherwise runs properly, then either you have named
        the incorrect file name or the installation file is corrupt or
        incomplete. Check the file name, download the installer again if
        necessary, and be sure to follow any specific instructions for your
        operating system posted on the <ulink
        url="http://www.jedit.org">jEdit web site</ulink>.
      </para></answer>
    </qandaentry>

<qandaentry>
	<question id="install-noclassdef">
		<para>
			After downloading <filename>jedit322install.jar</filename>, I tried to run
			<userinput>java jedit322install.jar</userinput>, but got the error message,
			<screen>Exception in main(), NoClassDefFoundError: jedit322install/jar.</screen> What am I doing wrong?
		</para>
	</question>
	<answer>
  
		<para>
			You need to specify the <userinput>-jar</userinput> option for the Java
			application loader so that the loader will search the installation archive
			for the starting class file. Without the option, it treats the archive as a
			single class file (which it is not!), thus producing the error. The correct
			command line would be <userinput>java -jar jedit322install.jar</userinput>.
		</para>
	</answer>
</qandaentry>



  </qandadiv>

  <qandadiv id="install-linux">
    <title>Installing jEdit on Linux systems</title>

<qandaentry>
	<question id="install-jedit-home">
		<para>
			After installing jEdit on Linux, running the <userinput>jedit</userinput>
			command causes the error message:
			<screen>Warning: JAVA_HOME environment variable not set</screen>
			How can I fix this?
		</para>
	</question>
	<answer>
		<para>
			Your <filename>jedit</filename> shell script should
			be modified to have the <userinput>JAVA_HOME</userinput> variable
			defined as the directory containing	the executables of
			your desired Java runtime environment (JRE).
		</para>
	</answer>
</qandaentry>

<qandaentry>
	<question id="install-mandrake-kaffe">
		<para>
			How can I get jEdit to run on Mandrake Linux 8.1? When I try to start the
			program, I keep getting an error which begins as follows:
			<screen>java/lang/NoClassDefFoundError: Ljavax/swing/text/Document; at
			java.lang.reflect.Method.invoke(Method.java:native) at
			kaffe.jar.ExecJarName.main</screen>
		</para>
	</question>
	<answer>
	  	<para>
			This version of Mandrake Linux uses the Open Source Kaffe package as its default
			Java virtual machine. The jEdit application requires Sun's Swing package, which
			is not included with Kaffe. However, the developers of Kaffe claim that Kaffe
			and Swing are fully compatible. You therefore have two choices. You can obtain a
			copy of Sun's Swing package (version 1.1.1 is known to work with Kaffe) and
			place it on the classpath used by Kaffe. Alternatively, you can install Sun's
			JDK for Linux and modify the script used to launch jEdit to point to Sun's
			application loader instead of Kaffe. This is likely to be a simpler operation.
		</para>
	</answer>
</qandaentry>

<qandaentry>
	<question id="install-linux-keyboard">
		<para>
			I installed jEdit 3.2.2 from the RPM on Mandrake 8.1 and I am unable to send any
			keyboard inputs to jEdit. But the mouse interacts with the program just fine. I
			have tried running it on Sun's JDK 1.3.1 and Blackdown's latest JDK (Dec. 2001)
			without any luck.
		</para>
	</question>
	<answer>
		<para>
			This problem has been reported with various combinations of window managers and
			desktop environments. The IBM JDK has not been reported to have this problem. In
			addition, there have not been reported problems with the Sun and Blackdown JDK's
			when running under the Sawfish window manager.
		</para>
	</answer>
</qandaentry>

</qandadiv>

<qandadiv id="install-mac">
  <title>Install jEdit on MacOS</title>
  <qandaentry> 
    <question id="install.mac9-basic">
      <para>How do I install jEdit on MacOS 8 or MacOS 9?</para>
    </question>
    <answer>
      <para>
        To install Jedit on Mac OS 9.1 and earlier download JBinary which 
        is part of the MRJ SDK 2.2 package available from Apple. Once 
        you have installed JBinary do the following:
      </para>  
      <procedure>
        <step><para>Drag the jEdit installer to JBinary and JBinary 
        will launch.</para></step>
        <step><para>In the Command window in the Class path box replace 
        <userinput>jedit322install,</userinput> with 
        <userinput>installer.Install</userinput>.</para></step>
        <step><para>Then click the Run button. The installer will 
        install jEdit on your system.</para></step>
      </procedure>
      <para>
        Once you have completed installing jEdit locate the jedit.jar 
        file and do the following:
      </para>  
      <procedure>
        <step><para>Drag the <filename>jedit.jar</filename> to JBinary 
        and JBinary will launch.</para></step>
        <step><para>In the Command window in the Class path box replace 
        <userinput>jedit</userinput> with 
        <userinput>org.gjt.sp.jedit.jEdit</userinput>.</para></step>
        <step><para>Then click the Save settings button. It will ask 
        for an application name and will create a double-clickable icon 
        on your desktop.</para></step>
        <step><para>Double-click on your icon to launch jEdit.</para></step>
       </procedure>
     </answer>
   </qandaentry>  

</qandadiv>


  <qandadiv id="install-windows">
    <title>Installing jEdit on Windows</title>
    <qandaentry>
      <question id="install-windows-basic"><para>
        Is there anything different about installing jEdit on Windows?
      </para></question>
      <answer><para>
        For the Microsoft Windows family of operating systems, jEdit
        provides an additional package of features called jEditLauncher.
        These features include:
        <itemizedlist>
            <listitem><para>
              Built-in shortcut icons for launching jEdit;
            </para></listitem>
            <listitem><para>
              Support for opening files in jEdit using custom entries in
              the context (right-click) menu of the Windows shell;
            </para></listitem>
            <listitem><para>
              Support for running BeanShell scripts in jEdit from
              outside the application;
            </para></listitem>
            <listitem><para>
              Support for launching jEdit and loading files using
              scripting languages such as VBScript, Perl and Python;
            </para></listitem>
            <listitem><para>
              Automatic uninstallation of jEdit using the
              <quote>Add/Remove Programs</quote> applet in Control Panel.
            </para></listitem>
        </itemizedlist>
        The package is a recommended option that is selected by default when you
        install jEdit. The Java installer application launches a separate
        Windows installer module for the native Windows executables that
        comprise the jEditLauncher package. If the installation involves an
        upgrade, you may be asked to reboot your computer to complete the process.
      </para></answer>
    </qandaentry>

    <qandaentry>
      <question id="install-windows-components"><para>
        Do I need any special Windows components to run jEditLauncher?
      </para></question>
      <answer><para>
        Regardless of the version of Windows that you use, if you have kept it
        reasonably up-to-date with service packs or component upgrades from
        Microsoft, you should have no trouble running jEditLauncher.
        Users of Windows 98, Windows ME, Windows NT (version 4.0) or
        Windows 2000 have not reported problems involving missing
        components.
      </para>
      <para>
        Some users of older versions of Windows 95 may need to upgrade their
        version of the Windows Sockets package. Others may be missing
        Microsoft's package for supporting DCOM (Distributed Component
        Object Model) components on Windows 95. Both the <ulink url=
        "http://www.microsoft.com/windows95/downloads/contents/wuadmintools/s_wunetworkingtools/w95sockets2/">
        Windows Sockets upgrade</ulink> and the <ulink
        url="http://www.microsoft.com/com/dcom/dcom95/dcom1_3.asp">
        DCOM package</ulink> are available for download from Microsoft.
      </para></answer>
    </qandaentry>

    <qandaentry>
        <question id="install-windows-vm"><para>
            Can I run jEdit on Microsoft's virtual machine?
        </para></question>
        <answer>
          <para>
             You can run version 3.2.2 if you put Sun's Swing 1.1.1
             package in the classpath of Microsoft's Java application loaders
             <command>jview</command> or <command>wjview</command>.
             An article describing the advantages and disadvantages
             of doing this, and detailing the necessary procedures, may
             be found on the <ulink
             url="http://community.jedit.org/article.php?sid=14&amp;mode=&amp;order=0">jEdit
             Community</ulink> web site.
         </para>
           <para>
                The forthcoming new version of jEdit, version 4.0, will require
                the Java 2 platform, and therefore will not be compatible with
                Microsoft's virtual machine.
            </para>
        </answer>
    </qandaentry>


<qandaentry>
	<question id="install-windows-badcommand">
		<para>
			When trying to install jEdit on Windows Me with an MS-DOS prompt, after entering
			<userinput>java -jar jedit322install.jar</userinput> I get the message
			<userinput>bad command or file	name</userinput>.
			I have tried various alternatives but still cannot install.
		</para>
	</question>
	<answer>
		<para>
			You should confirm that you have a Java runtime environment installed, which
			will include <filename>java.exe</filename>. Make sure that the directory
			containing <filename>java.exe</filename> is found
			in the value of your <filename>PATH</filename> environment variable.
			Otherwise you should give the full path to <filename>java.exe</filename>
			on your command line.
		</para>
	</answer>
</qandaentry>



<qandaentry>
	<question id="install-windows-errmessage">
		<para>
			After installing jEdit on Windows, when I try to run
			<filename>jedit.exe</filename> I get the message
			<screen>The JEditLauncher component does not appear to be installed.</screen>
		</para>
	</question>
	<answer>
		<para>
			The dialog presenting this message asks if you would like to install the
			launcher. Select <userinput>Yes</userinput> and supply further information
			as prompted. A file	named <filename>install.log</filename> is generated in the
			same directory as <filename>jedit.exe</filename> that
			contains information on the launcher's installation. You can send this file
			along with jEdit's Activity Log if you continue to have problems running jEdit
			with the launcher package.
		</para>
	</answer>
</qandaentry>

<qandaentry>
	<question id="install-error-regkey">
		<para>
			When I try to run the jEdit installation package in Windows, I get an error
			message, <screen>Error opening registration key
            "software\javasoft\java runtime	environment".</screen> How can I fix this?
		</para>
	</question>
	<answer>
		<para>
			The problem is not with jEdit but may be caused by your installation of the Java
			runtime environment. Under Windows, Sun's Java application loader relies on
			entries in the Windows registry to find the files that create the runtime
			environment and a Java virtual machine. The loader (java.exe or javaw.exe) is
			unable to find the necessary registration entry and therefore sends the error
			message. The best approach to fixing this is to uninstall and reinstall the JDK.
		</para>
	</answer>
</qandaentry>

  </qandadiv>


  <qandadiv id="problems-starting">
    <title>Problems starting jEdit</title>

    <qandaentry>
      <question id="wont-start"><para>
        jEdit won't start.  What should I do?
      </para></question>
      <answer><para>
        If you don't have a clue as to why you cannot run jEdit, it's
        best to perform a step-by-step diagnosis.  Begin by finding the
        Java application loader you are using: <userinput>java.exe</userinput>,
        <userinput>javaw.exe</userinput> or <userinput>java</userinput>. Make sure
        it is running by entering its full path with the <userinput>-h</userinput>
        parameter in a terminal or console window.  If you can't find
        the Java application loader, your Java runtime environment package
        may be missing or incomplete.
      </para>
      <para>
          Next, find where you have installed jEdit.  You should look
          for the file <filename>jedit.jar</filename> which contains all
          of the application's Java class files in a compressed archive.
      </para>
      <para>
          Once you have both files, run the Java loader with the
          <userinput>-jar</userinput> option and with
          <filename>jedit.jar</filename> as the target.  Make sure that
          you either specify full paths for both files or that the
          directories for the files are part of your <filename>PATH</filename>
          environment variable. If jEdit does not load at this point, the likely
          problem is a corrupt <filename>jedit.jar</filename> file. Try
          downloading the application again.
      </para>
      <para>
          If jEdit does load using this procedure, you need to examine
          the <quote>shortcut</quote> loading mechanism you wish to use.
      </para>
      <para>
        On Linux and MacOS X, you need to find and examine the <filename>jedit</filename>
        shell script provided by the installation routine to confirm that the
        script's commands target the correct files and locations, and that
        variables like <filename>JAVA_HOME</filename> are either defined in the
        script or elsewhere in your shell's environment. Don't forget to make
        sure that the script's file permissions allow you to execute it.
      </para>
      <para>
          On Windows, if you are using a batch script to run jEdit, the
          same points (other than file permissions) apply to examining
          <filename>jedit.bat</filename>.  If you are using
          jEditLauncher, run <userinput>jedit /p</userinput> in jEdit's
          installation directory from a command line to get the custom
          loader's setup dialog.  Here you can check the paths for both
          the Java application loader and jEdit as well as any command
          line parameters for both programs.  If the parameters seems correct
          but jEdit will not load with the Windows launcher, try
          uninstalling and reinstalling the launcher by running
          <userinput>jedit /u</userinput> followed by
          <userinput>jedit /i</userinput>.
      </para>
      <para>
          If at this point you're still stuck, ask for help on the
          jedit-users mailing list, the jEdit Community
          <quote>Installation</quote> message board or on IRC.
          You're bound to find someone quickly.
      </para>
      </answer>
    </qandaentry>

    <qandaentry>
      <question id="start-missing-plugins"><para>
        After jEdit starts, I can't see all of the plugins I have downloaded.
        How can I make them appear?
      </para></question>
      <answer><para>
        If you use jEdit's Plugin Manager to download and install plugins, your
        plugins will be found in the <filename>jars</filename> subdirectory of
        one of two directories: either the directory in which jEdit is
        installed, or the current user's settings directory. These are the only
        location jEdit examines when it loads plugins at startup.
      </para>
      <para>
        The default location of the settings directory depends on your operating
        system. You can find out its location during a jEdit session by
        evaluating <userinput>jedit.getSettingsDirectory()</userinput> in BeanShell.
      </para>
      <para>
          The settings directory can be changed by using the
          <userinput>-settings</userinput> userinput line parameter. If you change the
          location of the settings directory with this parameter, jEdit will not
          be able to find plugin archive files in the old location.
          If you use or change the <userinput>-settings</userinput>
          parameter, make sure your plugins don't get left behind.
      </para>
      </answer>
    </qandaentry>

  </qandadiv>

</qandaset>

</sect1>