Gentoo Archives: gentoo-commits

From: "Christian Faulhammer (fauli)" <fauli@g.o>
To: gentoo-commits@l.g.o
Subject: [gentoo-commits] emacs r1283 - / emacsguide
Date: Thu, 02 Jul 2009 08:28:33
Message-Id: E1MMHeh-0007GX-3G@stork.gentoo.org
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&lt;TAB&gt;&lt;TAB&gt;</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>