1 |
Author: fauli |
2 |
Date: 2009-07-02 08:28:30 +0000 (Thu, 02 Jul 2009) |
3 |
New Revision: 1283 |
4 |
|
5 |
Added: |
6 |
emacsguide/ |
7 |
emacsguide/emacsguide.xml |
8 |
Log: |
9 |
temporary location for Emacs user guide, provided by Marc Murphy |
10 |
|
11 |
Added: emacsguide/emacsguide.xml |
12 |
=================================================================== |
13 |
--- emacsguide/emacsguide.xml (rev 0) |
14 |
+++ emacsguide/emacsguide.xml 2009-07-02 08:28:30 UTC (rev 1283) |
15 |
@@ -0,0 +1,482 @@ |
16 |
+<?xml version="1.0" encoding="UTF-8"?> |
17 |
+<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
18 |
+<!-- $Header$ --> |
19 |
+ |
20 |
+<guide link="/doc/en/emacsguide.xml" lang="en"> |
21 |
+ <title>GNU Emacs Introduction</title> |
22 |
+ |
23 |
+ <author title="Author"> |
24 |
+ <mail link="clock_cycles@×××××.com">Marc Murphy</mail> |
25 |
+ </author> |
26 |
+ <author title="Contributor"> |
27 |
+ <mail link="fauli@g.o">Christian Faulhammer</mail> |
28 |
+ </author> |
29 |
+ |
30 |
+ <abstract> |
31 |
+ This guide is meant to be a nice introduction to GNU Emacs in Gentoo. |
32 |
+ </abstract> |
33 |
+ |
34 |
+ <!-- The content of this document is licensed under the CC-BY-SA |
35 |
+ license --> |
36 |
+ <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
37 |
+ <license/> |
38 |
+ |
39 |
+ <version>0.44</version> |
40 |
+ <date>2009-07-02</date> |
41 |
+ |
42 |
+ <chapter> |
43 |
+ <title>Installation and setup</title> |
44 |
+ <section> |
45 |
+ <title>Installing</title> |
46 |
+ <body> |
47 |
+ <p>First, you must install Emacs.</p> |
48 |
+ |
49 |
+ <pre caption="Code Sample"> |
50 |
+ # emerge --pretend --verbose app-editors/emacs |
51 |
+ </pre> |
52 |
+ <!-- find /usr/portage/profiles/use.local* -type f -print0 | xargs -0 -e grep -nH -e emacs --> |
53 |
+ <table> |
54 |
+ <tr> |
55 |
+ <th>Flag</th> |
56 |
+ <th>Description</th> |
57 |
+ <th>Notes</th> |
58 |
+ </tr> |
59 |
+ <tr> |
60 |
+ <ti>alsa</ti> |
61 |
+ <ti>Determine if ALSA should be used</ti> |
62 |
+ <ti>Emacs autodetects ALSA. That test is removed by the ebuild if |
63 |
+ the flag is not set. This is for cases where ALSA is installed but |
64 |
+ the user does not wish support for it in Emacs.</ti> |
65 |
+ </tr> |
66 |
+ <tr> |
67 |
+ <ti>dbus</ti> |
68 |
+ <ti>Make Emacs D-Bus aware (Emacs 23 only).</ti> |
69 |
+ <ti></ti> |
70 |
+ </tr> |
71 |
+ <tr> |
72 |
+ <ti>gif</ti> |
73 |
+ <ti>Support for GIF images.</ti> |
74 |
+ <ti></ti> |
75 |
+ </tr> |
76 |
+ <tr> |
77 |
+ <ti>gpm</ti> |
78 |
+ <ti>Support for console-based mouse driver (Emacs 23 only).</ti> |
79 |
+ <ti></ti> |
80 |
+ </tr> |
81 |
+ <tr> |
82 |
+ <ti>gtk</ti> |
83 |
+ <ti>Use the GIMP Toolkit (GTK+) as windowing toolkit (menu bar |
84 |
+ etc.)</ti> |
85 |
+ <ti>When this toolkit is activated along with alternative ones (see |
86 |
+ other USE flags), GTK+ is chosen. This is in sync with upstream's |
87 |
+ wishes.</ti> |
88 |
+ </tr> |
89 |
+ <tr> |
90 |
+ <ti>gzip-el</ti> |
91 |
+ <ti>Zip up all el files.</ti> |
92 |
+ <ti>The zip binary is autodetected. So even when this USE flag is |
93 |
+ disabled but the binary is found, all el files will be compressed. |
94 |
+ The ebuild takes of that care by confusing the configure |
95 |
+ script.</ti> |
96 |
+ </tr> |
97 |
+ <tr> |
98 |
+ <ti>hesiod</ti> |
99 |
+ <ti>Use the Hesiod name service system.</ti> |
100 |
+ <ti></ti> |
101 |
+ </tr> |
102 |
+ <tr> |
103 |
+ <ti>jpeg</ti> |
104 |
+ <ti>Support for JPEG images.</ti> |
105 |
+ <ti></ti> |
106 |
+ </tr> |
107 |
+ <tr> |
108 |
+ <ti>kerberos</ti> |
109 |
+ <ti>Support for the Kerberos network authentication protocol.</ti> |
110 |
+ <ti></ti> |
111 |
+ </tr> |
112 |
+ <tr> |
113 |
+ <ti>leim</ti> |
114 |
+ <ti>Extended methods for input encodings (Emacs 21 only).</ti> |
115 |
+ <ti></ti> |
116 |
+ </tr> |
117 |
+ <tr> |
118 |
+ <ti>m17n-lib</ti> |
119 |
+ <ti>Use the m17n-lib multilingual library for complex text layout, |
120 |
+ e.g. for Indic scripts (Emacs 23 only).</ti> |
121 |
+ <ti>Only available if "xft" is enabled too.</ti> |
122 |
+ </tr> |
123 |
+ <tr> |
124 |
+ <ti>motif</ti> |
125 |
+ <ti>A windowing toolkit.</ti> |
126 |
+ <ti></ti> |
127 |
+ </tr> |
128 |
+ <tr> |
129 |
+ <ti>nls</ti> |
130 |
+ <ti>This makes use of gettext, an easy way to provide translations |
131 |
+ of strings (Emacs 21 only).</ti> |
132 |
+ <ti></ti> |
133 |
+ </tr> |
134 |
+ <tr> |
135 |
+ <ti>png</ti> |
136 |
+ <ti>Support for PNG images.</ti> |
137 |
+ <ti></ti> |
138 |
+ </tr> |
139 |
+ <tr> |
140 |
+ <ti>sendmail</ti> |
141 |
+ <ti>Build with support for mail transfer agent (Emacs 21 only).</ti> |
142 |
+ <ti></ti> |
143 |
+ </tr> |
144 |
+ <tr> |
145 |
+ <ti>sound</ti> |
146 |
+ <ti>Control the availability of sound support.</ti> |
147 |
+ <ti></ti> |
148 |
+ </tr> |
149 |
+ <tr> |
150 |
+ <ti>source</ti> |
151 |
+ <ti>Install the C source files and make them available in the |
152 |
+ internal documentation system of GNU Emacs.</ti> |
153 |
+ <ti></ti> |
154 |
+ </tr> |
155 |
+ <tr> |
156 |
+ <ti>svg</ti> |
157 |
+ <ti>Support for SVG images (Emacs 23 only).</ti> |
158 |
+ <ti></ti> |
159 |
+ </tr> |
160 |
+ <tr> |
161 |
+ <ti>tiff</ti> |
162 |
+ <ti>Support for TIFF images.</ti> |
163 |
+ <ti></ti> |
164 |
+ </tr> |
165 |
+ <tr> |
166 |
+ <ti>toolkit-scroll-bars</ti> |
167 |
+ <ti>Instead of the internal scroll bars, the ones from the windowing |
168 |
+ toolkit are used.</ti> |
169 |
+ <ti>You will lose some functionality (split windows by clicking on |
170 |
+ the scroll bar for example).</ti> |
171 |
+ </tr> |
172 |
+ <tr> |
173 |
+ <ti>X</ti> |
174 |
+ <ti>Let Emacs use an X session if available. Text mode can always |
175 |
+ be forced.</ti> |
176 |
+ <ti></ti> |
177 |
+ </tr> |
178 |
+ <tr> |
179 |
+ <ti>Xaw3d</ti> |
180 |
+ <ti>A windowing toolkit.</ti> |
181 |
+ <ti></ti> |
182 |
+ </tr> |
183 |
+ <tr> |
184 |
+ <ti>xft</ti> |
185 |
+ <ti>Choose an alternative font renderer (Emacs 23 only).</ti> |
186 |
+ <ti></ti> |
187 |
+ </tr> |
188 |
+ <tr> |
189 |
+ <ti>xpm</ti> |
190 |
+ <ti>Support for XPM images.</ti> |
191 |
+ <ti>If disabled, all logos, icons etc. in Emacs are displayed in |
192 |
+ grayscale. This flag is forced through EAPI 1 features.</ti> |
193 |
+ </tr> |
194 |
+ </table> |
195 |
+ <p> |
196 |
+ You could unpack the Emacs sources and run <c>./configure |
197 |
+ --help</c> to see the optional support. If you don't use the X |
198 |
+ or gtk flags, you will rely on the keyboard to use Emacs. |
199 |
+ Otherwise, <c>emacs -nw</c> is the terminal mode. |
200 |
+ </p> |
201 |
+ </body> |
202 |
+ </section> |
203 |
+ <section> |
204 |
+ <title>Eselect</title> |
205 |
+ <body> |
206 |
+ <pre caption="Eselect"> |
207 |
+ # emerge app-admin/eselect |
208 |
+ # eselect emacs list |
209 |
+ Available Emacs symlink targets: |
210 |
+ [1] emacs-22 |
211 |
+ [2] emacs-23 * |
212 |
+ # eselect emacs set 1 |
213 |
+ Switching emacs to emacs-22 ... |
214 |
+ Switching ctags to exuberant-ctags ... |
215 |
+ Switching etags to etags-emacs-22 ... |
216 |
+ # eselect emacs list |
217 |
+ Available Emacs symlink targets: |
218 |
+ [1] emacs-22 * |
219 |
+ [2] emacs-23 |
220 |
+ </pre> |
221 |
+ </body> |
222 |
+ </section> |
223 |
+ <section> |
224 |
+ <title>Client/Server</title> |
225 |
+ <body> |
226 |
+ <p> |
227 |
+ Emacs can work as a server for emacsclient. To use this type M-x |
228 |
+ server-start in a running Emacs session. Then it's <c>emacsclient |
229 |
+ file1 file2 file3</c> to edit your files or mail. |
230 |
+ </p> |
231 |
+ </body> |
232 |
+ </section> |
233 |
+ <section> |
234 |
+ <title>Modes</title> |
235 |
+ <body> |
236 |
+ <p> |
237 |
+ Some types of files have modes created for them. If you edit |
238 |
+ Python or PHP code, this piece of information is for you. This |
239 |
+ is a convenient way to install elisp files (.el and |
240 |
+ byte-compiled .elc) thanks to the Emacs team! This is done as |
241 |
+ root. Note the # prompt. |
242 |
+ </p> |
243 |
+ <pre caption="Code Sample"> |
244 |
+ # emerge --pretend --verbose app-emacs/python-mode |
245 |
+ # emerge --pretend --verbose app-emacs/php-mode |
246 |
+ Cscope can work with Emacs very conveniently. |
247 |
+ # echo "dev-util/cscope emacs" >> /etc/portage/package.use |
248 |
+ That will append the quoted text to the file "/etc/portage/package.use". |
249 |
+ # emerge dev-util/cscope |
250 |
+ </pre> |
251 |
+ </body> |
252 |
+ </section> |
253 |
+ <section> |
254 |
+ <title>Built-in tutorial</title> |
255 |
+ <body> |
256 |
+ <p>There is a tutorial for Emacs available.</p> |
257 |
+ <pre caption="Code Sample"> |
258 |
+ M-x help-with-tutorial |
259 |
+ </pre> |
260 |
+ <p> |
261 |
+ That is Meta then x. The Meta key is escape or possibly Alt. Next |
262 |
+ you need to type help and use tab twice to see the completions. |
263 |
+ </p> |
264 |
+ </body> |
265 |
+ </section> |
266 |
+ </chapter> |
267 |
+ |
268 |
+ <chapter> |
269 |
+ <title>Dired</title> |
270 |
+ <body> |
271 |
+ <p>Lets start by looking at some files.</p> |
272 |
+ <pre caption="Code Sample"> |
273 |
+ Control-x, control-f, enter |
274 |
+ </pre> |
275 |
+ |
276 |
+ <p> |
277 |
+ Now you have dired, the directory editor. When you press enter on |
278 |
+ directories, you traverse the file structure. It is possible to |
279 |
+ quickly back up the tree with ^, shift-6. Over the course of editing, |
280 |
+ you may open many files. |
281 |
+ </p> |
282 |
+ <pre caption="Code Sample"> |
283 |
+ Control-x, control-b |
284 |
+ </pre> |
285 |
+ |
286 |
+ <p>That will split your screen and show the buffers that are open. When you want to split the screen, use control-x followed by a number.</p> |
287 |
+ <pre caption="Code Sample"> |
288 |
+ C-x 0 <comment>This makes the current buffer go away.</comment> |
289 |
+ C-x 1 <comment>This makes the current buffer take full screen.</comment> |
290 |
+ C-x 2 <comment>This will initiate the split and you can browse two different parts of a file.</comment> |
291 |
+ C-x 3 <comment>This is useful if you have a wide screen.</comment> |
292 |
+ </pre> |
293 |
+ </body> |
294 |
+ </chapter> |
295 |
+ |
296 |
+ <chapter> |
297 |
+ <title>Invoking Processes</title> |
298 |
+ <body> |
299 |
+ <p>Emacs can start subprocesses, like a shell or a debugger or even find and grep.</p> |
300 |
+ <pre caption="Code Sample"> |
301 |
+ <p>M-x shell</p> |
302 |
+ <p>M-x gdb</p> |
303 |
+ <p>M-x find-grep</p> |
304 |
+ <figure link="emacs.jpg" short="Find and Grep" caption="Search in Emacs"/> |
305 |
+ </pre> |
306 |
+ |
307 |
+ <note>Emacs can be used on compressed text in the gzip and bzip2 formats by invoking decompressors.</note> |
308 |
+ </body> |
309 |
+ </chapter> |
310 |
+ |
311 |
+ <chapter> |
312 |
+ <title>Emacs and Bash Equivalents</title> |
313 |
+ <body> |
314 |
+ <p>Bash has some keystrokes in common with Emacs. You can search |
315 |
+ your shell history with control-r but not control-s. If you try |
316 |
+ control-s in bash, it will hide your typing. You can type |
317 |
+ control-q to see input to bash again. To cancel a search, type |
318 |
+ control-g. Just like Emacs, you can kill text several times with |
319 |
+ control-k and get it back with control-y. You can then use |
320 |
+ escape-y repetitions. You can suspend Emacs with control-z. Try |
321 |
+ the jobs command to see what is suspended. Then type fg or fg 1 |
322 |
+ to get back to Emacs.</p> |
323 |
+ </body> |
324 |
+ </chapter> |
325 |
+ |
326 |
+ <chapter> |
327 |
+ <title>Speedbar for Debugging and Navigation</title> |
328 |
+ <body> |
329 |
+ <p> |
330 |
+ If you're coding C, and you use <c>gcc -g</c> for debugging |
331 |
+ symbols, Emacs can split your screen and follow the current line |
332 |
+ of source code. If you use Emacs with X try speedbar. |
333 |
+ </p> |
334 |
+ <pre caption="Code Sample"> |
335 |
+ M-x speedbar |
336 |
+ </pre> |
337 |
+ |
338 |
+ <p> |
339 |
+ Now watch variables change just like any other development |
340 |
+ environment. You could also browse directories in speedbar or do |
341 |
+ other things by right-clicking. |
342 |
+ </p> |
343 |
+ </body> |
344 |
+ </chapter> |
345 |
+ |
346 |
+ <chapter> |
347 |
+ <title>Complete Text</title> |
348 |
+ <body> |
349 |
+ <p>Now is where some completion becomes useful. There is M-/ to complete a string and also some elisp that does much more.</p> |
350 |
+ <pre caption="Code Sample"> |
351 |
+ M-x hippie-expand |
352 |
+ </pre> |
353 |
+ |
354 |
+ <p> |
355 |
+ This has try-expand-list, try-expand-line, |
356 |
+ try-complete-file-name and many other things. It will cycle |
357 |
+ through trying to match what is immediately on the left of the |
358 |
+ cursor. It is much nicer to bind this to a key. |
359 |
+ </p> |
360 |
+ <pre caption="Code Sample"> |
361 |
+ M-x global-set-key |
362 |
+ </pre> |
363 |
+ |
364 |
+ <p>This could be persistent in a .emacs file.</p> |
365 |
+ <pre caption="Code Sample"> |
366 |
+ $ echo "(global-set-key [(f2)] 'hippie-expand)" >> ~/.emacs.d/init.el |
367 |
+ </pre> |
368 |
+ |
369 |
+ <note><c>man man</c> has this tip: (global-set-key [(f1)] (lambda () (interactive) (manual-entry (current-word))))</note> |
370 |
+ </body> |
371 |
+ </chapter> |
372 |
+ |
373 |
+ <chapter> |
374 |
+ <title>Emacs Lisp</title> |
375 |
+ <p> |
376 |
+ You could use the lisp interpreter to make lists or do some |
377 |
+ simple math. Type these in and then type control-x, control-e |
378 |
+ with the cursor at the end of them. Watch the minibuffer at the |
379 |
+ bottom of the screen. |
380 |
+ </p> |
381 |
+ <pre caption="Code Sample"> |
382 |
+ <p>(list 'a 'b 'c)</p> |
383 |
+ <p>(+ 1 2 3)</p> |
384 |
+ <p>(* (* 2 2) (/ 22 7))</p> |
385 |
+ <p>(message "%s" "This is an introduction to using Emacs in Gentoo.")</p> |
386 |
+ </pre> |
387 |
+ <p> |
388 |
+ Understanding how to navigate the cursor over lists is quite |
389 |
+ useful. With the cursor pointed on a [, (, or {, use M-C-f to |
390 |
+ go to the end. Use M-C-b to go to the beginning of the list. |
391 |
+ That is escape, control-f and escape, control-b |
392 |
+ respectively. |
393 |
+ </p> |
394 |
+ |
395 |
+ <p>You could load your elisp.</p> |
396 |
+ <pre caption="Code Sample"> |
397 |
+ M-x load-file |
398 |
+ </pre> |
399 |
+ |
400 |
+ <p> |
401 |
+ Now, you may want to clean up your code or make replacements in a |
402 |
+ function. Click and drag or use control-space to set a mark. |
403 |
+ </p> |
404 |
+ <pre caption="Code Sample"> |
405 |
+ M-x transient-mark-mode |
406 |
+ </pre> |
407 |
+ |
408 |
+ <p> |
409 |
+ That will toggle the highlighting of selected text. Now, M-% will |
410 |
+ prompt you to search and replace or query-replace. Also, |
411 |
+ global-font-lock-mode will toggle the syntax highlighting; |
412 |
+ indent-region will nicely indent nested code blocks or HTML. A quick |
413 |
+ comment comes from M-; or escape-semicolon. |
414 |
+ </p> |
415 |
+ </chapter> |
416 |
+ |
417 |
+ <chapter> |
418 |
+ <title>More Dired</title> |
419 |
+ <p>Now you may wish to do replacements in many files.</p> |
420 |
+ <pre caption="Code Sample"> |
421 |
+ <p>M-x dired<TAB><TAB></p> |
422 |
+ <p>M-x command-apropos <comment>This can show any dired command.</comment></p> |
423 |
+ </pre> |
424 |
+ |
425 |
+ <p>Now you see what is available. Here is one strategy.</p> |
426 |
+ <pre caption="Code Sample"> |
427 |
+ <p>M-x find-grep-dired</p> |
428 |
+ <p>%-m c$ <comment>This will mark C sources or filenames ending in c.</comment></p> |
429 |
+ <p>M-x dired-do-query-replace-regexp</p> |
430 |
+ </pre> |
431 |
+ </chapter> |
432 |
+ |
433 |
+ <chapter> |
434 |
+ <title>Remove Comments</title> |
435 |
+ <p> |
436 |
+ One common thing for Gentoo users is to strip comments from |
437 |
+ configuration files. This is convenient in Emacs with flush-lines |
438 |
+ </p> |
439 |
+ <pre caption="Code Sample"> |
440 |
+ <p>M-x flush-lines</p> |
441 |
+ <p>^#</p> |
442 |
+ <p> That will match lines beginning with a # which is a comment in most /etc configuration files.</p> |
443 |
+ </pre> |
444 |
+ </chapter> |
445 |
+ |
446 |
+ <chapter> |
447 |
+ <title>Ediff</title> |
448 |
+ <p> |
449 |
+ Since Gentoo respects your /etc/ configuration files, you may |
450 |
+ like <c>ediff</c> for file foo and ._cfg0000_foo. |
451 |
+ </p> |
452 |
+ <pre caption="Code Sample"> |
453 |
+ <p> |
454 |
+ You could run M-x find-dired with an argument like this: -name |
455 |
+ \._cfg* |
456 |
+ </p> |
457 |
+ <p>Control-x, control-f, control-a, control-k, /etc, enter.</p> |
458 |
+ <p>M-x ediff</p> |
459 |
+ </pre> |
460 |
+ </chapter> |
461 |
+ |
462 |
+ |
463 |
+ <chapter> |
464 |
+ <title>Macros</title> |
465 |
+ <p> |
466 |
+ An introduction to Emacs would not be complete without a section |
467 |
+ on macros. This is "Editor MACroS". In a buffer, type |
468 |
+ control-x, ( to begin. Then type what you want in the macro. |
469 |
+ You are recording keystrokes. Now type control-x, ) to finish |
470 |
+ the macro. Naming the macro is next with M-x |
471 |
+ name-last-kbd-macro. You could insert-kbd-macro into a .emacs |
472 |
+ file if you find it very useful. Perhaps you want to use that |
473 |
+ macro 10 times in a row. This is awkward, but control-u, 10, |
474 |
+ M-x mymacro. |
475 |
+ </p> |
476 |
+ </chapter> |
477 |
+ |
478 |
+ <chapter> |
479 |
+ <title>Sample .emacs</title> |
480 |
+ <pre caption="Code Sample"> |
481 |
+ <p>$ cat ~/.emacs.d/init.el</p> |
482 |
+ <p>(prefer-coding-system 'utf-8)</p> |
483 |
+ <p>(setq transient-mark-mode t)</p> |
484 |
+ <p>(show-paren-mode t)</p> |
485 |
+ <p>(setq column-number-mode t)</p> |
486 |
+ <p>(global-set-key [(f5)] (lambda() (interactive) (woman (current-word))))</p> |
487 |
+ <p>(global-set-key [(f6)] 'hippie-expand)</p> |
488 |
+ <p>(global-set-key [(f7)] 'replace-regexp)</p> |
489 |
+ <p>(global-set-key [(f8)] 'flush-lines)</p> |
490 |
+ <p>(global-set-key [(f9)] 'dired-do-delete)</p> |
491 |
+ <p></p> |
492 |
+ <p># cat /root/.emacs.d/init.el</p> |
493 |
+ <p>(load "/home/username/.emacs.d/init.el")</p> |
494 |
+ </pre> |
495 |
+ </chapter> |
496 |
+ |
497 |
+</guide> |