<?xml version="1.0"?>

<!-- ProjectViewer plugin user's guide -->
<!-- (C) 2001,2002 Stefan Kost, Calvin Yu -->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "docbookx.dtd">

<book>


<bookinfo>
    <title>ProjectViewer plugin</title>

    <authorgroup>
        <author><firstname>Marcelo</firstname><surname>Vanzin</surname></author>
        <author><firstname>Matthew</firstname><surname>Payne</surname></author>
        <author><firstname>Stefan</firstname><surname>Kost</surname></author>
        <author><firstname>Calvin</firstname><surname>Yu</surname></author>
        <author><firstname>Kevin</firstname><surname>Burton</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="presentation">
    <title>Presentation</title>

    <para>
	The ProjectViewer plugin allows to define group of files as projects.
    </para>

</chapter>

<chapter id="usage">
    <title>Using the ProjectViewer plugin</title>
    
    <para>
    The plugin interface consists of a tool bar, containing some command buttons,
    a combo box containing the currently available projects, and the project's
    views.
    </para>
    
    <bridgehead renderas='sect3'>What is a project?</bridgehead>
    
    <para>
    A project is a group of files. It has a name and a root directory. Any 
    files can be added to the project. Even files that do not exist may be
    added - they'll behave as "virtual" directories. The project is not tied
    to the filesystem layout when organizing your files.
    </para>

    <para>
    The project root, however, has some added functionality not available to
    other directories or files not related to the root. For example, when
    saving a file in jEdit, the plugins checks if the file is physically below 
    the current project's root directory, and in this case asks if the user
    wants to add the new file to the project. The project root is also used
    when importing files automatically, when creating new projects.
    </para>
    
    <para>
    To create a project, click the "Create Project" button in the toolbar, or
    choose the correspondent entry in the project combo box. This
    will show a dialog where you can enter the properties of the project you
    want to create. After you have chosen these properties, you'll be asked if you
    would like to import all files from the root directory. You may choose to 
    import using three different filtering methods: import all files, import
    using the plugin's import settings (defined in the jEdit Plugin Options) or
    use the CVS/Entries file for each directory below and including the root
    to choose the files to be imported.
    </para>
    
    <bridgehead renderas='sect3'>The User Interface</bridgehead>
    
    <para>
    There are three possible views of the files on a project: the "Folders" view,
    which shows the files as if in a file manager, organised in directories. The
    "Files" view, which shows all the project's files in a flat list. And the
    "Working Files", which shows the files currently opened in jEdit.
	The files in the different views are colored according to the patterns and
	colors you have choosen for the filesystem-browser. Furthermore currently
	open files are highlighted by underlining their names.
    </para>
    
    <para>
    Optionally, by choosing "All Projects" from the project selection box, a
    alternative view is shown, which displays data from all projects. Some
    plugin functionality is not available when in this mode.
    </para>
    
    <para>
    You can interact with the project in several ways. Double clicking on a file
    in the tree will cause it to be opened in a jEdit buffer, or, if the file
    is already opened, will cause it to be focused (if not the current buffer)
    or closed (if it is the current buffer). Using the right mouse button
    will show options related to the current selection on the tree, allowing
    you to remove files or directories from a project, deleting them from the
    disk, or rename them, among many other options.
    </para>
    
    <para>
    Right-clicking on a project will let you change the project's properties (the
    name and the root, for instance) and re-import files from the project's root
    directory. Changing the project root will cause the plugin to ask to import
    files from the new root, just like creating a new project does.
    </para>

    <bridgehead renderas='sect3'>Importing Files</bridgehead>
    
    <para>
    Differently from previous releases, the plugin does not follow the filesystem
    layout to organize files anymore, except for certain cases; notably, when 
    doing the initial import from the project root or when adding a file that
    has been saved to the project.
    </para>
    
    <para>
    In the import dialog (available by choosing "Import files" from the right-click
    menu), you can choose any files to be imported to the selected node (the one
    where you clicked to get the context menu). The same filters available when
    doing the initial import for the project are available in the file chooser.
    </para>
    
    <para>
    You may choose any files and directories to import, even files and directories
    that are not "children" of the selected node in the file system layout. This
    allows you to organize your files in any way you want. You may even enter the
    name of a non-existant file in the file chooser: it will be treated as a
    directory, and even though the directory does not exist on disk, you'll have
    the same functionality for it as you have for other directories in your project.
    </para>
    
    <para>
    When importing existing directories, you'll be asked if you want to import
    them recursively. Again, the three options for file filtering are presented,
    so you can have more control over which files are imported. The dialog will
    appear once for each import, and not for each directory in that particular
    import process.
    </para>
    
    <bridgehead renderas='sect3'>Commands available in the toolbar</bridgehead>
    
    <para>
    The tool bar provides a fast way to access some of the functionality of the
    Project Viewer plugin. The available commands are:
    </para>
    
    <itemizedlist>
        <listitem>
            <para>
            Create project: shows the project properties dialog, where you can 
            enter information about a new project. After creating a new
            project, you'll be asked if you want to import its files, and it
            will become the active project.
            </para>
        </listitem>
        <listitem>
            <para>
            Expand the file list: opens all nodes in the currently selected tree.
            </para>
        </listitem>
        <listitem>
            <para>
            Contract the file list: closes all nodes in the current tree.
            </para>
        </listitem>
        <listitem>
            <para>
            Open all files in this project: opens all files that are part of
            this project in jEdit buffers.
            </para>
        </listitem>
        <listitem>
            <para>
            Add file to project: shows a dialog where you can choose single files
            to add to the current project.
            </para>
        </listitem>
        <listitem>
            <para>
            Import files into this project: shows a dialog where you can choose
            a directory from which the plugin will look for files that comply
            with the Import Properties (see <emphasis>Customization</emphasis>
            below), and add these files to the current project.
            </para>
        </listitem>
        <listitem>
            <para>
            Remove: remove the currently selected node(s) from the project, be
            them files or directories. If a project is selected in the tree, 
            the project will be removed. A confirmation dialog is show when
            removing directories, multiple nodes or projects (but not when
            removing single files).
            </para>
        </listitem>
    </itemizedlist>
    
</chapter>

<chapter id="customization">
    <title>Customization</title>

    <para>
    Several options are configurable from the jEdit options dialog. There are
    options to control the GUI of the plugin, and internal behaviour when
    executing several actions. The options are:
    </para>
    
    <bridgehead renderas='sect3'>General Behaviour Options</bridgehead>

    <itemizedlist>
        <listitem>
            <para>
            Close files on project change: if selected, files from the current
            project that are opened in jEdit will be closed when you switch to
            another project.
            </para>
        </listitem>
        <listitem>
            <para>
            Remember open files: if selected, files opened in the current project
            will be re-opened when you select the same project in a later moment,
            even between different jEdit sessions.
            </para>
        </listitem>
        <listitem>
            <para>
            Delete non-existant files from list: if selected, each file in the
            project is verified to exist when the project loads. If the file does
            not exist, it is removed from the project.
            </para>
        </listitem>
        <listitem>
            <para>
            Save project data on change: if selected, any change to a project
            (including or removing a project, for example) will cause the data
            to be saved on disk.
            </para>
        </listitem>
    </itemizedlist>

    <bridgehead renderas='sect3'>GUI Options</bridgehead>
    
    <itemizedlist>
        <listitem>
            <para>
            Show toolbar: whether to show the plugin's toolbar or not. The 
            toolbar is automatically hidden when no tree is selected for
            showing, regardless of this option.
            </para>
        </listitem>
        <listitem>
            <para>
            Show folders tree: if the "Folders" tree view should be shown.
            </para>
        </listitem>
        <listitem>
            <para>
            Show files tree: if the "Files" tree view should be shown. Disabling
            this view can greatly improve performance when your projects have
            many files.
            </para>
        </listitem>
        <listitem>
            <para>
            Show working files tree: if the "Working Filer" tree view should be
            shown.
            </para>
        </listitem>
    </itemizedlist>
    
    <bridgehead renderas='sect3'>Import Options</bridgehead>
    
    <itemizedlist>
        <listitem>
            <para>
            Extensions to include: a list of file extensions to be included in
            a project when automatically importing directories, separated by
            spaces.
            </para>
        </listitem>
        <listitem>
            <para>
            Directories to ignore: space-separated list of directory names to
            ignore when doing automatic import of files.
            No files withing directories whose names are listed here will be
            imported.
            </para>
        </listitem>
        <listitem>
            <para>
            Files to include: list of file names to include (useful when there
            are files without extensions in your projects).
            </para>
        </listitem>
    </itemizedlist>

</chapter>

<chapter id="troubleshooting">
    <title>Troubleshooting</title>

    <bridgehead renderas='sect3'>ProjectViewer, jEdit and XML Parsers</bridgehead>

    <para>
    The configuration for the ProjectViewer plugin is now stored in XML format;
    this makes it mandatory to have an XML parser available in the system. For
    those using Java 1.3, you can dowload Crimson or Xerces from 
    <ulink url="http://xml.apache.org">http://xml.apache.org</ulink>, or install
    jEdit's XML plugin.
    </para>
    
    <para>
    For those using JDK 1.4, Crimson is already available in the default
    installations. However, there may be a conflict between the JAXP runtime
    available in the JRE 1.4 and the Xerces parser that comes with the XML
    plugin for jEdit, due to some class loader issues. If you have such a
    configuration, please install Xerces in the JDK/JRE extensions directory
    (usually [path_to_jdk]/jre/lib/ext).
    </para>
</chapter>

<chapter id="license">
    <title>License</title>

    <para>
    The source code is distributed under the GPL.
    Please see
    <ulink url="http://www.fsf.org/copyleft/gpl.html">
        http://www.fsf.org/copyleft/gpl.html
    </ulink>
    </para>
</chapter>


<chapter id="feedback">
    <title>Feedback</title>

    <para>
    The preferred way to send bug reports is to use the
    Sourceforge Bug Tracker at
    <ulink url="http://sourceforge.net/bugs/?group_id=588">
        http://sourceforge.net/bugs/?group_id=588
    </ulink>
    </para>

    <para>You can also write to:</para>
    <itemizedlist>
        <listitem>
        <para>
            Stefan Kost <email>ensonic@sonicpulse.de</email>;
        </para>
		</listitem>
        <listitem>
        <para>
            or jEdit-users mailing-list
            <email>jedit-users@lists.sourceforge.net</email>;
        </para>
        </listitem>
        <listitem>
        <para>
            or jEdit-devel mailing-list
            <email>jedit-devel@lists.sourceforge.net</email>.
        </para>
        </listitem>
    </itemizedlist>
</chapter>


<chapter id="credits">
    <title>Credits</title>

    <itemizedlist>
        <listitem>
        <para>
            ProjectViewer was previously (up to 1.0.2) maintained by Calvin Yu
        </para>
        </listitem>
        <listitem>
        <para>
            ProjectViewer was originally developed Kevin A. Burton
        </para>
        </listitem>
    </itemizedlist>
</chapter>


</book>