plugins.docbook 61.2 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
<chapter id="plugins">

<chapterinfo>
<authorgroup>
<author>&Anders.Lund; &Anders.Lund.mail;</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
</chapterinfo>

<title>Working with Plugins</title>

Yuri Chornoivan's avatar
Yuri Chornoivan committed
12
<para>&kate; offers several plugins. There are two types of these plugins:
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
13
14
some are written in native C++, while others are written in the Python programming
language.  There are subtle differences in these, described below.</para>
15

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
16
<para>You can enable any type of plugin in the <link
17
linkend="configuring-kate-configdialog">configuration dialog</link>, which also
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
18
provides access to additional configuration options for plugins that require
19
it.</para>
20
21
22
23
24
25
26
27

<sect1 id="kate-application-plugins">
<title>&kate; Application Plugins</title>

<!-- from doc/kate-addons/index.docbook -->
<para>
&kate; plugins are additional functions for the &kate; editor.  They can
add extra menus and shortcuts, and extend &kate;'s features.  You can
28
29
install as many or as few as you like, from within &kate;.
Open &kate;'s configuration dialog with
30
31
32
33
34
35
36
37
38
39
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kate;...</guimenuitem></menuchoice>
Select <menuchoice><guimenu>Application</guimenu><guimenuitem>Plugins</guimenuitem></menuchoice> to
choose the wanted plugins.
</para>

<para>
The available application plugins are:
</para>
<itemizedlist>
<listitem>
40
<para>Backtrace Browser - Backtrace navigation tool view</para>
41
42
</listitem>
<listitem>
43
<para><link linkend="kate-application-plugin-build">Build Plugin</link> - Compile or Make and parse error messages</para>
44
45
</listitem>
<listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
46
<para>Close Except/Like - Close group of documents based on a common path or file extension</para>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
47
48
</listitem>
<listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
49
<para>CTags - Look up definitions/declarations with CTags</para>
50
51
</listitem>
<listitem>
52
<para>Document switcher - Quick document switching with <keycombo action="simul">&Alt;&Tab;</keycombo> behavior</para>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
53
54
</listitem>
<listitem>
55
56
<para><link linkend="kate-application-plugin-fsbrowser">File system browser</link> -
  File system browser tool view</para>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
57
58
</listitem>
<listitem>
Burkhard Lück's avatar
Burkhard Lück committed
59
60
61
<para>Documents - Displays the open files in a file tree</para>
</listitem>
<listitem>
62
63
<para><link linkend="kate-application-plugin-gdb">&gdb;</link> - Provides a
simple &gdb; frontend</para>
64
65
</listitem>
<listitem>
66
<para>Icon picker - Invokes Cuttlefish icon picker</para>
67
68
</listitem>
<listitem>
69
<para>Lumen - Lumen is a Autocompletion Plugin for D, using the DCD autocompletion server</para>
70
71
</listitem>
<listitem>
72
<para>Open Header - Opens the corresponding .h/[.cpp|.c] file</para>
73
74
</listitem>
<listitem>
75
<para>Project Plugin - Project plugin for kate</para>
76
77
</listitem>
<listitem>
78
79
80
81
<para>Replicode</para>
</listitem>
<listitem>
<para>Rust code completion - Code completion for Rust source code</para>
82
83
</listitem>
<listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
84
85
<para><link linkend="kate-application-plugin-searchinfiles">Search &amp; Replace</link> - 
Search or replace patterns in opened documents or in files on disk</para>
86
87
</listitem>
<listitem>
88
<para><link linkend="kate-application-plugin-snippets">Snippets tool view</link> - Tool view embedding the snippets management</para>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
89
90
</listitem>
<listitem>
91
92
<para><link linkend="kate-application-plugin-sql">SQL Plugin</link> - Execute
query on SQL databases</para>
93
94
</listitem>
<listitem>
95
<para>Symbol Viewer - Extract and show reference symbols from source</para>
96
97
</listitem>
<listitem>
98
<para><link linkend="kate-application-plugin-konsole">Terminal tool view</link> - Tool view embedding a terminal widget</para>
99
100
101
</listitem>
<listitem>
<para>Text Filter - Easy text filtering</para>
102
103
</listitem>
<listitem>
104
<para><link linkend="kate-application-plugin-xmltools">&XML;Completetion</link> - Lists &XML; elements,
105
106
107
108
109
attributes, attribute values and entities allowed by DTD</para>
</listitem>
</itemizedlist>
</sect1>

110
111
<sect1 id="kate-application-plugin-build">
<!--http://kate-editor.org/2011/06/21/kate-plugin-updates-part-1/ -->
112
<sect1info>
113
114
115
116
<authorgroup>
<author><firstname>Salma</firstname> <surname>Sultana</surname></author>
<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
</authorgroup>
117
</sect1info>
118
<title>Build Plugin</title>
119

120
121
<sect2 id="build-intro">
<title>Introduction</title>
122

123
124
<para>The Build plugin allows you to run actions like build, clean and compile
on a project.</para>
125

126
</sect2>
127

128
129
<sect2 id="build-using">
<title>Using the Build Plugin</title>
130

131
132
133
134
<para>The Build plugin adds a <guilabel>Build Output</guilabel> tool view at the
bottom and a <guimenu>Build</guimenu> menu on the menubar. The tool view can be used to configure
build target settings, while the menu can be used to perform build, clean and
compile actions.</para>
135
136


137
138
139
140
141
142
143
<para>The <guilabel>Build Output</guilabel> tool view has three tabs:</para>

<itemizedlist>
<listitem><para><guilabel>Target Settings</guilabel></para></listitem>
<listitem><para><guilabel>Output</guilabel></para></listitem>
<listitem><para><guilabel>Errors &amp; Warnings</guilabel></para></listitem>
</itemizedlist>
144

145
146
147
148
149
150
151
152
<sect3 id="build-using-target-settings">
<title>Target Settings tab</title>

<para>The target settings tab can be used to configure various build targets.</para>

<para>Each target contains four configuration options:</para>

<variablelist>
153
<varlistentry>
154
155
156
<term><guilabel>Working Directory</guilabel></term>
<listitem><para>You can set the path to the project here. Leave this empty to
use the directory the current document is located in.</para></listitem>
157
158
159
</varlistentry>

<varlistentry>
160
161
162
<term><guilabel>Build</guilabel></term>
<listitem><para>This option lets you define the build command. It is set to
<command>make</command> by default.</para></listitem>
163
164
165
</varlistentry>

<varlistentry>
166
167
168
<term><guilabel>Clean</guilabel></term>
<listitem><para>The option lets you define the clean command. It is set to
<command>make clean</command> by default.</para></listitem>
169
170
171
</varlistentry>

<varlistentry>
172
173
174
<term><guilabel>Quick Compile</guilabel></term>
<listitem><para>This option lets you define the quick compile command. It is set
to <command>gcc -Wall -g %f</command> by default.</para></listitem>
175
176
177
</varlistentry>
</variablelist>

178
179
180
<para>One can create a new target by using the <guibutton>New</guibutton> button.
The <guibutton>Copy</guibutton> button can be used to make a copy of an existing
target. To delete a target, use the <guibutton>Delete</guibutton> button.</para>
181

182
</sect3>
183

184
185
<sect3 id="build-using-output">
<title>Output tab</title>
186

187
188
<para>The <guilabel>Output</guilabel> tab shows the console output generated by
the last command.</para>
189

190
</sect3>
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
<sect3 id="buiid-using-errors">
<title>Errors &amp; Warnings</title>

<para>The <guilabel>Errors &amp; Warnings</guilabel> tab lists the errors and
warnings generated by the last command.</para>

<para>Each line contains a message and the file name and line number if available.
Clicking on the error or warning takes you to the appropriate file and places
the cursor on the corresponding line number.</para>

<para>There are <guibutton>Errors</guibutton>, <guibutton>Warnings</guibutton>,
and <guibutton>Others</guibutton> buttons at the top that allow you to show
or hide those categories of output.</para>

<!--FIXME: These shortcuts now seem to be used by the Project plugin in 4.11.
            https://bugs.kde.org/show_bug.cgi?id=328170 -->
<para>To navigate to the previous error, press
<keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo>.
To navigate to the next error, press
<keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo>.</para>

</sect3>
</sect2>

<sect2 id="build-menu">
217
218
<title>Menu Structure</title>

219
<variablelist id="build-build">
220
<varlistentry>
Burkhard Lück's avatar
Burkhard Lück committed
221
<term><menuchoice>
222
<guimenu>Build</guimenu><guimenuitem>Build</guimenuitem>
Burkhard Lück's avatar
Burkhard Lück committed
223
</menuchoice></term>
224
225
<listitem><para>Runs the <guilabel>Build</guilabel> command for the currently
selected target.</para></listitem>
226
227
</varlistentry>

228
<varlistentry id="build-clean">
Burkhard Lück's avatar
Burkhard Lück committed
229
<term><menuchoice>
230
<guimenu>Build</guimenu><guimenuitem>Clean</guimenuitem>
Burkhard Lück's avatar
Burkhard Lück committed
231
</menuchoice></term>
232
233
<listitem><para>Runs the <guilabel>Clean</guilabel> command for the currently
selected target.</para></listitem>
234
235
</varlistentry>

236
<varlistentry id="build-compile">
Burkhard Lück's avatar
Burkhard Lück committed
237
<term><menuchoice>
238
<guimenu>Build</guimenu><guimenuitem>Quick Compile</guimenuitem>
Burkhard Lück's avatar
Burkhard Lück committed
239
</menuchoice></term>
240
241
<listitem><para>Runs the <guilabel>Quick Compile</guilabel> command for the
currently selected target.</para></listitem>
242
243
</varlistentry>

244
245
246
247
248
249
250
251
<varlistentry id="build-previous-error">
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo></shortcut>
<guimenu>Build</guimenu><guimenuitem>Previous Error</guimenuitem>
</menuchoice></term>
<listitem><para>Moves the cursor to the location of the previous error in the
document.</para></listitem>
</varlistentry>
252

253
254
255
256
257
258
259
260
<varlistentry id="build-next-error">
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo></shortcut>
<guimenu>Build</guimenu><guimenuitem>Next Error</guimenuitem>
</menuchoice></term>
<listitem><para>Moves the cursor to the location of the next error in the
document.</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
261

262
263
264
265
266
267
<varlistentry>
<term><menuchoice id="build-targets">
<guimenu>Build</guimenu><guisubmenu>Targets</guisubmenu>
</menuchoice></term>
<listitem><para>Select from a list of targets configured by the user.</para></listitem>
</varlistentry>
268

269
270
271
272
273
274
<varlistentry>
<term><menuchoice id="build-next-target">
<guimenu>Build</guimenu><guimenuitem>Next Target</guimenuitem>
</menuchoice></term>
<listitem><para>Switch to the next target configured by the user.</para></listitem>
</varlistentry>
275

276
</variablelist>
277
278
</sect2>

279
280
281
282
283
284
285
<sect2 id="build-ack">
<title>Thanks and Acknowledgments</title>
<para>The &kate; Build Plugin was written by Kåre Särs.</para>
<para>Special thanks to Google Code-In 2011 participant Salma Sultana for
writing much of this section.</para>
</sect2>
</sect1>
286

287
<sect1 id="kate-application-plugin-fsbrowser">
288

289
<title>Filesystem Browser</title>
290

291
292
<para>The Filesystem Browser is a folder viewer, allowing you to open
files from a displayed folder in the current frame.</para>
293

294
295
296
<sect2 id="fsbrowser-menu">
<title>Menu Structure</title>
<variablelist>
297

298
299
300
301
302
303
304
305
<varlistentry id="view-toolviews-show-filebrowser">
<term><menuchoice>
<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
<guimenuitem>Show Filesystem Browser</guimenuitem>
</menuchoice></term>
<listitem>
<para>Toggle the display of &kate;'s Filesystem Browser.</para>
</listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
306
307
</varlistentry>

308
309
</variablelist>
</sect2>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
310

311
312
<sect2 id="fsbrowser-interface">
<title>Interface</title>
313

314
315
<para>From the top down, the Filesystem Browser consists of the following
elements:</para>
316

317
<variablelist>
318
<varlistentry>
319
320
321
322
<term>A Toolbar</term>
<listitem>
<para>This contains standard navigations tool buttons:</para>
<variablelist>
323
<varlistentry>
324
325
326
<term><guibutton>Back</guibutton></term>
<listitem><para>Causes the folder view to <command>cd</command> to the previously displayed folder in the history.
This button is disabled, if there is no previous item.</para></listitem>
327
328
</varlistentry>
<varlistentry>
329
330
331
<term><guibutton>Forward</guibutton></term>
<listitem><para>Causes the folder view to <command>cd</command> to the next folder in the history.
This button is disabled, if there is no next folder.</para></listitem>
332
</varlistentry>
333
334
335
336
337
<!--varlistentry>
<term><guibutton>Parent Folder</guibutton></term>
<listitem><para>This will cause the folder view to <command>cd</command> to the immediate parent of the currently displayed
folder if possible.</para></listitem>
</varlistentry-->
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
338
<varlistentry>
339
340
<term><guibutton>Bookmarks</guibutton></term>
<listitem><para>Opens a submenu to edit or add bookmarks and to add a new bookmark folder.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
341
342
</varlistentry>
<varlistentry>
343
344
345
346
347
348
<term><guibutton>Current Document Folder</guibutton></term>
<listitem><para>This button will cause the folder view to
<command>cd</command> to the folder of the currently active
document if possible. This button is disabled, if the active document
is a new, unsaved file, or the folder in which it resides can not
be decided.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
349
350
</varlistentry>
<varlistentry>
351
352
353
<term><guibutton>Options</guibutton></term>
<listitem>
<variablelist>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
354
<varlistentry>
355
356
<term><guimenuitem>Short View</guimenuitem></term>
<listitem><para>Displays only the filenames.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
357
</varlistentry>
358
<varlistentry>
359
360
361
<term><guimenuitem>Detailed View</guimenuitem></term>
<listitem><para>Displays <guilabel>Name</guilabel>, <guilabel>Date</guilabel>,
<guilabel>Size</guilabel> and <guilabel>Type</guilabel> of the files.</para></listitem>
362
363
</varlistentry>
<varlistentry>
364
365
<term><guimenuitem>Tree View</guimenuitem></term>
<listitem><para>Like Short View, but folders can be expanded to view their contents.</para></listitem>
366
367
</varlistentry>
<varlistentry>
368
369
370
<term><guimenuitem>Detailed Tree View</guimenuitem></term>
<listitem><para>This also allows folders to be expanded, but displays the additional columns
available in Detailed View.</para></listitem>
371
372
</varlistentry>
<varlistentry>
373
374
<term><guimenuitem>Show Hidden Files</guimenuitem></term>
<listitem><para>Displays files normally hidden by your &OS;.</para></listitem>
375
376
</varlistentry>
<varlistentry>
377
378
379
<term><guimenuitem>Automatically synchronize with current document</guimenuitem></term>
<listitem><para>When this option is enabled the filesystem browser will automatically <command>cd</command>
to the folder of the document currently open in the editing area every time it changes.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
380
</varlistentry>
381
382
383
384
385
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</listitem>
386
387
388
</varlistentry>

<varlistentry>
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
<term>A Location Entry</term>
<listitem>
<para>This displays a breadcrumb navigation to the currently open folder, similarly to
&dolphin;.  You can click on a any folder to browse to it, or click on one of the
arrows to the left of a folder to select any folders beneath it.  You may also
select from your list of Places by clicking the leftmost icon in the breadcrumb
navigation, which displays an icon that represents your current Place.</para>

<para>You can also click to the right of the breadcrumbs to change them to a text box
where you can type the path of a folder to browse. The &URL;
entry maintains a list of previously typed paths. To choose one, use
the arrow button to the right of the entry.</para>
<tip><para>The &URL; entry has folder auto-completion. The completion
method can be set using the &RMB; menu of the text
entry.</para></tip>
</listitem>
405
406
407
</varlistentry>

<varlistentry>
408
409
<term>A Folder View</term>
<listitem><para>This is a standard &kde; folder view.</para></listitem>
410
411
412
</varlistentry>

<varlistentry>
413
414
415
416
417
418
419
420
421
422
423
424
425
<term>A Filter Entry</term>
<listitem>
<para>The Filter entry allows you to enter a filter for the files
displayed in the folder view. The filter uses standard globs; patterns
must be separated by white space. Example: <userinput>*.cpp *.h
*.moc</userinput></para>
<para>To display all files, enter a single asterisk
<userinput>*</userinput>.</para>
<para>The filter entry saves the last 10 filters entered between
sessions.  To use one, press the arrow button on the right of the entry
and select the desired filter string.  You can disable the filter by pressing
the <guibutton>Clear text</guibutton> button to the left of the autocompletion
arrow button.</para>
426
427
428
</listitem>
</varlistentry>

429
430
431
432
433
434
435
436
437
438
439
</variablelist>
</sect2>


<sect2 id="fsbrowser-config">
<title>Configuration</title>

<para>This plugin can be configured on the <guilabel>Filesystem Browser</guilabel> page
of <link linkend="configuring-kate-configdialog">&kate;'s configuration</link>.</para>

<variablelist>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
440
<varlistentry>
441
442
443
444
445
<term><guilabel>Toolbar</guilabel></term>
<listitem><para>Configure the buttons on the Filesystem Browser toolbar
by moving the ones you want enabled to the <guilabel>Selected Actions</guilabel>
list, and order them using the arrow buttons at the side of the list.</para>
 </listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
446
447
</varlistentry>

448
</variablelist>
449
450
</sect2>
</sect1>
451

452
453
454
455
456
457
458
459
460
<sect1 id="kate-application-plugin-gdb">
<!--http://kate-editor.org/2011/06/23/kate-plugin-updates-part-2/-->
<sect1info>
<authorgroup>
<author><firstname>Martin</firstname> <surname>Gergov</surname></author>
<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
</authorgroup>
</sect1info>
<title>&gdb; Plugin</title>
461

462
463
<sect2 id="gdb-intro">
<title>Introduction</title>
464

465
466
<para>&kappname;'s &gdb; plugin provides a simple frontend to the popular &GNU;
Project Debugger.</para>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
467

468
469
470
471
472
<important>
<para>Previous experience with &gdb; is strongly recommended.  For more
information on using &gdb;, visit <ulink url="http://www.gnu.org/s/gdb/">the
&gdb; website</ulink>.</para>
</important>
473

474
475
476
477
478
479
480
481
482
483
<para>You can enable the &gdb; plugin in
<link linkend="config-dialog-plugins">the Plugins section of &kappname;'s
configuration</link>.</para>

<para>For the plugin to work properly, you must have a source file (of any type
supported by &gdb;) and an executable.</para>

<tip>
<para>If you compile using &gcc;/<command>g++</command> you might want to use
the <command><parameter>-ggdb</parameter></command> command line argument.
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
484
</para>
485
486
487
488
489
490
491
</tip>

<para>After these preparations are made, open the source file in &kappname;,
enter the path to the executable in the <guilabel>Settings</guilabel> tab of the
<guilabel>Debug View</guilabel> tool view, and select
<menuchoice><guimenu>Debug</guimenu><guimenuitem>Start Debugging</guimenuitem></menuchoice>
from the menu to get started.</para>
492
493
494

</sect2>

495
496
497
498
499
<sect2 id="gdb-menus">
<title>Menu and Toolbar Structure</title>

<para>All of these options are available in &kappname;'s menus, and many are
available on the Debug toolbar as well.</para>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
500

501
<variablelist>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
502

503
<varlistentry id="gdb-menus-show-debug-view">
Burkhard Lück's avatar
Burkhard Lück committed
504
<term><menuchoice>
505
<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Debug View</guimenuitem>
Burkhard Lück's avatar
Burkhard Lück committed
506
</menuchoice></term>
507
508
<listitem><para>Shows a tool view containing &gdb; output, the &gdb; command
line used, and other settings.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
509
510
</varlistentry>

511
<varlistentry id="gdb-menus-show-locals">
Burkhard Lück's avatar
Burkhard Lück committed
512
<term><menuchoice>
513
<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Locals</guimenuitem>
Burkhard Lück's avatar
Burkhard Lück committed
514
</menuchoice></term>
515
516
<listitem><para>Shows a list of all currently loaded variables and their values.
</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
517
518
</varlistentry>

519
<varlistentry id="gdb-menus-show-call-stack">
Burkhard Lück's avatar
Burkhard Lück committed
520
<term><menuchoice>
521
<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Call Stack</guimenuitem>
Burkhard Lück's avatar
Burkhard Lück committed
522
</menuchoice></term>
523
<listitem><para>Shows a &gdb; backtrace.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
524
525
</varlistentry>

526
<varlistentry id="gdb-menus-targets">
Burkhard Lück's avatar
Burkhard Lück committed
527
<term><menuchoice>
528
<guimenu>Debug</guimenu><guisubmenu>Targets</guisubmenu>
Burkhard Lück's avatar
Burkhard Lück committed
529
</menuchoice></term>
530
531
<listitem><para>A submenu containing a list of targets (executables).
</para></listitem>
532
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
533

534
535
536
537
538
539
<varlistentry id="gdb-menus-arg-lists">
<term><menuchoice>
<guimenu>Debug</guimenu><guisubmenu>Arg Lists</guisubmenu>
</menuchoice></term>
<listitem><para>A submenu containing all argument lists.</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
540

541
542
543
544
545
546
<varlistentry id="gdb-menus-start">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Start Debugging</guimenuitem>
</menuchoice></term>
<listitem><para>Starts &gdb; with a target.</para></listitem>
</varlistentry>
547

548
549
550
551
552
553
<varlistentry id="gdb-menus-kill">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Kill / Stop Debugging</guimenuitem>
</menuchoice></term>
<listitem><para>Stops &gdb;.</para></listitem>
</varlistentry>
Burkhard Lück's avatar
Burkhard Lück committed
554

555
556
557
558
559
560
<varlistentry id="gdb-menus-restart">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Restart Debugging</guimenuitem>
</menuchoice></term>
<listitem><para>Restarts &gdb;.</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
561

562
563
564
565
566
567
568
<varlistentry id="gdb-menus-break">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Toggle Breakpoint / Break</guimenuitem>
</menuchoice></term>
<listitem><para>Set a breakpoint at the current cursor position.
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
569

570
571
572
573
574
575
576
<varlistentry id="gdb-menus-step-in">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Step In</guimenuitem>
</menuchoice></term>
<listitem><para>Execute the present statement (function call will be debugged).
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
577

578
<varlistentry id="gdb-menus-step-over">
Burkhard Lück's avatar
Burkhard Lück committed
579
<term><menuchoice>
580
<guimenu>Debug</guimenu><guimenuitem>Step Over</guimenuitem>
Burkhard Lück's avatar
Burkhard Lück committed
581
</menuchoice></term>
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
<listitem><para>Execute the present statement (function call will not be
debugged).</para></listitem>
</varlistentry>

<varlistentry id="gdb-menus-step-out">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Step Out</guimenuitem>
</menuchoice></term>
<listitem><para>Resumes execution until the program that is executing
terminates.</para></listitem>
</varlistentry>

<varlistentry id="gdb-menus-move-pc">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Move PC</guimenuitem>
</menuchoice></term>
<listitem><para>Move program counter (next execution).</para></listitem>
</varlistentry>

<varlistentry id="gdb-menus-run-to-cursor">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Run To Cursor</guimenuitem>
</menuchoice></term>
<listitem><para>Runs the program until it reaches current cursor position.
</para></listitem>
</varlistentry>

<varlistentry id="gdb-menus-continue">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Continue</guimenuitem>
</menuchoice></term>
<listitem><para>Ignores any breakpoints and executes program until it terminates
(successfully or not).</para></listitem>
</varlistentry>

<varlistentry id="gdb-menus-print-value">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Print Value</guimenuitem>
</menuchoice></term>
<listitem><para>Prints the value of the variable that the cursor is currently
pointing to.</para></listitem>
</varlistentry>

<varlistentry id="gdb-menus-toolbar">
<term><menuchoice>
<guimenu>Settings</guimenu><guisubmenu>Toolbars Shown</guisubmenu><guimenuitem>&gdb; Plugin</guimenuitem>
</menuchoice></term>
<listitem><para>Display the debugging toolbar.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
630
631
632
</varlistentry>

</variablelist>
633

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
634
635
</sect2>

636
637
<sect2 id="gdb-debug-view">
<title>Debug View</title>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
638

639
640
<para>The <guilabel>Debug View</guilabel> tool view consists of several tabs:
</para>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
641
642

<variablelist>
643

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
644
<varlistentry>
645
<term><guilabel>&gdb; Output</guilabel></term>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
646
<listitem>
647
648
649
650
651
652
653
654
655
656
657
658
659
<para>Contains output from &gdb; and a &gdb; command line.</para>

<screenshot id="screenshot-gdb-output">
<screeninfo>The Output Tab</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="gdb-output.png" format="PNG"/></imageobject>
<textobject><phrase>The Output tab.</phrase></textobject>
<caption><para>The <guilabel>Output</guilabel> tab displaying the output from a
debugging session.</para></caption>
</mediaobject>
</screenshot>

</listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
660
</varlistentry>
661

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
662
<varlistentry>
663
<term><guilabel>Settings</guilabel></term>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
664
665
<listitem>
<variablelist>
666

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
667
<varlistentry>
668
669
<term><guilabel>Target</guilabel></term>
<listitem><para>Path to the target (executable) for debugging.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
670
</varlistentry>
671

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
672
<varlistentry>
673
674
675
<term><guilabel>Working Directory</guilabel></term>
<listitem><para>The current working directory provided to the target.
</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
676
</varlistentry>
677

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
678
<varlistentry>
679
680
<term><guilabel>Arg List</guilabel></term>
<listitem><para>Arguments passed to the program.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
681
</varlistentry>
682

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
683
<varlistentry>
684
685
<term><guilabel>Keep focus</guilabel></term>
<listitem><para>Keeps focus on the &gdb; command line.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
686
</varlistentry>
687

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
688
<varlistentry>
689
690
691
692
<term><guilabel>Redirect IO</guilabel></term>
<listitem><para>Opens a new <guilabel>IO</guilabel> tab in the <guilabel>Debug
View</guilabel> where you can view output and provide input to the running
program.</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
693
</varlistentry>
694

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
695
696
</variablelist>

697
698
699
700
701
702
703
704
705
<screenshot id="screenshot-gdb-settings">
<screeninfo>The Settings Tab</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="gdb-settings.png" format="PNG"/></imageobject>
<textobject><phrase>The Settings tab.</phrase></textobject>
<caption><para>The <guilabel>Settings</guilabel> tab displaying the configuration
of a debugging session.</para></caption>
</mediaobject>
</screenshot>
706

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
707
708
709
710
</listitem>
</varlistentry>

<varlistentry>
711
<term><guilabel>IO</guilabel></term>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
712
<listitem>
713
714
715
716
717
718
719
720
721
722
723
724
725
<para>Contains an area that displays output from the running program and a
command line where you may provide input to it.</para>

<screenshot id="screenshot-gdb-io">
<screeninfo>The IO Tab</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="gdb-io.png" format="PNG"/></imageobject>
<textobject><phrase>The IO tab.</phrase></textobject>
<caption><para>The <guilabel>IO</guilabel> tab displaying output from a simple
test program.</para></caption>
</mediaobject>
</screenshot>

T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
726
727
728
729
730
</listitem>
</varlistentry>

</variablelist>

731
</sect2>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
732

733
734
<sect2 id="gdb-other">
<title>Call Stack and Locals</title>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
735

736
737
<para>The <guilabel>Call Stack</guilabel> tool view contains a list of the formatted
backtrace returned from &gdb;.</para>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
738

739
740
741
742
743
744
745
746
747
<screenshot id="screenshot-gdb-call-stack">
<screeninfo>The &gdb; Call Stack Tool View</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="gdb-call-stack.png" format="PNG"/></imageobject>
<textobject><phrase>The Call Stack tool view.</phrase></textobject>
<caption><para>The &gdb; Plugin's <guilabel>Call Stack</guilabel> tool view.
</para></caption>
</mediaobject>
</screenshot>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
748

749
750
<para>The <guilabel>Locals</guilabel> tool view contains a list of all currently
loaded variables from the program and their corresponding values.</para>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
751

752
753
754
755
756
757
758
759
760
<screenshot id="screenshot-gdb-locals">
<screeninfo>The &gdb; Locals Tool View</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="gdb-locals.png" format="PNG"/></imageobject>
<textobject><phrase>The Locals tool view.</phrase></textobject>
<caption><para>The &gdb; Plugin's <guilabel>Locals</guilabel> tool view.
</para></caption>
</mediaobject>
</screenshot>
761
762
763

</sect2>

764
765
<sect2 id="gdb-ack">
<title>Thanks and Acknowledgments</title>
766

767
768
<para>Special thanks to Google Code-In 2011 participant Martin Gergov for
writing much of this section.</para>
769
770
771

</sect2>

772
</sect1>
773

774
775
776
777
778
779
780
<sect1 id="kate-application-plugin-searchinfiles">
<sect1info>
<authorgroup><author>
&TC.Hollingsworth; &TC.Hollingsworth.mail;
</author></authorgroup>
</sect1info>
<title>Search &amp; Replace</title>
781

782
783
784
785
786
787
788
789
<sect2 id="searchinfiles-intro">
<title>Introduction</title>
<para>&kappname;'s Search &amp; Replace plugin allows you to search for text or
<ulink url="help:/katepart/regular-expressions.html">regular expressions</ulink>
in many different files at once.  You can search all open files, all the files
in one directory and optionally its subdirectories, or all files in the current
project.  You can even filter by filename, for instance searching only files
that end with a particular file extension.</para>
790

791
</sect2>
792

793
794
<sect2 id="searchinfiles-ui">
<title>Interface</title>
795

796
797
<sect3 id="searchinfiles-ui-query">
<title>Search Query</title>
798

799
800
<para>The following options are always displayed at the top of the Search in
Files tool view:</para>
801
802

<variablelist>
803

804
<varlistentry>
805
806
807
808
809
810
811
<term><guiicon>New Tab</guiicon></term>
<listitem><para>
You can have as many searches as you want open at the same time.  Simply click
the <guibutton>New Tab</guibutton> button at the top-left corner of the Search
tool view and a new results tab will open permitting you to perform another
search.
</para></listitem>
812
813
814
</varlistentry>

<varlistentry>
815
816
817
818
819
820
<term><guiicon>Toggle Results</guiicon></term>
<listitem><para>
The down arrow in the top right-corner of the Search in Files tool view will
toggle the bottom half of the tool view between displaying additional options
for the Search in Folder mode and the results of your search.
</para></listitem>
821
822
823
</varlistentry>

<varlistentry>
824
825
826
827
828
<term><guilabel>Find</guilabel></term>
<listitem><para>
This is where you type in what you want to find.  You may enter standard text, 
or a regular expression if enabled.
</para></listitem>
829
</varlistentry>
830

831
<varlistentry>
832
833
834
835
836
<term><guilabel>Replace</guilabel> (text box)</term>
<listitem><para>
Replacement text that will be added to file(s) in place of the text in the
<guilabel>Find</guilabel> text box.
</para></listitem>
837
838
839
</varlistentry>

<varlistentry>
840
841
842
843
844
845
<term><guibutton>Search</guibutton></term>
<listitem><para>
When you've finished configuring everything, just press the
<guibutton>Search</guibutton> button to perform your search.  You may also press
&Enter; in the <guilabel>Find</guilabel> text box to do the same.
</para></listitem>
846
847
848
</varlistentry>

<varlistentry>
849
850
851
852
853
854
855
856
<term><guibutton>Replace</guibutton></term>
<listitem><para>
When you've finished configuring everything, just press the
<guibutton>Replace</guibutton> button to replace the text entered in the
<guilabel>Find</guilabel> text box with that of the <guilabel>Replace</guilabel>
text box.  You may also press &Enter; in the <guilabel>Replace</guilabel> text 
box to do the same.
</para></listitem>
857
858
859
</varlistentry>

<varlistentry>
860
861
862
863
<term><guibutton>Next</guibutton></term>
<listitem><para>
Go to the next match of your search query, switching files if necessary.
</para></listitem>
864
865
866
</varlistentry>

<varlistentry>
867
868
869
870
871
<term><guibutton>Replace checked</guibutton></term>
<listitem><para>
The same as <guibutton>Replace</guibutton>, but will only perform replacements
in files that are checked in the pane below.
</para></listitem>
872
873
874
875
</varlistentry>

</variablelist>
</sect3>
Burkhard Lück's avatar
Burkhard Lück committed
876

877
878
<sect3 id="searchinfiles-ui-folder">
<title>Search in Folder Options</title>
879

880
881
882
<para>These options are displayed below the aforementioned query options. If search
results are being displayed instead, press the <guiicon>Toggle Results</guiicon>
button to display them.</para>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
883

884
<variablelist>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
885

886
887
888
889
890
891
892
<varlistentry>
<term><guilabel>Match case</guilabel></term>
<listitem><para>
Restricts search results to only those that have the exact same combination
of upper and lower case letters as your search query.
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
893

894
895
896
897
898
899
900
<varlistentry>
<term><guilabel>Regular expressions</guilabel></term>
<listitem><para>
Permits you to use <ulink url="help:/katepart/regular-expressions.html">regular
expressions</ulink> instead of simple text as your search query.
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
901

902
903
904
905
906
907
908
<varlistentry>
<term><guilabel>Expand results</guilabel></term>
<listitem><para>
Display all the results found in each file, instead of just a list of files
that contain the search query.
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
909

910
911
912
913
914
915
916
917
918
<varlistentry>
<term><guilabel>Search</guilabel></term>
<listitem><para>
This has three options.  Select <guilabel>in Open files</guilabel> to search all
files currently open in &kappname;.  Select <guilabel>in Folder</guilabel> to
search inside a folder and optionally its subfolders.  Select <guilabel>in
Project</guilabel> to search all the files listed in the currently open project.
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
919

920
921
922
923
924
925
926
927
928
<varlistentry>
<term><guilabel>Folder</guilabel></term>
<listitem><para>
You may enter the path of the folder you wish to search.  For instance, you might
enter <userinput>~/development/kde/kate/</userinput> if you wished to search the
&kate; source code.  This option is only available when using 
<guilabel>in Folder</guilabel> mode.
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
929

930
931
932
933
934
935
936
<varlistentry>
<term><guiicon>Open file dialog</guiicon></term>
<listitem><para>
Press this button to locate the folder in your desktop's folder browser. This 
button only works when using <guilabel>in Folder</guilabel> mode.
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
937

938
939
940
941
942
943
944
945
<varlistentry>
<term><guiicon>Up</guiicon></term>
<listitem><para>
Press this button to change <guilabel>Folder</guilabel> to the parent of the
currently selected folder. This button only works when using 
<guilabel>in Folder</guilabel> mode.
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
946

947
948
949
950
951
952
953
954
<varlistentry>
<term><guiicon>Restore Current Folder</guiicon></term>
<listitem><para>
This button will set the <guilabel>Folder</guilabel> entry to the folder in which
the currently open document is located. This  button only works when using 
<guilabel>in Folder</guilabel> mode.
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
955

956
957
958
959
960
961
962
963
964
965
966
<varlistentry>
<term><guilabel>Filter</guilabel></term>
<listitem><para>
This permits you to only search filenames that match a particular pattern.  For
instance, to only search files written in C++, change it to
<userinput>*.cpp</userinput>.  To search only files beginning with
<literal>kate</literal>, change it to <userinput>kate*</userinput>.  You can
enter multiple filters separated with a comma (<userinput>,</userinput>).  This
option is not available when using <guilabel>in Open files</guilabel> mode.
</para></listitem>
</varlistentry>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
967
968

<varlistentry>
969
970
971
972
973
974
975
976
<term><guilabel>Exclude</guilabel></term>
<listitem><para>
The opposite of <guilabel>Filter</guilabel>, this prevents &kappname; from
searching files that match the specified patterns.  As with 
<guilabel>Filter</guilabel>, you can enter multiple patterns separated with a 
comma (<userinput>,</userinput>). This option is not available when using
<guilabel>in Open files</guilabel> mode.
</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
977
978
979
</varlistentry>

<varlistentry>
980
981
982
983
984
985
<term><guilabel>Recursive</guilabel></term>
<listitem><para>
If this option is enabled, &kappname; will also search in all subfolders of the
selected folder. This option is only available when using 
<guilabel>in Folder</guilabel> mode.
</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
986
987
988
</varlistentry>

<varlistentry>
989
990
991
992
993
994
<term><guilabel>Include hidden</guilabel></term>
<listitem><para>
If this option is enabled, &kappname; will also search in files or folders that
are typically hidden by your &OS;. This option is only available when using 
<guilabel>in Folder</guilabel> mode.
</para></listitem>
T.C. Hollingsworth's avatar
T.C. Hollingsworth committed
995
996
997
</varlistentry>

<varlistentry>
998
999
1000
<term><guilabel>Follow symbolic links</guilabel></term>
<listitem><para>
The Search in Files plugin typically doesn't follow
For faster browsing, not all history is shown. View entire blame