← Back to branch summary

~ubuntu-branches/ubuntu/vivid/kate/vivid-updates

« back to all changes in this revision

Viewing changes to doc/kate/advanced.docbook

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2014-12-04 16:49:41 UTC
  • mfrom: (1.6.6)
  • Revision ID: package-import@ubuntu.com-20141204164941-l3qbvsly83hhlw2v
Tags: 4:14.11.97-0ubuntu1
* New upstream release
* Update build-deps and use pkg-kde v3 for Qt 5 build
* kate-data now kate5-data for co-installability

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/kate/advanced.docbook
1
 
<chapter id="advanced-editing-tools">
2
 
<chapterinfo>
3
 
<authorgroup>
4
 
<author>&Anders.Lund; &Anders.Lund.mail;</author>
5
 
<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author>
6
 
<!-- TRANS:ROLES_OF_TRANSLATORS -->
7
 
</authorgroup>
8
 
</chapterinfo>
9
 
<title>Advanced Editing Tools</title>
10
 
 
11
 
<sect1 id="advanced-editing-tools-comment">
12
 
 
13
 
<title>Comment/Uncomment</title>
14
 
 
15
 
<para>The <guimenuitem>Comment</guimenuitem> and <guimenuitem>Uncomment</guimenuitem> commands, available from the
16
 
<guimenu>Tools</guimenu> menu allow you to add or remove comment
17
 
markers to the selection, or the current line if no text is selected,
18
 
if comments are supported by the format of the text you are
19
 
editing.</para>
20
 
 
21
 
<para>The rules for how commenting is done are defined in the syntax
22
 
definitions, so if syntax highlighting is not used, commenting/uncommenting
23
 
is not possible. </para>
24
 
 
25
 
<para>Some formats define single line comment markers, some multiline
26
 
markers and some both.  If multiline markers are not available,
27
 
commenting out a selection that does not fully include its last line
28
 
is not possible.</para>
29
 
 
30
 
<para>If a single line marker is available, commenting single lines is
31
 
preferred where applicable, as this helps to avoid problems with
32
 
nested comments.</para>
33
 
 
34
 
<para>When removing comment markers, no uncommented text should be
35
 
selected. When removing multiline comment markers from a selection,
36
 
any whitespace outside the comment markers is ignored.</para>
37
 
 
38
 
<para><indexterm><primary>comment</primary></indexterm>
39
 
To place comment markers, use the
40
 
<menuchoice><guimenu>Tools</guimenu><guimenuitem>Comment</guimenuitem></menuchoice>
41
 
menu item or the related keyboard shortcut sequence, the default is
42
 
<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>.</para>
43
 
 
44
 
<para><indexterm><primary>uncomment</primary></indexterm>
45
 
To remove comment markers, use the
46
 
<menuchoice><guimenu>Tools</guimenu><guimenuitem>Uncomment</guimenuitem></menuchoice>
47
 
menu item or the related keyboard shortcut, the default is <keycombo
48
 
action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo>.</para>
49
 
 
50
 
</sect1>
51
 
 
52
 
<sect1 id="advanced-editing-tools-commandline">
53
 
<title>The Editor Component Command Line</title>
54
 
 
55
 
<para>&kappname;'s editor component has an internal command line, allowing you to
56
 
perform various actions from a minimal GUI. The command line is a text entry
57
 
at the bottom of the editor area; to show it select
58
 
<menuchoice><guimenu>View</guimenu><guimenuitem>Switch to Command Line</guimenuitem></menuchoice>
59
 
or use the shortcut (default is
60
 
<keycombo action="simul"><keycap>F7</keycap></keycombo>). The editor provides
61
 
a set of commands as documented below, and additional commands can be provided
62
 
by plugins.</para>
63
 
 
64
 
<para>To execute a command, type the command then press the return key. The
65
 
command line will indicate whether it succeeded and possibly display a message. If
66
 
you entered the command line by pressing <keycap>F7</keycap> it will
67
 
automatically hide after a few seconds. To clear the message and enter a new
68
 
command, press <keycap>F7</keycap> again.</para>
69
 
 
70
 
<para>The command line has a built-in help system; issue the command
71
 
<command>help</command> to get started. To see a list of all available commands
72
 
issue <command>help list</command>; to view help for a specific command, do
73
 
<command>help <replaceable>command</replaceable></command>.</para>
74
 
 
75
 
<para>The command line has a built in history, so you can reuse commands already
76
 
typed. To navigate the history, use the <keycap>Up</keycap> and
77
 
<keycap>Down</keycap> keys. When showing historical commands, the argument part
78
 
of the command will be selected, allowing you to easily overwrite the
79
 
arguments.</para>
80
 
 
81
 
<sect2 id="advanced-editing-tools-commandline-commands">
82
 
<title>Standard Command Line Commands</title>
83
 
 
84
 
<variablelist>
85
 
<title>Argument types</title>
86
 
 
87
 
<varlistentry>
88
 
<term>BOOLEAN</term>
89
 
<listitem><para>This is used with commands that turns things on or off.
90
 
Legal values are <userinput>on</userinput>, <userinput>off</userinput>,
91
 
<userinput>true</userinput>, <userinput>false</userinput>,
92
 
<userinput>1</userinput> or <userinput>0</userinput>.</para></listitem>
93
 
</varlistentry>
94
 
 
95
 
<varlistentry>
96
 
<term>INTEGER</term>
97
 
<listitem><para>An integer number.</para></listitem>
98
 
</varlistentry>
99
 
 
100
 
<varlistentry>
101
 
<term>STRING</term>
102
 
<listitem><para>A string, surrounded by single quotes (') or double quotes (") when it contains spaces.</para></listitem>
103
 
</varlistentry>
104
 
 
105
 
</variablelist>
106
 
 
107
 
 
108
 
 
109
 
<sect3 id="advanced-editing-tools-commandline-commands-configure">
110
 
<title>Commands for Configuring the Editor</title>
111
 
 
112
 
<para>These commands are provided by the editor component, and allow you to
113
 
configure the active document and view only. This is handy if you want to use
114
 
a setting different from the default settings, for example for indentation.
115
 
</para>
116
 
 
117
 
<variablelist>
118
 
 
119
 
<varlistentry>
120
 
<term><cmdsynopsis><command>set-tab-width</command><arg choice="req">INTEGER width</arg></cmdsynopsis></term>
121
 
<listitem><para>Sets the tab width to the number <userinput>width</userinput>.</para></listitem>
122
 
</varlistentry>
123
 
 
124
 
<varlistentry>
125
 
<term><cmdsynopsis><command>set-indent-width</command><arg choice="req">INTEGER width</arg></cmdsynopsis></term>
126
 
<listitem><para>Sets the indentation width to the number
127
 
<userinput>width</userinput>. Used only if you are indenting with
128
 
spaces.</para></listitem>
129
 
</varlistentry>
130
 
 
131
 
<varlistentry>
132
 
<term><cmdsynopsis><command>set-word-wrap-column</command><arg choice="req">INTEGER width</arg></cmdsynopsis></term>
133
 
<listitem><para>Sets the line width for hard wrapping to
134
 
<userinput>width</userinput>. This is used if you are having your text wrapped
135
 
automatically.</para></listitem>
136
 
</varlistentry>
137
 
 
138
 
<varlistentry>
139
 
<term><cmdsynopsis><command>set-icon-border</command><arg choice="req">BOOLEAN enable</arg>
140
 
</cmdsynopsis></term>
141
 
<listitem><para>Sets the visibility of the icon border.</para></listitem>
142
 
</varlistentry>
143
 
 
144
 
<varlistentry>
145
 
<term><cmdsynopsis><command>set-folding-markers</command><arg choice="req">BOOLEAN enable</arg></cmdsynopsis></term>
146
 
<listitem><para>Sets the visibility of the folding markers pane.</para></listitem>
147
 
</varlistentry>
148
 
 
149
 
<varlistentry>
150
 
<term><cmdsynopsis><command>set-line-numbers</command><arg choice="req">BOOLEAN enable</arg></cmdsynopsis></term>
151
 
<listitem><para>Sets the visibility of the line numbers pane.</para></listitem>
152
 
</varlistentry>
153
 
 
154
 
<varlistentry>
155
 
<term><cmdsynopsis><command>set-replace-tabs</command><arg choice="req">BOOLEAN enable</arg></cmdsynopsis></term>
156
 
<listitem><para>If enabled, tabs are replaced with spaces as you type.
157
 
</para></listitem>
158
 
</varlistentry>
159
 
 
160
 
<varlistentry>
161
 
<term><cmdsynopsis><command>set-remove-trailing-space</command><arg choice="req">BOOLEAN enable</arg></cmdsynopsis></term>
162
 
<listitem><para>If enabled, trailing whitespace is removed whenever the cursor
163
 
leaves a line.</para></listitem>
164
 
</varlistentry>
165
 
 
166
 
<varlistentry>
167
 
<term><cmdsynopsis><command>set-show-tabs</command><arg choice="req">BOOLEAN enable</arg></cmdsynopsis></term>
168
 
<listitem><para>If enabled, TAB characters and trailing whitespace will be
169
 
visualized by a small dot.</para></listitem>
170
 
</varlistentry>
171
 
 
172
 
<varlistentry>
173
 
<term><cmdsynopsis><command>set-show-indent</command><arg choice="req">BOOLEAN enable</arg></cmdsynopsis></term>
174
 
<listitem><para>If enabled, indentation will be visualized by a vertical dotted
175
 
line.</para></listitem>
176
 
</varlistentry>
177
 
 
178
 
<varlistentry>
179
 
<term><cmdsynopsis><command>set-indent-spaces</command><arg choice="req">BOOLEAN enable</arg></cmdsynopsis></term>
180
 
<listitem><para>If enabled, the editor will indent with
181
 
<option>indent-width</option> spaces for each indentation level, rather than
182
 
with one TAB character.</para></listitem>
183
 
</varlistentry>
184
 
 
185
 
<varlistentry>
186
 
<term><cmdsynopsis><command>set-mixed-indent</command><arg choice="req">BOOLEAN enable</arg></cmdsynopsis></term>
187
 
<listitem><para>If enabled, &kappname; will use a mix of TAB and spaces for
188
 
indentation. Each indentation level will be <option>indent-width</option> wide,
189
 
and more indentation levels will be optimized to use as many TAB characters as
190
 
possible.</para>
191
 
<para>When executed, this command will additionally set space indentation enabled,
192
 
and if the indent width is unspecified it will be set to half of the
193
 
<option>tab-width</option> for the document at the time of execution.</para></listitem>
194
 
</varlistentry>
195
 
 
196
 
<varlistentry>
197
 
<term><cmdsynopsis><command>set-word-wrap</command><arg choice="req">BOOLEAN
198
 
enable</arg></cmdsynopsis></term>
199
 
<listitem><para>Enables dynamic word wrap according to
200
 
<userinput>enable</userinput>.</para></listitem>
201
 
</varlistentry>
202
 
 
203
 
<varlistentry>
204
 
<term><cmdsynopsis><command>set-replace-tabs-save</command><arg choice="req">BOOLEAN enable
205
 
</arg></cmdsynopsis></term>
206
 
<listitem><para>When enabled, tabs will be replaced with whitespace whenever
207
 
 the document is saved.</para></listitem>
208
 
</varlistentry>
209
 
 
210
 
<varlistentry>
211
 
<term><cmdsynopsis><command>set-remove-trailing-space-save</command><arg choice="req">BOOLEAN enable</arg></cmdsynopsis></term>
212
 
<listitem><para>When enabled, trailing space will be removed from each line
213
 
whenever the document is saved.</para></listitem>
214
 
</varlistentry>
215
 
 
216
 
<varlistentry>
217
 
<term><cmdsynopsis><command>set-indent-mode</command><arg choice="req">STRING name</arg></cmdsynopsis></term>
218
 
<listitem><para>Sets the autoindentation mode to <userinput>name</userinput>.
219
 
If <userinput>name</userinput> is not known, the mode is set to 'none'. Valid
220
 
modes are 'none', 'normal', 'cstyle', 'haskell', 'lilypond', 'lisp', 'python',
221
 
'ruby' and 'xml'.</para></listitem>
222
 
</varlistentry>
223
 
 
224
 
<varlistentry>
225
 
<term><cmdsynopsis><command>set-auto-ident</command><arg choice="req">BOOLEAN script</arg></cmdsynopsis></term>
226
 
<listitem><para>Enable or disable autoindentation.</para></listitem>
227
 
</varlistentry>
228
 
 
229
 
<varlistentry>
230
 
<term><cmdsynopsis><command>set-highlight</command><arg choice="req">STRING highlight</arg></cmdsynopsis></term>
231
 
<listitem><para>Sets the syntax highlighting system for the document. The
232
 
argument must be a valid highlight name, as seen in the
233
 
<menuchoice><guimenu>Tools</guimenu><guisubmenu>Highlighting</guisubmenu></menuchoice>
234
 
menu. This command provides an autocompletion list for its
235
 
argument.</para></listitem>
236
 
</varlistentry>
237
 
 
238
 
<varlistentry>
239
 
<term><cmdsynopsis><command>reload-scripts</command></cmdsynopsis></term>
240
 
<listitem><para>Reload all <link linkend="dev-scripting">JavaScript
241
 
scripts</link> used by Kate, including indenters and command line scripts.</para></listitem>
242
 
</varlistentry>
243
 
 
244
 
<varlistentry>
245
 
<term><cmdsynopsis><command>set-mode</command><arg choice="req">STRING mode</arg></cmdsynopsis></term>
246
 
<listitem><para>Choose the filetype scheme for the current document.
247
 
</para></listitem>
248
 
</varlistentry>
249
 
 
250
 
<varlistentry>
251
 
<term><cmdsynopsis><command>nn[oremap]</command><arg choice="req">STRING original</arg>
252
 
<arg choice="req">STRING mapped</arg></cmdsynopsis></term>
253
 
<listitem><para>Map the key sequence <userinput>original</userinput> to 
254
 
<userinput>mapped</userinput>.</para></listitem>
255
 
</varlistentry>
256
 
 
257
 
</variablelist>
258
 
 
259
 
</sect3>
260
 
 
261
 
<sect3 id="advanced-editing-tools-commandline-commands-edit">
262
 
<title>Commands for editing</title>
263
 
 
264
 
<para>These commands modify the current document.</para>
265
 
 
266
 
<variablelist>
267
 
<varlistentry>
268
 
<term><cmdsynopsis><command>indent</command></cmdsynopsis></term>
269
 
<listitem><para>Indents the selected lines or the current line.</para></listitem>
270
 
</varlistentry>
271
 
 
272
 
<varlistentry>
273
 
<term><cmdsynopsis><command>unindent</command></cmdsynopsis></term>
274
 
<listitem><para>Unindents the selected lines or current line.</para></listitem>
275
 
</varlistentry>
276
 
 
277
 
<varlistentry>
278
 
<term><cmdsynopsis><command>cleanindent</command></cmdsynopsis></term>
279
 
<listitem><para>Cleans up the indentation of the selected lines or current line
280
 
according to the indentation settings in the document.
281
 
</para></listitem>
282
 
</varlistentry>
283
 
 
284
 
<varlistentry>
285
 
<term><cmdsynopsis><command>comment</command></cmdsynopsis></term>
286
 
<listitem><para>Inserts comment markers to make the selection or selected lines
287
 
or current line a comment according to the text format as defined by the syntax
288
 
highlight definition for the document.</para></listitem>
289
 
</varlistentry>
290
 
 
291
 
<varlistentry>
292
 
<term><cmdsynopsis><command>uncomment</command></cmdsynopsis></term>
293
 
<listitem><para>Removes comment markers from the selection or selected lines
294
 
or current line according to the text format as defined by the syntax highlight
295
 
definition for the document.</para></listitem>
296
 
</varlistentry>
297
 
 
298
 
<varlistentry>
299
 
<term><cmdsynopsis><command>kill-line</command></cmdsynopsis></term>
300
 
<listitem><para>Deletes the current line.</para></listitem>
301
 
</varlistentry>
302
 
 
303
 
<varlistentry>
304
 
<term><cmdsynopsis><command>replace</command><arg choice="req"> STRING pattern</arg>
305
 
<arg choice="req">STRING replacement</arg></cmdsynopsis></term>
306
 
<listitem><para>Replaces text matching <userinput>pattern</userinput> with
307
 
<userinput>replacement</userinput>. If you want to include whitespace in the
308
 
<userinput>pattern</userinput>, you must quote both the <userinput>pattern</userinput>
309
 
and <userinput>replacement</userinput> with single or double quotes. If the
310
 
arguments are unquoted, the first word is used as <userinput>pattern</userinput>
311
 
and the rest for <userinput>replacement</userinput>. If
312
 
<userinput>replacement</userinput> is empty, each occurrence of
313
 
<userinput>pattern</userinput> is removed.</para>
314
 
<para>You can set flags to configure the search by adding a colon, followed
315
 
by one or more letters each representing a configuration, giving the form
316
 
<userinput>replace:options pattern replacement</userinput>. Available options
317
 
are:
318
 
 
319
 
<variablelist>
320
 
 
321
 
<varlistentry>
322
 
<term><userinput>b</userinput></term>
323
 
<listitem><para>Search backwards.</para></listitem>
324
 
</varlistentry>
325
 
 
326
 
<varlistentry>
327
 
<term><userinput>c</userinput></term>
328
 
<listitem><para>Search from cursor position.</para></listitem>
329
 
</varlistentry>
330
 
 
331
 
<varlistentry>
332
 
<term><userinput>e</userinput></term>
333
 
<listitem><para>Search in the selection only.</para></listitem>
334
 
</varlistentry>
335
 
 
336
 
<varlistentry>
337
 
<term><userinput>r</userinput></term>
338
 
<listitem><para>Do regular expression search. If set, you may use
339
 
<userinput>\N</userinput> where N is a number to represent captures in the
340
 
replacement string.</para></listitem>
341
 
</varlistentry>
342
 
 
343
 
<varlistentry>
344
 
<term><userinput>s</userinput></term>
345
 
<listitem><para>Do case sensitive search.</para></listitem>
346
 
</varlistentry>
347
 
 
348
 
<varlistentry>
349
 
<term><userinput>p</userinput></term>
350
 
<listitem><para>Prompt for permission to replace the next occurrence.</para></listitem>
351
 
</varlistentry>
352
 
 
353
 
<varlistentry>
354
 
<term><userinput>w</userinput></term>
355
 
<listitem><para>Match whole words only.</para></listitem>
356
 
</varlistentry>
357
 
 
358
 
</variablelist>
359
 
 
360
 
</para>
361
 
</listitem>
362
 
</varlistentry>
363
 
 
364
 
<varlistentry>
365
 
<term><cmdsynopsis><command>date</command><arg choice="req">STRING format</arg></cmdsynopsis></term>
366
 
<listitem><para>Inserts a date/time string as defined by the specified
367
 
<userinput>format</userinput>, or the format <quote>yyyy-MM-dd hh:mm:ss</quote>
368
 
if none is specified. The following translations are done when interpreting
369
 
<userinput>format</userinput>:
370
 
 
371
 
<informaltable>
372
 
<tgroup cols="2">
373
 
<tbody>
374
 
<row><entry><literal>d</literal></entry><entry>The day as number without a leading zero (1-31).</entry></row>
375
 
<row><entry><literal>dd</literal></entry><entry>The day as number with a leading zero (01-31).</entry></row>
376
 
<row><entry><literal>ddd</literal></entry><entry>The abbreviated localized day name (e.g. 'Mon'..'Sun').</entry></row>
377
 
<row><entry><literal>dddd</literal></entry><entry>The long localized day name (e.g. 'Monday'..'Sunday').</entry></row>
378
 
<row><entry><literal>M</literal></entry><entry>The month as number without a leading zero (1-12).</entry></row>
379
 
<row><entry><literal>MM</literal></entry><entry>The month as number with a leading zero (01-12).</entry></row>
380
 
<row><entry><literal>MMMM</literal></entry><entry>The long localized month name (e.g. 'January'..'December').</entry></row>
381
 
<row><entry><literal>MMM</literal></entry><entry>The abbreviated localized month name (e.g. 'Jan'..'Dec').</entry></row>
382
 
<row><entry><literal>yy</literal></entry><entry>The year as two digit number
383
 
(00-99).</entry></row>
384
 
<row><entry><literal>yyyy</literal></entry><entry>The year as four digit number (1752-8000).</entry></row>
385
 
<row><entry><literal>h</literal></entry><entry>The hour without a leading zero (0..23 or 1..12 if AM/PM display).</entry></row>
386
 
<row><entry><literal>hh</literal></entry><entry>The hour with a leading zero (00..23 or 01..12 if AM/PM display).</entry></row>
387
 
<row><entry><literal>m</literal></entry><entry>The minute without a leading zero (0..59).</entry></row>
388
 
<row><entry><literal>mm</literal></entry><entry>The minute with a leading zero (00..59).</entry></row>
389
 
<row><entry><literal>s</literal></entry><entry>The second without a leading zero (0..59).</entry></row>
390
 
<row><entry><literal>ss</literal></entry><entry>The second with a leading zero (00..59).</entry></row>
391
 
<row><entry><literal>z</literal></entry><entry>The milliseconds without leading zeroes (0..999).</entry></row>
392
 
<row><entry><literal>zzz</literal></entry><entry>The milliseconds with leading zeroes (000..999).</entry></row>
393
 
<row><entry><literal>AP</literal></entry><entry>Use AM/PM display. AP will be replaced by either "AM" or "PM".</entry></row>
394
 
<row><entry><literal>ap</literal></entry><entry>Use am/pm display. ap will be replaced by either "am" or "pm".</entry></row>
395
 
</tbody>
396
 
</tgroup>
397
 
</informaltable>
398
 
 
399
 
</para></listitem>
400
 
</varlistentry>
401
 
 
402
 
<varlistentry>
403
 
<term><cmdsynopsis><command>char</command><arg choice="req">STRING identifier</arg></cmdsynopsis></term>
404
 
<listitem>
405
 
<para>This command allows you to insert literal characters by their
406
 
numerical identifier, in decimal, octal or hexadecimal form.
407
 
To use it launch the Editing Command dialog and type <userinput>char:
408
 
[number]</userinput> in the entry box, then hit
409
 
<guibutton>OK</guibutton>.</para>
410
 
 
411
 
<example>
412
 
<title><command>char</command> examples</title>
413
 
 
414
 
<para>Input: <userinput>char:234</userinput></para>
415
 
<para>Output: <computeroutput>&#234;</computeroutput></para>
416
 
<para>Input: <userinput>char:0x1234</userinput></para>
417
 
<para>Output: <computeroutput>&#x1234;</computeroutput></para>
418
 
</example>
419
 
 
420
 
</listitem>
421
 
</varlistentry>
422
 
 
423
 
<varlistentry>
424
 
<term>
425
 
<indexterm><primary>replace, sed style</primary>
426
 
<secondary>search, sed style</secondary></indexterm>
427
 
<command>s///[ig]</command> <command>%s///[ig]</command></term>
428
 
 
429
 
<listitem>
430
 
<para>This command does a sed-like search/replace operation on the
431
 
current line, or on the whole file (<command>%s///</command>).</para>
432
 
 
433
 
<para>In short, the text is searched for text matching the
434
 
<emphasis>search pattern</emphasis>, the regular expression between
435
 
the first and the second slash, and when a match is found, the
436
 
matching part of the text is replaced with the expression between the
437
 
second and last slash. Parentheses in the search pattern
438
 
create <emphasis>back references</emphasis>, that is the command
439
 
remembers which part of the string matched in the parentheses; these
440
 
strings can be reused in the replace pattern, referred to as
441
 
<userinput>\1</userinput> for the first set of parentheses,
442
 
<userinput>\2</userinput> for the second and so on.</para>
443
 
 
444
 
<para>To search for a literal <literal>(</literal> or
445
 
<literal>)</literal>, you need to <emphasis>escape</emphasis> it using
446
 
a backslash character: <userinput>\(\)</userinput></para>
447
 
 
448
 
<para>If you put an <userinput>i</userinput> at the end of the
449
 
expression, the matching will be case insensitive. If you put a
450
 
<userinput>g</userinput> at the end, all occurrences of the pattern will be
451
 
replaced, otherwise only the first occurrence is replaced.</para>
452
 
 
453
 
<example>
454
 
 
455
 
<title>Replacing text in the current line</title>
456
 
 
457
 
<para>Your friendly compiler just stopped, telling you that the class
458
 
<classname>myClass</classname> mentioned in line 3902 in your source file
459
 
is not defined.</para>
460
 
 
461
 
<para>&quot;Buckle!&quot; you think, it is of course
462
 
<classname>MyClass</classname>. You go to line 3902, and instead of trying
463
 
to find the word in the text, you launch the Editing Command Dialog,
464
 
enter <userinput>s/myclass/MyClass/i</userinput>, hit the
465
 
<guibutton>OK</guibutton> button, save the file and compile &ndash;
466
 
successfully without the error.</para>
467
 
 
468
 
</example>
469
 
 
470
 
<example>
471
 
<title>Replacing text in the whole file</title>
472
 
 
473
 
<para>Imagine that you have a file, in which you mention a <quote>Miss
474
 
Jensen</quote> several times, when someone comes in and tells you that
475
 
she just got married to <quote>Mr Jones</quote>. You want, of course,
476
 
to replace each and every occurrence of <quote>Miss Jensen</quote>
477
 
with <quote>Ms Jones</quote>.</para>
478
 
 
479
 
<para>Enter the command line and issue the command
480
 
<userinput>%s/Miss Jensen/Ms Jones/</userinput> and hit return, you
481
 
are done.</para>
482
 
 
483
 
</example>
484
 
 
485
 
<example>
486
 
<title>A More Advanced Example</title>
487
 
 
488
 
<para>This example makes use of <emphasis>back references</emphasis>
489
 
as well as a <emphasis>character class</emphasis> (if you do not know what
490
 
that is, please refer to the related documentation mentioned
491
 
below).</para>
492
 
 
493
 
<para>Suppose you have the following line:
494
 
 
495
 
<programlisting>void MyClass::DoStringOps( String      &amp;foo, String &amp;bar, String *p, int  &amp;a, int &amp;b )</programlisting>
496
 
</para>
497
 
<para>Now you realize that this is not nice code, and decide that you
498
 
want to use the <constant>const</constant> keyword for all
499
 
<quote>address of</quote> arguments, those characterized by the &amp;
500
 
operator in front of the argument name. You would also like to
501
 
simplify the white space, so that there is only 1 whitespace character
502
 
between each word.</para>
503
 
 
504
 
<para>Launch the Editing Command Dialog, and enter:
505
 
<userinput>s/\s+(\w+)\s+(&amp;)/ const \1 \2/g</userinput> and hit the
506
 
<guibutton>OK</guibutton> button. The <userinput>g</userinput> at the end of the expression makes
507
 
the regular expression recompile for each match to save the <emphasis>backreferences</emphasis>.</para>
508
 
 
509
 
<para>Output:
510
 
 
511
 
<computeroutput>void MyClass::DoStringOps( const String &amp;foo, const String &amp;bar, String *p, const int &amp;a, const int &amp;b )</computeroutput></para>
512
 
 
513
 
<para>Mission completed! Now, what happened? Well, we looked for some
514
 
white space (<literal>\s+</literal>) followed by one or more
515
 
alphabetic characters (<literal>\w+</literal>) followed by some more
516
 
whitespace (<literal>\s+</literal>) followed by an ampersand, and in
517
 
the process saved the alphabetic chunk and the ampersand for reuse in
518
 
the replace operation. Then we replaced the matching part of our line
519
 
with one whitespace followed by <quote>const</quote> followed by one
520
 
whitespace followed by our saved alphabetical chunk
521
 
(<literal>\1</literal>) followed by one whitespace followed by our
522
 
saved ampersand (<literal>\2</literal>)</para>
523
 
 
524
 
<para>Now in some cases the alphabetical chunk was
525
 
<quote>String</quote>, in some <quote>int</quote>, so using the
526
 
character class <literal>\w</literal> and the <literal>+</literal>
527
 
quantifier proved a valuable asset.</para>
528
 
 
529
 
</example>
530
 
 
531
 
</listitem>
532
 
 
533
 
</varlistentry>
534
 
 
535
 
<varlistentry>
536
 
<term><cmdsynopsis><command>sort</command></cmdsynopsis></term>
537
 
<listitem><para>Sorts the selected text or entire document.</para></listitem>
538
 
</varlistentry>
539
 
 
540
 
<varlistentry>
541
 
<term><cmdsynopsis><command>natsort</command></cmdsynopsis></term>
542
 
<listitem><para>Sort the selected lines or entire document naturally.</para>
543
 
 
544
 
<example>
545
 
<title><command>sort</command> vs. <command>natsort</command></title>
546
 
<para><userinput><command>sort</command>(a10, a1, a2)</userinput> results in
547
 
                            <computeroutput>a1, a10, a2</computeroutput></para>
548
 
<para><userinput><command>natsort</command>(a10, a1, a2)</userinput> results in
549
 
                            <computeroutput>a1, a2, a10</computeroutput></para>
550
 
</example></listitem>
551
 
</varlistentry>
552
 
 
553
 
<varlistentry>
554
 
<term><cmdsynopsis><command>moveLinesDown</command></cmdsynopsis></term>
555
 
<listitem><para>Move selected lines down.</para></listitem>
556
 
</varlistentry>
557
 
 
558
 
<varlistentry>
559
 
<term><cmdsynopsis><command>moveLinesUp</command></cmdsynopsis></term>
560
 
<listitem><para>Move selected lines up.</para></listitem>
561
 
</varlistentry>
562
 
 
563
 
<varlistentry>
564
 
<term><cmdsynopsis><command>uniq</command></cmdsynopsis></term>
565
 
<listitem><para>Remove duplicated lines from the selected text or the whole
566
 
document.</para></listitem>
567
 
</varlistentry>
568
 
 
569
 
<varlistentry>
570
 
<term><cmdsynopsis><command>rtrim</command></cmdsynopsis></term>
571
 
<listitem><para>Remove trailing space from the selected text or the whole
572
 
document.</para></listitem>
573
 
</varlistentry>
574
 
 
575
 
<varlistentry>
576
 
<term><cmdsynopsis><command>ltrim</command></cmdsynopsis></term>
577
 
<listitem><para>Remove leading space from the selected text or the whole
578
 
document.</para></listitem>
579
 
</varlistentry>
580
 
 
581
 
<varlistentry>
582
 
<term><cmdsynopsis><command>join</command><arg choice="opt">STRING separator</arg></cmdsynopsis></term>
583
 
<listitem><para>Join selected lines or whole document.  Optionally takes a parameter
584
 
defining a separator, for example:  <userinput><command>join</command> ', '</userinput>
585
 
</para></listitem>
586
 
</varlistentry>
587
 
 
588
 
<varlistentry>
589
 
<term><cmdsynopsis><command>rmblank</command></cmdsynopsis></term>
590
 
<listitem><para>Remove all blank spaces from the selected text or the whole
591
 
document.</para></listitem>
592
 
</varlistentry>
593
 
 
594
 
<varlistentry>
595
 
<term><cmdsynopsis><command>unwrap</command></cmdsynopsis></term>
596
 
<listitem><para>Unwrap the selected text or the whole document.</para></listitem>
597
 
</varlistentry>
598
 
 
599
 
<varlistentry>
600
 
<term><cmdsynopsis><command>each</command><arg choice="req">STRING script</arg></cmdsynopsis></term>
601
 
<listitem><para>Given a JavaScript function as an argument, call that for the list of
602
 
selected lines and replace them with the return value of that callback.</para>
603
 
 
604
 
<example>
605
 
<title>Join selected lines</title>
606
 
<para><userinput><command>each</command> 'function(lines){return lines.join(", ")}'
607
 
</userinput></para>
608
 
 
609
 
<para>Or, more briefly:</para>
610
 
<para><userinput><command>each</command> 'lines.join(", ")'</userinput></para>
611
 
</example>
612
 
 
613
 
</listitem>
614
 
</varlistentry>
615
 
 
616
 
 
617
 
 
618
 
<varlistentry>
619
 
<term><cmdsynopsis><command>filter</command><arg choice="req">STRING script</arg></cmdsynopsis></term>
620
 
<listitem><para>Given a JavaScript function as an argument, call that for the list of
621
 
selected lines and remove those where the callback returns false.</para>
622
 
 
623
 
<example>
624
 
<title>Remove blank lines</title>
625
 
<para><userinput><command>filter</command> 'function(1){return 1.length > 0;}'
626
 
</userinput></para>
627
 
 
628
 
<para>Or, more briefly:</para>
629
 
<para><userinput><command>filter</command> 'line.length > 0'</userinput></para>
630
 
</example>
631
 
 
632
 
</listitem>
633
 
</varlistentry>
634
 
 
635
 
<varlistentry>
636
 
<term><cmdsynopsis><command>map</command><arg choice="req">STRING script</arg></cmdsynopsis></term>
637
 
<listitem><para>Given a JavaScript function as an argument, call that for the list of
638
 
selected lines and replace the line with the value of the callback.</para>
639
 
 
640
 
<example>
641
 
<title>Remove blank lines</title>
642
 
<para><userinput><command>map</command> 'function(line){return
643
 
line.replace(/^s+/,"");}'
644
 
</userinput></para>
645
 
 
646
 
<para>Or, more briefly:</para>
647
 
<para><userinput><command>map</command> 'line.replace(/^s+/,"")'</userinput></para>
648
 
</example>
649
 
 
650
 
</listitem>
651
 
</varlistentry>
652
 
 
653
 
<varlistentry>
654
 
<term><cmdsynopsis><command>duplicateLinesUp</command></cmdsynopsis></term>
655
 
<listitem><para>Duplicate the selected lines above the current selection.</para>
656
 
</listitem>
657
 
</varlistentry>
658
 
 
659
 
<varlistentry>
660
 
<term><cmdsynopsis><command>duplicateLinesDown</command></cmdsynopsis></term>
661
 
<listitem><para>Duplicate the selected lines below the current selection.</para>
662
 
</listitem>
663
 
</varlistentry>
664
 
 
665
 
</variablelist>
666
 
 
667
 
</sect3>
668
 
 
669
 
<sect3 id="advanced-editing-tools-commandline-commands-navigation">
670
 
<title>Commands for navigation</title>
671
 
 
672
 
<variablelist>
673
 
 
674
 
<varlistentry>
675
 
<term><cmdsynopsis><command>goto</command><arg choice="req">INT line</arg></cmdsynopsis></term>
676
 
<listitem><para>This command navigates to the specified line.</para></listitem>
677
 
</varlistentry>
678
 
 
679
 
<varlistentry>
680
 
<term><cmdsynopsis><command>grep</command> <arg choice="req">STRING pattern</arg>
681
 
</cmdsynopsis></term>
682
 
<listitem><para>Search the document for the regular expression
683
 
<userinput>pattern</userinput>. For more information, see
684
 
<xref linkend="regular-expressions" /></para>
685
 
</listitem>
686
 
</varlistentry>
687
 
 
688
 
<varlistentry>
689
 
<term><cmdsynopsis><command>find</command><arg choice="req">STRING pattern</arg></cmdsynopsis></term>
690
 
<listitem><para>This command navigates to the first occurrence of
691
 
<userinput>pattern</userinput> according to the configuration. Following
692
 
occurrences can be found using
693
 
<menuchoice><guimenu>Edit</guimenu><guimenuitem>Find Next</guimenuitem></menuchoice>
694
 
(the default shortcut is <keycap>F3</keycap>).</para>
695
 
<para>The find command can be configured by appending a colon followed by one or
696
 
more options, the form is
697
 
<userinput>find:options pattern</userinput>. The
698
 
    following options are supported:</para>
699
 
 
700
 
<variablelist>
701
 
 
702
 
<varlistentry>
703
 
<term><userinput>b</userinput></term>
704
 
<listitem><para>Search backwards.</para></listitem>
705
 
</varlistentry>
706
 
 
707
 
<varlistentry>
708
 
<term><userinput>c</userinput></term>
709
 
<listitem><para>Search from cursor position.</para></listitem>
710
 
</varlistentry>
711
 
 
712
 
<varlistentry>
713
 
<term><userinput>e</userinput></term>
714
 
<listitem><para>Search in the selection only.</para></listitem>
715
 
</varlistentry>
716
 
 
717
 
<varlistentry>
718
 
<term><userinput>r</userinput></term>
719
 
<listitem><para>Do regular expression search. If set, you may use
720
 
<userinput>\N</userinput> where N is a number to represent captures in the
721
 
replacement string.</para></listitem>
722
 
</varlistentry>
723
 
 
724
 
<varlistentry>
725
 
<term><userinput>s</userinput></term>
726
 
<listitem><para>Do case sensitive search.</para></listitem>
727
 
</varlistentry>
728
 
 
729
 
<varlistentry>
730
 
<term><userinput>w</userinput></term>
731
 
<listitem><para>Match whole words only.</para></listitem>
732
 
</varlistentry>
733
 
 
734
 
</variablelist>
735
 
</listitem>
736
 
 
737
 
</varlistentry>
738
 
 
739
 
<varlistentry>
740
 
<term><cmdsynopsis><command>ifind</command><arg choice="req">STRING pattern</arg></cmdsynopsis></term>
741
 
<listitem><para>This command provides <quote>as-you-type</quote> searching. You
742
 
can configure the behavior of the search by appending a colon
743
 
followed by one or more options, like this:
744
 
<userinput>ifind:options pattern</userinput>. Allowed options are
745
 
 
746
 
<variablelist>
747
 
<varlistentry>
748
 
<term><userinput>b</userinput></term>
749
 
<listitem><para>Search backwards.</para></listitem>
750
 
</varlistentry>
751
 
 
752
 
<varlistentry>
753
 
<term><userinput>r</userinput></term>
754
 
<listitem><para>Do regular expression search.</para></listitem>
755
 
</varlistentry>
756
 
 
757
 
<varlistentry>
758
 
<term><userinput>s</userinput></term>
759
 
<listitem><para>Do case sensitive search.</para></listitem>
760
 
</varlistentry>
761
 
 
762
 
<varlistentry>
763
 
<term><userinput>c</userinput></term>
764
 
<listitem><para>Search from cursor position.</para></listitem>
765
 
</varlistentry>
766
 
 
767
 
</variablelist>
768
 
</para></listitem>
769
 
</varlistentry>
770
 
 
771
 
</variablelist>
772
 
 
773
 
</sect3>
774
 
 
775
 
 
776
 
<sect3 id="advanced-editing-tools-commandline-commands-basic">
777
 
<title>Commands for Basic Editor Functions (These depend on the application the editor component is used in)</title>
778
 
 
779
 
<variablelist>
780
 
 
781
 
<varlistentry>
782
 
<term><cmdsynopsis><command>w</command></cmdsynopsis></term>
783
 
<listitem><para>Save the current document.</para></listitem>
784
 
</varlistentry>
785
 
 
786
 
<varlistentry>
787
 
<term><cmdsynopsis><command>wa</command></cmdsynopsis></term>
788
 
<listitem><para>Save all currently open documents.</para></listitem>
789
 
</varlistentry>
790
 
 
791
 
<varlistentry>
792
 
<term><cmdsynopsis><command>q</command></cmdsynopsis></term>
793
 
<listitem><para>Close the current document.</para></listitem>
794
 
</varlistentry>
795
 
 
796
 
<varlistentry>
797
 
<term><cmdsynopsis><command>qa</command></cmdsynopsis></term>
798
 
<listitem><para>Close all open documents.</para></listitem>
799
 
</varlistentry>
800
 
 
801
 
<varlistentry>
802
 
<term><cmdsynopsis><command>wq</command></cmdsynopsis></term>
803
 
<listitem><para>Save and close the current document.</para></listitem>
804
 
</varlistentry>
805
 
 
806
 
<varlistentry>
807
 
<term><cmdsynopsis><command>wqa</command></cmdsynopsis></term>
808
 
<listitem><para>Save and close all currently open documents.</para></listitem>
809
 
</varlistentry>
810
 
 
811
 
<varlistentry>
812
 
<term><cmdsynopsis><command>x</command></cmdsynopsis></term>
813
 
<listitem><para>Save and close the current document only if it has changed.
814
 
</para></listitem>
815
 
</varlistentry>
816
 
 
817
 
<varlistentry>
818
 
<term><cmdsynopsis><command>x</command></cmdsynopsis></term>
819
 
<listitem><para>Save and close all currently open documents only if they have
820
 
changed.</para></listitem>
821
 
</varlistentry>
822
 
 
823
 
<varlistentry>
824
 
<term><cmdsynopsis><command>bp</command></cmdsynopsis></term>
825
 
<listitem><para>Go to the previous document in the documents list.
826
 
</para></listitem>
827
 
</varlistentry>
828
 
 
829
 
<varlistentry>
830
 
<term><cmdsynopsis><command>bn</command></cmdsynopsis></term>
831
 
<listitem><para>Go to the next document in the documents list.
832
 
</para></listitem>
833
 
</varlistentry>
834
 
 
835
 
<varlistentry>
836
 
<term><cmdsynopsis><command>new</command></cmdsynopsis></term>
837
 
<listitem><para>Open a new document in horizontal split view.
838
 
</para></listitem>
839
 
</varlistentry>
840
 
 
841
 
<varlistentry>
842
 
<term><cmdsynopsis><command>vnew</command></cmdsynopsis></term>
843
 
<listitem><para>Open a new document in vertical split view.
844
 
</para></listitem>
845
 
</varlistentry>
846
 
 
847
 
<varlistentry>
848
 
<term><cmdsynopsis><command>e</command></cmdsynopsis></term>
849
 
<listitem><para>Reload the current document if it has changed on disk.
850
 
</para></listitem>
851
 
</varlistentry>
852
 
 
853
 
<varlistentry>
854
 
<term><cmdsynopsis><command>enew</command></cmdsynopsis></term>
855
 
<listitem><para>Edit a new document.
856
 
</para></listitem>
857
 
</varlistentry>
858
 
 
859
 
<varlistentry>
860
 
<term><cmdsynopsis><command>print</command></cmdsynopsis></term>
861
 
<listitem><para>Open the Print dialog to print the current document.
862
 
</para></listitem>
863
 
</varlistentry>
864
 
 
865
 
</variablelist>
866
 
 
867
 
</sect3>
868
 
 
869
 
 
870
 
</sect2>
871
 
 
872
 
</sect1>
873
 
 
874
 
<sect1 id="advanced-editing-tools-code-folding">
875
 
<title>Using Code Folding</title>
876
 
 
877
 
<para>Code folding allows you to hide parts of a document in the editor, making
878
 
it easier to overview large documents. In &kappname; the foldable regions are
879
 
calculated using rules defined in the syntax highlight definitions, and
880
 
therefore it is only available in some formats - typically program source code,
881
 
XML markup and similar. Most highlight definitions supporting code folding
882
 
also lets you manually define foldable regions, typically using the
883
 
<userinput>BEGIN</userinput> and <userinput>END</userinput> keywords.</para>
884
 
 
885
 
<para>To use the code folding feature, activate the folding markers using
886
 
<menuchoice><guimenu>View</guimenu><guimenuitem>Show Folding
887
 
Markers</guimenuitem></menuchoice> menu item if they are not already visible.
888
 
The Folding Markers Pane on the left side of the screen displays a graphical
889
 
view of the foldable regions, with triangle symbols to indicate the possible operation
890
 
on a given region: a top down triangle means that the region is expanded, clicking it will
891
 
collapse the region and a right pointing triangle will be displayed instead.</para>
892
 
<!--FIXME change Three to Four when Unfold Toplevel Nodes action is back-->
893
 
<para>Three commands are provided to manipulate the state of folding regions,
894
 
 see the <link linkend="view-code-folding">menu documentation</link>.
895
 
 </para>
896
 
 
897
 
<para>The folded lines are remembered when a file is closed, so when you reopen
898
 
the file the folded nodes will still be folded. This applies to reload operations
899
 
as well.</para>
900
 
 
901
 
<para>If you do not want to use the code folding feature, you can disable
902
 
the <guilabel>Show folding markers (if available)</guilabel> option in the
903
 
<link linkend="appearance">Appearance</link> page of the editor
904
 
configuration.</para>
905
 
 
906
 
</sect1>
907
 
 
908
 
</chapter>