ViewVC logotype

Contents of /climacs/Doc/climacs-user.texi

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.14 - (hide annotations)
Wed Sep 6 17:42:08 2006 UTC (7 years, 7 months ago) by thenriksen
Branch: MAIN
Changes since 1.13: +89 -0 lines
File MIME type: application/x-texinfo
Load rectangle.lisp before misc-commands.lisp to silence warning.
1 rstrandh 1.1 \input texinfo @c -*-texinfo-*-
2     @c %**start of header
3     @setfilename climacs-user
4     @settitle Climacs User Manual
5     @c %**end of header
7     @copying
8     The Climacs User manual
10     Copyright @copyright{} 2005 Robert Strandh.
12     @end copying
14     @titlepage
15     @title Climacs User Manual
16     @sp 2
17     @author Robert Strandh
19     @page
20     @vskip 0pt plus 1filll
21     @insertcopying
23     @end titlepage
25     @contents
27     @macro climacs{}
28     Climacs
29     @end macro
31     @macro cl{}
32     Common Lisp
33     @end macro
35     @node Top
36     @top
38     @menu
39     * Introduction::
40     * Conventions::
41     * Concepts::
42     * Basic editing commands::
43     * Different editing modes::
44     * Kill ring::
45 thenriksen 1.14 * Groups::
46 rstrandh 1.3 * Advanced editing commands::
47 rstrandh 1.4 * Getting help::
48 rstrandh 1.7 * Proposal for new buffer/pane relations::
49 rstrandh 1.1 * Key Index::
50     * Concept Index::
51     @end menu
54     @node Introduction
55     @chapter Introduction
57     @climacs{} is a text editor in the Emacs family. However, @climacs{}
58     differs from Emacs in various ways.
60     For one thing, @climacs{} is written in Common Lisp rather than Emacs
61     Lisp. Common Lisp is a much more complete language than Emacs Lisp
62     with essential features such as packages, classes, etc.
64     Moreover, @climacs{} uses the Common-Lisp Interface Manager (CLIM) as its
65     substrate for managing everything that has to do with user
66     interaction, including event handling, text rendering, and
67     multi-windowing (called panes in CLIM terminology).
69     Also, since @climacs{} uses CLIM, there is no need for @climacs{} itself to
70     serve as the basis for other applications such as news readers, mail
71     readers, directory editors, web browsers, etc. the way it is done with
72     Emacs. Instead, such applications are better written as stand-alone
73     CLIM applications that can then communicate with @climacs{} using CLIM
74     and Common Lisp as the common substrate.
76     The main purpose of @climacs{} is not to replace Emacs. Instead, it is
77     primarily intended as a text editor for Common Lisp developers.
78     Notice that this is not the same as a text editor for Common Lisp
79     @emph{development}, since Common Lisp developers might need other
80     features such as editing HTML or spell checking, etc., not directly
81     related to Common Lisp development.
83     @node Conventions
84     @chapter Conventions
86     Many @climacs{} commands are invoked by typing a sequence of
87     keystrokes. A complete sequence of keystrokes invokes a
88     @climacs{} @emph{command} which has a @emph{name}. Sometimes it is
89     useful to know that name, even though the command is usually invoked
90     by typing the key sequence. For that reason, in this manual we often
91     give the corresponding command name together with the key sequence to
92     invoke it.
94     @node Concepts
95     @chapter Concepts
97     In order to use @climacs{} effectively, you need to know some concepts
98     that are used by it, and referred to in this manual.
100     @menu
101     * Buffer::
102     * Window and pane::
103     * Mark and point::
104     * Key sequence::
105     @end menu
107     @node Buffer
108     @section Buffer
110     A @climacs{} @emph{buffer}
111     @cindex buffer
112 thenriksen 1.12 is a named, editable sequence of arbitrary @cl{} objects. If the buffer
113 rstrandh 1.1 contains text, most of those objects will be @emph{Unicode
114 thenriksen 1.12 characters}. When editing a file, the contents of the file will be
115     loaded into a buffer with a name corresponding to the name of the file
116     (creating the buffer in the process), and all editing operations will be
117     performed on the buffer. Upon saving, the contents of the buffer will be
118     written to the file associated with it. @xref{Editing the contents of a
119     file}. A buffer does not necessarily have a file associated with it, for
120     example, the @emph{*scratch*} buffer automatically created upon
121     @climacs{} startup is not associated with any file.
122 rstrandh 1.1 @cindex character
123     @cindex Unicode
125     @node Window and pane
126     @section Window and pane
128     A @climacs{} buffer may or may not be on display. If it is, it is on
129 thenriksen 1.12 display in a @emph{pane}
130 rstrandh 1.1 @cindex pane
131     or a @emph{window}.
132     @cindex window
133 thenriksen 1.12 A pane does not necessarily contain a buffer, it may just be a pane
134     containing output from Climacs. These panes are known as @emph{typeout
135     panes},
136     @cindex typeout pane
137     and their contents are lost when they are destroyed.
138 rstrandh 1.1
139     @node Mark and point
140     @section Mark and point
142     Positions into a @climacs{} buffer are determined by @emph{marks}
143     @cindex mark
144     which can be either @emph{left sticky},
145     @cindex left sticky
146     meaning that if an object is inserted where such a mark is, it ends up
147     @emph{to the left} of the newly inserted object, or @emph{right
148     sticky},
149     @cindex right sticky
150     meaning that if an object is inserted where such a mark is, it ends up
151     @emph{to the right} of the newly inserted object.
153     A distinguished mark that is associated with each @climacs{} pane is
154     called the @emph{point}.
155     @cindex point
156     There is a point associated with each window. Each of several windows
157     that display the same buffer has its own point. In addition, a buffer
158     that is not on display has a point that is taken over by the first
159     window that displays the buffer. Points are right-sticky marks, even
160     when a language such as Arabic is edited, simply because by
161     convention, the @climacs{} buffer is considered as being organized
162 rstrandh 1.6 from left to right. It is a question of @emph{rendering} as to whether
163 rstrandh 1.1 the objects in the buffer are actually displayed from left to right,
164     from right to left, or in any other appropriate order.
166     @node Key sequence
167     @section Key sequence
169     Typically, @climacs{} is operated by @emph{key sequences}
170     @cindex key sequence
171     issued by the user. A key sequence is a sequence of key strokes,
172     where a key stroke can be a simple character such as @kbd{f} or
173     @kbd{&}, or a key with one or more @emph{modifiers}
174     @cindex modifier
175     such as @key{Control}, @key{Shift}, @key{Meta}, etc.
177     Some key sequences result in the execution of a @climacs{}
178     @emph{command}.
179     @cindex command
180     Such a key sequence is called a @emph{complete key sequence}
181 rstrandh 1.6 @cindex complete key sequence
182     or an @emph{order}.
183 rstrandh 1.1 @cindex order
185     @node Basic editing commands
186     @chapter Basic editing commands
188     The basic editing commands of @climacs{} are identical or at least
189     similar to the corresponding Emacs commands. This is deliberate. We
190     do not believe in introducing gratuitous differences where such
191     differences have little or no importance. A typical Emacs user
192     should therefore feel quite comfortable with the basic editing
193     commands of @climacs{}.
195     @menu
196 rstrandh 1.5 * Entering and exiting Climacs::
197 rstrandh 1.1 * Numeric arguments::
198     * Entering and deleting text::
199     * Moving around::
200     * Extended commands::
201 rstrandh 1.2 * Editing the contents of a file::
202 rstrandh 1.1 @end menu
204 rstrandh 1.5 @node Entering and exiting Climacs
205     @section Entering and exiting Climacs
206 rstrandh 1.1
207     The typical way of entering @climacs{} is to type a @cl{}
208     @emph{expression} at the prompt of a @cl{} @emph{listener} such as:
210     @lisp
211 thenriksen 1.13 CL-USER> (climacs:climacs)
212     @end lisp
214     @climacs{} also has an option to start in a new thread:
216     @lisp
217     CL-USER> (climacs:climacs :new-process t)
218 rstrandh 1.1 @end lisp
220     You exit from @climacs{} by typing @kbd{C-x C-c} (@command{Quit}).
221     @kindex C-x C-c
222     If you have buffers
223     associated with files that have not been saved to their respective
224     files, @climacs{} will ask whether you would like those buffers
225     saved. In addition, if you answer no to any of those questions, you
226     will be asked to confirm that you want to quit @climacs{} anyway. The
227     reason for this pestering on the part of @climacs{} is that currently
228 rstrandh 1.6 when you quit @climacs{}, the buffer contents are lost.
229 rstrandh 1.1
230     @node Numeric arguments
231     @section Numeric arguments
233     Many @climacs{} commands allow the use of a @emph{numeric argument}.
234     @cindex numeric argument
235     A numeric argument is used as a prefix to a @climacs{} command, and
236     modifies the behavior of that command in some useful way which varies
237     from command to command.
239     Typically, a numeric argument prefix makes the command repeat its
240     action a number of times indicated by the numeric argument prefix.
241     For instance, the command @command{Delete Object}, usually associated
242     with the order @kbd{C-d}, normally deletes a single object from the
243     buffer. However, if given a numeric argument, it deletes that many
244     objects.
246     Other commands modify their behavior according to whether a numeric
247     argument has been given, but do not take into account the specific
248     numeric value indicated. For instance, the command @command{Delete
249     Horizontal Space}, when given no numeric argument, deletes whitespace
250     both before and after point. With a numeric argument, it deletes only
251     whitespace @emph{before} point.
253     Yet other commands may both modify what they do and repeat according
254     to the numeric value of the argument. For instance, the command
255     @command{Kill Line}, when given no numeric argument, kills to the end
256     of the line if point is not already at the end of the line, but does
257     not kill the newline character at the end of the line and kills the
258     newline character if point is at the end of a line. However, if given
259     a numeric argument, @command{Kill Line} kills that many lines.
261     There are two ways of giving a numeric argument to a @climacs{}
262     command. One way is to first type @kbd{C-u},
263     @kindex C-u
264     then a sequence of
265     decimal digits, and finally the order that invokes the command. For
266     instance, to delete the next 15 objects after point, you could type
267     @kbd{C-u 1 5 C-d}. The other way is to hold down the @key{Meta} key
268     (usually the one marked @key{Alt}) while typing the decimal digits, as
269     in @kbd{M-1 M-5 C-d}.
271     Some commands accept negative numeric arguments. In that case, start
272     the sequence with the minus sign as in @kbd{C-u - 1 5 C-d}, which in
273     this case will delete buffer objects @emph{before} the point rather
274     than after.
276     @node Entering and deleting text
277     @section Entering and deleting text
279     @menu
280     * Entering text::
281     * Deleting by objects::
282     * Deleting by words::
283     * Deleting by lines::
284     @end menu
286     @node Entering text
287     @subsection Entering text
289     In contrast to other text editors such as VI, @climacs{} does not have
290     a specific @emph{insert mode}. Instead, @climacs{} is always in
291     insert mode, in that characters that are typed on the keyboard
292     immediately get inserted at the @emph{point}.
294     @node Deleting by objects
295     @subsection Deleting by objects
297     To erase objects that have been inserted, you can use the
298     @key{Backspace} (@command{Backward Delete Object}
299     key, which deletes the object immediately to the left of the point.
300     To delete an object @emph{to the right} of the point, use the
301     @kbd{C-d}
302     @kindex C-d
303     (@command{Delete Object}) order. When used with a numeric
304     argument, these commands delete that many objects.
306     @node Deleting by words
307     @subsection Deleting by words
309     It is also possible to delete larger chunks of buffer contents. The
310     order @kbd{M-d}
311     @kindex M-d
312 rstrandh 1.2 (@command{Kill Word}) is used to delete the @emph{word}
313     @cindex word
314 rstrandh 1.1 @emph{following} point. If point is not at the beginning of a word,
315     then the part of the word that follows point is deleted. The order
316     @kbd{M-@key{Backspace}}
317     @kindex M-@key{Backspace}
318     (@command{Backward Kill Word}) is used to
319     delete the word @emph{preceding} point. If point is not at the end of
320     a word, then the part of the word that precedes point is deleted.
321     When used with a numeric argument, these commands delete that many
322     words. Since these command names contain the word @emph{kill}, they
323     use the kill-ring (@pxref{kill-ring}).
325     @node Deleting by lines
326     @subsection Deleting by lines
328     @climacs{} allows you to delete buffer objects one or more lines at a
329     time. The order @kbd{C-k}
330     @kindex C-k
331     (@command{Kill Line}) lets you do this. When point is @emph{not} at
332     the end of a line, then this command kills the buffer contents from
333     point up to, but not including the following newline object. When
334     instead point @emph{is} at the end of a line, only the following
335     newline object is removed.
337     When used with a numeric argument, this command is not simply repeated
338     that many times. Instead, the number of lines indicated by the
339 rstrandh 1.6 numeric argument are removed.
340 rstrandh 1.1
341     Because this command name contains the word @emph{kill} it saves the
342     deleted objects on the @emph{kill ring} (@pxref{kill-ring}).
344     @node Moving around
345     @section Moving around
347     @menu
348     * Moving by objects::
349     * Moving by words::
350     * Moving by lines::
351     @end menu
353     @node Moving by objects
354     @subsection Moving by objects
356     @climacs{} allows you to move around in the buffer in various ways.
357     The most frequent way of moving around is by one buffer position at a
358     time.
360     The order @kbd{C-f}
361     @kindex C-f
362     (@command{Forward Object}) allows you to
363     advance the position of point by one position. If given a numeric
364     argument, it advances by that many positions. The @command{Forward
365     Object} command is also associated with the @emph{right-arrow key}.
367     The order @kbd{C-b}
368     @kindex C-b
369     (@command{Backward Object}) allows you to move the
370     position of point backward by one position. If given a numeric
371     argument, it moves back by that many positions. The @command{Backward
372     Object} command is also associated with the @emph{left-arrow key}.
374     @node Moving by words
375     @subsection Moving by words
377 rstrandh 1.6 @climacs{} will allow you to move around by larger units than
378 rstrandh 1.2 objects.
380     The order @kbd{M-f}
381     @kindex M-f
382     (@command{Forward Word}) lets you move forward over the @emph{word}
383     @cindex word
384     following point. With a numeric argument, this command moves point
385     forward that many words.
387     The order @kbd{M-b}
388     @kindex M-b
389     (@command{Backward Word}) lets you move backward over the @emph{word}
390     @cindex word
391     preceding point. With a numeric argument, this command moves point
392     backward that many words.
394     Notice the analogy between the commands for moving by objects
395     (@kbd{C-f}, @kbd{C-b}) and those for moving by words (@kbd{M-f},
396     @kbd{M-b}).
398 rstrandh 1.1 @node Moving by lines
399     @subsection Moving by lines
401     @climacs{} has commands to move by one or several @emph{lines} at a
402     time.
404     The order @kbd{C-p}
405     @kindex C-p
406     (@command{Previous Line}) allows you to
407     move point @emph{up} to the previous line. If given a numeric
408     argument, it moves up by that many lines. The command
409     @command{Previous Line} is also associated with the @emph{up-arrow
410     key}.
412     The order @kbd{C-n}
413     @kindex C-n
414     (@command{Next Line}) allows you to
415     move point @emph{down} to the next line. If given a numeric
416     argument, it moves down by that many lines. The command
417     @command{Next Line} is also associated with the @emph{down-arrow
418     key}.
420 rstrandh 1.6 When you move by lines, @climacs{} tries to be smart about which
421 rstrandh 1.1 @emph{column} point ends up in, in the following way: when a sequence
422     of commands that move by lines is given, the initial column of point
423     is remembered (this is called the @emph{goal column}). @climacs{}
424     then tries to position point in that column of the target line. If
425     the target line has fewer than that many columns, point is positioned
426     at the end of the target line. The goal column is discarded when the
427     sequence of commands is interrupted by some unrelated command.
429     @node Extended commands
430     @section Extended commands
432     In order to make editing as efficient as possible, many @climacs{}
433     commands can be invoked by key sequences. It is, however, possible to
434     invoke most @climacs{} commands by using the order @kbd{M-x} which
435     invokes the command @command{Extended Command} which lets you type the
436     @emph{name} of the command in the minibuffer at the prompt.
437     In general, you do not have to type the full name of the command,
438     because @climacs{} uses CLIM's completion mechanism so that you can
439     complete the name by typing some prefix and then use the @key{TAB} key
440     to complete.
442     Some @climacs{} commands @emph{must} be invoked through the use of
443     @command{Extended Command}. The reason for this is that key sequences
444     are a precious resource, and for rarely-used commands, it is better
445     not to waste a key sequence.
446 rstrandh 1.2
447     @node Editing the contents of a file
448     @section Editing the contents of a file
450     Transfering the contents of a text file into a @climacs{} buffer is
451     referred to as @emph{finding} the file.
452     @cindex finding a file
454     There are two ways of transfering the contents of a buffer to a file.
455     One is to @emph{save} the buffer, which means to transfer the contents
456     to the file that is already associated with the buffer. The other is
457     to @emph{write} the buffer, which means to transfer the contents to a
458     different file than that associated with the buffer, or to write the
459     contents of a buffer that has no associated file to some file.
461     @menu
462     * Finding a file:: Moving text from a file to a @climacs{} buffer
463     * Saving a buffer:: Moving text from a buffer to the associated file
464     * Writing a buffer:: Moving text from a buffer to a different file
465     @end menu
467     @node Finding a file
468     @subsection Finding a file
470     To find a file, use the order @kbd{C-x C-f}
471     @kindex C-x C-f
472     (@command{Find File}).
474     @climacs{} will prompt for the name of a file. For typing the file
475     name, you can use @emph{completion} (using the @key{TAB} key), or you
476     can use the right mouse button to get a list of all the files that
477     match the prefix you typed.
479     The result of finding a file is that a @emph{buffer} will be created
480     that has the name of the file, and the file will be associated with
481 rstrandh 1.6 that buffer when the content is saved.
482 rstrandh 1.2
483     @node Saving a buffer
484     @subsection Saving a buffer
486     To save a buffer, use the order @kbd{C-x C-s}
487     @kindex C-x C-s
488     (@command{Save Buffer}).
489     The contents of the buffer will be transfered to the file associated
490     with the buffer if there is one. If the buffer has no file name
491     associated with it, then this command behaves just like @command{Write
492     Buffer} (@pxref{write-buffer}).
494     @node Writing a buffer
495     @subsection Writing a buffer
496     @anchor{write-buffer}
498     To write a buffer to a file, use the order @kbd{C-x C-w}
499     @kindex C-x C-w
500     (@command{Write Buffer}). @climacs{} will prompt for the name of a
501     file to save the buffer contents in. Completion (by using the
502     @key{TAB} key, or by using the right mouse button) can be used if the
503     name is that of an existing file.
504 rstrandh 1.1
505     @node Different editing modes
506     @chapter Different editing modes
508     @menu
509     * Overwrite mode::
510     @end menu
512     @node Overwrite mode
513     @section Overwrite mode
515     Normally, typing ordinary characters to @climacs{} results in these
516     characters being @emph{inserted} at point. Sometimes, however, it is
517     useful to treat a line of objects as being of @emph{fixed length}, and
518 rstrandh 1.6 have @climacs{} @emph{replace} objects as new ones are being typed.
519 rstrandh 1.1
520     This is exactly the purpose of @climacs{} @emph{overwrite mode}. This
521     mode alters the insert commands so that the object after point is
522     first deleted.
524     You can toggle between the normal mode of operation and overwrite mode
525     by using the @key{Insert}
526     @kindex @key{Insert}
527     (@command{Toggle Overwrite Mode}) key.
529     @node Kill ring
530     @chapter Kill ring
531     @anchor{kill-ring}
533     Many @climacs{} commands that remove objects from a buffer save these
534     objects on a global @emph{kill ring}.
535     @cindex kill ring
537 thenriksen 1.14 @node Groups
538     @chapter Groups
540     @menu
541     * The group metaphor::
542     * Group commands::
543     @end menu
545     @node The group metaphor
546     @section The group metaphor
548     @climacs{} supports a useful and powerful concept called @emph{groups}.
549     @cindex group
550     Groups are conceptually just lists of buffers or files, and when used in
551     conjunction with a command, means that the command operates on all
552     buffers or files designated by the group. For example, a
553     string-replaceable command might perform string-replacement in several
554     buffers, and not just the current one. A command that supports
555     operations on multiple files or buffers at a time, via groups, is called
556     a @emph{group-aware command}.
557     @cindex group-aware command.
558     However, a group is not limited to designating a simple list of static
559     elements, the exact elements designated by a group may depend on the
560     context in which a group-using command is invoked - for example, a group
561     may designate ``all files in the same directory as the current
562     buffer''. In this case, the specific files designated by the group can
563     change if the user switches to another buffer. Every group has a unique
564     name and all references to the group are performed with this name as the
565     key.
567     At all times, Climacs may have an @emph{active group}.
568     @cindex active group
569     The active group is used to control the scope of effect of group-aware
570     commands - when such a command is executed, it will look at the active
571     group to get a list of files and buffers, and perform its operations on
572     all elements in the group. The exact behavior of commands with respect
573     to groups is dependent on the command itself, though. The act of setting
574     the active group is called @emph{selecting a group},
575     @cindex selecting a group
576     specifically, selecting the group that is set as the active group. It is
577     also possible to deselect the active group, in which case most
578     group-aware commands will simply perform their operations on the current
579     buffer.
581     Specifically, there are two different kind of groups - @emph{specific
582     groups}
583     @cindex specific groups
584     and @emph{persistent groups}.
585     @cindex persistent groups
586     Specific groups can be defined by the user through the command
587     interface, @pxref{Group commands}. They are simple lists of buffers or
588     files, and if a buffer named in a group is killed, it will be removed
589     from the group. Creating a buffer with the same name, or the same file,
590     will not result in the buffer being re-added to the group. Specific
591     groups are also lost when @climacs{} is terminated. Persistent groups,
592     on the other hand, are usually pre-defined groups with more complex
593     behavior. Their exact list of designated files and buffers is usually
594     context-dependent and not calculated until they are needed. It is not
595     currently possible to define persistent groups through the command
596     interface, though some persistent groups support user-defined filters
597     and options. When a persistent group is selected as the active group, it
598     may query the user for values - for example, a persistent group
599     designating all files in a given directory, may ask the user for a
600     directory when it is selected.
602     @node Group commands
603     @section Group commands
605     Specific groups can be defined by using the order @kbd{C-x g d}
606     @kindex C-x g d
607     (@command{Define Group}). You will be queried for a name for the group
608     and a list of buffers, and a group with the specified name and buffers
609     will be created and selected as the active group. Alternatively, you can
610     use the order @kbd{C-x g f}
611     @kindex C-x g f
612     (@command{Define File Group}, which will query for files instead of
613     buffers. If you wish to select an already existing group (persistent or
614     specific) as the active group, you can use the order @kbd{C-x g s}.
615     @kindex C-x g s
616     You can deselect the active group with the order @kbd{C-x g u}
617     @kindex C-x g u
618     (@command{Deselect Group}) - this will usually make all group-aware
619     commands operate on just the current buffer. To see which group is the
620     active group, use the order @kbd{C-x g c}
621     @kindex C-x g c
622     (@command{Current Group}), and to see the buffers and files designated
623     by the active group, use @kbd{C-x g l} (@command{List Group Contents}).
625 rstrandh 1.3 @node Advanced editing commands
626     @chapter Advanced editing commands
628     @menu
629     * Keyboard macros::
630     * Searching and replacing::
631     @end menu
633     @node Keyboard macros
634     @section Keyboard macros
636     Sometimes, it is useful to be able to repeat a sequence of keystrokes
637 rstrandh 1.6 several times. @climacs{} allows you to do this through a feature
638 rstrandh 1.3 called @emph{keyboard macros}.
639     @cindex keyboard macro
640     @climacs{} does this by @emph{recording} whatever the user types on
641 rstrandh 1.6 the keyboard, and then making it possibly to @emph{replay} the
642 rstrandh 1.3 recorded sequence.
644     To start recording a sequence of keystrokes, use the order @kbd{C-x (}
645     @kindex C-x (
646     (@command{Start Kbd Macro}). You will see the word @samp{Def}
647     appearing on the mode line, indicating that a keyboard macro is being
648     defined. As long as recording is in effect, every keystroke will be
649     saved for later use.
651     To stop recording a sequence of keystrokes, use the order @kbd{C-x )}
652     @kindex C-x )
653     (@command{End Kbd Macro}). The word @samp{Def} will disappear from
654     the mode line, indicating that keystrokes are no longer being
655     recorded.
657     To replay a previously recorded sequence of keystrokes, use the order
658     @kbd{C-x e}
659     @kindex C-x e
660     (@command{Call Last Kbd Macro}). When used with a numeric argument,
661     this command will repeat the sequence of keystrokes that many times.
663     @node Searching and replacing
664     @section Searching and replacing
665 rstrandh 1.4
666 thenriksen 1.11 @climacs{} has a number of useful searching and replacing commands. The
667 thenriksen 1.10 replacing commands come in two flavors - querying commands and
668     non-querying commands. The former will unconditionally replace all
669     matches, while the latter will query before each replacement. Note that
670     the searching and replacing commands only affect the buffer contents
671     after point.
673     @menu
674     * Simple search::
675     * Incremental search::
676     * The isearch command loop::
677     * Replacing single strings::
678     * Replacing multiple different strings::
679     * The query-replace command loop::
680     @end menu
682     @node Simple search
683     @subsection Simple search
685     The simplest search command is @command{String Search}. It prompts for a
686     string and moves point to after the next occurrence of the
687     string. @command{Reverse String Search} is similar, but searches
688     backwards from point, and puts point before the first occurrence of the
689     string.
691     The commands @command{Word Search} and @command{Reverse Word Search} are
692     very similar to @command{String Search} and @command{Reverse String
693     Search}, but only finds matches that are whole words.
695     The commands @command{Regex Search Forward} and @command{Regex Search
696     Backward} are similar to @command{String Search} and @command{Reverse
697     Word Search}, but do not search for plain strings. Instead, they ask the
698     user to enter a regular expression and attempts to find a match in the
699     buffer.
701     You can use the command @command{How Many} to count the number of
702     matches in the buffer for a given regular expression. When invoked, the
703     command will ask for a regular expression, and then proceed to search
704     through the buffer, counting each match for the regular expression, and
705     finally print the number of matches to the minibuffer.
707     @node Incremental search
708     @subsection Incremental search
710     Incremental search, or @emph{isearch} in common speech, is different
711     from string search, in that point is moved to matches in the buffer,
712     while the search string is being entered, thus, the user receives
713     immediate feedback while entering the search string. Incremental search
714     is controlled through a command loop. @xref{The isearch command loop}.
716     Incremental search can be entered via two orders, @kbd{C-s}
717     @kindex C-s
718     (@command{Isearch Forward}) and @kbd{C-r}
719     @kindex C-r
720     (@command{Isearch Backward}). These commands starts a command loop that
721     searches forwards and backwards by default, respectively. Note that the
722     search direction can be changed from inside the command loop, no matter
723     which of these commands were used to start it.
725     @node The isearch command loop
726     @subsection The isearch command loop
728     The isearch command loop consists of the user typing in characters for
729 thenriksen 1.11 the search string, and @climacs{} moving point ahead to the most immediate
730 thenriksen 1.10 instance of the provided string, while the user is typing. Apart from
731     simply entering text, the user can manipulate the command loop by
732     entering the following orders:
734     @table @kbd
735     @item C-s
736     Move to next match for current search string and set the search
737     direction to forward.
738     @item C-r
739     Move to previous match for current search string and set the search
740     direction to backward.
741     @item C-j
742     Append a ``newline'' character to the current search string.
743     @item C-w
744     Append the word at point to the current search string.
745     @item C-y
746     Append the line at point to the current search string.
747     @item M-y
748     Append the head of the kill ring to the search string.
749     @item @key{Backspace}
750     Delete the last element of the search string. This is not the same as
751     deleting the last character - for example, if the word at point has been
752     appended to the search string via @kbd{C-w}, this order will delete the
753     entire word, not just the last character of the word.
754     @item @key{Newline}
755     Exit the isearch command loop.
756     @end table
758     @node Replacing single strings
759     @subsection Replacing single strings
761     The basic string-replacement command can be accessed through the order
762     @kbd{C-x e}
763     @kindex C-x e
764     (@command{Replace String}). This command will prompt for two strings,
765     and replace all instances of the first string following point in the
766     current buffer, with the second string. This command is not querying,
767     and will thus not prompt before each replacement, so if you desire this
768     behavior, use the order @kbd{M-%}
769     @kindex M-%
770     (@command{Query Replace}) instead. @xref{The query-replace command loop}.
772     @node Replacing multiple different strings
773     @subsection Replacing multiple different strings
775     It is often desirable to be able to replace multiple, different strings
776     with one command - for instance, you might want to replace all
777     occurrences of ``foo'' with ``bar'' and all occurrences of ``bar'' with
778     ``baz'', without having the replacements affect each other. For this,
779 thenriksen 1.11 @climacs{} provides the command @command{Multiple Query Replace}, which
780 thenriksen 1.10 will prompt for pairs of strings, replacing the first with the second.
781     Entering an empty search string stops the prompting and starts the
782     query-replace command loop. It is also possible to use @command{Multiple
783     Query Replace From Buffer}, which will read the string pairs from a
784     buffer provided by the user.
786     If you wish to exchange two strings for one another, use the command
787     @command{Query Exchange}, which will prompt for two strings, and replace
788     them for each other in the current buffer.
790     @node The query-replace command loop
791     @subsection The query-replace command loop
793     When invoking one of the querying replace commands, you will enter a
794     command loop with specialized commands for manipulating the replacement
795     process.
797     The command loop will loop across the buffer, and for each match, the
798     command loop will read an order from the user. The following orders and
799     their corresponding commands are available:
801     @table @kbd
802     @item y, @key{Space}
803     Replace the current match with the provided string, go to next
804     match.
805     @item n, @key{Rubout}, @key{Backspace}
806     Do not replace the current match, go to next match.
807     @item q, @key{Newline}
808     Quit the command loop, preserving all replacements already made.
809     @item .
810     Replace the current match with the provided string and quit the
811     command loop.
812     @item !
813     Replace all matches with the provided replacement strings.
814     @end table
816 rstrandh 1.4 @node Getting help
817     @chapter Getting help
819     In addition to this manual, @climacs{} contains an online help
820     facility. There are several different topics that you can get help
821     with. Most of these topics are obtained by some order using the
822     @kbd{C-h}
823     @kindex C-h
824 thenriksen 1.9 prefix key. The key following @kbd{C-h} determines what kind of help
825 rstrandh 1.4 information is displayed.
827     @menu
828 thenriksen 1.10 * Help with a command::
829 rstrandh 1.4 * Help with a key binding::
830     * Help with a particular key sequence::
831 thenriksen 1.10 * Help finding a command::
832 rstrandh 1.4 * Help finding an order for a command::
833     @end menu
835 thenriksen 1.9 @node Help with a command
836     @section Help with a command
838     To get documentation about a particular command, use the order @kbd{C-h
839     f}
840     @kindex C-h f
841 thenriksen 1.12 (@command{Describe Command}). You will be prompted for the name of a
842     command, and if you provide a valid command name, a typeout pane
843 thenriksen 1.9 containing information about which function the command calls, which
844     gestures the command can be invoked through, as well as a description of
845     the command, will be displayed.
847 rstrandh 1.4 @node Help with a key binding
848     @section Help with a key binding
850     To obtain a list of all orders and the associated commands that are
851     valid in a particular context, use the order @kbd{C-h b}
852     @kindex C-h b
853     (@command{Describe Bindings}). A table with each command name and
854     associated order (if any) is displayed in a new window.
856     @node Help with a particular key sequence
857     @section Help with a particular key sequence
859     To obtain a description of what some putative order will do, use the
860 thenriksen 1.10 order @kbd{C-h c}p
861 rstrandh 1.4 @kindex C-h c
862 rstrandh 1.6 (@command{Describe Key Briefly}). You will be prompted for a key
863 rstrandh 1.4 sequence. If the key sequence you type is bound to a command, the
864 rstrandh 1.6 command name will be displayed in the minibuffer. Otherwise, a message
865 rstrandh 1.4 indicating that the key is not bound to a command will be displayed.
867 thenriksen 1.9 For more detailed information, use the order @kbd{C-h c}
868     @kindex C-h k
869     (@command{Describe Key}). You will be prompted for a key sequence, and
870     if the key sequence you provide is bound to a command, documentation for
871     that command, as well as any arguments the given key binding calls the
872 thenriksen 1.12 command with, will be shown in a typeout pane.
873 thenriksen 1.9
874     @node Help finding a command
875 thenriksen 1.12 @section Help finding a command
876 thenriksen 1.9
877     If you do not know which commands are applicable to a given situation,
878     you can use the order @kbd{C-h a}
879     @kindex C-h a
880     (@command{Apropos Command}) to perform a keyword-based search for
881 thenriksen 1.12 commands. You will be prompted for a keyword, after which @climacs{}
882     will search through the available commands for commands that are
883     connected to the keyword. If commands are found, they will be displayed
884     in a typeout pane along with the gestures you can use to invoke
885     them. You can also click on the names of the commands to get more
886     thorough documentation.
887 thenriksen 1.9
888 rstrandh 1.4 @node Help finding an order for a command
889     @section Help finding an order for a command
891     Sometimes, you know the name of a command, and would like to find out
892     whether it is bound to any order, and if so, which one(s). For that,
893     you can use the order @kbd{C-h w}
894     @kindex C-h w
895     (@command{Where Is}). You will be prompted for a command name
896     (completion can be used as usual), and if the command name given is
897     bound to an order, that order will displayed in the minibuffer.
898     Otherwise, a message indicating that the command is not bound to any
899     order will be displayed.
900 rstrandh 1.7
901     @node Proposal for new buffer/pane relations
902     @chapter Proposal for new buffer/pane relations
904     There is a proposal on the table to make the way @climacs{} manages
905     buffers and panes incompatible with that of Emacs, and in the process
906     thus cleaning up 30 years of baggage.
908     The proposal is to no longer allow buffers without panes. Instead, a
909     buffer will always be associated with at least one pane, though that
910     pane could be adopted or disowned to make it visible or invisible.
911     The advantage of this organization is that a buffer will no longer
912     contain a point. Also, panes can contain other things that buffers
913     such as buffer lists, debugger applications, etc.
915     For this to work, we need to define how the effect of certain
916     commands related to buffers and windows will be altered. The proposal
917     is:
919     C-x 2 creates an additional pane with its own point and that shares
920     the buffer of the current pane. It also adopts the new pane by the
921     same mechanism used now (creating a vbox pane containing the two. C-x
922     3 is similar except that it uses a hbox instead.
924     C-x 0 does not destroy the pane, but just disowns it (by replacing the
925     rack it is in by the pane itself).
927     C-x 1 does the equivalent of C-x 0 on all other visible panes.
929     C-x k kills the current pane. If that happens to be the last pane
930     containing a particular buffer, then the buffer is lost as well.
932     C-x b replaces the current pane by some arbitrary pane displaying the
933     buffer that has been requested (or creates a new buffer and a new pane
934     if the buffer requested does not exist?).
935 rstrandh 1.1
936     @node Key Index
937     @unnumbered Key Index
939     @printindex ky
941     @node Concept Index
942     @unnumbered Concept Index
944     @printindex cp
946     @bye

  ViewVC Help
Powered by ViewVC 1.1.5