Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

[edfaca]: docs / users-guide.xml Maximize Restore History

Download this file

users-guide.xml    289 lines (243 with data), 10.7 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
<?xml version="1.0"?>
<book xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation='http://www.docbook.org/xsd/4.4/docbook.xsd' >
<!-- :wrap=soft:maxLineLen=0: -->
<title>jEdit CtagsInterface Plugin Guide</title>
<bookinfo>
<authorgroup>
<author><firstname>Shlomy</firstname><surname>Reinstein</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="intro">
<title> Introduction </title>
<para>
The CtagsInterfacePlugin provides three dockables, a
<guilabel>Tag List</guilabel>, a <guilabel>Tag Preview</guilabel> and a
<guilabel>Progress</guilabel>. It also provides a number of operations that
allow you to quickly jump from one file location to another in the editor,
based on the context of the caret, and the indexed tag information obtained
from the <ulink url="http://ctags.sourceforge.net/">Exuberant Ctags</ulink>
executable. And finally, it provides a plugin interface through which other
jEdit plugins can easily access ctags data.
</para>
</chapter>
<chapter id="setup">
<title> Setup and Configuration </title>
<para>
CtagsInterface will happily index all files in your project or source
tree, unless you tell it otherwise.
Under <literal>Plugin Options - CtagsInterface - General</literal> you will
find a field for specifying
<emphasis role="bold">Ctags Invocation Options</emphasis>. By adding extra
options to this field, as shown below, you can specify that only certain
file types are scanned and indexed. Read the manual pages of exuberant ctags
for more information about the options available.
</para>
<literallayout> --languages=c,c++,java,python </literallayout>
<para>
When the option to 'Match tags with language of current buffer' is selected
tooltips and completion suggestions will only be shown from tags whose language
matches that of the file in the current buffer. This is done according to file
extension and the mapping can be seen by calling ctags with the
<literal>--list-maps</literal> option. If the source file's language hasn't
been tagged nothing will be shown, to fix this retag your source files including
the 'l' flag in the ctags <literal>--fields</literal> option.
</para>
</chapter>
<chapter id="tagdbs">
<title> Tagging Projects, Source Trees/Archives and Tag/Source Files</title>
<para>
CtagsInterface uses a Lucene index to keep track of tag data from multiple
projects, directory trees/archives and tag/source files. The
<guimenuitem>Plugin Options - CtagsInterface</guimenuitem> provides
dialogs for adding projects, directory trees/archives and tag/source files
that should be indexed.
</para>
<para>
The first step is to add the projects, source trees/archives or tag/source files
that you want to be tagged in the index. Tagging is done in the background, you
can continue working with jEdit meanwhile. The tagging progress is shown in the
<guilabel>Progress</guilabel> dockable, in a tab of a tabbed pane. When
done, you can lookup tags from the projects, source trees/archives and tag/source files.
</para>
<para>
You can add projects two ways. From the ProjectViewer, right click on the
project and <guimenuitem>Add Project to index</guimenuitem>, or from
<guimenuitem>Plugin Options - CtagsInterface - Projects</guimenuitem>.
</para>
<para>
Similarly, you can add source trees/archives from
<guimenuitem>Plugin options - CtagsInterface - Source Trees</guimenuitem>.
You can also add source trees from the file system browser context menu:
<guimenuitem>Plugins - Add source tree to tag index</guimenuitem>.
Lastly tag and source files can be added from
<guimenuitem>Plugin options - CtagsInterface - Files</guimenuitem>
and the source file currently in your buffer can be added through
the <guimenuitem>Add current file</guimenuitem> action.
</para>
</chapter>
<chapter id="lookup">
<title> Tag Lookup </title>
<para>
By default, tag lookup will search the entire tag index for matching tags,
including all added projects and source trees.
</para>
<para>
When using jEdit with ProjectViewer, you might be working with a set of
files, and have to frequently check another set of files that you are
reusing. This means that you will probably want to restrict your search
to only the projects and source trees that are related to your project.
</para>
<para>
By editing the properties of the current project, you can see a
<guilabel>Dependencies</guilabel> pane, which allows you to set the
related projects, source trees/archives or tag files on an individual project basis. While
running the Tag Preview, or performing a Jump to Tag while working in a
project that has dependencies set, CtagsInterface should restrict its
searches to tag data from only those projects and directory trees.
</para>
<para>
This is especially useful in the case where there are many projects /
source trees indexed in the tags database that are not related to each
other.
</para>
</chapter>
<chapter id="actions">
<title> Actions </title>
<formalpara><title> Add tag File </title>
<para>
Adds an already generated ctags file to the database.
</para>
</formalpara>
<formalpara><title> Tag all projects </title>
<para>
This does exactly what it says: it goes through
<emphasis role="bold">every</emphasis> project that ProjectViewer knows
about, and tags their files, adding the tag data to the embedded database.
</para>
</formalpara>
<formalpara><title> Suggest completion options </title>
<para>
Suggests code-completion options from the tag database. This includes
completion of function calls, using SuperAbbrevs for conveniently
filling-in the parameter values.
</para>
</formalpara>
<section id="dynamic-actions">
<title> Dynamic Actions </title>
<para>
In addition to these built-in actions, CtagsInterface allows you to create
dynamic Actions, which are custom Lucene queries, which can be bound to
keyboard shortcuts. Each such Lucene query should retrieve a list of tags
from the database. There are 3 types of dynamic actions:
<orderedlist>
<listitem><para>
Jump to tag - execute the query and show the list of tags it retrieved
in the <guilabel>Tag List</guilabel> dockable, allowing you to jump to any
of them. In case the query returns a single tag, the dynamic action jumps
to it directly, without showing it in the dockable.</para>
</listitem>
<listitem><para>
Search prefix - execute the query and show the "Prefix search" popup so
you can choose a tag from the query results using its prefix. </para>
</listitem>
<listitem> <para>
Search string - execute the query and show the "Prefix search" popup so
you can choose a tag from the query results using a substring. </para>
</listitem>
</orderedlist>
</para>
<para>
To manage (create/delete/modify) dynamic actions, select the
<guilabel>Actions</guilabel> pane in the plugin options. To define a new
dynamic action, click the <guilabel>+</guilabel> button. You will be asked
to provide a name for the action and a Lucene query. The action name you
provide should not contain spaces, as it is used to define an ordinary
edit action. The Lucene query can make use of the following keywords:
<itemizedlist>
<listitem>
<para>
<guilabel>{tag}</guilabel>: The tag being looked up
</para>
</listitem>
<listitem>
<para>
<guilabel>{project}</guilabel>: The name of the active project
</para>
</listitem>
</itemizedlist>
Here are a few examples:
<itemizedlist>
<listitem><para>_name:{tag} AND kind:function AND origin:{project}
</para></listitem>
<listitem><para>_name:{tag} AND kind:prototype AND origin:{project}
</para></listitem>
</itemizedlist>
</para>
</section>
</chapter>
<chapter id="dockables">
<title> CtagsInterface Dockables </title>
<para>
There are three dockables that you can use from CtagsInterface.
</para>
<formalpara> <title> Tag List </title>
<para>
When <action>jump to tag</action> is invoked, if there is more than one
possible match, the Tag List dockable is displayed, where you can preview
and select the choices of jump locations.
</para>
</formalpara>
<formalpara> <title> Tag Preview </title>
<para>
This dockable is updated automatically (after a configurable delay)
whenever the caret is moved over a location that is a known symbol in the
tag index.
</para>
</formalpara>
<formalpara> <title> Progress </title>
<para>
This dockable shows the progress of tagging activities in a tabbed pane.
Each activity has its own tab. By default, a tab closes automatically a
few seconds after the activity is over, but you can configure this in the
<guilabel>General </guilabel> option pane.
You can close a tab manually by middle-clicking the tab title or clicking
the <guilabel>Close</guilabel> button in the dockable.
</para>
</formalpara>
</chapter>
<chapter id="pluginservices">
<title> Services to other plugins </title>
<para>
CtagsInterface also offers services to other plugins, such as ClassBrowser
and CodeHelper:
</para>
<orderedlist>
<listitem><para> Queries of the tag index</para></listitem>
<listitem><para> Jumping to tags </para></listitem>
</orderedlist>
<para>
Since the CtagsInterface manages the tag information and runs ctags, other
plugins do not need to call/depend on ctags directly. This also means that
in the future, the CtagsInterface may be extended to work with other
code-indexing tools.
</para>
</chapter>
<appendix id="changelog">
<title> Changelog </title>
<para> For a list of changes in this plugin, see the
<ulink url="docs/CHANGES.txt">change log</ulink>.
</para>
</appendix>
</book>