/jEdit/tags/jedit-4-1-pre5/doc/FAQ/faq-items1.xml

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

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

<!-- $Id: faq-items1.xml 4040 2002-02-17 13:41:20Z jgellene $
-->

<sect1 id="faq-intro"><title>Introduction</title>
<para>
  This document explains many of the basic features of jEdit and provides
  solutions for commonly encountered problems. It is not the principal
  resource for learning how to use and customize jEdit. The application
  includes an extensive User's Guide available from within jEdit by
  selecting <guimenuitem>jEdit Help</guimenuitem> on the
  <guimenu>Help</guimenu> menu.
</para>
<para>
  The User's Guide includes tutorials on writing macros and plugins as
  well as an annotated guide to jEdit's Application Programming Interface
  (API). It is worth browsing through the User's Guide to get a full sense
  of what jEdit has to offer. This document is intended to supplement the
  User's Guide by focusing on specific, relatively narrow topics in the
  traditional question-and-answer format.
</para>
<para>
  Each section of this document deals with a different category of topics,
  and each begins with a listing of the questions covered. This should
  allow you to find the information you are seeking quickly.
</para>

</sect1>

<sect1 id="getting-jedit"><title>General Information and Availability</title>
<para>
  This section deals with some background information and how to obtain the
  latest version of jEdit.
</para>

<qandaset defaultlabel="qanda">

  <qandadiv id="about">
    <title>About jEdit</title>
    <qandaentry>
      <question id="whatis"><para>
        What is jEdit?
      </para></question>
      <answer><para>
        jEdit is a programmer's text editor written in Java, being
        developed by Slava Pestov and others. It has an easy to use
        interface that resembles that of many other Windows and MacOS
        text editors.  It is also highly customizable, and contains a
        <quote>plugin</quote> architecture that allows its features to
        be extended by additional programs.
      </para></answer>
    </qandaentry>
    <qandaentry>
      <question id="difftext"><para>
        What is the difference between a text editor and a word
        processor?
      </para></question>
      <answer><para>
        These categories are not absolute but refer to the primary
        purpose of an editing program and the focus of its features.
        </para>
        <para>
        A text editor is an application that edits files containing plain text
        without automatically formatting the text for printing or other publication.
        Typically the contents of such a file consists of data used by another
        application - for example, source code that a compiler will process or
        markup text that a web browser will display. A word processor deals with
        the preparation of documents for printing or similar publication.
        Besides editing text, a modern word processor allows the user to choose
        multiple fonts, margin sizes, line spacing, indentation, and a variety
        of other details that affect the appearance of the document being
        edited. In a text editor, these features are present, if at all, only in
        a basic form, and for the limited purpose of helping the user compose
        and organize the text. In place of word processing features, a text
        editor contains many features that allow the user to prepare and work with
        text quickly and efficiently.
        </para>
        <para>
        The jEdit application is a text editor, not a word processor. It
        contains a large assortment of features for manipulating source code,
        markup text, and other text files. As a programmer's text editor, it
        also has many features to help programmers manage their projects and
        work with other programming tools.
      </para></answer>
    </qandaentry>
    <qandaentry>
      <question id="features"><para>
        What features does jEdit have?
      </para></question>
      <answer><para>
        The short answer is, too many to list here.  There is a detailed
        list available on the <ulink
        url="http://www.jedit.org/index.php?page=features">jEdit web
        site</ulink>, but here are some of the major features:
       </para>
       <itemizedlist>
          <listitem><para>
            Comprehensive online help
          </para></listitem>
          <listitem><para>
            Multiple editor windows and split editing panes within a single
            editing window
          </para></listitem>
          <listitem><para>
            Unlimited undo/redo
          </para></listitem>
          <listitem><para>
            Copy and paste with an unlimited number of clipboards
            (known as <quote>registers</quote>)
          </para></listitem>
          <listitem><para>
            <quote>Markers</quote> for remembering positions
            in files to return to later
          </para></listitem>
          <listitem><para>
            Rectangular selection
          </para></listitem>
          <listitem><para>
            Multiple selection for manipulating several chunks of text at once
          </para></listitem>
          <listitem><para>
            Syntax highlighting for more than 60 file types
          </para></listitem>
          <listitem><para>
            Intelligent bracket matching that skips quoted literals
            and comments
          </para></listitem>
          <listitem><para>
            Auto indent and word wrap
          </para></listitem>
          <listitem><para>
            Abbreviations
          </para></listitem>
          <listitem><para>
            <quote>Folding</quote> display mode that hides levels of
            indented text specified by the user
          </para></listitem>
          <listitem><para>
            Search and replace using both literal text and regular expressions
          </para></listitem>
          <listitem><para>
            <quote>HyperSearch</quote> option to show all found
            matches in a list
          </para></listitem>
          <listitem><para>
            File management functions available from within jEdit, including
            deleting and renaming files and creating new directories
          </para></listitem>
          <listitem><para>
            Choice of character encoding for loading and saving files
          </para></listitem>
          <listitem><para>
            Automatic compression and decompression of GZipped (.gz) files
          </para></listitem>
          <listitem><para>
            Plugin support for loading files from ZIP and TAR archives
          </para></listitem>
          <listitem><para>
            Plugin support for loading and saving files on FTP servers
          </para></listitem>
          <listitem><para>
            Fully customizable keyboard shortcuts, tool bar and right-click
            context menu
          </para></listitem>
          <listitem><para>
            Macro system permitting recording and writing of macros in the
            BeanShell scripting language
          </para></listitem>
          <listitem><para>
            An internal <quote>plugin manager</quote> that downloads and installs
            new and updated plugins from within jEdit
          </para></listitem>

        </itemizedlist>
      </answer>
    </qandaentry>

    <qandaentry>
      <question id="what-plugin"><para>
        What is a jEdit <quote>plugin</quote>?
      </para></question>
      <answer><para>
        A plugin is an application that is designed to work with jEdit
        by providing additional features that can be used from within
        the main program. Often the plugin will provide a visible user
        interface in a window that can be docked to jEdit's main view
        window.
      </para>
      <para>
        There are currently over 40 publicly available plugins that
        provide such services as a Java source code browser, a
        command-line shell, templated text insertion, and source code
        project management. They can be downloaded, installed, and kept
        current from within jEdit's <quote>Plugin Manager</quote>.
        There is also a section of the jEdit web site called <ulink
        url="http://plugins.jedit.org/">Plugin Central</ulink> that
        maintains a descriptive index and download links for all publicly
        available plugins.
      </para>
      <para>
        Additional questions and answers regarding plugins may be found
        in the section of this document entitled
        <link linkend="plugins"><quote>Working with
        Plugins</quote></link>.
      </para></answer>
    </qandaentry>

    <qandaentry>
      <question id="get-doc"><para>
        How do I get documentation on jEdit?
      </para></question>
      <answer><para>
        There is a comprehensive User's Guide available from within the program
        using the <guimenu>Help</guimenu> menu. The User's Guide can also
        be downloaded from the <ulink
        url="http://www.jedit.org/index.php?page=download&amp;platform=source">
        jEdit web site</ulink> in Portable Document Format (PDF), suitable for
        online display or printing.
      </para></answer>
    </qandaentry>
    <qandaentry>
      <question id="is-newsgroup"><para>
        Is there a newsgroup or mailing list devoted to jEdit?
      </para></question>
      <answer><para>
        Currently there is no newsgroup devoted to jEdit. There are three
        active mailing lists that are freely available by subscription:
      </para>
      <itemizedlist>
        <listitem><para>
          The <ulink url=
          "http://lists.sourceforge.net/lists/listinfo/jedit-users">
          jedit-users list</ulink>, for comments and questions about
          using jEdit and its features
        </para></listitem>
        <listitem><para>
          The <ulink url=
          "http://lists.sourceforge.net/lists/listinfo/jedit-devel">
          jedit-devel list</ulink>, for discussion of development issues by
          members of the developer team and other interested persons
        </para></listitem>
        <listitem><para>
          The <ulink url=
          "http://lists.sourceforge.net/lists/listinfo/jedit-announce">
          jedit-announce list</ulink>, a low-volume list used for announcing
          new releases of jEdit and plugins
        </para></listitem>
      </itemizedlist>
      <para>
        Each of these lists can be obtained on a full-text message or a daily
        digest basis.  The daily digest bundles groups of postings in a single
        email message.
      </para>
      <para>
        If you are only interested in version announcements and plugin updates,
        <ulink url="http://lists.sourceforge.net/lists/listinfo/jedit-announce">
        subscribe to the jedit-announce list</ulink>. If you would like to participate
        in discussion or ask questions regarding jEdit, <ulink url=
        "http://lists.sourceforge.net/lists/listinfo/jedit-users">subscribe to the
        jedit-users list</ulink>. If you are interested in jEdit's development or want
        to write plugins, <ulink
        url="http://lists.sourceforge.net/lists/listinfo/jedit-devel">
        subscribe to jedit-devel</ulink>.
      </para>
      <para>
        Do not cross-post to both lists. All jEdit developers are
        subscribed to both the jedit-users and jedit-devel lists, so a post to
        jedit-users will be seen by most members of both lists. Also, keep in
        mind that both jEdit-users and
        jEdit-devel are high-traffic lists, and can fill up your mailbox unless
        you check your email regularly.
      </para>
      </answer>
    </qandaentry>
    <qandaentry>
      <question id="is-website"><para>
        Is there a web site devoted to jEdit?
      </para></question>
      <answer><para>
        There are several. The official <ulink url="http://www.jedit.org">jEdit
        web site</ulink> contains extensive information on all things having to
        do with jEdit. There are also resources available for those interested
        in jEdit development on the <ulink url=
        "http://sourceforge.net/projects/jedit">jEdit project page</ulink> of
        the <ulink url="http://sourceforge.net">SourceForge web site</ulink>.
      </para>
      <para>
        The <ulink url="http://community.jedit.org">jEdit Community</ulink> web
        site has articles on jEdit and related topics, user-submitted macros and
        other download resources, and listings of web links of interest to jEdit
        users. It has a message board system to allow users to ask
        questions and provide feedback on the project without having to subscribe
        to jEdit's mailing lists. Because the message boards have relatively low
        volume, using the mailing lists will often be a more effective
        approach.
      </para>
      <para>
          The jEdit Community site also has an <quote>Interactive FAQ</quote>
          facility that allows you to post questions to be answered by
          other users, and a screenshot gallery containg images
          submitted by users.
      </para></answer>
    </qandaentry>
    <qandaentry>
      <question id="copyright"><para>
        Are there copyright restrictions on the use of jEdit?
      </para></question>
      <answer><para>
        The jEdit application is free, <quote>Open Source</quote> software released
        under the <ulink url="http://www.gnu.org/licenses/licenses.html#GPL">
        GNU General Public License</ulink>. This ensures that jEdit and its source
        code remains freely available for use and distribution by the public.
        For specific copyright questions, you should review the General Public
        License and seek appropriate advice. Broadly speaking, there are no
        restrictions on the use of the program as a text editor, and its source
        code can be copied or modified for use in another program that is
        governed by the General Public License.
      </para>
      <para>
        Plugin application that are available using jEdit's Plugin Manager
        facility, as well as plugins available through the <ulink
        url="http://plugins.jedit.org">Plugin Central</ulink> web site or
        <ulink url="http://community.jedit.org">jEdit Community</ulink>, are
        governed either by the General Public License or another commonly
        recognized <quote>Open Source</quote> software license.  This means
        that use of the application, including use for commercial purposes,
        is unrestricted without any requirement of royalty or license fee payments.
        To incorporate source code or an application or plugin as a whole in another
        application, you must consult the specific license terms to determine
        whether and on what basis you are permitted to do so.
      </para>
      </answer>
    </qandaentry>
    <qandaentry>
      <question id="java-only"><para>
        Is jEdit only useful for programming in Java?
      </para></question>
      <answer><para>
        Absolutely not. Many of the jEdit's plugin applications, and a few of
        the macros distributed with the program, target the Java language or
        integrate tools used in Java development.  However, the core application
        is designed to work with any programming or markup language.  Included
        with jEdit are packages providing syntax highlighting,
        abbreviations and other programming support for over 60 programming
        languages and file types, including C, C++, C#,
        Cobol, HTML, Java, Javascript, Lisp, Pascal, Perl, PHP, Python,
        TCL, Visual Basic and XML. The full list can be found on the
        <ulink url="http://www.jedit.org/index.php?page=features">jEdit web
        site</ulink>.
      </para></answer>
    </qandaentry>
    <qandaentry>
      <question id="knowing-java"><para>
        Do I need to know Java to use jEdit?
      </para></question>
      <answer><para>
        No. In fact, you do not need to know any specific programming language
        other than the ones with which you work.
      </para>
      <para>
        At some point in your use of jEdit, you will no doubt want to write your
        own macros to execute long or complex routines with a single command or
        keyboard shortcut. Macros in jEdit are written in a simplified dialect
        of Java called <ulink url="http://www.beanshell.org"> BeanShell</ulink>.
        Its syntax will be familiar to users of Java, C++ and other
        object-oriented languages, and it is not hard to learn even if you have
        no experience with those languages.  The User's Guide provided
        with jEdit contains an extensive tutorial on writing macros.
      </para></answer>
    </qandaentry>
    <qandaentry>
      <question id="needed-software"><para>
        What software do I need to install and run jEdit?
      </para></question>
      <answer><para>
        Since jEdit runs on a Java platform, at a minimum you will need a Java
        Runtime Environment (JRE) package. If you are planning to use jEdit to
        program in Java, you will need a full Java Development Kit (JDK) package.
        We recommend obtaining a JDK package.
      </para>
      <para>
        The current version of jEdit, version 4.0, requires a Java runtime
        environment having a release version of 1.3 or greater.  It will
        not run on versions 1.1 or 1.2. The <ulink
        url="http://www.jedit.org/index.php?page=compatibility">jEdit web
        site</ulink> contains a detailed discussion on the compatibility of
        various publicly available JDK's for the major operating systems.
      </para></answer>
    </qandaentry>
    <qandaentry>
      <question id="just-learning"><para>
        I've just started to learn programming. Is jEdit a good choice for my
        first text editor?
      </para></question>
      <answer><para>
        It is an excellent choice. Its basic features are extremely easy to use,
        and you will find things like abbreviations, keyboard shortcuts and
        macros to be great time-savers. It has built-in packages called
        <quote>edit modes</quote> that automatically display keywords, tags, and
        other program elements in different colors, making it easier to view and
        organize your code. It works well with many Open Source and proprietary
        programming tools. Because of its extensive customization features, it
        can adapt to your preferences and work patterns as you become more
        experienced. Finally, it's free, so you can buy a lot of programming texts
        with the money you will save.
      </para></answer>
    </qandaentry>

  </qandadiv>

  <qandadiv id="latest-version">
    <title>Getting the latest version</title>
    <qandaentry>
      <question id="get-latest-version"><para>
        How do I obtain the latest version of jEdit?
      </para></question>
      <answer><para>
        The program is in a continuing state of evolution. It is usually
        available in two versions, a <quote>stable</quote> version and a
        <quote>development</quote> version. A stable version represents a
        release of jEdit that is considered to be free of serious bugs or
        performance problems and suitable for general use. A
        <quote>development</quote> version includes new features or new elements
        of program design that require testing and possible further refinement.
        A development version contains the token <quote>pre</quote> in its
        version number, as in <literal>4.0pre5</literal>.
      </para>
      <para>
        The latest stable and development versions of jEdit are always
        available from the <ulink url="http://www.jedit.org">jEdit
        web site</ulink> and from the <ulink url="http://sourceforge.net/
        projects/jedit">jEdit project page</ulink> of the
        <ulink url="http://sourceforge.net">SourceForge web site</ulink>,
        which hosts jEdit's development resources.
      </para>
      <para>
        In addition, a plugin named <application>Check jEdit
        Version</application> can be run from within jEdit by selecting
        <guimenuitem>Check jEdit Version</guimenuitem> from the application's
        <guimenu>Plugins</guimenu> menu. It queries the jEdit web site, compares
        version information with the version of the currently running
        instance of jEdit, and reports the result to the user in a message box.
        It will tell you if you do not have the latest version of jEdit, regardless
        of whether that version is in <quote>stable</quote> or
        <quote>development</quote> form.
      </para>
      <para>
        Finally, if you subscribe to the <ulink
        url="http://lists.sourceforge.net/lists/listinfo/jedit-announce">
        jedit-announce</ulink> or <ulink
        url="http://lists.sourceforge.net/lists/listinfo/jedit-users">
        jedit-users</ulink> mailing lists, you will receive a email whenever
        a new release of jEdit becomes available.
      </para></answer>
    </qandaentry>
    <qandaentry>
      <question id="get-source"><para>
        How do I obtain a copy of the jEdit source code?
      </para></question>
      <answer><para>
        The latest version of jEdit's source code is available from the
        <ulink url="http://www.jedit.org/index.php?page=download&amp;platform=source">
        jEdit web site</ulink> or the <ulink url=
        "http://sourceforge.net/project/showfiles.php?group_id=588">
        SourceForge web site</ulink>. The web site provides the source code for the
        latest stable and development version, while the SourceForge site has
        a more extensive archive covering earlier versions.
      </para>
      <para>
        If you are interested in testing the absolutely latest changes to jEdit,
        and you are familiar with compiling your own Java programs and working
        with CVS, you can download the current code maintained in the <ulink
        url="http://sourceforge.net/cvs/?group_id=588">SourceForge
        CVS repository</ulink>.
      </para></answer>
    </qandaentry>
    <qandaentry>
	    <question id="get-latest-faq"><para>
        Where can I get the latest version of this document?</para>
      </question><answer>
        <para>
          The latest release of this document is available at the
          <ulink
          url="http://jedit-community.sourceforge.net/modules.php?op=modload&amp;name=Include_Pages&amp;file=index&amp;req=viewarticle&amp;artid=5">
          jEdit Community web site</ulink>.
        </para>
      </answer>
    </qandaentry>


<qandaentry>
	<question id="jedit-compile">
		<para>
			How do you set the classpath and compile the java files in jEdit?
		</para>
	</question>
	<answer>
		<para>
			Consult an article on the <ulink url="http://community.jedit.org">jEdit
			Community</ulink> web site entitled <quote>Build jEdit yourself: the 'Open'
			in Open Source</quote>.
		</para>
	</answer>
</qandaentry>

  </qandadiv>

</qandaset>

</sect1>

<sect1 id="problems"><title>Getting Answers and Reporting Problems</title>
<para>
  This section deals with how to get answers to questions that the
  documentation does not address, how you can report problems with jEdit
  or its plugins, and how best to communicate with the jEdit developer team.
</para>
<qandaset defaultlabel="qanda">

  <qandadiv id="get-answers-div">
    <title>Getting answers</title>
    <qandaentry>
      <question id="get-answers"><para>
        How do I get answers to my questions about jEdit?
      </para></question>
      <answer>
        <para>
          You should look for answers in the following places:
        </para>
        <itemizedlist>
          <listitem><para>
            The User's Guide available from the application's
            <guimenu>Help</guimenu> menu.
          </para></listitem>
          <listitem><para>
            This FAQ document.
          </para></listitem>
          <listitem><para>
            The archives of jEdit's mailing lists.  Archives for both the
            <ulink url="http://www.geocrawler.com/redir-sf.php3?list=jedit-users">
            jedit-users list</ulink> and the
            <ulink url="http://www.geocrawler.com/redir-sf.php3?list=jedit-devel">
            jedit-devel list</ulink> are available.
          </para></listitem>
        </itemizedlist>
        <para>
            If you cannot find help using those resources, post your question to the
            <ulink url="mailto:jedit-users@lists.sourceforge.net"> jedit-users
            list</ulink>. You will have to <ulink
            url="http://lists.sourceforge.net/lists/listinfo/jedit-users">
            subscribe to the mailing list</ulink> in order to
            post, but it is well worth it, and you can elect to have daily bundles
            of messages sent to you to keep email traffic down. Many questions
            are answered on the mailing list within 24 hours. The developers who
            respond to user questions generally do not send direct replies, so you
            will need to monitor messages from the mailing list is order to
            obtain an answer.
        </para>
      </answer>
    </qandaentry>
    <qandaentry>
        <question id="interactive-help"><para>
           Where can I get interactive help for jEdit?
        </para></question>
        <answer><para>
            There is an IRC channel, <filename>#jedit</filename>, available
            on the irc.openprojects.net server that is dedicated to jEdit support
            and discussion among developers.  You can reach it using
            any IRC client (including Chatzilla), as well as the IRC plugin
            for jEdit.
         </para>
         <para>
            There is almost always someone from the developer team
            signed on the channel. Just say hello and describe your problem.
        </para></answer>
    </qandaentry>
  </qandadiv>
  <qandadiv id="bugs">
    <title>Reporting bugs</title>
    <qandaentry>
      <question id="report-bugs"><para>
        How do I report a bug I have found in jEdit?
      </para></question>
      <answer><para>
        To be as helpful as possible to the jEdit developer team and other
        users, you should use the <ulink
        url="http://sourceforge.net/tracker/index.php?group_id=588&amp;atid=100588">
        bug tracker database</ulink> that the jEdit project maintains on the
        <ulink url="http://sourceforge.net/">SourceForge web site</ulink>. You
        do not need to be a SourceForge member to post a bug report.
      </para>
      <para>
        Before posting a bug report, spend a few moments searching the bug
        database to see if a similar report has already been made. The bug
        tracker has a search facility that will let search for bug reports using
        a variety of criteria. If you find a similar bug report, and you
        have additional information to contribute, post a comment
        to the report. If you do not find a similar bug report, submit a new
        report.
      </para></answer>
    </qandaentry>
    <qandaentry>
      <question id="bug-report"><para>
        What information should I include in a bug report?
      </para></question>
      <answer><para>
        The form in the bug tracker report provides several fields for
        submitting information. If you are unsure about a particular
        item, leave it at the default setting provided in the form.
      </para>
      <para>
        The more important fields are <quote>Category</quote>,
        <quote>Summary</quote> and the <quote>Initial comment</quote>.
        When you write your initial comment describing the bug, you
        should specify the versions of jEdit, the Java platform and
        operating system you are using, because bugs often arise that
        are specific to particular versions.  Sometimes the bug
        arises from the Java runtime environment or even the
        operating system, and knowing these details helps the
        developer team design testing and other debugging strategies.
      </para>
      <para>
        One of the macros installed with jEdit is called <guimenuitem>Make Bug
        Report</guimenuitem>. You will it find under the
        <guimenuitem>Misc</guimenuitem> category of the <guimenu>Macros
        </guimenu> menu. This macro extracts information regarding your jEdit
        installation and a stack trace from the last error recorded by jEdit's
        Activity Log and places it in a new text buffer. In many cases, the
        information furnished by the macro is all that is necessary to provide a
        helpful description of a bug. You can simply cut and paste the
        output of the macro into the <quote>Initial comment</quote> field of the
        bug report form.
     </para></answer>
   </qandaentry>

<qandaentry>
<question id="bug-track">
<para>
How do I track the status of a jEdit bug report?
</para>
</question>
<answer>
<para>
If you know the bug report number, go to this web address:
<userinput>http://sourceforge.net/tracker/index.php?func=detail&amp;aid=######&amp;group_id=588&amp;atid=100588</userinput>,
where <userinput>######</userinput> is the bug report number. If you don't know the bug report number,
you can browse and search the <ulink
url="http://sourceforge.net/tracker/index.php?group_id=588&amp;atid=100588">
bug database</ulink> to find the problem in which you are interested.
</para>
</answer>
</qandaentry>


  </qandadiv>

  <qandadiv id="contact">
    <title>Contacting jEdit developers</title>
    <qandaentry>
      <question id="contact-team"><para>
        How do I contact members of the jEdit developer team?
      </para></question>
      <answer><para>
        If you want to ask a question, make a feature request or offer other
        general comments, the easiest way is to join and post a message to the
        <ulink url="mailto:jedit-users@lists.sourceforge.net">
        jedit-users mailing list</ulink>. All developers are members. If you are
        interested in working on jEdit or writing a plugin for it, use the
        <ulink url="mailto:jedit-users@lists.sourceforge.net">
        jedit-devel list</ulink>.  Email addresses for individual developers
        can be found on the <ulink
        url="http://sourceforge.net/project/memberlist.php?group_id=588">
        SourceForge web site</ulink>.
      </para></answer>
    </qandaentry>
  </qandadiv>

</qandaset>

</sect1>