/[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.5 - (show annotations)
Thu Sep 22 23:25:14 2005 UTC (8 years, 6 months ago) by rstrandh
Branch: MAIN
Changes since 1.4: +3 -3 lines
File MIME type: application/x-texinfo
Include the user manual in the Makefile.

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

  ViewVC Help
Powered by ViewVC 1.1.5