<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article 
        PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<title>Tags Plugin</title><articleinfo>
<authorgroup>
<author><othername>Kenrick Drew</othername></author>
<author><othername>Ollie Rutherfurd</othername></author>
<author><othername>Shlomy Reinstein</othername></author>
</authorgroup>
<edition>Version 3.1.0</edition>
</articleinfo>
<!-- $Id: users-guide.xml 19082 2010-12-02 15:52:44Z kpouer $ -->
<section>
<title>Introduction</title>
<para>The Tags plugin allows one to &quot;jump&quot; to the definition of a
class, function, variable, etc... using tag index files.
For example, in C programs, the user can immediately jump to the
definition of a desired function or data structure without having
to know where or what file it is defined. Tag jumping can be
accomplished by either selecting the desired tag, placing the
cursor on the tag, or entering the tag.</para><para>Tag index files are created by <ulink url="http://ctags.sourceforge.net/">ctags</ulink> (<ulink url="http://ctags.sourceforge.net/">http://ctags.sourceforge.net/</ulink>).</para></section>
<section>
<title>Creating Tag Index Files</title>
<para>For the Tags plugin to be useful, you must generate tag index files
using <citetitle>ctags</citetitle>.</para><para>To generate a tag index file for all source files in the
current directory:</para><programlisting>
ctags *</programlisting>
<para>To generate a tag index file or all source files in the
current directory and child directories:</para><programlisting>
ctags -R</programlisting>
<para>See the man page or documentation that comes with your version
of <citetitle>ctags</citetitle> for more information on using <citetitle>ctags</citetitle>.</para><para>Note that file paths in tag index file are relative to the
generated file, unless you pass absolute paths to <citetitle>ctags</citetitle>.</para><para><emphasis role="strong">Tag index files must be sorted, as the Tags plugin searches
using a binary search. By default Exuberant CTags sorts generated
tag index files.</emphasis></para></section>
<section>
<title>Usage</title>
<section>
<title>Tag Jumping</title>
<para>There are 2 ways to jump to a desired tag:</para><orderedlist>
<listitem>
<para>Place the cursor on or select the desired tag. Use
<citetitle>Plugins</citetitle> &gt; <citetitle>Tags</citetitle> &gt; <citetitle>Follow Tag</citetitle>.  <citetitle>Plugins</citetitle> &gt; <citetitle>Tags</citetitle> &gt;
<citetitle>Follow Tag (New View)</citetitle> will jump to a tag in a new view.</para></listitem>
<listitem>
<para><citetitle>Plugins</citetitle> &gt; <citetitle>Tags</citetitle> &gt; <citetitle>Follow Tag...</citetitle> will prompt you for
the desired tag. The <citetitle>Open new view</citetitle> checkbox will jump
to the entered tag in an new view.</para></listitem>
</orderedlist>
</section>
<section>
<title>The Tag Stack</title>
<para>The <citetitle>Tag Stack</citetitle> provides a visual history of tags you've followed
and where you've jumped from.  When you jump to (or <citetitle>follow</citetitle>) a
tag, both the location you jumped from and the location of the
tag you followed are pushed onto the <citetitle>Tag Stack</citetitle>.  Aside from
seeing how you've moved through buffers, the <citetitle>Tag Stack</citetitle> enables
you to jump to any of the positions in the stack.</para><para>For each position, the <citetitle>Tag Stack</citetitle> displays the line number, filename
and directory and the contents of the line (in bold).  The line before
and after are also displayed to provide some context.</para><blockquote>
<mediaobject><imageobject><imagedata backrefs="" classes="" dupnames="" fileref="tagstack.png" ids="" names="" />
</imageobject></mediaobject></blockquote>
<para>The context menu for the <citetitle>Tag Stack</citetitle> provides the follow actions:</para><variablelist>
<varlistentry>
<term>
<varname><citetitle>Go to</citetitle>:</varname></term>
<listitem>
<para>Move the caret to the position, leaving the item on the stack.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<varname><citetitle>Remove</citetitle>:</varname></term>
<listitem>
<para>Remove the selected element from the <citetitle>Tag Stack</citetitle>, without
changing the caret position.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<varname><citetitle>Pop</citetitle>:</varname></term>
<listitem>
<para>Move the caret to the topmost position on the stack, and remove
the topmost position.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<varname><citetitle>Clear</citetitle>:</varname></term>
<listitem>
<para>Removes all positions from the <citetitle>Tag Stack</citetitle> without moving the caret.</para></listitem>
</varlistentry>
</variablelist>
<para><citetitle>Tag Stack</citetitle> actions are accessible via <citetitle>Plugins</citetitle> &gt; <citetitle>Tags</citetitle>:</para><variablelist>
<varlistentry>
<term>
<varname><citetitle>Pop Position</citetitle>:</varname></term>
<listitem>
<para>Return to the topmost position on the stack.  This will
also remove the position from the <citetitle>Tag Stack</citetitle>.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<varname><citetitle>Push Position onto Tag Stack</citetitle>:</varname></term>
<listitem>
<para>Puts your current position at the top of the <citetitle>Tag Stack</citetitle>.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<varname><citetitle>Clear Tag Stack</citetitle>:</varname></term>
<listitem>
<para>Removes all elements from the <citetitle>Tag Stack</citetitle>.</para></listitem>
</varlistentry>
</variablelist>
<para>Each jEdit <citetitle>View</citetitle> has it's own stack.</para></section>
<section>
<title>Tag Collisions</title>
<para>A tag collision can occur when there is more than one defintion
for a specific tag as defined in the tag index files. This
especially occurs on object oriented programming languages, and
local projects where you are using a global system tag index
file along with a local tag index file. To easily facilitate
tag collisions, if more than one tag is found in the tag index
files, you are presented, located under the cursor, a list of
choices. You can select the desired tag by either using the
mouse, keyboard arrow keys or number keys (1 - 9 only).  The
tag collision list can be dismissed with the Escape (<citetitle>Esc</citetitle>) key.
The tag collision list can also be converted to a dialog
with the Space key.</para><para>If the <citetitle>Tag List</citetitle> dockable window is open, the list will be shown
in the dockable window instead of in a pop-up window. The
<citetitle>Tag List</citetitle> dockable window provides a 'Filter' menu using which
you can quickly filter the list of tags by the available attribute
values.</para></section>
</section>
<section>
<title>Configuration</title>
<para>The Tags plugin can be configured under the <citetitle>Plugins</citetitle> &gt;
<citetitle>Plugin Options...</citetitle>.</para><section>
<title>General</title>
<para><citetitle>Position dialogs under cursor</citetitle>:</para><blockquote>
<para>If your window manager is set to have window focus
follow the mouse pointer, and doesn't automatically
shift the window focus to new dialogs/windows,
this option can be helpful. Any dialog that the
plugin creates will be automatically placed under
the cursor. This is currently experimental. Note
that this doesn't work well for window managers
which automatically shift focus to new dialogs/windows.</para></blockquote>
<para><citetitle>Tags extend through member access operator</citetitle>:</para><blockquote>
<para>When tagging in the text area, the plugin by
default will consider the tag to be the word
under the cursor as well as any member access.</para></blockquote>
<para><citetitle>If tag match is found continue searching subsequent tag index files</citetitle>:</para><blockquote>
<para>By default, the first matching tag (or groups of tags
if a tag collision occurs) found will stop the search.
Using this option will allow all tag files to be searched,
results in searches taking longer.</para></blockquote>
<para><citetitle>Use line numbers when following tags, if specified in the tag files</citetitle>:</para><blockquote>
<para>Invoking Ctags with:</para><blockquote>
<para>--fields=+l</para></blockquote>
<para>causes it to add a &quot;line&quot; attribute to each tag, specifying
the line number in which the tag is defined. By default,
the &quot;follow tag&quot; operation ignores the line attribute of the
tag and uses the pattern to locate the tag. This has the
advantage that the tag may be located even if the file has
changed since it was indexed by Ctags.
However, using the pattern to locate the
tag does not work if there are multiple tags with the same
name and pattern in the file, which is common in object
oriented languages (e.g. an actionPerformed method in
several anonymous Java classes defined in the same file, or
a C function definition and forward declaration in the same
file).
In such cases, the line numbers can be used to locate the
tags. If the line attributes are specified in the tag files,
using this option causes the &quot;follow tag&quot; operation to jump
to the specified line number instead of searching for the
pattern.</para></blockquote>
<para><citetitle>Number of tag files to keep in memory</citetitle>:</para><blockquote>
<para>The tags plugin caches remote tag index files, when
editing over FTP, SFTP, etc...  To avoid loading remote
tag index files every time you wish to jump to a tag
defintion, these are cached.  This value controls how
many remote index files to cache in memory.</para></blockquote>
<para><citetitle>Keep local tags files in memory</citetitle></para><blockquote>
<para>If enabled, tag index file located on the local filesystem
are cached in memory, just as remote ones, rather than
reading them as a RandomAccessFile.  This may result
in slightly faster searching, but can dramatically increase
memory usage.</para></blockquote>
</section>
<section>
<title>Actions</title>
<para>List of actions that provide the &quot;follow tag&quot; functionality with
filtering of the tag list in case of collisions. For example,
you can create an action that jumps only to function prototypes,
or only to tags that belong to a certain class.
The filtering is based on tag attributes. Ctags provides command-
line options for adding various tag attributes (fields) to its
tag files, such as access, class, kind, scope etc. For custom
actions to work, this attribute information must exist in the tag
files.</para><para>Each action that you add has a name, an associated attribute and
a list of values for that attribute. When the action is invoked,
it first runs the &quot;follow tag&quot; action, and if tags are found,
it goes over the list of values one by one, and for each value
it reduces the list to only those tags having this value for
the attribute. If tags were found to have this value for the
attribute, these tags are then used for jumping or for the tag
collision popup/dockable. If no tags in the list have any of
the values, the action indicates that no tags were found.</para></section>
<section>
<title>Tag Files</title>
<para>List of tag index files the Tags plugin uses to search for
tag definitions.</para><para>&quot;tags&quot; is a special entry that doesn't represent an actual
file but rather the name of the file to look for in the current
buffer's directory.  The Tags plugin can also search for this
file in the current buffer's parent directories.  Double-click
on the entry to edit it.</para><para>The order of entries in the list is the order in which files
will be searched.</para></section>
</section>
<section>
<title>Suggested Keyboard Shortcuts and UI</title>
<para>Here are some suggested key bindings. These do stomp on
some jEdit key bindings, but I find that they work well.
They are based on the vi (and it's clones) key bindings
for tagging.</para><informaltable frame="all">
<tgroup cols="2">
<colspec colname="col_1" />
<colspec colname="col_2" />
<thead>
<row>
<entry><para>Action</para></entry>
<entry><para>Shortcut</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>Follow Tag</para></entry>
<entry><para>C+]</para></entry>
</row>
<row>
<entry><para>Follow Tag (New View)</para></entry>
<entry><para>C+S+]</para></entry>
</row>
<row>
<entry><para>Follow Tag...</para></entry>
<entry><para>A+]</para></entry>
</row>
<row>
<entry><para>Pop Position</para></entry>
<entry><para>C+T</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Keyboard shortcuts can be defined under the <citetitle>Shortcuts</citetitle> node
of the <citetitle>Global Options</citetitle> dialog.</para><para>Also one can place the tagging commands in the Context Menu.
Context menu items can be defined under the <citetitle>Context Menu</citetitle>
node of the Global Options dialog.</para></section>
<section>
<title>Where to Find <citetitle>ctags</citetitle></title>
<para>You can find the Exuberant C Tags program at:</para><blockquote>
<para><ulink url="http://ctags.sourceforge.net">http://ctags.sourceforge.net</ulink></para></blockquote>
<para>Exuberant C Tags is also included in the cygwin distribution
for Windows.</para><para>You can also use the standard UNIX ctags program, or the GNU
C Tags program, but you'll find that Exuberant C Tags
provides a bit more info (or too much depending on how much
of a minimalist you are).</para></section>
<section>
<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></section>
<section>
<title>Known Bugs/Limitations</title>
<itemizedlist>
<listitem>
<para>Tag index files <emphasis role="strong">MUST</emphasis> be sorted. This is becuase
tags are search for using a binary search.</para></listitem>
<listitem>
<para>Bachward searching patterns <literal>(?...?)</literal> are not supported.</para></listitem>
</itemizedlist>
</section>
<section>
<title>Future Directions</title>
<para>See TODO.TXT</para></section>
<section>
<title>Feedback</title>
<para>The preferred way to send bug reports or feature requests 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>jEdit-users mailing-list &lt;<ulink url="mailto:jedit-users@lists.sourceforge.net">jedit-users@lists.sourceforge.net</ulink>&gt;;</para></listitem>
<listitem>
<para>jEdit-devel mailing.list &lt;<ulink url="mailto:jedit-devel@lists.sourceforge.net">jedit-devel@lists.sourceforge.net</ulink>&gt;.</para></listitem>
<listitem>
<para>Ollie Rutherfurd &lt;<ulink url="mailto:oliver@jedit.org">oliver@jedit.org</ulink>&gt; (Current Maintainer)</para></listitem>
</itemizedlist>
</section>
<section>
<title>Credits</title>
<itemizedlist>
<listitem>
<para>Vim reference manual (Bram Moolenaar)</para></listitem>
<listitem>
<para>Exuberant C Tags man page (Darren Hiebert)</para></listitem>
</itemizedlist>
</section>
<section>
<title>Changelog</title>
<itemizedlist>
<listitem>
<para>Version 2.0.2 (???)</para><itemizedlist>
<listitem>
<para>Updated for jEdit 4.3 API changes.</para></listitem>
<listitem>
<para>Fixed: Random Access Files weren't closed if no tag was found.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 2.0.1 (Mar 2005)</para><itemizedlist>
<listitem>
<para>Fixed recursive directory search on local FS.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 2.0 (Nov 2004)</para><itemizedlist>
<listitem>
<para>Tags plugin now uses jEdit's Virtual File Systems
(enabling the plugin to work over FTP, SFTP, etc...).</para></listitem>
<listitem>
<para>Tags plugin can no longer be used stand-alone (outside of jEdit).</para></listitem>
<listitem>
<para>Various fixes, changes, etc...</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 1.1.2, bug fix (Jun 2004)</para><itemizedlist>
<listitem>
<para>Fixed StringIndexOutOfBoundsException, if tag ended with &quot;\&quot;.
Bug report &amp; patch from Ian MacLarty.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 1.1.1, bug fix (Apr 2004)</para><itemizedlist>
<listitem>
<para>escaping <literal>$</literal> when searching for tag definition.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 1.1, update (Dec 2003)</para><itemizedlist>
<listitem>
<para>Added the ability to specify the sort order of the current
buffer tag index file.</para></listitem>
<listitem>
<para>Added the ability to clear the tag stack.</para></listitem>
<listitem>
<para>Replaced text field in Enter Tag dialog with history text
field.</para></listitem>
<listitem>
<para>Quickly reject tag index files if last tag in file is
less than the tag we are looking for.</para></listitem>
<listitem>
<para>Added the ability to specify whether tags extend through
the member access operator.</para></listitem>
<listitem>
<para>Restore search and replace search string after following tag.</para></listitem>
<listitem>
<para>Ability to enable or disable tag index files without having
to remove them from the tag index filepath list.</para></listitem>
<listitem>
<para>Experimental: Ability for dialogs to appear under the cursor.</para></listitem>
<listitem>
<para>Ability to keep tag collision dialog.</para></listitem>
<listitem>
<para>Ability to convert tag collision popup into dialog.</para></listitem>
<listitem>
<para>Focus to return to history panel when checkbox is used in
Enter Tag dialog.</para></listitem>
<listitem>
<para>Focus to return to list when checkbox is used in Tag
Collision dialog.</para></listitem>
<listitem>
<para>Updated for jEdit 4.2 plugin API.</para></listitem>
<listitem>
<para>Ability to search for tag index files for current buffer
in parent directories of the current buffer.</para></listitem>
<listitem>
<para>Added <citetitle>Tag Stack</citetitle> dockable.</para></listitem>
<listitem>
<para>Tag index filenames can contain spaces.</para></listitem>
<listitem>
<para>Added <citetitle>Push Current Position onto Stack</citetitle>.</para></listitem>
<listitem>
<para>Converted docs to DocBook and added a build.xml file.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 1.0.6, bug fixes (Feb 2002)</para><itemizedlist>
<listitem>
<para>Fixed bug where the escape character <literal>'\'</literal> was showing
up in the user visible search string.</para></listitem>
<listitem>
<para>Used JEditTextArea.offsetToXY() to position popup
within folded, and wrapped text.</para></listitem>
<listitem>
<para>Requires java 1.3</para></listitem>
<listitem>
<para>Requires JEdit 4.0</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 1.0.3, update (Nov 2001)</para><itemizedlist>
<listitem>
<para>Replaced Macros.error with GUIUtilities.error.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 1.0.2, bug fixes (Nov 2001)</para><itemizedlist>
<listitem>
<para>Fixed bug where if you removed tag index files from
the search the code would remember the later entries.</para></listitem>
<listitem>
<para>Fixed bug where searching for tag search string in
file was using the search file set.</para></listitem>
<listitem>
<para>Fixed bug in option panel where changes to the list of
tag index files were always committed even if you
pressed &quot;Cancel&quot;.</para></listitem>
<listitem>
<para>Fixed exuberant tag info display when mixed tag files
are used.</para></listitem>
<listitem>
<para>Removed directions from COPYING.</para></listitem>
<listitem>
<para>Added some initial user hidden development code.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 1.0.1, bug fixes (Nov 2001)</para><itemizedlist>
<listitem>
<para>Fixed bug where if you added a new tag file, then
moved that file in the list, a null exception occured
during tagging.</para></listitem>
<listitem>
<para>If tag collision popup is wider than the screen, place
it flush to the left side of the screen.</para></listitem>
<listitem>
<para>Ability to have commas in tag index file path names.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 1.0, Initial public release (Oct 2001)</para><itemizedlist>
<listitem>
<para>Made Enter Tag dialog a stand alone dialog (no JOptionPane).</para></listitem>
<listitem>
<para>Moved enter event into KeyPressed() in enter tag dialog.</para></listitem>
<listitem>
<para>Added the display of exuberant info from the tag indx file.</para></listitem>
<listitem>
<para>Reverted back to platform independent Monospaced font
for tag collision list.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 0.9.2 (Oct 2001)</para><itemizedlist>
<listitem>
<para>Listen for ENTER in Enter Tag dialog.</para></listitem>
<listitem>
<para>Use KeyEventWorkaround.processKeyEvent() in key listener.</para></listitem>
<listitem>
<para>Removed display of wait cursor when opening tag
definition file.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 0.9.1 (Oct 2001)</para><itemizedlist>
<listitem>
<para>Removed Tags.displayMessage in favor of
org.gjt.sp.util.Log.log()</para></listitem>
<listitem>
<para>Used ^ and $ from tag index file when searching (regexp)</para></listitem>
<listitem>
<para>Fixed bug where search string wasn't complete</para></listitem>
<listitem>
<para>Fixed off by 1 bug when tag index file uses line numbers</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 0.9 (Oct 2001)</para><itemizedlist>
<listitem>
<para>Scroll pane for collision dialog.</para></listitem>
<listitem>
<para>Added public Tags.pushPosition()</para></listitem>
<listitem>
<para>Better display tag information collision list.</para></listitem>
<listitem>
<para>Fixed bugs introduced in 0.7.3.</para></listitem>
<listitem>
<para>Display tag line numbers in collision list when search
string is a line number.</para></listitem>
<listitem>
<para>Changed font of collision list from &quot;Monospaced&quot; to
&quot;Courier New&quot;.</para></listitem>
<listitem>
<para>Removed public use of tag catagories.</para></listitem>
<listitem>
<para>Fixed Enter Tag dialog focus issue.</para></listitem>
<listitem>
<para>Only display 1 - 9 in collision list.</para></listitem>
<listitem>
<para>Resolve relative tag defintion files before possible
use of tag collision list.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 0.7.3 (Oct 2001)</para><itemizedlist>
<listitem>
<para>Ability to use number keys with the tag collision popup.</para></listitem>
<listitem>
<para>Fixed relative tag defintion file name path problem.</para></listitem>
<listitem>
<para>Fixed problem when tagging from command line.</para></listitem>
<listitem>
<para>Fixed infinite loop problem when backtracking to
beginning of first line in tag index file.</para></listitem>
<listitem>
<para>Fixed crash when tag is on last line of tag index file.</para></listitem>
<listitem>
<para>Made Java 1.1 compatible</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 0.7.2 (Oct 2001)</para><itemizedlist>
<listitem>
<para>Added the ability to specify the tag index file name,
when using the tag index file in the current buffer's
directory.</para></listitem>
<listitem>
<para>Added error message when tag defintion file does not exist</para></listitem>
<listitem>
<para>Updated HTML Documentaiton.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 0.7.1 (Oct 2001)</para><itemizedlist>
<listitem>
<para>Updated HTML Documentaiton.</para></listitem>
<listitem>
<para>Updated labels and property strings.</para></listitem>
<listitem>
<para>Let user know if no tag index files have been specified.</para></listitem>
<listitem>
<para>Removed tag index file type specification.</para></listitem>
<listitem>
<para>Removed some unneeded code.</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 0.7 (Oct 2001)</para><itemizedlist>
<listitem>
<para>HTML Documentation</para></listitem>
<listitem>
<para>Use AbstractOptionPane for Global Options dialog</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 0.5 (Oct 2001)</para><itemizedlist>
<listitem>
<para>??</para></listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Version 0.3 (Sep 2001)</para><itemizedlist>
<listitem>
<para>Initial beta release</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<!-- :mode=rest: -->
</section>
</article>