<!-- Antelope Users Guide -->
<!-- (C) 2002 Dale Anson -->

<book>
<bookinfo>
    <title>Antelope Users Guide, Version @buildnum@</title>

    <authorgroup>
        <author><firstname>Dale</firstname><surname>Anson</surname></author>
    </authorgroup>

</bookinfo>

<chapter id="legal">
@style@
    <title>Legalities</title>
    <para>
    Per the Apache license (see below):
    </para>

    <para>
"This product includes software developed by the
Apache Software Foundation (http://www.apache.org/)."
    </para>

    <para>
        Antelope is licensed under the same Apache license as Ant:
    </para>

    <para>
    <programlisting>
    <![CDATA[
The Apache Software License, Version 1.1

Copyright (c) 2001-2002 The Apache Software Foundation.  All rights
reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the
   distribution.

3. The end-user documentation included with the redistribution, if
   any, must include the following acknowlegement:
      "This product includes software developed by the
       Apache Software Foundation (http://www.apache.org/)."
   Alternately, this acknowlegement may appear in the software itself,
   if and wherever such third-party acknowlegements normally appear.

4. The names "The Jakarta Project", "Ant", and "Apache Software
   Foundation" must not be used to endorse or promote products derived
   from this software without prior written permission. For written
   permission, please contact apache@apache.org.

5. Products derived from this software may not be called "Apache"
   nor may "Apache" appear in their names without prior written
   permission of the Apache Group.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
====================================================================

This software consists of voluntary contributions made by many
individuals on behalf of the Apache Software Foundation.  For more
information on the Apache Software Foundation, please see
<http://www.apache.org/>.
    ]]>
    </programlisting>
    </para>

    <para>
Some of the icons used in Antelope are from Sun's Java Look and Feel Graphics Repository. The following license pertains to those icons:
    <programlisting>
    <![CDATA[
Copyright 2000 by Sun Microsystems, Inc. All
Rights Reserved.

Sun grants you ("Licensee") a non-exclusive,
royalty free, license to use, and redistribute
this software graphics artwork, as individual
graphics or as a collection, as part of software
code or programs that you develop, provided that
i) this copyright notice and license accompany
the software graphics artwork; and ii) you do not
utilize the software graphics artwork in a manner
which is disparaging to Sun. Unless enforcement
is prohibited by applicable law, you may not
modify the graphics, and must use them true to
color and unmodified in every way.

This software graphics artwork is provided "AS
IS," without a warranty of any kind. ALL EXPRESS
OR IMPLIED CONDITIONS, REPRESENTATIONS AND
WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND
ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES
SUFFERED BY LICENSEE AS A RESULT OF USING,
MODIFYING OR DISTRIBUTING THE SOFTWARE GRAPHICS
ARTWORK.

IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE
FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR
DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL,
INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED
AND REGARDLESS OF THE THEORY OF LIABILITY,
ARISING OUT OF THE USE OF OR INABILITY TO USE
SOFTWARE GRAPHICS ARTWORK, EVEN IF SUN HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

If any of the above provisions are held to be in
violation of applicable law, void, or
unenforceable in any jurisdiction, then such
provisions are waived to the extent necessary for
this Disclaimer to be otherwise enforceable in
such jurisdiction.
    ]]>
    </programlisting>
    </para>
</chapter>

<chapter id="intro">
@style@
<title>Introduction</title>

<para>
<emphasis role="bold"><emphasis role="italic">Due to changes in the jEdit API, Antelope plugin versions prior to 2.60 are for jEdit 4.1, versions 2.60 and later require jEdit 4.2 or later.
</emphasis></emphasis>
</para>

<para>
Disclaimer: Typically, the documentation is not quite up-to-date with the software. There may be some discrepancies between the text and pictures in this guide from what you see when you run the application. If you see a problem with this documentation, please post a bug at http://antelope.tigris.org. Thank you!
</para>

<para>
Antelope is a graphical user interface for running Ant. It provides a set of buttons, one per target, which makes it easy to start a specific Ant operation. Basically, an Ant build file is opened with Antelope and the targets defined in the build file can be executed by clicking a button. Antelope is much more than a thin wrapper around Ant, however.
</para>

<para>
Antelope can run in two different environments. It can run as a stand-alone GUI application and as a plugin to jEdit (www.jedit.org), an excellent open source editor for programmers.
</para>

<para>
As a stand-alone application, Antelope provides the ability to create and edit Ant build files, the ability to run build file targets, and can trace target and task execution in a quasi-debug mode. Output from the build process can be captured to a file and/or to screen and performance statistics can be gathered to guide optimization efforts. Several very useful tasks to extend Ant are included.
</para>

<para>
As a jEdit plugin, Antelope expands the features of the stand-alone application to nicely integrate with the text editor and with the Console and ErrorList plugins. Antelope has an open API that allows other plugins to utilize Antelope's capabilities.
</para>

<para>
In either mode, Antelope provides property and reference inspection and the ability to set properties that would be passed as parameters to Ant on the command line.
</para>

<para>
<figure>
<title>Introducing Antelope</title>
<imageobject>
    <imagedata fileref="standalone.gif" format="GIF"/>
</imageobject>
</figure>
</para>
</chapter>

<chapter id="installation">
@style@
<title>Installation</title>
<section id="install_ant">
@style@
<title>Install Ant</title>
<para>
Antelope assumes you already have Ant installed. If you don't, you can get it from http://ant.apache.org. You need to have Ant installed before Antelope will run.
</para>
</section>
<section id="install_app">
@style@
<title>Installing Antelope as a Stand-Alone Application</title>
<para>
This section assumes you'll install Antelope as a stand-alone application by hand. It's really quite easy:
</para>
<para>
Download the Antelope application zip file.
</para>
<para>
Unzip the file.
</para>
<para>
Change to the AntelopeApp_@buildnum@ directory.
</para>
<para>
Start Antelope by using this command: java -jar AntelopeApp_@buildnum@.jar
</para>
</section>

<section id="install_plugin">
@style@
<title>Installing Antelope as a jEdit Plugin</title>
<para>
You can install Antelope in jEdit by using the Plugin Manager. Just follow the instructions for installing any plugin found in the jEdit help system. This section assumes you'll install Antelope into jEdit by hand because Antelope is updated much more frequently than jEdit's Plugin Central. It's really quite easy:
</para>

<para>
<itemizedlist>
<listitem>
Download the Antelope plugin jar file.
</listitem>
<listitem>
Copy it to jEdit's jar directory.
</listitem>
<listitem>
Check that ANT_HOME is set as an environment variable.
</listitem>
<listitem>
Start jEdit.
</listitem>
</itemizedlist>
</para>

<para>
Note that the Antelope plugin depends on the Console and ErrorList plugins, so you'll need to install those from the Plugin Manager also.
</para>

<para>
First, download the plugin zip file. Unzip it. The file named Antelope.jar is the plugin jar file.
</para>
<para>
Second, figure out where to put it. jEdit wants its plugins in one of two places, either $jedit_home/jars or $user_home/.jedit/jars. The best place is $user.home/.jedit/jars.
</para>
<para>
So where is $user_home? That depends on your operating system.
</para>
<para>
For Windows 95 and later, it's usually C:\Documents and Settings\yourusername, where yourusername is the name you use to log on to Windows. On my Windows 2000 machine, it's C:\Documents and Settings\danson, so I would copy the jar file into C:\Documents and Settings\danson\.jedit\jars.
</para>
<para>
For Linux or Unix, $user_home is usually /home/yourusername or /export/home/yourusename. On my Linux box, it's /home/danson, so I would copy the jar file into /home/danson/.jedit/jars.
</para>
<para>
The third step is letting Antelope know where you have Ant installed. This directory is known as "ANT_HOME". For example, on my Windows 2000 machine, I have Ant installed in c:\apache-ant-1.6.0, so that would be my ANT_HOME. Antelope looks in a few places when it starts:
<itemizedlist>
<listitem>
First, it looks for a System property named ANT_HOME. You could set a System property on the command-line to start jEdit (something like java -mx64m -DANT_HOME=c:/apache-ant-1.6.0 -jar jedit.jar) or if you're using Windows, you can set something similar in the jEdit launcher tool (Start - Programs - jEdit - Set jEdit Parameters).
</listitem>
<listitem>
Second, it looks for an environment variable named ANT_HOME. This is actually the preferred method, and is recommended in the Ant installation instructions. How you set an environment variable depends on your operating system, on Windows, go to Start - Settings - Control Panel - System - Advanced - Environment Variables. On Linux or Unix, I'll assume you know what to do.
</listitem>
<listitem>
If there is no environment variable set, then Antelope looks in the jEdit jars directories. You can copy the files from ANT_HOME/lib to the jEdit jars directory like you did with the Antelope jar file, and jEdit will automatically load them. This wasn't a bad solution with Ant 1.5 as there were only a couple of jars to maintain, but Ant 1.6 comes with about 20 jar files, so it's a bit more cumbersome.
</listitem>
<listitem>
If Ant is not found in any of these locations, it will ask you.
</listitem>
</itemizedlist>
Once Ant is found, the location will be stored by Antelope for future use. If you want to change the location, use jEdit's "Plugin" menu, then "Plugin Options", then "Antelope" in the plugin list. If you erase the setting found there, Antelope will follow the same procedure to find Ant next time it is started.
</para>

<para>
As a plugin, Antelope provides two "dockable" windows.  Use jEdit's menu "Utilites, Global Options, Docking" to dock the windows.  I find it convenient to dock the "Antelope" window on the right, and the "Ant Output" window on the bottom.  The "Antelope" window is where you'll see the buttons to run targets, the "Ant Output" windows is where you'll see any output produced by Ant as it runs.  Technically, the "Ant Output" window shows anything written to the system standard output stream, so you may see messages produced by other plugins there also.
</para>

<para>
To reiterate:
<itemizedlist>
<listitem>
Download the Antelope plugin jar file.
</listitem>
<listitem>
Copy it to jEdit's jar directory.
</listitem>
<listitem>
Check that ANT_HOME is set as an environment variable.
</listitem>
<listitem>
Start jEdit.  Dock Antelope.
</listitem>
</itemizedlist>
</para>
</section>
</chapter>

<chapter id="requirements">
@style@
<title>Requirements</title>

<para>
See the <link linkend="installation">installation instructions</link> for the specific requirements for Antelope. Antelope does require Java 1.5 or later as it makes use of both java.util.logging and java.util.prefs APIs which were introduced in that version.
</para>

<para>
<emphasis role="bold"><emphasis role="italic">Due to changes in the jEdit API, Antelope plugin versions prior to 2.60 are for jEdit 4.1, versions 2.60 and later require jEdit 4.2 or later.
</emphasis></emphasis>
</para>

<para>
Antelope does require Ant 1.5.x or later, which is a separate download. Ant is available from <ulink url="http://ant.apache.org">http://ant.apache.org</ulink>. Antelope has been tested extensively with Ant 1.5.x, and seems to work with no problems with Ant 1.6.x. If your development environment already runs Ant, you have everything you need to run Antelope.
</para>

<para>
A note about Ant 1.6: With the release of Ant 1.6, the Ant developers have choosen to package the classes that formerly were part of "optional.jar" into a variety of smaller jar files.
</para>

</chapter>

<chapter id="runningantelope">
@style@
<title>Running Antelope</title>

<section id="options">
@style@
<title>Option Settings</title>
<para>
Either way, Antelope is operated almost identically. To set up Antelope, click on the "Options" button. This will display the following:
</para>

<para>
<figure>
<title>Options Panel</title>
<imageobject>
    <imagedata fileref="options_general.gif" format="GIF"/>
</imageobject>
</figure>
</para>

<para>
When running Antelope as a stand-alone application, the options "Save all files before running targets" and "Use error parsing" are not available. This is the only difference between the stand-alone and the plugin.
</para>

<para>
The available options on the "General" tab are:
</para>

<itemizedlist>

<listitem>
<para>
<emphasis role="bold">Save all files before running targets</emphasis> <emphasis>This is only available when running as a jEdit plugin.</emphasis> If checked, all files that are currently open for editing in jEdit will be saved before running the selected target. The default setting is checked, that is, do save all files before executing the target.
</para>
</listitem>

<listitem>
<para>
<emphasis role="bold">Use error parsing</emphasis> <emphasis>This is only available when running as a jEdit plugin.</emphasis> If checked, output from the target will be passes through the Console plugin error parser and errors will be displayed in the ErrorList plugin. This is useful for tasks such as javac that produce standard error messages. Other tasks may not produce output suitable for error parsing, in which case, the output might be cleaner if this options is turned off. The default setting is checked, that is, do use error parsing.
</para>
</listitem>

<listitem>
<para>
<emphasis role="bold">Show performance statistics</emphasis> If checked, Antelope will keep track of the amount of time that each target and task takes to execute. At the end of the build, these times will be sorted from fastest to slowest and displayed following the build output. This can be useful to pinpoint slow and/or inefficient spots in the build process and identify those areas that could benefit from optimization. The default setting is unchecked, that is, do not show performance statistics.
</para>
</listitem>

<listitem>
<para>
<emphasis role="bold">Automatically reload build file</emphasis> If checked, Antelope will automatically reload the build file before running a target. That means that all properties will be reset to their original values or reloaded from property files as necessary. Keep in mind that properties set via the "Properties" button and dialog are not applied until the build file is reloaded. The default setting is checked, that is, do automatically reload the build file prior to each build. On the other hand, if there are properties that are loaded via a &lt;property file="filename.props"/&gt; or &lt;loadproperties srcfile="filename"/&gt;, Antelope will watch those files and reload the build file automatically if they change. Changes to such files cause a reload regardless of this setting.
</para>
</listitem>
</itemizedlist>

<para>
The available options on the "Targets" tab are:
</para>

<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Show subtargets</emphasis> There are several common conventions for designating "primary" targets and "subtargets", also referred to as "public" and "private" targets. Primary (or public) targets are those that are invoked directly, while subtargets (or private targets) are generally "helper" targets that are invoked from other targets. Antelope supports three of the most common conventions:

    <itemizedlist>
    <listitem>
    <para>
    One method of distinguishing between primary and subtargets is only giving descriptions to primary targets. Unchecking the "Show targets without descriptions" will cause Antelope to display buttons only for targets that have a description.
    </para>
    </listitem>

    <listitem>
    <para>
    Another common method to designate subtargets is to use "dot" notation, for example, a "clean" target may have two helper targets, "clean.docs" and "clean.api.docs". Unchecking the "Show targets with dots" will cause Antelope to display a button for the "clean" target but not the "clean.docs" nor the "clean.api.docs" targets.
    </para>
    </listitem>

    <listitem>
    <para>
    The third method of designating subtargets is to start the names of these targets with a dash, for example, "-clean.docs" and "-clean.api.docs". Unchecking the "Show targets with dash" will cause Antelope to display a button for each such target.
    </para>
    </listitem>
    </itemizedlist>
By default, none of these options are selected. Antelope displays all private targets in italics.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Sort target buttons</emphasis> By default, the target buttons are sorted alphabetically by target name. Unchecking this box will cause the target buttons to be displayed in the order that they appear in the build file.
</para>
</listitem>
</itemizedlist>

<para>
The available options on the "Messages" tab are:
</para>

<itemizedlist>

<listitem>
<para>
<emphasis role="bold">Set message level</emphasis> There are five message levels available and are in order of verbosity, "Error" being the least verbose and "Debug" being the most. For general use, "Information" is about right and is the default setting.
</para>
</listitem>
</itemizedlist>

<para>
The available options on the "General" tab are:
</para>

<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Show message events</emphasis> Ant produces messages on various events as it runs a target. Generally, all Ant messages are useful, but these can be adjusted as necessary. Turning off 'Target events' and 'Task events' will generally show all the important information without too much excess output. The default is that 'Build events' and 'Log events' are checked.
</para>
</listitem>

</itemizedlist>

<para>
The available options on the "Appearance" tab are:
</para>


<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Show button text</emphasis> This will turn on or off the display of the text on the control buttons.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Show button icon</emphasis> This will turn on or off the display of the icon on the control buttons.
</para>
</listitem>
</itemizedlist>

<para>
All option settings are stored per build file (except for the Appearance settings), which means that when you close one file and open another, the option settings for the new file will be retrieved and automatically set.
</para>
</section>

<section id="standalone">
@style@
<title>Antelope as a Stand-Alone Application</title>

<para>
Note: previous releases of Antelope recommended using Ant with the included "run.xml" to start Antelope.  This is no longer recommended.  If you have Java 1.5 and Ant 1.6 or 1.7, just run the jar file as below, or in Windows and some Linux distributions, you can double click the jar file to start Antelope.
</para>
<para>
Start Antelope by running:
</para>

<para>
<programlisting>
<![CDATA[
    cd AntelopeApp_@buildnum@
    java -jar AntelopeApp_@buildnum@.jar
]]>
</programlisting>
</para>

<para>
The first time you run this you will be asked to enter the location of the 'lib' directory of your Ant installation.
</para>

<para>
You can also install Antelope by hand. Antelope is packaged as a single jar file, Antelope.jar. Several other jar files may be necessary:
</para>

<itemizedlist>
<listitem>
<para><emphasis role="bold">ant.jar</emphasis> Antelope requires Ant to do anything useful. Ant is available at http://ant.apache.org. Put it in your classpath.
</para>
</listitem>

<listitem>
<para><emphasis role="bold">(Ant 1.5.x) optional.jar</emphasis> This is an optional library that is distributed with Ant. It has additional Ant tasks that may be useful. Put it in your classpath as required.
</para>
</listitem>

<listitem>
<para><emphasis role="bold">(Ant 1.6.x) ant-launcher.jar</emphasis> Ant 1.6.0 split the main ant.jar into a number of smaller files to improve performance and managability. For Ant 1.6.x, ant-launcher.jar is the file that is used to actually start Ant. This jar must also be in your classpath.
</para>
</listitem>

<listitem>
<para><emphasis role="bold">tools.jar</emphasis> This is distributed with the Java Software Development Kit. If your build file makes use of any of the JDK tools (such as javac or javadoc), put this in your classpath.
</para>
</listitem>

<listitem>
<para><emphasis role="bold">An XML parser</emphasis> This can be one of several publicly available XML parsers. Ant is shipped with the Xerces parser. To use the Xerces parser shipped with Ant, add xercesImpl.jar and xml-api.jar from the ${ant.home}/lib directory to your classpath. If you have Java 1.5, it also comes with a built-in XML parser. See the <link linkend="xmlparser">note</link> about having multiple parsers in your classpath and how to get around this problem.
</para>
</listitem>

</itemizedlist>

<para>
<emphasis role="bold">Unless you are running an older version of Java and/or an older version of Ant, just running the jar file will automatically include all necessary files.</emphasis>
</para>

<para>
Here is Antelope running as a stand-alone application:
</para>

<para>
<figure>
<title>Antelope as a stand-alone application</title>
<imageobject>
    <imagedata fileref="standalone.gif" format="GIF"/>
</imageobject>
</figure>
</para>

<para>
Antelope as a stand-alone application provides a few features not found in the plugin version. In the plugin version, these features are provided by jEdit, so are not duplicated. The additional features are:
</para>

<para>
<itemizedlist>
<listitem><para>The "File" menu deals with the build file, providing the ability to create a new build file, open a build file and to save changes to the build file. Antelope provides some basic editing capabilities, but is not intended to be a full-featured editor. You may find other editors more suited to editing build files. </para></listitem>
<listitem><para>Also on the "File" menu is the list of recently opened files. This is handy for choosing a file that was previously opened without using the file chooser.</para></listitem>
<listitem><para>The "Output" menu provides the ability to save the Ant output to a file and to clear the 'Output' window.</para></listitem>
<listitem><para>The "Options" menu provides the ability to set a number of options for the application:</para>
<para>
<figure>
<title>Font chooser</title>
<imageobject>
    <imagedata fileref="font_dialog.gif" format="GIF"/>
</imageobject>
</figure>
The same font will be used for both the editor and output window.
</para>

<para>
<figure>
<title>Editor options</title>
<imageobject>
    <imagedata fileref="editor_options_dialog.gif" format="GIF"/>
</imageobject>
</figure>
</para>

<para>
<figure>
<title>Syntax highlighting options</title>
<imageobject>
    <imagedata fileref="syntax_dialog.gif" format="GIF"/>
</imageobject>
</figure>
Syntax hightlighting only applies to the editor window, not the output window.
</para>

</listitem>
</itemizedlist>
</para>

<para>
Printing is not available in this version, but is on the feature list for implementation.
</para>

</section>

<section id="plugin">
@style@
<title>Antelope as a jEdit Plugin</title>

<para>
<emphasis role="bold"><emphasis role="italic">Due to changes in the jEdit API, Antelope plugin versions prior to 2.60 are for jEdit 4.1, versions 2.60 and later require jEdit 4.2 or later.
</emphasis></emphasis>
</para>

<para>
Here is Antelope running in jEdit:
</para>

<para>
<figure>
<title>Antelope in jEdit</title>
<imageobject>
    <imagedata fileref="jedit.gif" format="GIF"/>
</imageobject>
</figure>
</para>

<para>
Errors found by Ant during a build (for example, a compilation error) will be shown in the ErrorList plugin.
</para>

</section>
</chapter>

<chapter id="runningtargets">
@style@
<title>Running Ant Targets</title>

<para>
Ant targets are ran by simply clicking the associated button. The button for a running target will show red text. As the target executes, progress will be displayed on the progress bar below the button panel and output will be displayed either on the "Output" tab (in stand-alone mode) or in the Console window (in jEdit). The progress bar will be colored green as each task executes and succeeds, the bar will turn red on a build failure.
</para>
<imageobject>
    <imagedata fileref="target_buttons.gif" format="GIF"/>
</imageobject>

<para>
Long running targets can be stopped by clicking any of the target buttons. If Antelope is being ran as a jEdit plugin, execution can also be stopped by clicking the "Stop" button on the Console plugin. Depending on what the particular target is set to do, you may need to click the button several times to get execution to stop. An example is the &lt;java&gt; task with the "fork" attribute set to true. Ant starts a separate thread for the java task, so two clicks will be necessary, one to stop the jvm thread and one to stop the Ant thread.
</para>

<para>
Multiple targets can be selected to run one right after another by selecting the "Multiple targets" checkbox. When this checkbox is checked, the target buttons become checkboxes. Check the targets in the order that you want them to execute. The sequence of execution is displayed along side the target name. In the image below, the "docs-xalan" target will run first, followed by the "dist" target. Once you have selected some targets to run, start them by clicking the "Execute" button. The currently running target will be displayed in the progress bar. Once execution has started, it can be stopped by clicking the "Execute" button a second time. Again, depending on what the particular target is set to do, you may need to click it several times to get execution to stop.
</para>
<imageobject>
    <imagedata fileref="multiple_targets.gif" format="GIF"/>
</imageobject>
</chapter>

<chapter id="propertydisplay">
@style@
<title>Displaying Ant Properties</title>
<para>
The "Properties" button displays the current properties and references known to Ant from the current build file and the system environment. This is handy for determining exactly what Ant thinks a specific property value is. "Properties" and "References" are for viewing only, not for editing. The "Properties" shows all properties known to the Ant project: system properties, user properties, and global properties set in the build file. The "References" tab shows all global references known to the Ant project.
</para>

<para>
Note that in some cases, not all properties can be shown. Some properties may be set "on the fly" during the build, others may be read from properties files. When trying to debug a build file, it may be useful to use the <link linkend="tracing">"trace"</link> mode, which attempts to load all properties as they are encountered without actually executing any tasks.
</para>

<para>
<figure>
<title>Displaying Ant Properties</title>
<imageobject>
    <imagedata fileref="properties.gif" format="GIF"/>
</imageobject>
</figure>
</para>

<para>
The "User" tab is for setting user properties. These are properties that would normally be passed to Ant on the command line. These properties are persistent for the build file, so each time the build file is opened, the user properties will be restored. To enter a new property, click the "New" button to create a blank row in the table. Be sure to "enter" the name and value, that is press the 'Tab' or 'Enter' key or click out of the cell to make sure the name and/or value are stored. To remove a property, empty the corresponding value.
</para>

<para>
<figure>
<title>Displaying User-Defined Properties</title>
<imageobject>
    <imagedata fileref="user_properties.gif" format="GIF"/>
</imageobject>
</figure>
</para>

<para>
The "Description" tab shows some information about the build file project. The version of Ant that is in use, a list of targets in the build file, and other useful information is shown.
</para>

<para>
<figure>
<title>Displaying Project Description</title>
<imageobject>
    <imagedata fileref="description_properties.gif" format="GIF"/>
</imageobject>
</figure>
</para>

</chapter>

<chapter id="editing">
@style@
<title>Editing the Build File</title>

<para>
Clicking the "Edit" button puts Antelope in 'edit' mode. Antelope will display a tree representing the build file. Clicking on any item in the tree moves the cursor in the editor to that item in the build file.
</para>

<para>
As a jEdit plugin, clicking the "Edit" button will open the build file in a jEdit buffer.
</para>

<para>
As a stand-alone application, clicking the "Edit" button opens the "Edit" tab to edit the build file.
</para>

<para>
When the file is saved (either by saving the buffer in jEdit or by using the File - Save Build File menu item in stand-alone mode), Antelope will immediately reload the build file to pick up any changes and refresh the button panel to reflect those changes.
</para>

<para>
<emphasis>
Note: If the build file has an xml format error, the target buttons will disappear when the file is saved. To make the buttons reappear, correct the error and resave. Usually the output will give some indication of the error in the build file.
</emphasis>
</para>

<para>
Here is Antelope in edit mode:
</para>

<para>
<figure>
<title>Antelope in 'Edit' Mode</title>
<imageobject>
    <imagedata fileref="editmode.gif" format="GIF"/>
</imageobject>
</figure>
</para>

<para>
Icons:
</para>

<para>
<inlinemediaobject>
<imageobject>
   <imagedata fileref="ant.gif" format="GIF"/>
</imageobject>
</inlinemediaobject>
An Ant Project.
</para>

<para>
<inlinemediaobject>
<imageobject>
   <imagedata fileref="red_ant.gif" format="GIF"/>
</imageobject>
</inlinemediaobject>
An imported Ant Project.
</para>

<para>
<inlinemediaobject>
<imageobject>
   <imagedata fileref="Target16.gif" format="GIF"/>
</imageobject>
</inlinemediaobject>
An Ant Target in the main project file.
</para>

<para>
<inlinemediaobject>
<imageobject>
   <imagedata fileref="RedTarget16.gif" format="GIF"/>
</imageobject>
</inlinemediaobject>
An Ant Target in an imported project file.
</para>

<para>
<inlinemediaobject>
<imageobject>
   <imagedata fileref="Wrench16.gif" format="GIF"/>
</imageobject>
</inlinemediaobject>
An Ant Task.
</para>

<para>
Note the navigation arrows circled in red in the above image. As you click on items in the edit tree, the cursor in the editor panel will move to that item in the build file. The navigation arrows allow you to go back and forward, much like the back and forward buttons on a web browser. <emphasis>Beware that clicking on a target imported from another file will cause that file to be opened in the editor panel.</emphasis>
</para>

<para>
<figure>
<title>Dependency Tree</title>
<imageobject>
    <imagedata fileref="dependency_tree.gif" format="GIF"/>
</imageobject>
</figure>
</para>

<para>
Right clicking on a target in the edit tree shows a dependency tree for that target. A "dependency tree" shows a list of targets that the selected target will by virtue of the targets being listed in the targets' 'depends' attribute, as well as any targets that may be called by &lt;ant&gt; and &lt;antcall&gt; tasks contained in the target. Like the edit tree, clicking on targets in the dependency tree will also move the cursor in the editor panel to the selected item.
</para>

<para id="tip">
<emphasis role="bold">Tip:</emphasis> Antelope can open most xml files and display them in the editor and in the tree. If the xml file is not a build file (as determined by the root element being "project"), then the "Run" and "Trace" mode buttons will be disabled.
</para>
</chapter>

<chapter id="tracing">
@style@
<title>Tracing Target Execution</title>
<para>
Antelope is put into 'tracing mode' when the "Trace" button is clicked. When in tracing mode, the background of the button panel will be blue. When in tracing mode, clicking the target buttons will not actually execute the target. Instead, the output will show the specific order of execution of tasks performed by the target and targets that the selected target depends on. This is useful for figuring out exactly what a specific target does and the order of operations. To turn off tracing mode, click the "Trace" button a second time.
</para>

<para>
In general, targets are not parsed below task level, that is, nested task attributes are not displayed. However, two tasks are treated specially as they have a direct bearing on how a target executes. These two tasks are <computeroutput>ant</computeroutput> and <computeroutput>antcall</computeroutput>. If the trace encounters the <computeroutput>ant</computeroutput> task, the <computeroutput>buildfile</computeroutput> and <computeroutput>target</computeroutput> attributes will be displayed, the build file loaded, and the target traced in that build file. If the trace encounters an <computeroutput>antcall</computeroutput> task, the <computeroutput>target</computeroutput> attribute will be parsed and the target will be traced.
</para>

<para>
Here is a sample trace:
</para>

<para>
<programlisting>
<![CDATA[
Tracing target: deploy-all
Legend: <target>[task]

<deploy-all>
<clean>[delete]
<deploy-all>[javac deprecation=on debug=on destdir=build srcdir=src
 includes=ise/ excludes=ise/antelope/plugin/ includejavaruntime=yes source=1.5]
<deploy-all>[copy todir=build]
<deploy-all>[jar jarfile=/usr/local/java/antelope/Antelope]
</deploy-all>

Done tracing target: deploy-all
]]>
</programlisting>
</para>

<para>
And a line by line explanation:
</para>

<para>
<table frame="all">
<title>Target Trace Example Explanation</title>
<tgroup cols="2">
<tbody>
<row><entry>Tracing target: deploy-all</entry><entry>The trace is going to trace the deploy-all target.</entry></row>
<row><entry>Legend: &lt;target&gt;[task]</entry><entry>Targets shown with angle brackets, tasks with square brackets.</entry></row>
<row><entry>&lt;deploy-all&gt;</entry><entry>The trace is starting on the deploy-all target.</entry></row>
<row><entry>&lt;clean&gt;[delete]</entry><entry>The deploy-all target depends on the clean target, which performs a 'delete' task.</entry></row>
<row><entry>&lt;deploy-all&gt;[javac deprecation=on debug=on destdir=build srcdir=src includes=ise/ excludes=ise/antelope/plugin/ includejavaruntime=yes source=1.5]</entry><entry>The deploy-all target executes a 'javac' task. The parameters for the task are shown.</entry></row>
<row><entry>&lt;deploy-all&gt;[copy todir=build]</entry><entry>The deploy-all target executes a 'copy' tasks. Most likely, this tasks has nested includes and/or excludes, which are not shown in the trace.</entry></row>
<row><entry>&lt;deploy-all&gt;[jar jarfile=/usr/local/java/antelope/Antelope]</entry><entry>The deploy-all target executes the 'jar' task.</entry></row>
<row><entry>&lt;/deploy-all&gt;</entry><entry>The trace has reached the end of the deploy-all target.</entry></row>
<row><entry>Done tracing target: deploy-all</entry><entry>Obviously, the trace is done.</entry></row>
</tbody>
</tgroup>
</table>
</para>

<para>
So the 'deploy_all' target first causes the 'clean' target to execute a 'delete' task, then causes the 'compile' target to execute a 'javac' task, and finally causes the 'deploy' target to create a jar file.
</para>

<para>
<figure>
<title>Antelope in 'Trace' Mode</title>
<imageobject>
    <imagedata fileref="tracemode.gif" format="GIF"/>
</imageobject>
</figure>
</para>

</chapter>


<chapter id="antlogger">
@style@
<title>AntLogger</title>

<para>
One of the classes distributed with Antelope is AntLogger, which is useful outside of Antelope. This is a special Ant logger and can be attached to Ant as the default logger on the command line. All Ant log messages are sent to a java.util.logging.Logger, so any number of handlers can be associated for controlling output. Make sure ise.antelope.AntLogger is in the classpath, then run Ant:
</para>

<para>
<computeroutput>ant -logger ise.antelope.AntLogger [other standard Ant options]</computeroutput>
</para>

<para>
<emphasis role="bold">Properties</emphasis>
</para>

<para>
Properties can be set either on the command line or in the build file. All are optional. These properties are read and set at the start of each call to <computeroutput>buildStarted</computeroutput>
</para>

<para>
<table frame="all">
<title>AntLogger Properties</title>
<tgroup cols="3">
<thead>
<row>
<entry>Property</entry>
<entry>Description</entry>
<entry>Default</entry>
</row>
</thead>
<tbody>
<row>
<entry>antlogger.echo</entry>
<entry>If set to true, output from this logger will be echoed to the original
System.out and System.err print streams.</entry>
<entry>false</entry>
</row>
<row>
<entry>antlogger.namespace</entry>
<entry>The namespace for the logger. See the java.util.logging.Logger API documentation for a discussion of logger namespaces. This should be a dot separated name and should normally be based on the package name or class name of the subsystem, such as org.apache.tools.ant.</entry>
<entry>ise.antelope.Antelope</entry>
</row>
<row>
<entry>antlogger.file</entry>
<entry>If used, will add a java.util.logging.FileHandler to the current logger. See the java.util.logging.FileHandler API for a discussion of the value pattern. Basically, this is the name of a file, but other things can be done.</entry>
<entry>none</entry>
</row>
<row>
<entry>antlogger.file.append</entry>
<entry>If set to true and antlogger.file is being used, then output will be appended to an existing file. If false, any existing file will be overwritten.</entry>
<entry>false</entry>
</row>
</tbody>
</tgroup>
</table>
</para>

<para>
<emphasis role="bold">Examples:</emphasis>
</para>

<para>
<programlisting>
<![CDATA[
<property name="antlogger.echo" value="true"/>
]]>
</programlisting>
</para>

<para>
- or -
</para>

<para>
<computeroutput>ant -logger ise.antelope.AntLogger -Dantlogger.echo=true [other options]</computeroutput>
</para>

<para>
<programlisting>
<![CDATA[
<property name="antlogger.namespace" value="com.mycompany.package"/>
]]>
</programlisting>
</para>

<para>
- or -
</para>

<para>
<computeroutput>ant -logger ise.antelope.AntLogger -Dantlogger.namespace=com.mycompany.package [other options]</computeroutput>
</para>

<para>
<programlisting>
<![CDATA[
<property name="antlogger.file" value="/tmp/output.log"/><br>
<property name="antlogger.file.append" value="true"/><br>
]]>
</programlisting>
</para>

<para>
- or -
</para>

<para>
<computeroutput>ant -logger ise.antelope.AntLogger -Dantlogger.file=/tmp/output.log -Dantlogger.file.append=true [other options]</computeroutput>
</para>

<para>
<emphasis role="bold">Output</emphasis>
</para>

<para>
Messages for certain build events are sent at a particular log Level. See java.util.logging.Level for a discussion of the various levels. AntLogger associates build events with log Levels as follows:
</para>

<para>
<table frame="all">
<title>AntLogger Error Levels</title>
<tgroup cols="2">
<tbody>
<row><entry>Level.ERROR</entry><entry>Build failed</entry></row>
<row><entry>Level.WARNING</entry><entry>Build succeeded</entry></row>
<row><entry>Level.CONFIG</entry><entry>Build started, task started/ended, target started/ended</entry></row>
<row><entry>Level.INFO</entry><entry>All other messages</entry></row>
</tbody>
</tgroup>
</table>
</para>

</chapter>

<chapter id="for-developers">
@style@
<title>For Developers</title>

<section id="embedding-antelope">
   @style@
<title>Embedding Antelope in Other Applications</title>

<para>
Antelope has an open API that allows developers to easily embed Antelope into other applications.
</para>

<para>
The main object to embed is AntelopePanel. AntelopePanel has three constructors:
<programlisting>
<![CDATA[
   public AntelopePanel()

   public AntelopePanel( CommonHelper helper )

   public AntelopePanel( File build_file, CommonHelper helper, boolean use_internal_menu )
]]>
</programlisting>
</para>

<para>
The first no-argument constructor is identical to:
<programlisting>
<![CDATA[
   public AntelopePanel( null, null, true )
]]>
</programlisting>

And the second constructor is identical to:
<programlisting>
<![CDATA[
   public AntelopePanel( null, helper, true )
]]>
</programlisting>
</para>

<para>
The third constructor allows the most flexibility:
<programlisting>
<![CDATA[
   public AntelopePanel( File build_file, CommonHelper helper, boolean use_internal_menu )
]]>
</programlisting>

</para>

<para>
<itemizedlist>
   <listitem>
   <emphasis role="bold">build_file</emphasis> If supplied a build file, the AntelopePanel will open the build file and construct it's button panel from it.
   </listitem>
   <listitem>
   <emphasis role="bold">helper</emphasis> CommonHelper is an interface and has a number of methods that may be provided by applications wishing to interact with the AntelopePanel. The CommonHelper interface will be covered in more detail below.
   </listitem>
   <listitem>
   <emphasis role="bold">use_internal_menu</emphasis> This boolean setting tells AntelopePanel whether or not to use it's internal menu. Applications may provide their own, or the default menu provided by AntelopePanel can be used. When Antelope is running as a jEdit plugin, the internal menu is used, when running as a stand-alone application, it is not.
   </listitem>
</itemizedlist>
</para>

<para>
The proper way to have your application interact with AntelopePanel is by writing a class that implements the CommonHelper interface.
</para>
<para>
<programlisting>
<![CDATA[


package ise.antelope.common;

import java.awt.event.ActionListener;

/**
 * Objects that want to manipulate AntelopePanel must implement this
 * interface.
 */
public interface CommonHelper extends ActionListener {

   /**
    * Event ID for trace event.
    */
   public final static int TRACE_EVENT = 550927;

   /**
    * Event ID for edit event.
    */
   public final static int EDIT_EVENT = 470226;

   /**
    * AntelopePanel will pass the target execution thread to the helper.
    * Implementors of this interface may interrupt the thread to cause
    * AntelopePanel to stop running a target.
    *
    * @param thread  the execution thread
    */
   public void setTargetExecutionThread( Thread thread );

   /**
    * Check if the helper can save before running a target.
    *
    * @return   true if the helper can save files.
    */
   public boolean canSaveBeforeRun();

   /**
    * Tell the helper to save now.
    */
   public void saveBeforeRun();

   /**
    * Tell the helper to clear its error source. This was implemented to
    * support the ErrorList plugin for jEdit, other editors may hava a similar
    * need.
    */
   public void clearErrorSource();

   /**
    * Should the AntelopePanel show its Edit button? Clicking the Edit button
    * should cause AntelopePanel to show the build file in an editor.
    *
    * @return  true if the AntelopePanel should show an edit button.
    */
   public boolean canShowEditButton();

   /**
    * An action that the helper would like to have happen when the
    * Edit button is clicked.
    *
    * @return   The edit button action
    */
   public ActionListener getEditButtonAction();


   /**
    * The action that the helper would like to have happen when the
    * Run button is clicked.
    *
    * @return   The run button action
    */
   public ActionListener getRunButtonAction();

   /**
    * Opens the given file in an editor.
    * @param the file to open.
    */
   public void openFile( java.io.File f );

   /**
    * Generally, the classloader returned by the helper will probably be null,
    * but some apps, like jEdit, use special classloaders. As AntProject needs
    * direct access to the classloader that loads Ant, the helper should pass
    * the classloader via this method.
    *
    * @return   The classloader that loaded Ant.
    */
   public ClassLoader getAntClassLoader();

   /**
    * The Ant installation that the helper uses may not be in the application classpath.
    * AntelopePanel needs to know where the Ant jars are located so it can run Ant
    * properly. Implementers may return null, meaning that the Ant jars are already
    * in the classpath.
    * <p>
    * <strong>WARNING:</strong> this method is likely to change. The helper should
    * not need to provide a list of jars, rather, it should provide an ANT_HOME
    * directory. Antelope should be smart enough to find the jars given the
    * directory, plus should automatically look in the standard Ant library
    * locations.
    * @return a list of the jars used by Ant. The individual list items must be Strings
    * representing the file names of the jar files. Note that other jars may be included,
    * such as custom Ant task libraries.
    */
   public java.util.List getAntJarList();

}
]]>
</programlisting>

</para>

<para>
At a minimum, you'll need to include all classes in the ise.antelope.common and ise.library packages.
</para>


</section>

<section id="jedit">
   @style@
<title>API for jEdit Plugin Developers</title>

<para>
Antelope can be used from other jEdit plugins that may desire to run Ant targets. The public API is described here, plus some examples of how to use this API from other plugins. You can also use this API from a beanshell macro, see the <link linkend="faq">FAQ section</link>.
</para>

<para>
<programlisting>
public static File getBuildFile(View view);
</programlisting>
This method returns a reference to the current build file.
</para>

<para>
<programlisting>
public static String[] getTargetList(File buildFile);
</programlisting>
This method returns a list of the target names in the given build file.
</para>

<para>
<programlisting>
public static void executeTarget( View view, File buildFile, String target );
</programlisting>
This method executes a target. Since the execution is through Antelope, output will be to the Console plugin and errors will be displayed in the ErrorList plugin. The AntelopePlugin will attempt to find an instance of Antelope for the given view, then execute the target. The target must exist in the given build file.
</para>

<para>
<programlisting>
public static void setBuildFile(View view, File buildFile);
</programlisting>
This method sets the current build file for the Antelope instance in the given view. Antelope will reload itself to reflect the new build file.
</para>

<para>
Following are some examples of calling these methods from your plugin. Notice that you do not need the Antelope source or classes to compile or run your plugin, so you do not need to make Antelope a dependency for the PluginManager. The examples only work if Antelope is actually installed as a jEdit plugin and do nothing otherwise. The best place to put these examples is in your plugin's Plugin class. These examples are suitable for copy and paste into your plugin's source code. You will need to import: org.gjt.sp.jedit.EditPlugin, org.gjt.sp.jedit.jEdit, org.gjt.sp.jedit.View, and java.io.File.
</para>

<para>
This simply returns "true" if Antelope is installed. It is convenient to call this method prior to calling the others.
<programlisting>
public static boolean isAntelopeAvailable() {
   EditPlugin ep = jEdit.getPlugin( "ise.antelope.plugin.AntelopePlugin" );
   return ep != null;
}
</programlisting>
</para>

<para>
This method returns a reference to the current build file or null if Antelope is not installed or on any other error.
<programlisting>
   public static File getBuildFile(View view) {
      if (view == null){
         return null;
      }
      if ( !isAntelopeAvailable() ) {
         return null;
      }
      EditPlugin ep = jEdit.getPlugin( "ise.antelope.plugin.AntelopePlugin" );
      try {
         Class c = ep.getClass();
         java.lang.reflect.Method m = c.getDeclaredMethod( "getBuildFile",
               new Class[]{View.class} );
         if ( m == null ) {
            return null;
         }
         return (File)m.invoke( null, new Object[]{view} );
      }
      catch ( Throwable e ) {
      }
      return null;
   }
</programlisting>
</para>

<para>
This method returns a list of targets in the given build file or null if Antelope is not installed or on any other error.
<programlisting>
   public static String[] getTargetList(File buildFile) {
      if (buildFile == null || !buildFile.exists()){
         return null;
      }
      if ( !isAntelopeAvailable() ) {
         return null;
      }
      EditPlugin ep = jEdit.getPlugin( "ise.antelope.plugin.AntelopePlugin" );
      try {
         Class c = ep.getClass();
         java.lang.reflect.Method m = c.getDeclaredMethod( "getTargetList",
               new Class[]{File.class} );
         if ( m == null ) {
            return null;
         }
         return (String[])m.invoke( null, new Object[]{buildFile} );
      }
      catch ( Throwable e ) {
      }
      return null;
   }
</programlisting>
</para>

<para>
This method will execute an Ant target via Antelope.
<programlisting>
   public static void executeAntTarget(View view, File buildFile, String target) {
      if (view == null || buildFile == null || target == null)
         return;
      if ( !isAntelopeAvailable() ) {
         return;
      }
      EditPlugin ep = jEdit.getPlugin( "ise.antelope.plugin.AntelopePlugin" );
      try {
         Class c = ep.getClass();
         java.lang.reflect.Method m = c.getDeclaredMethod( "executeTarget",
               new Class[]{View.class, File.class, String.class} );
         if ( m == null ) {
            return;
         }
         m.invoke( null, new Object[]{view, buildFile, target} );
      }
      catch ( Throwable e ) {
      }
   }
</programlisting>
</para>

<para>
This method will cause Antelope to load the given build file.
<programlisting>
   public static void setAntelopeBuildFile(View view, File buildFile) {
      if (buildFile == null || !buildFile.exists()){
         return;
      }
      if ( !isAntelopeAvailable() ) {
         return;
      }
      EditPlugin ep = jEdit.getPlugin( "ise.antelope.plugin.AntelopePlugin" );
      try {
         Class c = ep.getClass();
         java.lang.reflect.Method m = c.getDeclaredMethod( "setBuildFile",
               new Class[]{View.class, File.class} );
         if ( m == null ) {
            return;
         }
         m.invoke( null, new Object[]{view, buildFile} );
      }
      catch ( Throwable e ) {
      }
   }
</programlisting>
</para>
</section>

</chapter>

<chapter id="faq">
@style@
<title>Frequently Asked Questions</title>
<para>
<itemizedlist>

<listitem>
<para>
<emphasis role="bold">When I try to use the &lt;javac&gt; task, I keep getting a "no compiler found" error, but I have JAVA_HOME set correctly. How can I fix this?</emphasis>
</para>
<para>
Check two things: (1) make sure JAVA_HOME is really set correctly. Windows JDK installations by default set JAVA_HOME to point to the jre directory under your JDK installation. This is fine for running Java programs, but not for compiling. Set JAVA_HOME up one directory to point to the root of your JDK installation, not the jre directory. (2) make sure JAVA_HOME/bin is in your PATH. This is the directory that contains javac.
</para>
<para>
Here are some example settings from my Windows 2000 computer:
</para>
<para>
<programlisting>
JAVA_HOME = c:\j2sdk1.4.1_02
PATH = (path to windows,etc);c:\j2sdk1.4.1_02\bin;
</programlisting>
</para>
</listitem>

<listitem>
<para>
<emphasis role="bold">I'd like to assign a key to a target button when running Antelope as a jEdit plugin. Is there anyway I can do this?</emphasis>
</para>
<para>
Mark Pollard and I worked out this solution:
</para>
<para>
In jEdit, open a new buffer and paste this in:
</para>
<para>
<programlisting>
jEdit.saveAllBuffers(view, false);
VFSManager.waitForRequests();
ise.antelope.plugin.AntelopePlugin plugin =
jEdit.getPlugin("ise.antelope.plugin.AntelopePlugin");
plugin.executeTarget(view, plugin.getBuildFile(view), "compile");
</programlisting>
</para>
<para>
Replace 'compile' with the name of the target you want to run. Save it in your ${user.home}/.jedit/macros directory (on my Windows machine, this is c:\Documents and Settings\danson\.jedit\macros, on my Linux box, it's /home/danson/.jedit/macros). Name it whatever you want, but be sure to give it a .bsh extention.
</para>
<para>
Depending on your jEdit version, it will either be automatically loaded or use the 'Macros' menu, then 'Rescan macros' item. Then under the 'Utilities' menu -> 'Global Options' -> 'Shortcuts', pick 'Macros' from the drop down box on the right, and assign a key to the macro you just saved.
</para>
<para>
If you name your targets consistently across your build files, this will work well for the targets that you run a lot, like 'compile' and 'test'.
</para>
</listitem>

<listitem>
<para>
<emphasis role="bold">I get out of memory errors when trying to run my build file in Antelope. How can I avoid this problem?</emphasis>
</para>
<para>
If you are starting Antelope with the run.xml file, edit this file and adjust this line:
</para>
<para>
<programlisting>
&lt;java classname="ise.antelope.app.Antelope" fork="true"&gt;
</programlisting>
</para>
<para>
to look like this:
</para>
<para>
<programlisting>
&lt;java classname="ise.antelope.app.Antelope" fork="true" maxmemory="128m"&gt;
</programlisting>
</para>
<para>
Adjust the maxmemory attribute as needed for your build.
</para>
<para>
If you are starting Antelope from command-line java, add the -Xmx parameter to the command line like this:
</para>
<para>
<programlisting>
java -Xmx128m -jar AntelopeApp_@buildnum@.jar
</programlisting>
</para>
</listitem>

<listitem>
<para>
<emphasis role="bold">All the buttons disappeared from Antelope. How do I get them back?</emphasis>
</para>
<para>
This means that you have an error in your build file and Antelope does not recognize it as valid xml. Usually the the output window will give some indication of the problem. Correct the build file and save it, and the buttons will reappear. (See the next question also.)
</para>
</listitem>

<listitem>
<para>
<emphasis role="bold">My build file uses external entities to include standard targets and properties. When I try to open this build file, all the buttons disappear. How do I get them back?</emphasis>
</para>
<para>
Antelope version 2.53 and earlier did not support external entities. Upgrade to a version later than 2.53. Also, be sure your external entities are declared correctly. This example is from the Ant FAQ:
<programlisting>
<![CDATA[
<?xml version="1.0"?>

<!DOCTYPE project [
    <!ENTITY common SYSTEM "file:./common.xml">
]>

<project name="test" default="test" basedir=".">

  <target name="setup">
    ...
  </target>

  &common;

  ...

</project>
]]>
</programlisting>

</para>
</listitem>

</itemizedlist>
</para>
</chapter>

<chapter id="support">
@style@
<title>Support</title>

<para>
Please visit the project web pages at
<ulink url="http://antelope.tigris.org">
http://antelope.tigris
</ulink> for reporting bugs, user mailing lists, and other technical resources. This is also the location for finding the latest releases. In particular, if you are using Antelope as a jEdit plugin, you will invariably find newer versions on the Antelope project web site than from jEdit's plugin manager.
</para>

<para>
You can also contact me directly at <email>danson@germane-software.com</email>
</para>

</chapter>

</book>