<?xml version="1.0"?>

<!-- ProjectViewer plugin user's guide -->
<!-- (C) 2001,2002,2003 Marcelo Vanzin, Stefan Kost -->

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

<book>

	<bookinfo>
    	<title>ProjectViewer plugin</title>
		<authorgroup>
			<author><firstname>Dale</firstname><surname>Anson</surname></author>
			<author><firstname>Kevin</firstname><surname>Burton</surname></author>
			<author><firstname>Stefan</firstname><surname>Kost</surname></author>
			<author><firstname>Matthew</firstname><surname>Payne</surname></author>
			<author><firstname>Marcelo</firstname><surname>Vanzin</surname></author>
			<author><firstname>Calvin</firstname><surname>Yu</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 groups of files as
			projects.
		</para>

		<bridgehead renderas='sect3'>What is a project?</bridgehead>

		<para>
			A project is a group of files. It has a name, a root
			directory, and an optional URL Root, along with other
			options that can be made available by other plugins.
		</para>

		<para>
			In this version of Project Viewer, the files in a project
			are not restricted to the project root: any file can be
			added to the project (or to any directory in the project),
			allowing you to organize your files however you find most
			convenient, independently of the file system layout. The
			project root and the files and directories below it have a
			special treatment not given to others, though.
		</para>

		<para>
			If a project is intented for website development, setting
			the URL Root will enable project files to be launched in a
			web browser. Suppose the project "Root" also correlates to
			the URL "http://localhost/myproject/" currently running on a
			web server, launching the file "hello.jsp" will launch the
			web browser with the URL
			"http://localhost/myproject/hello.jsp", if the file is
			directly under the root.
		</para>

		<para>
			To create a project, click the "Add/Edit Project" button in
			the toolbar, or choose "Add new project"  from under the
			desired group in the projects menu (accessible from jEdit's
			plugin menu of from the ProjectViewer toolbar).
		</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 menu containing the currently
			available projects (accessible through the button labeled
			with the current active node), and the project's views.
		</para>

		<para>
			To open a ProjectViewer window, you'll need to choose the
			"Open Project Viewer" action from the plugin's menu.
			Optionally, you can go to the Global Options dialog in
			jEdit, and dock the window in your favorite position (in the
			"Docking" tab). Note that activating a project or group
			using the plugin menu will not open a ProjectViewer window
			if one is not already opened.
		</para>

		<bridgehead renderas='sect3'>Organizing Your Projects</bridgehead>

		<para>
			Project Viewer allows you to organize your projects into
			groups. You can create as many groups as you with in an
			hierarchical manner, by using the "Add group here" command
			in the tree's context menu, or choosing the "New group here"
			entry from under the desired group in the projects menu.
		</para>

		<para>
			As with projects, it is possible to have groups as the root
			of the tree shown in the dockable window. For this, just
			choose a group from the projects menu to make it active.
			Some plugin functionality is not available when in this
			mode.
		</para>

		<para>
			You can also move projects and groups to other locations in
			your group hierarchy by using the "Move to..." command in
			the tree's context menu and choosing the desired destination
			from the displayed menu.
		</para>

		<bridgehead renderas='sect3'>The Project Views</bridgehead>

		<para>
			There are four 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. The "Working
			Files", which shows the files currently opened in jEdit. And
			the "Compact View", which compresses subdirectories into
			top-level nodes, showing a structure similar to the java
			package naming.
		</para>

		<para>
			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>
			You can interact with the project tree in several ways:
		</para>

		<itemizedlist>
			<listitem>
				<para>
				Double clicking on a file will cause it to be opened in
				a jEdit buffer. If the file is already open, then
				ProjectViewer follows the FileSystemBrowser
				configuration option to decide whether to close it or
				not.
				</para>
			</listitem>

			<listitem>
				<para>
				Middle-clicking on a file does the same as
				double-clicking, except it will always close open files.
				</para>
			</listitem>

			<listitem>
				<para>
				The right mouse button shows a context menu with 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>
			</listitem>

			<listitem>
				<para>
				Dragging a file from the trees and dropping it on
				jEdit's text area will cause the file to be opened.
				</para>
			</listitem>
		</itemizedlist>

		<bridgehead renderas='sect3'>Importing Files</bridgehead>

		<para>
			Differently from earlier 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 from an open buffer and is not currently part of
			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>

		<para>
			The importing process can be customized to import only the
			files you find important for your project. When browsing
			files or importing directories, you may choose any of the
			given file filter to filter out unwanted files. File filters
			include: Non-project files (default on importing, used for
			the "import all files" option), Import settings (see
			"Customization", below) and CVS/Entries (only list files
			listed in the CVS/Entries file of the current directory).
		</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>
					Add/Edit project: shows the project properties
					dialog, where you can enter information about a new
					project. If the "All Projects" view is used, and no
					node (or the root) is selected, the "Create Project"
					dialog apperas, instead of the current project's
					properties.
				</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>
					Add file to project root: shows a dialog where you
					can choose single files to add to the current
					project. Differently from the "Add files" in the
					context menu, this option will work as in the old
					Project Viewer versions, only importing files below
					the project root, and keeping the file system layout
					for files and directories.
				</para>
			</listitem>
		</itemizedlist>

		<bridgehead renderas='sect3'>Commands available in the context menu</bridgehead>

		<para>
			The context menu provides context-sensitive options based on
			the current tree selection. The following commands can be
			found in the context menu (some of them have already been
			explained above):
		</para>

		<itemizedlist>
			<listitem>
				<para>
					Add files: pops a file chooser from where you can
					choose any files or directories to import. These
					will be imported <emphasis>into the selected
					node</emphasis>, disregarding the file system
					layout. If importing directories, you'll be prompted
					if you want to do it recursively using one of the
					available filters.
				</para>
			</listitem>
			<listitem>
				<para>
					Add files from VFS: lets you select files from a
					jEdit VFS (Virtual File System), such as FTP. If you
					choose local files, ProjectViewer will add standard
					files instead of VFS files. The functionality of VFS
					files in ProjectViewer is rather limited when
					compared to standard files.
				</para>
			</listitem>
			<listitem>
				<para>
					Re-import files: this command will remove all files
					and directories below the project root, and re-read
					the file structure from disk according to the
					selected filter (which can be chosen from the dialog
					that pops up). It will also analyze directories not
					under the project root: it will re-import existing
					directories and remove stale files from "virtual"
					directories.
				</para>
			</listitem>
			<listitem>
				<para>
					Remove from project: this will remove the selected
					node from the project to which it belongs. It is
					also possible to remove multiple nodes at once.
				</para>
			</listitem>
			<listitem>
				<para>
					Delete from disk: this is only shown for files to
					which you have write permission. Choosing it will
					cause the files to be deleted from disk and removed
					from the project.
				</para>
			</listitem>
			<listitem>
				<para>
					Rename: this will prompt you for a new name for the
					selected node. If you check the "Don't change name
					on disk" option, only the node name on the tree will
					be changed; the file on disk will keep its current
					name.
				</para>
			</listitem>
			<listitem>
				<para>
					Archive project: this will prompt you for a file
					name. A JAR archive will be created containing all
					files below the project root.
				</para>
			</listitem>
			<listitem>
				<para>
					Preview in browser: this will open the file in the
					configured web browser. If a project URL is set,
					files below the project root will be redirected to
					the given URL; in other cases, the "file://"
					protocol will be used. The part of the file path
					corresponding to the project root will be removed
					when opening the file relatively to the project URL.
				</para>
			</listitem>
			<listitem>
				<para>
					Open with: this will open the selected file in a
					configured application associated with its extension
					(configured in the Project Viewer's plugin options).
					If no application is configured for the selected
					file, selecting this option will prompt you to
					choose an application.
				</para>
			</listitem>
		</itemizedlist>

		<bridgehead renderas='sect3'>Using PV commands from jEdit</bridgehead>

		<para>
			Some commands are also available as jEdit actions so that
			shortcuts can be assigned to them. You can check all the
			possible commands available as actions by going to the
			"Shortcuts" panel in the jEdit options dialog, and selecting
			the ProjectViewer plugin.
		</para>

		<para>
			When executing a command using a shortcut, you may notice
			that sometimes no action is performed and an error message
			appears in the status bar. This means that the action is not
			available for the current selection in the tree. To check
			which actions are available for the selected node(s), check
			the context menu by clicking the node with the right mouse
			button.
		</para>

		<bridgehead renderas='sect3'>Third party plugins commands</bridgehead>

		<para>
			Project Viewer can be extended by other plugins; they can
			add properties to a project and define new actions for nodes
			in the tree. Consult each plugins documentation for
			information about possible commands available for the
			Project Viewer plugin.
		</para>

		<para>
			For developers go to chapter <link linkend="developer"
			endterm="developer.title"/> to get some starting help fo how to
			cooperate with the Project Viewer plugin.
		</para>
	</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>
					Use external applications by default: if selected,
					files that are open from the tree (by either
					double-clicking or middle-clicking) will be opened
					using the external application configured for the
					file's extension, if any. If no application is
					found, it will be opened in jEdit. You can still
					open the file in jEdit by dragging the file node
					onto jEdit's text area. When opening in an external
					application, you'll lose support for auto-closing
					the file on project file, auto-loading the file when
					the project is re-activated and the file node won't
					be underlined, indicating it is opened..
				</para>
			</listitem>
			<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>
					Ask to import new files: if "Always" is selected,
					every time you save a file located below the active
					project's root, and the file is not yet part of the
					project, you'll be asked whether you want to import
					it. Selecting "Once per session" will ask only one
					time during the time the current project stays
					active. "Never" will disable this feature. "Auto
					import" will automatically add to the project any
					saved files which are under the project root and are
					not currently part of the project.
				</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 Files" tree
					view should be shown.
				</para>
			</listitem>
			<listitem>
				<para>
					Show compact tree: whether the "Compact" tree view
					should be shown.
				</para>
			</listitem>
			<listitem>
				<para>
					Use system icons for files: instead of using jEdit's
					icons, uses the system provided icon for each
					individual files. The jEdit icon will still be used
					when the file is opened. In some systems, the system
					icons may not be accessible from Java, so this
					option may not work as expected. Also, this option
					is only available if Java 2 version 1.4 or later is
					being used.
				</para>
			</listitem>
		</itemizedlist>

		<bridgehead renderas='sect3'>Import Options</bridgehead>

		<para>
			This controls the behaviour of the "Import settings" filter
			available when importing files.
		</para>

		<itemizedlist>
			<listitem>
				<para>
					Files to include: a list of globs that match files
					you want to include in a project (e.g., "*.html",
					"*.java", "README*"). If you want to exclude files
					from the automatic import, prepend the glob with the
					"!" character (e.g., "!*.class").
				</para>
			</listitem>
			<listitem>
				<para>
					Directories to ignore: space-separated list of globs
					to match directory names to ignore when doing
					automatic import of files. No files within
					directories whose names are listed here will be
					imported.
				</para>
			</listitem>
		</itemizedlist>

	    <bridgehead renderas='sect3'>Web Project Options</bridgehead>

		<itemizedlist>
			<listitem>
				<para>
					Use InfoViewer's browser settings: if you have the
					InfoViewer plugin installed, you can choose to check
					this box, and when asking to open a file in a web
					browser, InfoViewer is going to be used to launch
					you browser of choice.
				</para>
			</listitem>
			<listitem>
				<para>
					Browser path: the path to the web browser to be used
					for viewing selected files, with any needed
					command-line switches, in case you don't want to use
					the same settings as the InfoViewer plugin.
				</para>
			</listitem>
		</itemizedlist>

		<bridgehead renderas='sect3'>Editing the context menu</bridgehead>

		<para>
			ProjectViewer provides an interface similar to jEdit's
			context menu editor, where you can add actions to be
			displayed in the trees' context menus. You can't remove the
			default entries in the context menu, but any action
			available to jEdit can be added. It's important to notice
			that adding an action to the context menu won't make it
			"Project Viewer aware": unless the action is specifically
			written to interface with ProjectViewer, it will work the
			same way as it would if executed from any other place (such
			as the jEdit toolbar or menu).
		</para>

		<bridgehead renderas='sect3'>File Associations</bridgehead>

		<para>
			The "External Applications" option pane can be used to
			register applications you want to use for specific file
			type, accessible through the "Open with..." context menu
			command for files. Just add a file name glob and choose the
			application you wish to use for that entry.
		</para>

	</chapter>

	<chapter id="developer">
		<title id="developer.title">Developer Documentation</title>

		<para>
			At first, there's a comprehensive documentation included
			with the source distribution in Javadoc format. Just
			download the source from the jEdit CVS and create the
			documentation by executing the "javadoc" Ant task in the
			Project Viewer directory. Documentation will be created
			under the directory "build/docs/javadoc".
		</para>

		<para>
			External plugins can interact with the Project Viewer plugin in
			various ways:
			<itemizedlist>
				<listitem><para>By providing project specific properties: properties</para></listitem>
				<listitem><para>By creating new node types: nodes</para></listitem>
				<listitem><para>By creating node-specific actions: actions</para></listitem>
				<listitem><para>By listening to Project Viewer events</para></listitem>
			</itemizedlist>
		</para>

    <para>
		During the next sub chapters we will describe some common task
		for interacting with projectviewer.
    </para>

    <section id="developer-checkpv">
      <title id="developer-checkpv.title">Checking if projectviewer is available</title>
      The method described here requires a jEdit with version > 4.2preX.
      <informalexample>
        <programlisting>
EditPlugin pv;
pv=jEdit.getPlugin("projectviewer.ProjectPlugin",false);
if(pv!=null) {
   // we can use the projectviewer plugin
}
        </programlisting>
      </informalexample>
    </section>

    <section id="developer-prjfile">
      <title id="developer-prjfile.title">Getting the project the a given file belongs to</title>
      <informalexample>
        <programlisting>
ProjectManager pm=getInstance()
// then use java.util.Iterator getProjects();
// and foreach project use VPTNode node=prj.getChildNode(java.lang.String path);
        </programlisting>
      </informalexample>
    </section>

		<section id="developer-prjview">
      <title id="developer-prjview.title">Getting the project of the given view</title>

      <informalexample>
        <programlisting>
VPTProject prj=ProjectViewer.getActiveProject(org.gjt.sp.jedit.View aView);
ProjectViewer pv=ProjectViewer.getViewer(org.gjt.sp.jedit.View view);
        </programlisting>
      </informalexample>
    </section>

	</chapter>

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

		<bridgehead renderas='sect3'>Canonical File Paths</bridgehead>

		<para>
			The JRE, up to version 1.4 (at least), has a bug in
			JFileChooser when using the Metal Look &amp; Feel. It will
			resolve canonical paths when changing directories. While
			ProjectViewer tries to work around this issue, it may lead
			to some strange behaviors, especially when importing files.
		</para>

		<bridgehead renderas='sect3'>Large projects</bridgehead>

		<para>
			Large projects can take some time to load, especially over a
			network connection. This is due to the fact that Project
			Viewer resolves all canonical paths so that it can better
			interact with jEdit. If your project has lots of files
			("lots" meaning over one or two thousand), you may
			experience some delays when loading it. jEdit is not blocked
			while the project is loading, though, so you can continue
			your work.
		</para>

		<bridgehead renderas='sect3'>Multiple Viewer in same jEdit View</bridgehead>

		<para>
			jEdit allows multiple instances of the same dockable for the
			same view. Project Viewer does not support this feature and
			will issue an error message if you try to open two Project
			Viewer windows in the same view.
		</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/tracker/?atid=565475&amp;group_id=588">
				http://sourceforge.net/tracker/?atid=565475&amp;group_id=588
			</ulink>
			Please start the report subject with the text "ProjectViewer:".
		</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>