/[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.6 - (hide annotations)
Sat Sep 24 18:53:48 2005 UTC (8 years, 6 months ago) by rstrandh
Branch: MAIN
Changes since 1.5: +13 -12 lines
File MIME type: application/x-texinfo
Fixed spelling errors and a faulty index entry.
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
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 rstrandh 1.3 * Advanced editing commands::
46 rstrandh 1.4 * Getting help::
47 rstrandh 1.1 * 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 rstrandh 1.6 from left to right. It is a question of @emph{rendering} as to whether
149 rstrandh 1.1 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 rstrandh 1.6 @cindex complete key sequence
168     or an @emph{order}.
169 rstrandh 1.1 @cindex order
170    
171     @node Basic editing commands
172     @chapter Basic editing commands
173    
174     The basic editing commands of @climacs{} are identical or at least
175     similar to the corresponding Emacs commands. This is deliberate. We
176     do not believe in introducing gratuitous differences where such
177     differences have little or no importance. A typical Emacs user
178     should therefore feel quite comfortable with the basic editing
179     commands of @climacs{}.
180    
181     @menu
182 rstrandh 1.5 * Entering and exiting Climacs::
183 rstrandh 1.1 * Numeric arguments::
184     * Entering and deleting text::
185     * Moving around::
186     * Extended commands::
187 rstrandh 1.2 * Editing the contents of a file::
188 rstrandh 1.1 @end menu
189    
190 rstrandh 1.5 @node Entering and exiting Climacs
191     @section Entering and exiting Climacs
192 rstrandh 1.1
193     The typical way of entering @climacs{} is to type a @cl{}
194     @emph{expression} at the prompt of a @cl{} @emph{listener} such as:
195    
196     @lisp
197     CL-USER> (climacs:climacs)
198     @end lisp
199    
200     You exit from @climacs{} by typing @kbd{C-x C-c} (@command{Quit}).
201     @kindex C-x C-c
202     If you have buffers
203     associated with files that have not been saved to their respective
204     files, @climacs{} will ask whether you would like those buffers
205     saved. In addition, if you answer no to any of those questions, you
206     will be asked to confirm that you want to quit @climacs{} anyway. The
207     reason for this pestering on the part of @climacs{} is that currently
208 rstrandh 1.6 when you quit @climacs{}, the buffer contents are lost.
209 rstrandh 1.1
210     @node Numeric arguments
211     @section Numeric arguments
212    
213     Many @climacs{} commands allow the use of a @emph{numeric argument}.
214     @cindex numeric argument
215     A numeric argument is used as a prefix to a @climacs{} command, and
216     modifies the behavior of that command in some useful way which varies
217     from command to command.
218    
219     Typically, a numeric argument prefix makes the command repeat its
220     action a number of times indicated by the numeric argument prefix.
221     For instance, the command @command{Delete Object}, usually associated
222     with the order @kbd{C-d}, normally deletes a single object from the
223     buffer. However, if given a numeric argument, it deletes that many
224     objects.
225    
226     Other commands modify their behavior according to whether a numeric
227     argument has been given, but do not take into account the specific
228     numeric value indicated. For instance, the command @command{Delete
229     Horizontal Space}, when given no numeric argument, deletes whitespace
230     both before and after point. With a numeric argument, it deletes only
231     whitespace @emph{before} point.
232    
233     Yet other commands may both modify what they do and repeat according
234     to the numeric value of the argument. For instance, the command
235     @command{Kill Line}, when given no numeric argument, kills to the end
236     of the line if point is not already at the end of the line, but does
237     not kill the newline character at the end of the line and kills the
238     newline character if point is at the end of a line. However, if given
239     a numeric argument, @command{Kill Line} kills that many lines.
240    
241     There are two ways of giving a numeric argument to a @climacs{}
242     command. One way is to first type @kbd{C-u},
243     @kindex C-u
244     then a sequence of
245     decimal digits, and finally the order that invokes the command. For
246     instance, to delete the next 15 objects after point, you could type
247     @kbd{C-u 1 5 C-d}. The other way is to hold down the @key{Meta} key
248     (usually the one marked @key{Alt}) while typing the decimal digits, as
249     in @kbd{M-1 M-5 C-d}.
250    
251     Some commands accept negative numeric arguments. In that case, start
252     the sequence with the minus sign as in @kbd{C-u - 1 5 C-d}, which in
253     this case will delete buffer objects @emph{before} the point rather
254     than after.
255    
256     @node Entering and deleting text
257     @section Entering and deleting text
258    
259     @menu
260     * Entering text::
261     * Deleting by objects::
262     * Deleting by words::
263     * Deleting by lines::
264     @end menu
265    
266     @node Entering text
267     @subsection Entering text
268    
269     In contrast to other text editors such as VI, @climacs{} does not have
270     a specific @emph{insert mode}. Instead, @climacs{} is always in
271     insert mode, in that characters that are typed on the keyboard
272     immediately get inserted at the @emph{point}.
273    
274     @node Deleting by objects
275     @subsection Deleting by objects
276    
277     To erase objects that have been inserted, you can use the
278     @key{Backspace} (@command{Backward Delete Object}
279     key, which deletes the object immediately to the left of the point.
280     To delete an object @emph{to the right} of the point, use the
281     @kbd{C-d}
282     @kindex C-d
283     (@command{Delete Object}) order. When used with a numeric
284     argument, these commands delete that many objects.
285    
286     @node Deleting by words
287     @subsection Deleting by words
288    
289     It is also possible to delete larger chunks of buffer contents. The
290     order @kbd{M-d}
291     @kindex M-d
292 rstrandh 1.2 (@command{Kill Word}) is used to delete the @emph{word}
293     @cindex word
294 rstrandh 1.1 @emph{following} point. If point is not at the beginning of a word,
295     then the part of the word that follows point is deleted. The order
296     @kbd{M-@key{Backspace}}
297     @kindex M-@key{Backspace}
298     (@command{Backward Kill Word}) is used to
299     delete the word @emph{preceding} point. If point is not at the end of
300     a word, then the part of the word that precedes point is deleted.
301     When used with a numeric argument, these commands delete that many
302     words. Since these command names contain the word @emph{kill}, they
303     use the kill-ring (@pxref{kill-ring}).
304    
305     @node Deleting by lines
306     @subsection Deleting by lines
307    
308     @climacs{} allows you to delete buffer objects one or more lines at a
309     time. The order @kbd{C-k}
310     @kindex C-k
311     (@command{Kill Line}) lets you do this. When point is @emph{not} at
312     the end of a line, then this command kills the buffer contents from
313     point up to, but not including the following newline object. When
314     instead point @emph{is} at the end of a line, only the following
315     newline object is removed.
316    
317     When used with a numeric argument, this command is not simply repeated
318     that many times. Instead, the number of lines indicated by the
319 rstrandh 1.6 numeric argument are removed.
320 rstrandh 1.1
321     Because this command name contains the word @emph{kill} it saves the
322     deleted objects on the @emph{kill ring} (@pxref{kill-ring}).
323    
324     @node Moving around
325     @section Moving around
326    
327     @menu
328     * Moving by objects::
329     * Moving by words::
330     * Moving by lines::
331     @end menu
332    
333     @node Moving by objects
334     @subsection Moving by objects
335    
336     @climacs{} allows you to move around in the buffer in various ways.
337     The most frequent way of moving around is by one buffer position at a
338     time.
339    
340     The order @kbd{C-f}
341     @kindex C-f
342     (@command{Forward Object}) allows you to
343     advance the position of point by one position. If given a numeric
344     argument, it advances by that many positions. The @command{Forward
345     Object} command is also associated with the @emph{right-arrow key}.
346    
347     The order @kbd{C-b}
348     @kindex C-b
349     (@command{Backward Object}) allows you to move the
350     position of point backward by one position. If given a numeric
351     argument, it moves back by that many positions. The @command{Backward
352     Object} command is also associated with the @emph{left-arrow key}.
353    
354     @node Moving by words
355     @subsection Moving by words
356    
357 rstrandh 1.6 @climacs{} will allow you to move around by larger units than
358 rstrandh 1.2 objects.
359    
360     The order @kbd{M-f}
361     @kindex M-f
362     (@command{Forward Word}) lets you move forward over the @emph{word}
363     @cindex word
364     following point. With a numeric argument, this command moves point
365     forward that many words.
366    
367     The order @kbd{M-b}
368     @kindex M-b
369     (@command{Backward Word}) lets you move backward over the @emph{word}
370     @cindex word
371     preceding point. With a numeric argument, this command moves point
372     backward that many words.
373    
374     Notice the analogy between the commands for moving by objects
375     (@kbd{C-f}, @kbd{C-b}) and those for moving by words (@kbd{M-f},
376     @kbd{M-b}).
377    
378 rstrandh 1.1 @node Moving by lines
379     @subsection Moving by lines
380    
381     @climacs{} has commands to move by one or several @emph{lines} at a
382     time.
383    
384     The order @kbd{C-p}
385     @kindex C-p
386     (@command{Previous Line}) allows you to
387     move point @emph{up} to the previous line. If given a numeric
388     argument, it moves up by that many lines. The command
389     @command{Previous Line} is also associated with the @emph{up-arrow
390     key}.
391    
392     The order @kbd{C-n}
393     @kindex C-n
394     (@command{Next Line}) allows you to
395     move point @emph{down} to the next line. If given a numeric
396     argument, it moves down by that many lines. The command
397     @command{Next Line} is also associated with the @emph{down-arrow
398     key}.
399    
400 rstrandh 1.6 When you move by lines, @climacs{} tries to be smart about which
401 rstrandh 1.1 @emph{column} point ends up in, in the following way: when a sequence
402     of commands that move by lines is given, the initial column of point
403     is remembered (this is called the @emph{goal column}). @climacs{}
404     then tries to position point in that column of the target line. If
405     the target line has fewer than that many columns, point is positioned
406     at the end of the target line. The goal column is discarded when the
407     sequence of commands is interrupted by some unrelated command.
408    
409     @node Extended commands
410     @section Extended commands
411    
412     In order to make editing as efficient as possible, many @climacs{}
413     commands can be invoked by key sequences. It is, however, possible to
414     invoke most @climacs{} commands by using the order @kbd{M-x} which
415     invokes the command @command{Extended Command} which lets you type the
416     @emph{name} of the command in the minibuffer at the prompt.
417     In general, you do not have to type the full name of the command,
418     because @climacs{} uses CLIM's completion mechanism so that you can
419     complete the name by typing some prefix and then use the @key{TAB} key
420     to complete.
421    
422     Some @climacs{} commands @emph{must} be invoked through the use of
423     @command{Extended Command}. The reason for this is that key sequences
424     are a precious resource, and for rarely-used commands, it is better
425     not to waste a key sequence.
426 rstrandh 1.2
427     @node Editing the contents of a file
428     @section Editing the contents of a file
429    
430     Transfering the contents of a text file into a @climacs{} buffer is
431     referred to as @emph{finding} the file.
432     @cindex finding a file
433    
434     There are two ways of transfering the contents of a buffer to a file.
435     One is to @emph{save} the buffer, which means to transfer the contents
436     to the file that is already associated with the buffer. The other is
437     to @emph{write} the buffer, which means to transfer the contents to a
438     different file than that associated with the buffer, or to write the
439     contents of a buffer that has no associated file to some file.
440    
441     @menu
442     * Finding a file:: Moving text from a file to a @climacs{} buffer
443     * Saving a buffer:: Moving text from a buffer to the associated file
444     * Writing a buffer:: Moving text from a buffer to a different file
445     @end menu
446    
447     @node Finding a file
448     @subsection Finding a file
449    
450     To find a file, use the order @kbd{C-x C-f}
451     @kindex C-x C-f
452     (@command{Find File}).
453    
454     @climacs{} will prompt for the name of a file. For typing the file
455     name, you can use @emph{completion} (using the @key{TAB} key), or you
456     can use the right mouse button to get a list of all the files that
457     match the prefix you typed.
458    
459     The result of finding a file is that a @emph{buffer} will be created
460     that has the name of the file, and the file will be associated with
461 rstrandh 1.6 that buffer when the content is saved.
462 rstrandh 1.2
463     @node Saving a buffer
464     @subsection Saving a buffer
465    
466     To save a buffer, use the order @kbd{C-x C-s}
467     @kindex C-x C-s
468     (@command{Save Buffer}).
469     The contents of the buffer will be transfered to the file associated
470     with the buffer if there is one. If the buffer has no file name
471     associated with it, then this command behaves just like @command{Write
472     Buffer} (@pxref{write-buffer}).
473    
474     @node Writing a buffer
475     @subsection Writing a buffer
476     @anchor{write-buffer}
477    
478     To write a buffer to a file, use the order @kbd{C-x C-w}
479     @kindex C-x C-w
480     (@command{Write Buffer}). @climacs{} will prompt for the name of a
481     file to save the buffer contents in. Completion (by using the
482     @key{TAB} key, or by using the right mouse button) can be used if the
483     name is that of an existing file.
484 rstrandh 1.1
485     @node Different editing modes
486     @chapter Different editing modes
487    
488     @menu
489     * Overwrite mode::
490     @end menu
491    
492     @node Overwrite mode
493     @section Overwrite mode
494    
495     Normally, typing ordinary characters to @climacs{} results in these
496     characters being @emph{inserted} at point. Sometimes, however, it is
497     useful to treat a line of objects as being of @emph{fixed length}, and
498 rstrandh 1.6 have @climacs{} @emph{replace} objects as new ones are being typed.
499 rstrandh 1.1
500     This is exactly the purpose of @climacs{} @emph{overwrite mode}. This
501     mode alters the insert commands so that the object after point is
502     first deleted.
503    
504     You can toggle between the normal mode of operation and overwrite mode
505     by using the @key{Insert}
506     @kindex @key{Insert}
507     (@command{Toggle Overwrite Mode}) key.
508    
509     @node Kill ring
510     @chapter Kill ring
511     @anchor{kill-ring}
512    
513     Many @climacs{} commands that remove objects from a buffer save these
514     objects on a global @emph{kill ring}.
515     @cindex kill ring
516    
517 rstrandh 1.3 @node Advanced editing commands
518     @chapter Advanced editing commands
519    
520     @menu
521     * Keyboard macros::
522     * Searching and replacing::
523     @end menu
524    
525     @node Keyboard macros
526     @section Keyboard macros
527    
528     Sometimes, it is useful to be able to repeat a sequence of keystrokes
529 rstrandh 1.6 several times. @climacs{} allows you to do this through a feature
530 rstrandh 1.3 called @emph{keyboard macros}.
531     @cindex keyboard macro
532     @climacs{} does this by @emph{recording} whatever the user types on
533 rstrandh 1.6 the keyboard, and then making it possibly to @emph{replay} the
534 rstrandh 1.3 recorded sequence.
535    
536     To start recording a sequence of keystrokes, use the order @kbd{C-x (}
537     @kindex C-x (
538     (@command{Start Kbd Macro}). You will see the word @samp{Def}
539     appearing on the mode line, indicating that a keyboard macro is being
540     defined. As long as recording is in effect, every keystroke will be
541     saved for later use.
542    
543     To stop recording a sequence of keystrokes, use the order @kbd{C-x )}
544     @kindex C-x )
545     (@command{End Kbd Macro}). The word @samp{Def} will disappear from
546     the mode line, indicating that keystrokes are no longer being
547     recorded.
548    
549     To replay a previously recorded sequence of keystrokes, use the order
550     @kbd{C-x e}
551     @kindex C-x e
552     (@command{Call Last Kbd Macro}). When used with a numeric argument,
553     this command will repeat the sequence of keystrokes that many times.
554    
555     @node Searching and replacing
556     @section Searching and replacing
557 rstrandh 1.4
558     @node Getting help
559     @chapter Getting help
560    
561     In addition to this manual, @climacs{} contains an online help
562     facility. There are several different topics that you can get help
563     with. Most of these topics are obtained by some order using the
564     @kbd{C-h}
565     @kindex C-h
566     prefex key. The key following @kbd{C-h} determines what kind of help
567     information is displayed.
568    
569     @menu
570     * Help with a key binding::
571     * Help with a particular key sequence::
572     * Help finding an order for a command::
573     @end menu
574    
575     @node Help with a key binding
576     @section Help with a key binding
577    
578     To obtain a list of all orders and the associated commands that are
579     valid in a particular context, use the order @kbd{C-h b}
580     @kindex C-h b
581     (@command{Describe Bindings}). A table with each command name and
582     associated order (if any) is displayed in a new window.
583    
584     @node Help with a particular key sequence
585     @section Help with a particular key sequence
586    
587     To obtain a description of what some putative order will do, use the
588     order @kbd{C-h c}
589     @kindex C-h c
590 rstrandh 1.6 (@command{Describe Key Briefly}). You will be prompted for a key
591 rstrandh 1.4 sequence. If the key sequence you type is bound to a command, the
592 rstrandh 1.6 command name will be displayed in the minibuffer. Otherwise, a message
593 rstrandh 1.4 indicating that the key is not bound to a command will be displayed.
594    
595     @node Help finding an order for a command
596     @section Help finding an order for a command
597    
598     Sometimes, you know the name of a command, and would like to find out
599     whether it is bound to any order, and if so, which one(s). For that,
600     you can use the order @kbd{C-h w}
601     @kindex C-h w
602     (@command{Where Is}). You will be prompted for a command name
603     (completion can be used as usual), and if the command name given is
604     bound to an order, that order will displayed in the minibuffer.
605     Otherwise, a message indicating that the command is not bound to any
606     order will be displayed.
607 rstrandh 1.1
608     @node Key Index
609     @unnumbered Key Index
610    
611     @printindex ky
612    
613     @node Concept Index
614     @unnumbered Concept Index
615    
616     @printindex cp
617    
618     @bye

  ViewVC Help
Powered by ViewVC 1.1.5