43BSDReno/contrib/emacs-18.55/info/emacs-2 - annotate

Return to emacs-2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info

Annotation of 43BSDReno/contrib/emacs-18.55/info/emacs-2, revision 1.1.1.1

1.1 root 1: Info file emacs, produced by texinfo-format-buffer -*-Text-*-
2: from file emacs.tex
3:
4: This file documents the GNU Emacs editor.
5:
6: Copyright (C) 1985, 1986 Richard M. Stallman.
7:
8: Permission is granted to make and distribute verbatim copies of
9: this manual provided the copyright notice and this permission notice
10: are preserved on all copies.
11:
12: Permission is granted to copy and distribute modified versions of this
13: manual under the conditions for verbatim copying, provided also that the
14: sections entitled "The GNU Manifesto", "Distribution" and "GNU Emacs
15: General Public License" are included exactly as in the original, and
16: provided that the entire resulting derived work is distributed under the
17: terms of a permission notice identical to this one.
18:
19: Permission is granted to copy and distribute translations of this manual
20: into another language, under the above conditions for modified versions,
21: except that the sections entitled "The GNU Manifesto", "Distribution"
22: and "GNU Emacs General Public License" may be included in a translation
23: approved by the author instead of in the original English.
24:
25:
26: File: emacs Node: Basic, Prev: Command Switches, Up: Top, Next: Undo
27:
28: Basic Editing Commands
29: **********************
30:
31: We now give the basics of how to enter text, make corrections, and
32: save the text in a file. If this material is new to you, you might
33: learn it more easily by running the Emacs learn-by-doing tutorial. To
34: do this, type `Control-h t' (`help-with-tutorial').
35:
36:
37: Inserting Text
38: ==============
39:
40: To insert printing characters into the text you are editing, just type
41: them. This inserts the character into the buffer at the cursor (that is,
42: at "point"; *Note Point::). The cursor moves forward. Any characters
43: after the cursor move forward too. If the text in the buffer is
44: `FOOBAR', with the cursor before the `B', then if you type
45: `XX', you get `FOOXXBAR', with the cursor still before the
46: `B'.
47:
48: To "delete" text you have just inserted, use DEL. DEL
49: deletes the character BEFORE the cursor (not the one that the cursor
50: is on top of or under; that is the character AFTER the cursor). The
51: cursor and all characters after it move backwards. Therefore, if you type
52: a printing character and then type DEL, they cancel out.
53:
54: To end a line and start typing a new one, type RET. This inserts
55: a newline character in the buffer. If point is in the middle of a line,
56: RET splits the line. Typing DEL when the cursor is at the
57: beginning of a line rubs out the newline before the line, thus joining the
58: line with the preceding line.
59:
60: Emacs will split lines automatically when they become too long, if you
61: turn on a special mode called "Auto Fill" mode. *Note Filling::, for
62: how to use Auto Fill mode.
63:
64: Customization information: DEL in most modes runs the command named
65: `delete-backward-char'; RET runs the command `newline', and
66: self-inserting printing characters run the command `self-insert',
67: which inserts whatever character was typed to invoke it. Some major modes
68: rebind DEL to other commands.
69:
70: Direct insertion works for printing characters and SPC, but other
71: characters act as editing commands and do not insert themselves. If you
72: need to insert a control character or a character whose code is above 200
73: octal, you must "quote" it by typing the character `control-q'
74: (`quoted-insert') first. There are two ways to use `C-q':
75:
76: * `Control-q' followed by any non-graphic character (even `C-g')
77: inserts that character.
78: * `Control-q' followed by three octal digits inserts the character
79: with the specified character code.
80:
81: A numeric argument to `C-q' specifies how many copies of the
82: quoted character should be inserted (*Note Arguments::).
83:
84: If you prefer to have text characters replace (overwrite) existing
85: text rather than shove it to the right, you can enable Overwrite mode,
86: a minor mode. *Note Minor Modes::.
87:
88:
89: Changing the Location of Point
90: ==============================
91:
92: To do more than insert characters, you have to know how to move
93: point (*Note Point::). Here are a few of the commands for doing that.
94:
95: `C-a'
96: Move to the beginning of the line (`beginning-of-line').
97: `C-e'
98: Move to the end of the line (`end-of-line').
99: `C-f'
100: Move forward one character (`forward-char').
101: `C-b'
102: Move backward one character (`backward-char').
103: `M-f'
104: Move forward one word (`forward-word').
105: `M-b'
106: Move backward one word (`backward-word').
107: `C-n'
108: Move down one line, vertically (`next-line'). This command
109: attempts to keep the horizontal position unchanged, so if you start in
110: the middle of one line, you end in the middle of the next. When on
111: the last line of text, `C-n' creates a new line and moves onto it.
112: `C-p'
113: Move up one line, vertically (`previous-line').
114: `C-l'
115: Clear the screen and reprint everything (`recenter'). Text moves
116: on the screen to bring point to the center of the window.
117: `M-r'
118: Move point to left margin on the line halfway down the screen or
119: window (`move-to-window-line'). Text does not move on the
120: screen. A numeric argument says how many screen lines down from the
121: top of the window (zero for the top). A negative argument counts from
122: the bottom (-1 for the bottom).
123: `C-t'
124: Transpose two characters, the ones before and after the cursor
125: (`transpose-chars').
126: `M-<'
127: Move to the top of the buffer (`beginning-of-buffer'). With numeric
128: argument N, move to N/10 of the way from the top. *Note Arguments::,
129: for more information on numeric arguments.
130: `M->'
131: Move to the end of the buffer (`end-of-buffer').
132: `M-x goto-char'
133: Read a number N and move cursor to character number N.
134: Position 1 is the beginning of the buffer.
135: `M-x goto-line'
136: Read a number N and move cursor to line number N. Line 1
137: is the beginning of the buffer.
138: `C-x C-n'
139: Use the current column of point as the "semipermanent goal column" for
140: `C-n' and `C-p' (`set-goal-column'). Henceforth, those
141: commands always move to this column in each line moved into, or as
142: close as possible given the contents of the line. This goal column remains
143: in effect until canceled.
144: `C-u C-x C-n'
145: Cancel the goal column. Henceforth, `C-n' and `C-p' once
146: again try to avoid changing the horizontal position, as usual.
147:
148: If you set the variable `track-eol' to a non-`nil' value, then
149: `C-n' and `C-p' when at the end of the starting line move to the
150: end of the line. Normally, `track-eol' is `nil'.
151:
152:
153: Erasing Text
154: ============
155:
156: `DEL'
157: Delete the character before the cursor (`delete-backward-char').
158: `C-d'
159: Delete the character after the cursor (`delete-char').
160: `C-k'
161: Kill to the end of the line (`kill-line').
162: `M-d'
163: Kill forward to the end of the next word (`kill-word').
164: `M-DEL'
165: Kill back to the beginning of the previous word
166: (`backward-kill-word').
167:
168: You already know about the DEL key which deletes the character
169: before the cursor. Another key, `Control-d', deletes the character
170: after the cursor, causing the rest of the text on the line to shift left.
171: If `Control-d' is typed at the end of a line, that line and the next
172: line are joined together.
173:
174: To erase a larger amount of text, use the `Control-k' key, which
175: kills a line at a time. If `C-k' is done at the beginning or middle of
176: a line, it kills all the text up to the end of the line. If `C-k' is
177: done at the end of a line, it joins that line and the next line.
178:
179: *Note Killing::, for more flexible ways of killing text.
180:
181:
182: Files
183: =====
184:
185: The commands above are sufficient for creating and altering text in an
186: Emacs buffer; the more advanced Emacs commands just make things easier.
187: But to keep any text permanently you must put it in a "file". Files
188: are named units of text which are stored by the operating system for you to
189: retrieve later by name. To look at or use the contents of a file in any
190: way, including editing the file with Emacs, you must specify the file name.
191:
192: Consider a file named `/usr/rms/foo.c'. In Emacs, to begin editing
193: this file, type
194:
195: C-x C-f /usr/rms/foo.c RET
196:
197: Here the file name is given as an "argument" to the command `C-x C-f'
198: (`find-file'). That command uses the "minibuffer" to read the argument,
199: and you type RET to terminate the argument (*Note Minibuffer::).
200:
201: Emacs obeys the command by "visiting" the file: creating a buffer,
202: copying the contents of the file into the buffer, and then displaying the
203: buffer for you to edit. You can make changes in it, and then "save" the
204: file by typing `C-x C-s' (`save-buffer'). This makes the changes permanent
205: by copying the altered contents of the buffer back into the file
206: `/usr/rms/foo.c'. Until then, the changes are only inside your Emacs, and
207: the file `foo.c' is not changed.
208:
209: To create a file, just visit the file with `C-x C-f' as if it already
210: existed. Emacs will make an empty buffer in which you can insert the text
211: you want to put in the file. When you save your text with `C-x C-s',
212: the file will be created.
213:
214: Of course, there is a lot more to learn about using files. *Note Files::.
215:
216:
217: Help
218: ====
219:
220: If you forget what a key does, you can find out with the Help character,
221: which is `C-h'. Type `C-h k' followed by the key you want to know about;
222: for example, `C-h k C-n' tells you all about what `C-n' does. `C-h' is a
223: prefix key; `C-h k' is just one of its subcommands (the command
224: `describe-key'). The other subcommands of `C-h' provide different kinds of
225: help. Type `C-h' three times to get a description of all the help
226: facilities. *Note Help::.
227:
228: * Menu:
229:
230: * Blank Lines:: Commands to make or delete blank lines.
231: * Continuation Lines:: Lines too wide for the screen.
232: * Position Info:: What page, line, row, or column is point on?
233: * Arguments:: Numeric arguments for repeating a command.
234:
235:
236: File: emacs Node: Blank Lines, Prev: Basic, Up: Basic, Next: Continuation Lines
237:
238: Blank Lines
239: ===========
240:
241: Here are special commands and techniques for putting in and taking out
242: blank lines.
243:
244: `C-o'
245: Insert one or more blank lines after the cursor (`open-line').
246: `C-x C-o'
247: Delete all but one of many consecutive blank lines
248: (`delete-blank-lines').
249:
250: When you want to insert a new line of text before an existing line, you
251: can do it by typing the new line of text, followed by RET. However,
252: it may be easier to see what you are doing if you first make a blank line
253: and then insert the desired text into it. This is easy to do using the key
254: `C-o' (`open-line'), which inserts a newline after point but leaves
255: point in front of the newline. After `C-o', type the text for the new
256: line. `C-o F O O' has the same effect as `F O O RET', except for
257: the final location of point.
258:
259: You can make several blank lines by typing `C-o' several times, or by
260: giving it an argument to tell it how many blank lines to make.
261: *Note Arguments::, for how.
262:
263: If you have many blank lines in a row and want to get rid of them, use
264: `C-x C-o' (`delete-blank-lines'). When point is on a blank line which
265: is adjacent to at least one other blank line, `C-x C-o' deletes all but
266: one of the consecutive blank lines, leaving exactly one. With point on a
267: blank line with no other blank line adjacent to it, the sole blank line is
268: deleted, leaving none. When point is on a nonblank line, `C-x C-o'
269: deletes any blank lines following that nonblank line.
270:
271:
272: File: emacs Node: Continuation Lines, Prev: Blank Lines, Up: Basic, Next: Position Info
273:
274: Continuation Lines
275: ==================
276:
277: If you add too many characters to one line, without breaking it with a
278: RET, the line will grow to occupy two (or more) lines on the screen,
279: with a `\' at the extreme right margin of all but the last of them.
280: The `\' says that the following screen line is not really a distinct
281: line in the text, but just the "continuation" of a line too long to fit
282: the screen. Sometimes it is nice to have Emacs insert newlines
283: automatically when a line gets too long; for this, use Auto Fill mode
284: (*Note Filling::).
285:
286: Instead of continuation, long lines can be displayed by "truncation".
287: This means that all the characters that do not fit in the width of the
288: screen or window do not appear at all. They remain in the buffer,
289: temporarily invisible. `$' is used in the last column instead of
290: `\' to inform you that truncation is in effect.
291:
292: Continuation can be turned off for a particular buffer by setting the
293: variable `truncate-lines' to non-`nil' in that buffer. Truncation instead
294: of continuation also happens whenever horizontal scrolling is in use, and
295: optionally whenever side-by-side windows are in use (*Note Windows::).
296: Altering the value of `truncate-lines' makes it local to the current
297: buffer; until that time, the default value is in effect. The default is
298: initially `nil'. *Note Locals::.
299:
300:
301: File: emacs Node: Position Info, Prev: Continuation Lines, Up: Basic, Next: Arguments
302:
303: Cursor Position Information
304: ===========================
305:
306: If you are accustomed to other display editors, you may be surprised that
307: Emacs does not always display the page number or line number of point in
308: the mode line. This is because the text is stored in a way that makes it
309: difficult to compute this information. Displaying them all the time would
310: be intolerably slow. They are not needed very often in Emacs anyway,
311: but there are commands to compute them and print them.
312:
313: `M-x what-page'
314: Print page number of point, and line number within page.
315: `M-x what-line'
316: Print line number of point in the buffer.
317: `M-='
318: Print number of lines in the current region (`count-lines-region').
319: `C-x ='
320: Print character code of character after point, character position of
321: point, and column of point (`what-cursor-position').
322:
323: There are two commands for printing line numbers. `M-x what-line'
324: counts lines from the beginning of the file and prints the line number
325: point is on. The first line of the file is line number 1. These numbers
326: can be used as arguments to `M-x goto-line'. By contrast, `M-x
327: what-page' counts pages from the beginning of the file, and counts lines
328: within the page, printing both of them. *Note Pages::.
329:
330: While on this subject, we might as well mention `M-=' (`count-lines-region'),
331: which prints the number of lines in the region (*Note Mark::).
332: *Note Pages::, for the command `C-x l' which counts the lines in the
333: current page.
334:
335: The command `C-x =' (`what-cursor-position') can be used to find out
336: the column that the cursor is in, and other miscellaneous information about
337: point. It prints a line in the echo area that looks like this:
338:
339: Char: x (0170) point=65986 of 563027(12%) x=44
340:
341: (In fact, this is the output produced when point is before the `x=44'
342: in the example.)
343:
344: The two values after `Char:' describe the character following point,
345: first by showing it and second by giving its octal character code.
346:
347: `point=' is followed by the position of point expressed as a character
348: count. The front of the buffer counts as position 1, one character later
349: as 2, and so on. The next, larger number is the total number of characters
350: in the buffer. Afterward in parentheses comes the position expressed as a
351: percentage of the total size.
352:
353: `x=' is followed by the horizontal position of point, in columns from the
354: left edge of the window.
355:
356: If the buffer has been narrowed, making some of the text at the beginning and
357: the end temporarily invisible, `C-x =' prints additional text describing the
358: current visible range. For example, it might say
359:
360: Char: x (0170) point=65986 of 563025(12%) <65102 - 68533> x=44
361:
362: where the two extra numbers give the smallest and largest character position
363: that point is allowed to assume. The characters between those two positions
364: are the visible ones. *Note Narrowing::.
365:
366: If point is at the end of the buffer (or the end of the visible part),
367: `C-x =' omits any description of the character after point.
368: The output looks like
369:
370: point=563026 of 563025(100%) x=0
371:
372:
373: File: emacs Node: Arguments, Prev: Position Info, Up: Basic
374:
375: Numeric Arguments
376: =================
377:
378: Any Emacs command can be given a "numeric argument". Some commands
379: interpret the argument as a repetition count. For example, giving an
380: argument of ten to the key `C-f' (the command `forward-char', move
381: forward one character) moves forward ten characters. With these commands,
382: no argument is equivalent to an argument of one. Negative arguments are
383: allowed. Often they tell a command to move or act backwards.
384:
385: If your terminal keyboard has a META key, the easiest way to
386: specify a numeric argument is to type digits and/or a minus sign while
387: holding down the the META key. For example,
388: M-5 C-n
389: would move down five lines. The characters `Meta-1', `Meta-2', and
390: so on, as well as `Meta--', do this because they are keys bound to
391: commands (`digit-argument' and `negative-argument') that are
392: defined to contribute to an argument for the next command.
393:
394: Another way of specifying an argument is to use the `C-u'
395: (`universal-argument') command followed by the digits of the argument.
396: With `C-u', you can type the argument digits without holding
397: down shift keys. To type a negative argument, start with a minus sign.
398: Just a minus sign normally means -1. `C-u' works on all terminals.
399:
400: `C-u' followed by a character which is neither a digit nor a minus sign
401: has the special meaning of "multiply by four". It multiplies the argument
402: for the next command by four. `C-u' twice multiplies it by sixteen. Thus,
403: `C-u C-u C-f' moves forward sixteen characters. This is a good way to move
404: forward "fast", since it moves about 1/5 of a line in the usual size
405: screen. Other useful combinations are `C-u C-n', `C-u C-u C-n' (move down
406: a good fraction of a screen), `C-u C-u C-o' (make "a lot" of blank lines),
407: and `C-u C-k' (kill four lines).
408:
409: Some commands care only about whether there is an argument, and not about
410: its value. For example, the command `M-q' (`fill-paragraph') with
411: no argument fills text; with an argument, it justifies the text as well.
412: (*Note Filling::, for more information on `M-q'.) Just `C-u' is a
413: handy way of providing an argument for such commands.
414:
415: Some commands use the value of the argument as a repeat count, but do
416: something peculiar when there is no argument. For example, the command
417: `C-k' (`kill-line') with argument N kills N lines, including their
418: terminating newlines. But `C-k' with no argument is special: it kills the
419: text up to the next newline, or, if point is right at the end of the line,
420: it kills the newline itself. Thus, two `C-k' commands with no arguments
421: can kill a nonblank line, just like `C-k' with an argument of one. (*Note
422: Killing::, for more information on `C-k'.)
423:
424: A few commands treat a plain `C-u' differently from an ordinary
425: argument. A few others may treat an argument of just a minus sign
426: differently from an argument of -1. These unusual cases will be described
427: when they come up; they are always for reasons of convenience of use of the
428: individual command.
429:
430:
431:
432: File: emacs Node: Undo, Prev: Basic, Up: Top, Next: Minibuffer
433:
434: Undoing Changes
435: ***************
436:
437: Emacs allows all changes made in the text of a buffer to be undone,
438: up to a certain amount of change (8000 characters). Each buffer records
439: changes individually, and the undo command always applies to the
440: current buffer. Usually each editing command makes a separate entry
441: in the undo records, but some commands such as `query-replace'
442: make many entries, and very simple commands such as self-inserting
443: characters are often grouped to make undoing less tedious.
444:
445: `C-x u'
446: Undo one batch of changes (usually, one command worth) (`undo').
447: `C-_'
448: The same.
449:
450: The command `C-x u' or `C-_' is how you undo. The first time you give
451: this command, it undoes the last change. Point moves to the text
452: affected by the undo, so you can see what was undone.
453:
454: Consecutive repetitions of the `C-_' or `C-x u' commands undo earlier
455: and earlier changes, back to the limit of what has been recorded. If all
456: recorded changes have already been undone, the undo command prints an error
457: message and does nothing.
458:
459: Any command other than an undo command breaks the sequence of undo
460: commands. Starting at this moment, the previous undo commands are
461: considered ordinary changes that can themselves be undone. Thus, you can
462: redo changes you have undone by typing `C-f' or any other command that
463: will have no important effect, and then using more undo commands.
464:
465: If you notice that a buffer has been modified accidentally, the easiest
466: way to recover is to type `C-_' repeatedly until the stars disappear
467: from the front of the mode line. At this time, all the modifications you
468: made have been cancelled. If you do not remember whether you changed the
469: buffer deliberately, type `C-_' once, and when you see the last change
470: you made undone, you will remember why you made it. If it was an accident,
471: leave it undone. If it was deliberate, redo the change as described in the
472: preceding paragraph.
473:
474: Whenever an undo command makes the stars disappear from the mode line,
475: it means that the buffer contents are the same as they were when the
476: file was last read in or saved.
477:
478: Not all buffers record undo information. Buffers whose names start with
479: spaces don't; these buffers are used internally by Emacs and its extensions
480: to hold text that users don't normally look at or edit. Also, minibuffers,
481: help buffers and documentation buffers don't record undo information.
482:
483: At most 8000 or so characters of deleted or modified text can be
484: remembered in any one buffer for reinsertion by the undo command. Also,
485: there is a limit on the number of individual insert, delete or change
486: actions that can be remembered.
487:
488: The reason the `undo' command has two keys, `C-x u' and `C-_', set
489: up to run it is that it is worthy of a single-character key, but the way to
490: type `C-_' on some keyboards is not obvious. `C-x u' is an alternative
491: you can type in the same fashion on any terminal.
492:
493:
494: File: emacs Node: Minibuffer, Prev: Undo, Up: Top, Next: M-x
495:
496: The Minibuffer
497: **************
498:
499: The "minibuffer" is the facility used by Emacs commands to read
500: arguments more complicated than a single number. Minibuffer arguments can
501: be file names, buffer names, Lisp function names, Emacs command names, Lisp
502: expressions, and many other things, depending on the command reading the
503: argument. The usual Emacs editing commands can be used in the minibuffer
504: to edit the argument.
505:
506: When the minibuffer is in use, it appears in the echo area, and the
507: terminal's cursor moves there. The beginning of the minibuffer line
508: displays a "prompt" which says what kind of input you should supply and
509: how it will be used. Often this prompt is derived from the name of the
510: command that the argument is for. The prompt normally ends with a colon.
511:
512: Sometimes a "default argument" appears in parentheses after the
513: colon; it too is part of the prompt. The default will be used as the
514: argument value if you enter an empty argument (e.g., just type RET).
515: For example, commands that read buffer names always show a default, which
516: is the name of the buffer that will be used if you type just RET.
517:
518: The simplest way to give a minibuffer argument is to type the text you
519: want, terminated by RET which exits the minibuffer. You can get out
520: of the minibuffer, canceling the command that it was for, by typing
521: `C-g'.
522:
523: Since the minibuffer uses the screen space of the echo area, it can
524: conflict with other ways Emacs customarily uses the echo area. Here is how
525: Emacs handles such conflicts:
526:
527: * If a command gets an error while you are in the minibuffer, this does
528: not cancel the minibuffer. However, the echo area is needed for the
529: error message and therefore the minibuffer itself is hidden for a
530: while. It comes back after a few seconds, or as soon as you type
531: anything.
532:
533: * If in the minibuffer you use a command whose purpose is to print a
534: message in the echo area, such as `C-x =', the message is printed
535: normally, and the minibuffer is hidden for a while. It comes back
536: after a few seconds, or as soon as you type anything.
537:
538: * Echoing of keystrokes does not take place while the minibuffer is in
539: use.
540:
541: * Menu:
542:
543: * File: Minibuffer File. Entering file names with the minibuffer.
544: * Edit: Minibuffer Edit. How to edit in the minibuffer.
545: * Completion:: An abbreviation facility for minibuffer input.
546: * Repetition:: Re-executing commands that used the minibuffer.
547:
548:
549: File: emacs Node: Minibuffer File, Prev: Minibuffer, Up: Minibuffer, Next: Minibuffer Edit
550:
551: Minibuffers for File Names
552: ==========================
553:
554: Sometimes the minibuffer starts out with text in it. For example, when
555: you are supposed to give a file name, the minibuffer starts out containing
556: the "default directory", which ends with a slash. This is to inform
557: you which directory the file will be found in if you do not specify a
558: directory. For example, the minibuffer might start out with
559:
560: Find File: /u2/emacs/src/
561:
562: where `Find File: ' is the prompt. Typing `buffer.c' specifies the file
563: `/u2/emacs/src/buffer.c'. To find files in nearby directories, use `..';
564: thus, if you type `../lisp/simple.el', the file that you visit will be the
565: one named `/u2/emacs/lisp/simple.el'. Alternatively, you can kill with
566: `M-DEL' the directory names you don't want (*Note Words::).
567:
568: You can also type an absolute file name, one starting with a slash or a
569: tilde, ignoring the default directory. For example, to find the file
570: `/etc/termcap', just type the name, giving
571:
572: Find File: /u2/emacs/src//etc/termcap
573:
574: Two slashes in a row are not normally meaningful in Unix file names, but
575: they are allowed in GNU Emacs. They mean, "ignore everything before the
576: second slash in the pair." Thus, `/u2/emacs/src/' is ignored, and
577: you get the file `/etc/termcap'.
578:
579: If you set `insert-default-directory' to `nil', the default directory
580: is not inserted in the minibuffer. This way, the minibuffer starts out
581: empty. But the name you type, if relative, is still interpreted with
582: respect to the same default directory.
583:
584:
585: File: emacs Node: Minibuffer Edit, Prev: Minibuffer File, Up: Minibuffer, Next: Completion
586:
587: Editing in the Minibuffer
588: =========================
589:
590: The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual
591: Emacs commands are available for editing the text of an argument you are
592: entering.
593:
594: Since RET in the minibuffer is defined to exit the minibuffer,
595: inserting a newline into the minibuffer must be done with `C-o' or with
596: `C-q LFD'. (Recall that a newline is really the LFD
597: character.)
598:
599: The minibuffer has its own window which always has space on the screen
600: but acts as if it were not there when the minibuffer is not in use. When
601: the minibuffer is in use, its window is just like the others; you can
602: switch to another window with `C-x o', edit text in other windows and
603: perhaps even visit more files, before returning to the minibuffer to submit
604: the argument. You can kill text in another window, return to the
605: minibuffer window, and then yank the text to use it in the argument.
606: *Note Windows::.
607:
608: There are some restrictions on the use of the minibuffer window, however.
609: You cannot switch buffers in it---the minibuffer and its window are
610: permanently attached. Also, you cannot split or kill the minibuffer
611: window. But you can make it taller in the normal fashion with `C-x ^'.
612:
613: If while in the minibuffer you issue a command that displays help text
614: of any sort in another window, then that window is identified as the
615: one to scroll if you type `C-M-v' while in the minibuffer. This
616: lasts until you exit the minibuffer. This feature comes into play
617: if a completing minibuffer gives you a list of possible completions.
618:
619: Recursive use of the minibuffer is supported by Emacs. However, it is
620: easy to do this by accident (because of autorepeating keyboards, for
621: example) and get confused. Therefore, most Emacs commands that use the
622: minibuffer refuse to operate if the minibuffer window is selected. If the
623: minibuffer is active but you have switched to a different window, recursive
624: use of the minibuffer is allowed---if you know enough to try to do this,
625: you probably will not get confused.
626:
627: If you set the variable `enable-recursive-minibuffers' to be
628: non-`nil', recursive use of the minibuffer is always allowed.
629:
630:
631: File: emacs Node: Completion, Prev: Minibuffer Edit, Up: Minibuffer, Next: Repetition
632:
633: Completion
634: ==========
635:
636: When appropriate, the minibuffer provides a "completion" facility.
637: This means that you type enough of the argument to determine the rest,
638: based on Emacs's knowledge of which arguments make sense, and Emacs visibly
639: fills in the rest, or as much as can be determined from the part you have
640: typed.
641:
642: When completion is available, certain keys---TAB, RET, and SPC---are
643: redefined to complete an abbreviation present in the minibuffer into a
644: longer string that it stands for, by matching it against a set of
645: "completion alternatives" provided by the command reading the argument.
646: `?' is defined to display a list of possible completions of what you
647: have inserted.
648:
649: For example, when the minibuffer is being used by `Meta-x' to read
650: the name of a command, it is given a list of all available Emacs command
651: names to complete against. The completion keys match the text in the
652: minibuffer against all the command names, find any additional characters of
653: the name that are implied by the ones already present in the minibuffer,
654: and add those characters to the ones you have given.
655:
656: Case is normally significant in completion, because it is significant in
657: most of the names that you can complete (buffer names, file names and
658: command names). Thus, `fo' will not complete to `Foo'. When you
659: are completing a name in which case does not matter, case may be ignored
660: for completion's sake if the program said to do so.
661:
662:
663: Completion Example
664: ------------------
665:
666: A concrete example may help here. If you type `Meta-x au TAB', the TAB
667: looks for alternatives (in this case, command names) that start with `au'.
668: There are only two: `auto-fill-mode' and `auto-save-mode'. These are the
669: same as far as `auto-', so the `au' in the minibuffer changes to `auto-'.
670:
671: If you type TAB again immediately, there are multiple possibilities
672: for the very next character---it could be `s' or `f'---so no more
673: characters are added; but a list of all possible completions is displayed
674: in another window.
675:
676: If you go on to type `f TAB', this TAB sees `auto-f'. The only command
677: name starting this way is `auto-fill-mode', so completion inserts the rest
678: of that. You now have `auto-fill-mode' in the minibuffer after typing just
679: `au TAB f TAB'. Note that TAB has this effect because in the minibuffer it
680: is bound to the function `minibuffer-complete' when completion is supposed
681: to be done.
682:
683:
684: Completion Commands
685: -------------------
686:
687: Here is a list of all the completion commands, defined in the minibuffer
688: when completion is available.
689:
690: `TAB'
691: Complete the text in the minibuffer as much as possible
692: (`minibuffer-complete').
693: `SPC'
694: Complete the text in the minibuffer but don't add or fill out more
695: than one word (`minibuffer-complete-word').
696: `RET'
697: Submit the text in the minibuffer as the argument, possibly completing
698: first as described below (`minibuffer-complete-and-exit').
699: `?'
700: Print a list of all possible completions of the text in the minibuffer
701: (`minibuffer-list-completions').
702:
703: SPC completes much like TAB, but never goes beyond the next hyphen or
704: space. If you have `auto-f' in the minibuffer and type SPC, it finds that
705: the completion is `auto-fill-mode', but it stops completing after `fill-'.
706: This gives `auto-fill-'. Another SPC at this point completes all the way
707: to `auto-fill-mode'. SPC in the minibuffer runs the function
708: `minibuffer-complete-word' when completion is available.
709:
710: There are three different ways that RET can work in completing
711: minibuffers, depending on how the argument will be used.
712:
713: * "Strict" completion is used when it is meaningless to give any
714: argument except one of the known alternatives. For example, when
715: `C-x k' reads the name of a buffer to kill, it is meaningless to
716: give anything but the name of an existing buffer. In strict
717: completion, RET refuses to exit if the text in the minibuffer
718: does not complete to an exact match.
719:
720: * "Cautious" completion is similar to strict completion, except that
721: RET exits only if the text was an exact match already, not
722: needing completion. If the text is not an exact match, RET does
723: not exit, but it does complete the text. If it completes to an exact
724: match, a second RET will exit.
725:
726: Cautious completion is used for reading file names for files that must
727: already exist.
728:
729: * "Permissive" completion is used when any string whatever is
730: meaningful, and the list of completion alternatives is just a guide.
731: For example, when `C-x C-f' reads the name of a file to visit, any
732: file name is allowed, in case you want to create a file. In
733: permissive completion, RET takes the text in the minibuffer
734: exactly as given, without completing it.
735:
736: The completion commands display a list of all possible completions in a
737: window whenever there is more than one possibility for the very next
738: character. Also, typing `?' explicitly requests such a list. The
739: list of completions counts as help text, so `C-M-v' typed in the
740: minibuffer scrolls the list.
741:
742: When completion is done on file names, certain file names are usually
743: ignored. The variable `completion-ignored-extensions' contains a list of
744: strings; a file whose name ends in any of those strings is ignored as a
745: possible completion. The standard value of this variable has several
746: elements including `".o"', `".elc"', `".dvi"' and `"~"'. The effect is
747: that, for example, `foo' can complete to `foo.c' even though `foo.o' exists
748: as well. If the only possible completions are files that end in "ignored"
749: strings, then they are not ignored.
750:
751: Normally, a completion command that finds the next character is undetermined
752: automatically displays a list of all possible completions. If the variable
753: `completion-auto-help' is set to `nil', this does not happen,
754: and you must type `?' to display the possible completions.
755:
756:
757: File: emacs Node: Repetition, Prev: Completion, Up: Minibuffer
758:
759: Repeating Minibuffer Commands
760: =============================
761:
762: Every command that uses the minibuffer at least once is recorded on a
763: special history list, together with the values of the minibuffer arguments,
764: so that you can repeat the command easily. In particular, every
765: use of `Meta-x' is recorded, since `M-x' uses the minibuffer to
766: read the command name.
767:
768: `C-x ESC'
769: Re-execute a recent minibuffer command (`repeat-complex-command').
770: `M-p'
771: Within `C-x ESC', move to previous recorded command
772: (`previous-complex-command').
773: `M-n'
774: Within `C-x ESC', move to the next (more recent) recorded
775: command (`next-complex-command').
776: `M-x list-command-history'
777: Display the entire command history, showing all the commands
778: `C-x ESC' can repeat, most recent first.
779:
780: `C-x ESC' is used to re-execute a recent minibuffer-using
781: command. With no argument, it repeats the last such command. A numeric
782: argument specifies which command to repeat; one means the last one, and
783: larger numbers specify earlier ones.
784:
785: `C-x ESC' works by turning the previous command into a Lisp
786: expression and then entering a minibuffer initialized with the text for
787: that expression. If you type just RET, the command is repeated as
788: before. You can also change the command by editing the Lisp expression.
789: Whatever expression you finally submit is what will be executed. The
790: repeated command is added to the front of the command history unless it is
791: identical to the most recently executed command already there.
792:
793: Even if you don't understand Lisp syntax, it will probably be obvious
794: which command is displayed for repetition. If you do not change the text,
795: you can be sure it will repeat exactly as before.
796:
797: Once inside the minibuffer for `C-x ESC', if the command shown
798: to you is not the one you want to repeat, you can move around the list of
799: previous commands using `M-n' and `M-p'. `M-p' replaces the
800: contents of the minibuffer with the next earlier recorded command, and
801: `M-n' replaces them with the next later command. After finding the
802: desired previous command, you can edit its expression as usual and then
803: resubmit it by typing RET as usual. Any editing you have done on the
804: command to be repeated is lost if you use `M-n' or `M-p'.
805:
806: `M-p' is more useful than `M-n', since more often you will
807: initially request to repeat the most recent command and then decide to
808: repeat an older one instead. These keys are specially defined within
809: `C-x ESC' to run the commands `previous-complex-command' and
810: `next-complex-command'.
811:
812: The list of previous minibuffer-using commands is stored as a Lisp list
813: in the variable `command-history'. Each element is a Lisp expression
814: which describes one command and its arguments. Lisp programs can reexecute
815: a command by feeding the corresponding `command-history' element to
816: `eval'.
817:
818:
819: File: emacs Node: M-x, Prev: Minibuffer, Up: Top, Next: Help
820:
821: Running Commands by Name
822: ************************
823:
824: The Emacs commands that are used often or that must be quick to type are
825: bound to keys---short sequences of characters---for convenient use. Other
826: Emacs commands that do not need to be brief are not bound to keys; to run
827: them, you must refer to them by name.
828:
829: A command name is, by convention, made up of one or more words, separated
830: by hyphens; for example, `auto-fill-mode' or `manual-entry'. The
831: use of English words makes the command name easier to remember than a key
832: made up of obscure characters, even though it is more characters to type.
833: Any command can be run by name, even if it is also runnable by keys.
834:
835: The way to run a command by name is to start with `M-x', type the
836: command name, and finish it with RET. `M-x' uses the minibuffer
837: to read the command name. RET exits the minibuffer and runs the
838: command.
839:
840: Emacs uses the minibuffer for reading input for many different purposes;
841: on this occasion, the string `M-x' is displayed at the beginning of
842: the minibuffer as a "prompt" to remind you that your input should be
843: the name of a command to be run. *Note Minibuffer::, for full information
844: on the features of the minibuffer.
845:
846: You can use completion to enter the command name. For example, the
847: command `forward-char' can be invoked by name by typing
848:
849: M-x forward-char RET
850:
851: or
852:
853: M-x fo TAB c RET
854:
855: Note that `forward-char' is the same command that you invoke with
856: the key `C-f'. Any command (interactively callable function) defined
857: in Emacs can be called by its name using `M-x' whether or not any
858: keys are bound to it.
859:
860: If you type `C-g' while the command name is being read, you cancel
861: the `M-x' command and get out of the minibuffer, ending up at top level.
862:
863: To pass a numeric argument to the command you are invoking with
864: `M-x', specify the numeric argument before the `M-x'. `M-x'
865: passes the argument along to the function which it calls. The argument
866: value appears in the prompt while the command name is being read.
867:
868: Normally, when describing a command that is run by name, we omit the
869: RET that is needed to terminate the name. Thus we might speak of
870: `M-x auto-fill-mode' rather than `M-x auto-fill-mode RET'.
871: We mention the RET only when there is a need to emphasize its
872: presence, such as when describing a sequence of input that contains a
873: command name and arguments that follow it.
874:
875: `M-x' is defined to run the command `execute-extended-command',
876: which is responsible for reading the name of another command and invoking
877: it.
878:
879:
880: File: emacs Node: Help, Prev: M-x, Up: Top, Next: Mark
881:
882: Help
883: ****
884:
885: Emacs provides extensive help features which revolve around a single
886: character, `C-h'. `C-h' is a prefix key that is used only for
887: documentation-printing commands. The characters that you can type after
888: `C-h' are called "help options". One help option is `C-h';
889: that is how you ask for help about using `C-h'.
890:
891: `C-h C-h' prints a list of the possible help options, and then asks
892: you to go ahead and type the option. It prompts with a string
893:
894: A, B, C, F, I, K, L, M, N, S, T, V, W, C-c, C-d, C-n, C-w or C-h for more help:
895:
896: and you should type one of those characters.
897:
898: Typing a third `C-h' displays a description of what the options mean;
899: it still waits for you to type an option. To cancel, type `C-g'.
900:
901: Here is a summary of the defined help commands.
902:
903: `C-h a STRING RET'
904: Display list of commands whose names contain STRING
905: (`command-apropos').
906: `C-h b'
907: Display a table of all key bindings in effect now; local bindings of
908: the current major mode first, followed by all global bindings
909: (`describe-bindings').
910: `C-h c KEY'
911: Print the name of the command that KEY runs (`describe-key-briefly').
912: `c' is for `character'. For more extensive information on KEY,
913: use `C-h k'.
914: `C-h f FUNCTION RET'
915: Display documentation on the Lisp function named FUNCTION
916: (`describe-function'). Note that commands are Lisp functions, so
917: a command name may be used.
918: `C-h i'
919: Run Info, the program for browsing documentation files (`info').
920: The complete Emacs manual is available on-line in Info.
921: `C-h k KEY'
922: Display name and documentation of the command KEY runs (`describe-key').
923: `C-h l'
924: Display a description of the last 100 characters you typed
925: (`view-lossage').
926: `C-h m'
927: Display documentation of the current major mode (`describe-mode').
928: `C-h n'
929: Display documentation of Emacs changes, most recent first
930: (`view-emacs-news').
931: `C-h s'
932: Display current contents of the syntax table, plus an explanation of
933: what they mean (`describe-syntax').
934: `C-h t'
935: Display the Emacs tutorial (`help-with-tutorial').
936: `C-h v VAR RET'
937: Display the documentation of the Lisp variable VAR
938: (`describe-variable').
939: `C-h w COMMAND RET'
940: Print which keys run the command named COMMAND (`where-is').
941:
942:
943: Documentation for a Key
944: =======================
945:
946: The most basic `C-h' options are `C-h c' (`describe-key-briefly') and
947: `C-h k' (`describe-key'). `C-h c KEY' prints in the echo area the name of
948: the command that KEY is bound to. For example, `C-h c C-f' prints
949: `forward-char'. Since command names are chosen to describe what the
950: command does, this is a good way to get a very brief description of what
951: KEY does.
952:
953: `C-h k KEY' is similar but gives more information. It displays
954: the documentation string of the command KEY is bound to as well as
955: its name. This is too big for the echo area, so a window is used for the
956: display.
957:
958:
959: Help by Command or Variable Name
960: ================================
961:
962: `C-h f' (`describe-function') reads the name of a Lisp function
963: using the minibuffer, then displays that function's documentation string
964: in a window. Since commands are Lisp functions, you can use this to get
965: the documentation of a command that is known by name. For example,
966:
967: C-h f auto-fill-mode RET
968:
969: displays the documentation of `auto-fill-mode'. This is the only
970: way to see the documentation of a command that is not bound to any key
971: (one which you would normally call using `M-x').
972:
973: `C-h f' is also useful for Lisp functions that you are planning to
974: use in a Lisp program. For example, if you have just written the code
975: `(make-vector len)' and want to be sure that you are using
976: `make-vector' properly, type `C-h f make-vector RET'. Because
977: `C-h f' allows all function names, not just command names, you may find
978: that some of your favorite abbreviations that work in `M-x' don't work
979: in `C-h f'. An abbreviation may be unique among command names yet fail
980: to be unique when other function names are allowed.
981:
982: The function name for `C-h f' to describe has a default which is
983: used if you type RET leaving the minibuffer empty. The default is
984: the function called by the innermost Lisp expression in the buffer around
985: point, provided that is a valid, defined Lisp function name. For
986: example, if point is located following the text `(make-vector (car
987: x)', the innermost list containing point is the one that starts with
988: `(make-vector', so the default is to describe the function
989: `make-vector'.
990:
991: `C-h f' is often useful just to verify that you have the right
992: spelling for the function name. If `C-h f' mentions a default in the
993: prompt, you have typed the name of a defined Lisp function. If that tells
994: you what you want to know, just type `C-g' to cancel the `C-h f'
995: command and go on editing.
996:
997: `C-h w COMMAND RET' tells you what keys are bound to COMMAND. It prints
998: a list of the keys in the echo area. Alternatively, it says that the
999: command is not on any keys, which implies that you must use `M-x' to call
1000: it.
1001:
1002: `C-h v' (`describe-variable') is like `C-h f' but describes Lisp
1003: variables instead of Lisp functions. Its default is the Lisp symbol around
1004: or before point, but only if that is the name of a known Lisp variable.
1005: *Note Variables::.
1006:
1007:
1008: Apropos
1009: =======
1010:
1011: A more sophisticated sort of question to ask is, "What are the commands
1012: for working with files?" For this, type `C-h a file RET', which displays a
1013: list of all command names that contain `file', such as `copy-file',
1014: `find-file', and so on. With each command name appears a brief description
1015: of how to use the command, and what keys you can currently invoke it with.
1016: For example, it would say that you can invoke `find-file' by typing `C-x
1017: C-f'. The `a' in `C-h a' stands for `Apropos'; `C-h a' runs the Lisp
1018: function `command-apropos'.
1019:
1020: Because `C-h a' looks only for functions whose names contain the
1021: string which you specify, you must use ingenuity in choosing the string.
1022: If you are looking for commands for killing backwards and `C-h a
1023: kill-backwards RET' doesn't reveal any, don't give up. Try just
1024: `kill', or just `backwards', or just `back'. Be persistent.
1025: Pretend you are playing Adventure. Also note that you can use a
1026: regular expression as the argument (*Note Regexps::).
1027:
1028: Here is a set of arguments to give to `C-h a' that covers many
1029: classes of Emacs commands, since there are strong conventions for naming
1030: the standard Emacs commands. By giving you a feel for the naming
1031: conventions, this set should also serve to aid you in developing a
1032: technique for picking `apropos' strings.
1033:
1034: char, line, word, sentence, paragraph, region, page, sexp, list, defun,
1035: buffer, screen, window, file, dir, register, mode,
1036: beginning, end, forward, backward, next, previous, up, down, search, goto,
1037: kill, delete, mark, insert, yank, fill, indent, case,
1038: change, set, what, list, find, view, describe.
1039:
1040: To list all Lisp symbols that contain a match for a regexp, not just
1041: the ones that are defined as commands, use the command `M-x apropos'
1042: instead of `C-h a'.
1043:
1044:
1045: Other Help Commands
1046: ===================
1047:
1048: `C-h i' (`info') runs the Info program, which is used for
1049: browsing through structured documentation files. The entire Emacs manual
1050: is available within Info. Eventually all the documentation of the GNU
1051: system will be available. Type `h' after entering Info to run
1052: a tutorial on using Info.
1053:
1054: If something surprising happens, and you are not sure what commands you
1055: typed, use `C-h l' (`view-lossage'). `C-h l' prints the last
1056: 100 command characters you typed in. If you see commands that you don't
1057: know, you can use `C-h c' to find out what they do.
1058:
1059: Emacs has several major modes, each of which redefines a few keys and
1060: makes a few other changes in how editing works. `C-h m' (`describe-mode')
1061: prints documentation on the current major mode, which normally describes
1062: all the commands that are changed in this mode.
1063:
1064: `C-h b' (`describe-bindings') and `C-h s' (`describe-syntax') present
1065: other information about the current Emacs mode. `C-h b' displays a list of
1066: all the key bindings now in effect; the local bindings of the current major
1067: mode first, followed by the global bindings (*Note Key Bindings::). `C-h
1068: s' displays the contents of the syntax table, with explanations of each
1069: character's syntax (*Note Syntax::).
1070:
1071: The other `C-h' options display various files of useful information.
1072: `C-h C-w' displays the full details on the complete absence of warranty for
1073: GNU Emacs. `C-h n' (`view-emacs-news') displays the file `emacs/etc/NEWS',
1074: which contains documentation on Emacs changes arranged chronologically.
1075: `C-h t' (`help-with-tutorial') displays the learn-by-doing Emacs tutorial.
1076: `C-h C-c' (`describe-copying') displays the file `emacs/etc/COPYING', which
1077: tells you the conditions you must obey in distributing copies of Emacs.
1078: `C-h C-d' (`describe-distribution') displays the file `emacs/etc/DISTRIB',
1079: which tells you how you can order a copy of the latest version of Emacs.
1080:
1081:
1082: File: emacs Node: Mark, Prev: Help, Up: Top, Next: Killing
1083:
1084: The Mark and the Region
1085: ***********************
1086:
1087: There are many Emacs commands which operate on an arbitrary contiguous
1088: part of the current buffer. To specify the text for such a command to
1089: operate on, you set "the mark" at one end of it, and move point to the
1090: other end. The text between point and the mark is called "the region".
1091: You can move point or the mark to adjust the boundaries of the region. It
1092: doesn't matter which one is set first chronologically, or which one comes
1093: earlier in the text.
1094:
1095: Once the mark has been set, it remains until it is set again at another
1096: place. The mark remains fixed with respect to the preceding character if
1097: text is inserted or deleted in the buffer. Each Emacs buffer has its own
1098: mark, so that when you return to a buffer that had been selected
1099: previously, it has the same mark it had before.
1100:
1101: Many commands that insert text, such as `C-y' (`yank') and
1102: `M-x insert-buffer', position the mark at one end of the inserted
1103: text---the opposite end from where point is positioned, so that the region
1104: contains the text just inserted.
1105:
1106: Aside from delimiting the region, the mark is also useful for remembering
1107: a spot that you may want to go back to. To make this feature more useful,
1108: Emacs remembers 16 previous locations of the mark, in the `mark ring'.
1109:
1110: * Menu:
1111:
1112: * Setting Mark:: Commands to set the mark.
1113: * Using Region:: Summary of ways to operate on contents of the region.
1114: * Marking Objects:: Commands to put region around textual units.
1115: * Mark Ring:: Previous mark positions saved so you can go back there.
1116:
1117:
1118: File: emacs Node: Setting Mark, Prev: Mark, Up: Mark, Next: Using Region
1119:
1120: Setting the Mark
1121: ================
1122:
1123: Here are some commands for setting the mark:
1124:
1125: `C-SPC'
1126: Set the mark where point is (`set-mark-command').
1127: `C-@'
1128: The same.
1129: `C-x C-x'
1130: Interchange mark and point (`exchange-point-and-mark').
1131:
1132: For example, if you wish to convert part of the buffer to all upper-case,
1133: you can use the `C-x C-u' (`upcase-region') command, which operates
1134: on the text in the region. You can first go to the beginning of the text
1135: to be capitalized, type `C-SPC' to put the mark there, move to
1136: the end, and then type `C-x C-u'. Or, you can set the mark at the end
1137: of the text, move to the beginning, and then type `C-x C-u'. Most
1138: commands that operate on the text in the region have the word `region'
1139: in their names.
1140:
1141: The most common way to set the mark is with the `C-SPC' command
1142: (`set-mark-command'). This sets the mark where point is. Then you
1143: can move point away, leaving the mark behind. It is actually incorrect to
1144: speak of the character `C-SPC'; there is no such character. When
1145: you type SPC while holding down CTRL, what you get on most
1146: terminals is the character `C-@'. This is the key actually bound to
1147: `set-mark-command'. But unless you are unlucky enough to have a
1148: terminal where typing `C-SPC' does not produce `C-@', you
1149: might as well think of this character as `C-SPC'.
1150:
1151: Since terminals have only one cursor, there is no way for Emacs to show
1152: you where the mark is located. You have to remember. The usual solution
1153: to this problem is to set the mark and then use it soon, before you forget
1154: where it is. But you can see where the mark is with the command `C-x
1155: C-x' (`exchange-point-and-mark') which puts the mark where point was and
1156: point where the mark was. The extent of the region is unchanged, but the
1157: cursor and point are now at the previous location of the mark.
1158:
1159: `C-x C-x' is also useful when you are satisfied with the location of
1160: point but want to move the mark; do `C-x C-x' to put point there and
1161: then you can move it. A second use of `C-x C-x', if necessary, puts
1162: the mark at the new location with point back at its original location.
1163:
1164:

unix.superglobalmegacorp.com

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.