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

Download this file

users-guide.xml    355 lines (296 with data), 13.9 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
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
<?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>
<section id="tags-plugin">
<title> Replacing the Tags plugin </title>
<para> With the exception of the "push/pop position" actions, all other features
of the old Tags plugin (no longer supported) should be available from CtagsInterface.
The push/pop position actions are available from the Navigator plugin.
</para>
</section>
</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>. The options required
for smooth running of CtagsInterface are
<literallayout>--fields=+anzKiSl</literallayout>, in addition,
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>
</chapter>
<chapter id="tagdbs">
<title> Tagging Projects, Trees, Archives and Source and Tag Files</title>
<para>
CtagsInterface uses a Lucene index to keep track of tag data from multiple
origins (currently projects, trees, archives and source and tag files).
<guimenuitem>Plugin Options - CtagsInterface</guimenuitem> provides three
panes for defining which origins should be indexed:
<guimenuitem>Trees/Archives</guimenuitem>,
<guimenuitem>Files</guimenuitem> and <guimenuitem>Projects</guimenuitem>.
</para>
<para>
The first step is to add the origins that you want to be tagged. 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 origins you
have added.
</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 trees and archives from
<guimenuitem>Plugin options - CtagsInterface - Trees/Archives</guimenuitem>.
You can also add source files and trees from the file system browser
context menu:
<guimenuitem>Plugins - Add source files/trees to tag index</guimenuitem>. </para>
<para>
Lastly source and tag 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.
Tags files can be added with the action <guimenuitem> Add Tag File...</guimenuitem>.
</para>
<para>
Tags can be removed from the index using the options pane, actions in
<guimenuitem>Plugins - CtagsInterface</guimenuitem> or the ProjectViewer
context menu
</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 origins.
</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 origins 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, trees/archives or 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 dependencies. </para>
<para> This is especially useful in the case where there are many origins
indexed in the tags index that are not related to each other. </para>
<para> In addition, when the option to 'Match tags with language of current
buffer' is selected searches will be restricted to tags whose language
matches that of the file in the current buffer. File extension is used to do
this matching 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 and this option is selected searches will return nothing, to fix
this retag your source files including the 'l' flag in the ctags
<literal>--fields</literal> option. </para>
</chapter>
<chapter id="actions">
<title> Actions </title>
<formalpara><title> Add Current File </title>
<para>
Tags the file in the current buffer and adds it to the index.
</para>
</formalpara>
<formalpara><title> Update Current File </title> <para> Updates the file in
the current buffer in the index, doesn't add the file as an origin if it's
already in the index. </para> </formalpara>
<formalpara><title> Remove Current File </title> <para> Removes the tags from
the file in the current buffer and their origin from the index. </para>
</formalpara>
<formalpara><title> Remove All Tags </title>
<para>
Removes all tags and their origins from the index.
</para>
</formalpara>
<formalpara><title> Jump to tag </title> <para> Opens the file that the tag
currently under the caret originates from and moves the caret to the tag
definition within that file. </para> </formalpara>
<formalpara><title> Tag Preview Current </title> <para> Previews the tag
currently under the caret in the Tag Preview dockable. Useful when the "Follow
caret" Tag Preview option is deselected </para> </formalpara>
<formalpara><title> Search tag by substring </title> <para> Provides a dialog
to conduct a substring search of the tag index, results returned in a pop-up.
</para> </formalpara>
<formalpara><title> Search tag by prefix </title> <para> Provides a dialog to
conduct a prefix search of the tag index, results returned in a pop-up.
</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 index.
</para>
</formalpara>
<formalpara><title> Suggest completion options </title>
<para>
Suggests code-completion options from the tag index. This includes
completion of function calls, using SuperAbbrevs for conveniently
filling-in the parameter values.
</para>
</formalpara>
<formalpara><title> Run Query </title> <para> Provides a dialog for running
queries on the tag index using the Lucene query syntax. </para> </formalpara>
<formalpara><title> Show Query Dialog </title> <para> Provides a dialog and
results pane for running queries on the tag index using the Lucene query
syntax. </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 index. 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 used to preview tags currently being edited, and has an
option to update automatically (after a configurable delay) whenever the
caret is moved over a location that is a known symbol in the tag index.
The dockable has an optional gutter with numbers and folding that matches
the mode used in the previewed buffer. In addition CtagsSideKick can be
forced as the fold handler if it's been installed. Using this and the
option to collapse all folds allows for a more compact preview that's
restricted to lines that have been parsed by CtagsSideKick. This can be
modified by specifying which kinds of tags CtagsSideKick includes in
<guimenuitem>Plugin Options - CtagsSideKick - Tree Style - Ctags
invocation options</guimenuitem>. For instance adding
<literallayout>--java-kinds=cmp</literallayout> to the invocation option
will lead to folds being added around the classes, methods and packages
of java files when they are previewed. See
<literallayout>--list-kinds</literallayout> in the ctags documentation
for more information.
</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>