/[climacs]/climacs/Doc/climacs-user.texi
ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.7 - (show annotations)
Wed Oct 19 18:03:07 2005 UTC (8 years, 6 months ago) by rstrandh
Branch: MAIN
Changes since 1.6: +36 -0 lines
File MIME type: application/x-texinfo
Added a chapter describing a proposal to change the buffer/pane
relations.  This chapter will disappear once the proposal is
implemented, and the description of the existing key bindings will be
altered.
1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename climacs-user
4 @settitle Climacs User Manual
5 @c %**end of header
6
7 @copying
8 The Climacs User manual
9
10 Copyright @copyright{} 2005 Robert Strandh.
11
12 @end copying
13
14 @titlepage
15 @title Climacs User Manual
16 @sp 2
17 @author Robert Strandh
18
19 @page
20 @vskip 0pt plus 1filll
21 @insertcopying
22
23 @end titlepage
24
25 @contents
26
27 @macro climacs{}
28 Climacs
29 @end macro
30
31 @macro cl{}
32 Common Lisp
33 @end macro
34
35 @node Top
36 @top
37
38 @menu
39 * Introduction::
40 * Conventions::
41 * Concepts::
42 * Basic editing commands::
43 * Different editing modes::
44 * Kill ring::
45 * Advanced editing commands::
46 * Getting help::
47 * Proposal for new buffer/pane relations::
48 * Key Index::
49 * Concept Index::
50 @end menu
51
52
53 @node Introduction
54 @chapter Introduction
55
56 @climacs{} is a text editor in the Emacs family. However, @climacs{}
57 differs from Emacs in various ways.
58
59 For one thing, @climacs{} is written in Common Lisp rather than Emacs
60 Lisp. Common Lisp is a much more complete language than Emacs Lisp
61 with essential features such as packages, classes, etc.
62
63 Moreover, @climacs{} uses the Common-Lisp Interface Manager (CLIM) as its
64 substrate for managing everything that has to do with user
65 interaction, including event handling, text rendering, and
66 multi-windowing (called panes in CLIM terminology).
67
68 Also, since @climacs{} uses CLIM, there is no need for @climacs{} itself to
69 serve as the basis for other applications such as news readers, mail
70 readers, directory editors, web browsers, etc. the way it is done with
71 Emacs. Instead, such applications are better written as stand-alone
72 CLIM applications that can then communicate with @climacs{} using CLIM
73 and Common Lisp as the common substrate.
74
75 The main purpose of @climacs{} is not to replace Emacs. Instead, it is
76 primarily intended as a text editor for Common Lisp developers.
77 Notice that this is not the same as a text editor for Common Lisp
78 @emph{development}, since Common Lisp developers might need other
79 features such as editing HTML or spell checking, etc., not directly
80 related to Common Lisp development.
81
82 @node Conventions
83 @chapter Conventions
84
85 Many @climacs{} commands are invoked by typing a sequence of
86 keystrokes. A complete sequence of keystrokes invokes a
87 @climacs{} @emph{command} which has a @emph{name}. Sometimes it is
88 useful to know that name, even though the command is usually invoked
89 by typing the key sequence. For that reason, in this manual we often
90 give the corresponding command name together with the key sequence to
91 invoke it.
92
93 @node Concepts
94 @chapter Concepts
95
96 In order to use @climacs{} effectively, you need to know some concepts
97 that are used by it, and referred to in this manual.
98
99 @menu
100 * Buffer::
101 * Window and pane::
102 * Mark and point::
103 * Key sequence::
104 @end menu
105
106 @node Buffer
107 @section Buffer
108
109 A @climacs{} @emph{buffer}
110 @cindex buffer
111 is an editable sequence of arbitrary @cl{} objects. If the buffer
112 contains text, most of those objects will be @emph{Unicode
113 characters}.
114 @cindex character
115 @cindex Unicode
116
117 @node Window and pane
118 @section Window and pane
119
120 A @climacs{} buffer may or may not be on display. If it is, it is on
121 display in a @emph{pane}
122 @cindex pane
123 or a @emph{window}.
124 @cindex window
125
126 @node Mark and point
127 @section Mark and point
128
129 Positions into a @climacs{} buffer are determined by @emph{marks}
130 @cindex mark
131 which can be either @emph{left sticky},
132 @cindex left sticky
133 meaning that if an object is inserted where such a mark is, it ends up
134 @emph{to the left} of the newly inserted object, or @emph{right
135 sticky},
136 @cindex right sticky
137 meaning that if an object is inserted where such a mark is, it ends up
138 @emph{to the right} of the newly inserted object.
139
140 A distinguished mark that is associated with each @climacs{} pane is
141 called the @emph{point}.
142 @cindex point
143 There is a point associated with each window. Each of several windows
144 that display the same buffer has its own point. In addition, a buffer
145 that is not on display has a point that is taken over by the first
146 window that displays the buffer. Points are right-sticky marks, even
147 when a language such as Arabic is edited, simply because by
148 convention, the @climacs{} buffer is considered as being organized
149 from left to right. It is a question of @emph{rendering} as to whether
150 the objects in the buffer are actually displayed from left to right,
151 from right to left, or in any other appropriate order.
152
153 @node Key sequence
154 @section Key sequence
155
156 Typically, @climacs{} is operated by @emph{key sequences}
157 @cindex key sequence
158 issued by the user. A key sequence is a sequence of key strokes,
159 where a key stroke can be a simple character such as @kbd{f} or
160 @kbd{&}, or a key with one or more @emph{modifiers}
161 @cindex modifier
162 such as @key{Control}, @key{Shift}, @key{Meta}, etc.
163
164 Some key sequences result in the execution of a @climacs{}
165 @emph{command}.
166 @cindex command
167 Such a key sequence is called a @emph{complete key sequence}
168 @cindex complete key sequence
169 or an @emph{order}.
170 @cindex order
171
172 @node Basic editing commands
173 @chapter Basic editing commands
174
175 The basic editing commands of @climacs{} are identical or at least
176 similar to the corresponding Emacs commands. This is deliberate. We
177 do not believe in introducing gratuitous differences where such
178 differences have little or no importance. A typical Emacs user
179 should therefore feel quite comfortable with the basic editing
180 commands of @climacs{}.
181
182 @menu
183 * Entering and exiting Climacs::
184 * Numeric arguments::
185 * Entering and deleting text::
186 * Moving around::
187 * Extended commands::
188 * Editing the contents of a file::
189 @end menu
190
191 @node Entering and exiting Climacs
192 @section Entering and exiting Climacs
193
194 The typical way of entering @climacs{} is to type a @cl{}
195 @emph{expression} at the prompt of a @cl{} @emph{listener} such as:
196
197 @lisp
198 CL-USER> (climacs:climacs)
199 @end lisp
200
201 You exit from @climacs{} by typing @kbd{C-x C-c} (@command{Quit}).
202 @kindex C-x C-c
203 If you have buffers
204 associated with files that have not been saved to their respective
205 files, @climacs{} will ask whether you would like those buffers
206 saved. In addition, if you answer no to any of those questions, you
207 will be asked to confirm that you want to quit @climacs{} anyway. The
208 reason for this pestering on the part of @climacs{} is that currently
209 when you quit @climacs{}, the buffer contents are lost.
210
211 @node Numeric arguments
212 @section Numeric arguments
213
214 Many @climacs{} commands allow the use of a @emph{numeric argument}.
215 @cindex numeric argument
216 A numeric argument is used as a prefix to a @climacs{} command, and
217 modifies the behavior of that command in some useful way which varies
218 from command to command.
219
220 Typically, a numeric argument prefix makes the command repeat its
221 action a number of times indicated by the numeric argument prefix.
222 For instance, the command @command{Delete Object}, usually associated
223 with the order @kbd{C-d}, normally deletes a single object from the
224 buffer. However, if given a numeric argument, it deletes that many
225 objects.
226
227 Other commands modify their behavior according to whether a numeric
228 argument has been given, but do not take into account the specific
229 numeric value indicated. For instance, the command @command{Delete
230 Horizontal Space}, when given no numeric argument, deletes whitespace
231 both before and after point. With a numeric argument, it deletes only
232 whitespace @emph{before} point.
233
234 Yet other commands may both modify what they do and repeat according
235 to the numeric value of the argument. For instance, the command
236 @command{Kill Line}, when given no numeric argument, kills to the end
237 of the line if point is not already at the end of the line, but does
238 not kill the newline character at the end of the line and kills the
239 newline character if point is at the end of a line. However, if given
240 a numeric argument, @command{Kill Line} kills that many lines.
241
242 There are two ways of giving a numeric argument to a @climacs{}
243 command. One way is to first type @kbd{C-u},
244 @kindex C-u
245 then a sequence of
246 decimal digits, and finally the order that invokes the command. For
247 instance, to delete the next 15 objects after point, you could type
248 @kbd{C-u 1 5 C-d}. The other way is to hold down the @key{Meta} key
249 (usually the one marked @key{Alt}) while typing the decimal digits, as
250 in @kbd{M-1 M-5 C-d}.
251
252 Some commands accept negative numeric arguments. In that case, start
253 the sequence with the minus sign as in @kbd{C-u - 1 5 C-d}, which in
254 this case will delete buffer objects @emph{before} the point rather
255 than after.
256
257 @node Entering and deleting text
258 @section Entering and deleting text
259
260 @menu
261 * Entering text::
262 * Deleting by objects::
263 * Deleting by words::
264 * Deleting by lines::
265 @end menu
266
267 @node Entering text
268 @subsection Entering text
269
270 In contrast to other text editors such as VI, @climacs{} does not have
271 a specific @emph{insert mode}. Instead, @climacs{} is always in
272 insert mode, in that characters that are typed on the keyboard
273 immediately get inserted at the @emph{point}.
274
275 @node Deleting by objects
276 @subsection Deleting by objects
277
278 To erase objects that have been inserted, you can use the
279 @key{Backspace} (@command{Backward Delete Object}
280 key, which deletes the object immediately to the left of the point.
281 To delete an object @emph{to the right} of the point, use the
282 @kbd{C-d}
283 @kindex C-d
284 (@command{Delete Object}) order. When used with a numeric
285 argument, these commands delete that many objects.
286
287 @node Deleting by words
288 @subsection Deleting by words
289
290 It is also possible to delete larger chunks of buffer contents. The
291 order @kbd{M-d}
292 @kindex M-d
293 (@command{Kill Word}) is used to delete the @emph{word}
294 @cindex word
295 @emph{following} point. If point is not at the beginning of a word,
296 then the part of the word that follows point is deleted. The order
297 @kbd{M-@key{Backspace}}
298 @kindex M-@key{Backspace}
299 (@command{Backward Kill Word}) is used to
300 delete the word @emph{preceding} point. If point is not at the end of
301 a word, then the part of the word that precedes point is deleted.
302 When used with a numeric argument, these commands delete that many
303 words. Since these command names contain the word @emph{kill}, they
304 use the kill-ring (@pxref{kill-ring}).
305
306 @node Deleting by lines
307 @subsection Deleting by lines
308
309 @climacs{} allows you to delete buffer objects one or more lines at a
310 time. The order @kbd{C-k}
311 @kindex C-k
312 (@command{Kill Line}) lets you do this. When point is @emph{not} at
313 the end of a line, then this command kills the buffer contents from
314 point up to, but not including the following newline object. When
315 instead point @emph{is} at the end of a line, only the following
316 newline object is removed.
317
318 When used with a numeric argument, this command is not simply repeated
319 that many times. Instead, the number of lines indicated by the
320 numeric argument are removed.
321
322 Because this command name contains the word @emph{kill} it saves the
323 deleted objects on the @emph{kill ring} (@pxref{kill-ring}).
324
325 @node Moving around
326 @section Moving around
327
328 @menu
329 * Moving by objects::
330 * Moving by words::
331 * Moving by lines::
332 @end menu
333
334 @node Moving by objects
335 @subsection Moving by objects
336
337 @climacs{} allows you to move around in the buffer in various ways.
338 The most frequent way of moving around is by one buffer position at a
339 time.
340
341 The order @kbd{C-f}
342 @kindex C-f
343 (@command{Forward Object}) allows you to
344 advance the position of point by one position. If given a numeric
345 argument, it advances by that many positions. The @command{Forward
346 Object} command is also associated with the @emph{right-arrow key}.
347
348 The order @kbd{C-b}
349 @kindex C-b
350 (@command{Backward Object}) allows you to move the
351 position of point backward by one position. If given a numeric
352 argument, it moves back by that many positions. The @command{Backward
353 Object} command is also associated with the @emph{left-arrow key}.
354
355 @node Moving by words
356 @subsection Moving by words
357
358 @climacs{} will allow you to move around by larger units than
359 objects.
360
361 The order @kbd{M-f}
362 @kindex M-f
363 (@command{Forward Word}) lets you move forward over the @emph{word}
364 @cindex word
365 following point. With a numeric argument, this command moves point
366 forward that many words.
367
368 The order @kbd{M-b}
369 @kindex M-b
370 (@command{Backward Word}) lets you move backward over the @emph{word}
371 @cindex word
372 preceding point. With a numeric argument, this command moves point
373 backward that many words.
374
375 Notice the analogy between the commands for moving by objects
376 (@kbd{C-f}, @kbd{C-b}) and those for moving by words (@kbd{M-f},
377 @kbd{M-b}).
378
379 @node Moving by lines
380 @subsection Moving by lines
381
382 @climacs{} has commands to move by one or several @emph{lines} at a
383 time.
384
385 The order @kbd{C-p}
386 @kindex C-p
387 (@command{Previous Line}) allows you to
388 move point @emph{up} to the previous line. If given a numeric
389 argument, it moves up by that many lines. The command
390 @command{Previous Line} is also associated with the @emph{up-arrow
391 key}.
392
393 The order @kbd{C-n}
394 @kindex C-n
395 (@command{Next Line}) allows you to
396 move point @emph{down} to the next line. If given a numeric
397 argument, it moves down by that many lines. The command
398 @command{Next Line} is also associated with the @emph{down-arrow
399 key}.
400
401 When you move by lines, @climacs{} tries to be smart about which
402 @emph{column} point ends up in, in the following way: when a sequence
403 of commands that move by lines is given, the initial column of point
404 is remembered (this is called the @emph{goal column}). @climacs{}
405 then tries to position point in that column of the target line. If
406 the target line has fewer than that many columns, point is positioned
407 at the end of the target line. The goal column is discarded when the
408 sequence of commands is interrupted by some unrelated command.
409
410 @node Extended commands
411 @section Extended commands
412
413 In order to make editing as efficient as possible, many @climacs{}
414 commands can be invoked by key sequences. It is, however, possible to
415 invoke most @climacs{} commands by using the order @kbd{M-x} which
416 invokes the command @command{Extended Command} which lets you type the
417 @emph{name} of the command in the minibuffer at the prompt.
418 In general, you do not have to type the full name of the command,
419 because @climacs{} uses CLIM's completion mechanism so that you can
420 complete the name by typing some prefix and then use the @key{TAB} key
421 to complete.
422
423 Some @climacs{} commands @emph{must} be invoked through the use of
424 @command{Extended Command}. The reason for this is that key sequences
425 are a precious resource, and for rarely-used commands, it is better
426 not to waste a key sequence.
427
428 @node Editing the contents of a file
429 @section Editing the contents of a file
430
431 Transfering the contents of a text file into a @climacs{} buffer is
432 referred to as @emph{finding} the file.
433 @cindex finding a file
434
435 There are two ways of transfering the contents of a buffer to a file.
436 One is to @emph{save} the buffer, which means to transfer the contents
437 to the file that is already associated with the buffer. The other is
438 to @emph{write} the buffer, which means to transfer the contents to a
439 different file than that associated with the buffer, or to write the
440 contents of a buffer that has no associated file to some file.
441
442 @menu
443 * Finding a file:: Moving text from a file to a @climacs{} buffer
444 * Saving a buffer:: Moving text from a buffer to the associated file
445 * Writing a buffer:: Moving text from a buffer to a different file
446 @end menu
447
448 @node Finding a file
449 @subsection Finding a file
450
451 To find a file, use the order @kbd{C-x C-f}
452 @kindex C-x C-f
453 (@command{Find File}).
454
455 @climacs{} will prompt for the name of a file. For typing the file
456 name, you can use @emph{completion} (using the @key{TAB} key), or you
457 can use the right mouse button to get a list of all the files that
458 match the prefix you typed.
459
460 The result of finding a file is that a @emph{buffer} will be created
461 that has the name of the file, and the file will be associated with
462 that buffer when the content is saved.
463
464 @node Saving a buffer
465 @subsection Saving a buffer
466
467 To save a buffer, use the order @kbd{C-x C-s}
468 @kindex C-x C-s
469 (@command{Save Buffer}).
470 The contents of the buffer will be transfered to the file associated
471 with the buffer if there is one. If the buffer has no file name
472 associated with it, then this command behaves just like @command{Write
473 Buffer} (@pxref{write-buffer}).
474
475 @node Writing a buffer
476 @subsection Writing a buffer
477 @anchor{write-buffer}
478
479 To write a buffer to a file, use the order @kbd{C-x C-w}
480 @kindex C-x C-w
481 (@command{Write Buffer}). @climacs{} will prompt for the name of a
482 file to save the buffer contents in. Completion (by using the
483 @key{TAB} key, or by using the right mouse button) can be used if the
484 name is that of an existing file.
485
486 @node Different editing modes
487 @chapter Different editing modes
488
489 @menu
490 * Overwrite mode::
491 @end menu
492
493 @node Overwrite mode
494 @section Overwrite mode
495
496 Normally, typing ordinary characters to @climacs{} results in these
497 characters being @emph{inserted} at point. Sometimes, however, it is
498 useful to treat a line of objects as being of @emph{fixed length}, and
499 have @climacs{} @emph{replace} objects as new ones are being typed.
500
501 This is exactly the purpose of @climacs{} @emph{overwrite mode}. This
502 mode alters the insert commands so that the object after point is
503 first deleted.
504
505 You can toggle between the normal mode of operation and overwrite mode
506 by using the @key{Insert}
507 @kindex @key{Insert}
508 (@command{Toggle Overwrite Mode}) key.
509
510 @node Kill ring
511 @chapter Kill ring
512 @anchor{kill-ring}
513
514 Many @climacs{} commands that remove objects from a buffer save these
515 objects on a global @emph{kill ring}.
516 @cindex kill ring
517
518 @node Advanced editing commands
519 @chapter Advanced editing commands
520
521 @menu
522 * Keyboard macros::
523 * Searching and replacing::
524 @end menu
525
526 @node Keyboard macros
527 @section Keyboard macros
528
529 Sometimes, it is useful to be able to repeat a sequence of keystrokes
530 several times. @climacs{} allows you to do this through a feature
531 called @emph{keyboard macros}.
532 @cindex keyboard macro
533 @climacs{} does this by @emph{recording} whatever the user types on
534 the keyboard, and then making it possibly to @emph{replay} the
535 recorded sequence.
536
537 To start recording a sequence of keystrokes, use the order @kbd{C-x (}
538 @kindex C-x (
539 (@command{Start Kbd Macro}). You will see the word @samp{Def}
540 appearing on the mode line, indicating that a keyboard macro is being
541 defined. As long as recording is in effect, every keystroke will be
542 saved for later use.
543
544 To stop recording a sequence of keystrokes, use the order @kbd{C-x )}
545 @kindex C-x )
546 (@command{End Kbd Macro}). The word @samp{Def} will disappear from
547 the mode line, indicating that keystrokes are no longer being
548 recorded.
549
550 To replay a previously recorded sequence of keystrokes, use the order
551 @kbd{C-x e}
552 @kindex C-x e
553 (@command{Call Last Kbd Macro}). When used with a numeric argument,
554 this command will repeat the sequence of keystrokes that many times.
555
556 @node Searching and replacing
557 @section Searching and replacing
558
559 @node Getting help
560 @chapter Getting help
561
562 In addition to this manual, @climacs{} contains an online help
563 facility. There are several different topics that you can get help
564 with. Most of these topics are obtained by some order using the
565 @kbd{C-h}
566 @kindex C-h
567 prefex key. The key following @kbd{C-h} determines what kind of help
568 information is displayed.
569
570 @menu
571 * Help with a key binding::
572 * Help with a particular key sequence::
573 * Help finding an order for a command::
574 @end menu
575
576 @node Help with a key binding
577 @section Help with a key binding
578
579 To obtain a list of all orders and the associated commands that are
580 valid in a particular context, use the order @kbd{C-h b}
581 @kindex C-h b
582 (@command{Describe Bindings}). A table with each command name and
583 associated order (if any) is displayed in a new window.
584
585 @node Help with a particular key sequence
586 @section Help with a particular key sequence
587
588 To obtain a description of what some putative order will do, use the
589 order @kbd{C-h c}
590 @kindex C-h c
591 (@command{Describe Key Briefly}). You will be prompted for a key
592 sequence. If the key sequence you type is bound to a command, the
593 command name will be displayed in the minibuffer. Otherwise, a message
594 indicating that the key is not bound to a command will be displayed.
595
596 @node Help finding an order for a command
597 @section Help finding an order for a command
598
599 Sometimes, you know the name of a command, and would like to find out
600 whether it is bound to any order, and if so, which one(s). For that,
601 you can use the order @kbd{C-h w}
602 @kindex C-h w
603 (@command{Where Is}). You will be prompted for a command name
604 (completion can be used as usual), and if the command name given is
605 bound to an order, that order will displayed in the minibuffer.
606 Otherwise, a message indicating that the command is not bound to any
607 order will be displayed.
608
609 @node Proposal for new buffer/pane relations
610 @chapter Proposal for new buffer/pane relations
611
612 There is a proposal on the table to make the way @climacs{} manages
613 buffers and panes incompatible with that of Emacs, and in the process
614 thus cleaning up 30 years of baggage.
615
616 The proposal is to no longer allow buffers without panes. Instead, a
617 buffer will always be associated with at least one pane, though that
618 pane could be adopted or disowned to make it visible or invisible.
619 The advantage of this organization is that a buffer will no longer
620 contain a point. Also, panes can contain other things that buffers
621 such as buffer lists, debugger applications, etc.
622
623 For this to work, we need to define how the effect of certain
624 commands related to buffers and windows will be altered. The proposal
625 is:
626
627 C-x 2 creates an additional pane with its own point and that shares
628 the buffer of the current pane. It also adopts the new pane by the
629 same mechanism used now (creating a vbox pane containing the two. C-x
630 3 is similar except that it uses a hbox instead.
631
632 C-x 0 does not destroy the pane, but just disowns it (by replacing the
633 rack it is in by the pane itself).
634
635 C-x 1 does the equivalent of C-x 0 on all other visible panes.
636
637 C-x k kills the current pane. If that happens to be the last pane
638 containing a particular buffer, then the buffer is lost as well.
639
640 C-x b replaces the current pane by some arbitrary pane displaying the
641 buffer that has been requested (or creates a new buffer and a new pane
642 if the buffer requested does not exist?).
643
644 @node Key Index
645 @unnumbered Key Index
646
647 @printindex ky
648
649 @node Concept Index
650 @unnumbered Concept Index
651
652 @printindex cp
653
654 @bye

  ViewVC Help
Powered by ViewVC 1.1.5