/[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 - (hide annotations)
Wed Oct 19 18:03:07 2005 UTC (8 years, 5 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 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.7 * Proposal for new buffer/pane relations::
48 rstrandh 1.1 * 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 rstrandh 1.6 from left to right. It is a question of @emph{rendering} as to whether
150 rstrandh 1.1 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 rstrandh 1.6 @cindex complete key sequence
169     or an @emph{order}.
170 rstrandh 1.1 @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 rstrandh 1.5 * Entering and exiting Climacs::
184 rstrandh 1.1 * Numeric arguments::
185     * Entering and deleting text::
186     * Moving around::
187     * Extended commands::
188 rstrandh 1.2 * Editing the contents of a file::
189 rstrandh 1.1 @end menu
190    
191 rstrandh 1.5 @node Entering and exiting Climacs
192     @section Entering and exiting Climacs
193 rstrandh 1.1
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 rstrandh 1.6 when you quit @climacs{}, the buffer contents are lost.
210 rstrandh 1.1
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 rstrandh 1.2 (@command{Kill Word}) is used to delete the @emph{word}
294     @cindex word
295 rstrandh 1.1 @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 rstrandh 1.6 numeric argument are removed.
321 rstrandh 1.1
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 rstrandh 1.6 @climacs{} will allow you to move around by larger units than
359 rstrandh 1.2 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 rstrandh 1.1 @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 rstrandh 1.6 When you move by lines, @climacs{} tries to be smart about which
402 rstrandh 1.1 @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 rstrandh 1.2
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 rstrandh 1.6 that buffer when the content is saved.
463 rstrandh 1.2
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 rstrandh 1.1
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 rstrandh 1.6 have @climacs{} @emph{replace} objects as new ones are being typed.
500 rstrandh 1.1
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 rstrandh 1.3 @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 rstrandh 1.6 several times. @climacs{} allows you to do this through a feature
531 rstrandh 1.3 called @emph{keyboard macros}.
532     @cindex keyboard macro
533     @climacs{} does this by @emph{recording} whatever the user types on
534 rstrandh 1.6 the keyboard, and then making it possibly to @emph{replay} the
535 rstrandh 1.3 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 rstrandh 1.4
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 rstrandh 1.6 (@command{Describe Key Briefly}). You will be prompted for a key
592 rstrandh 1.4 sequence. If the key sequence you type is bound to a command, the
593 rstrandh 1.6 command name will be displayed in the minibuffer. Otherwise, a message
594 rstrandh 1.4 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 rstrandh 1.7
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 rstrandh 1.1
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