Mercurial > emacs
comparison man/eshell.texi @ 32542:9b4c05d377c9
Fix markup and chapter structure of the document.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Mon, 16 Oct 2000 18:24:30 +0000 |
parents | b09ded79f0f9 |
children | e21feeab77fb |
comparison
equal
deleted
inserted
replaced
32541:97b47d019f1b | 32542:9b4c05d377c9 |
---|---|
1 \input texinfo @c -*-texinfo-*- | 1 \input texinfo @c -*-texinfo-*- |
2 | 2 |
3 @c "@(#)$Name: $:$Id: eshell.texi,v 1.1 2000/10/13 09:47:34 johnw Exp $" | 3 @c "@(#)$Name: $:$Id: eshell.texi,v 1.2 2000/10/13 10:32:23 johnw Exp $" |
4 | 4 |
5 @c Documentation for Eshell: The Emacs Shell. | 5 @c Documentation for Eshell: The Emacs Shell. |
6 @c Copyright (C) 1999-2000 Free Software Foundation, Inc. | 6 @c Copyright (C) 1999-2000 Free Software Foundation, Inc. |
7 | 7 |
8 @c This file is part of GNU Emacs | 8 @c This file is part of GNU Emacs |
24 @c %**start of header | 24 @c %**start of header |
25 @setfilename ../info/eshell | 25 @setfilename ../info/eshell |
26 @settitle Eshell: The Emacs Shell | 26 @settitle Eshell: The Emacs Shell |
27 @c %**end of header | 27 @c %**end of header |
28 | 28 |
29 @c @dircategory Emacs | 29 @dircategory Emacs |
30 @direntry | 30 @direntry |
31 * Eshell: (eshell). A command shell implemented in Emacs Lisp. | 31 * Eshell: (eshell). A command shell implemented in Emacs Lisp. |
32 @end direntry | 32 @end direntry |
33 @setchapternewpage on | 33 @setchapternewpage on |
34 | 34 |
101 except that the section entitled ``GNU General Public License'' and this | 101 except that the section entitled ``GNU General Public License'' and this |
102 permission notice may be included in translations approved by the Free | 102 permission notice may be included in translations approved by the Free |
103 Software Foundation instead of in the original English. | 103 Software Foundation instead of in the original English. |
104 @end titlepage | 104 @end titlepage |
105 | 105 |
106 @contents | |
107 | |
106 @c ================================================================ | 108 @c ================================================================ |
107 @c The real text starts here | 109 @c The real text starts here |
108 @c ================================================================ | 110 @c ================================================================ |
109 | 111 |
110 @node Top, What is Eshell?, (dir), (dir) | 112 @node Top, What is Eshell?, (dir), (dir) |
120 @c This manual is updated to release 2.3.2 of Eshell. | 122 @c This manual is updated to release 2.3.2 of Eshell. |
121 @end ifinfo | 123 @end ifinfo |
122 | 124 |
123 @menu | 125 @menu |
124 * What is Eshell?:: A brief introduction to the Emacs Shell. | 126 * What is Eshell?:: A brief introduction to the Emacs Shell. |
127 * Installation:: | |
125 * Bugs and ideas:: | 128 * Bugs and ideas:: |
129 * Concept Index:: | |
130 * Function and Variable Index:: | |
131 * Key Index:: | |
126 @end menu | 132 @end menu |
127 | 133 |
128 @node What is Eshell?, Bugs and ideas, Top, Top | 134 @node What is Eshell?, Installation, Top, Top |
129 @chapter What is Eshell? | 135 @chapter What is Eshell? |
130 @cindex What is Eshell? | 136 @cindex what is Eshell? |
131 | 137 @cindex Eshell, what it is |
132 Eshell is a command shell written using Emacs Lisp. All of what it does | 138 |
139 Eshell is a @dfn{command shell} written using Emacs Lisp. All of what it does | |
133 it uses Emacs' facilities to do. This means Eshell is as portable as | 140 it uses Emacs' facilities to do. This means Eshell is as portable as |
134 Emacs itself. It also means that cooperation with other Lisp code is | 141 Emacs itself. It also means that cooperation with other Lisp code is |
135 natural and seamless. | 142 natural and seamless. |
136 | 143 |
137 So what is a command shell? To properly understand the role of a shell, | 144 So what is a command shell? To properly understand the role of a shell, |
140 do---or give it ``commands''. These commands take many forms, such as | 147 do---or give it ``commands''. These commands take many forms, such as |
141 clicking with a mouse on certain parts of the screen. But that is only | 148 clicking with a mouse on certain parts of the screen. But that is only |
142 one form of command input. | 149 one form of command input. |
143 | 150 |
144 By far the most versatile way to express what you want the computer to | 151 By far the most versatile way to express what you want the computer to |
145 do is using an abbreviated language, called script. In script, instead | 152 do is using an abbreviated language, called @dfn{a script}. In a |
153 script, instead | |
146 of telling the computer, ``list my files, please'', we write just | 154 of telling the computer, ``list my files, please'', we write just |
147 ``list''. In fact, this command is so commonly used that we abbreviate | 155 ``list''. In fact, this command is so commonly used that we abbreviate |
148 it to ``ls''. Typing @code{ls} in a command shell is a script way of | 156 it to ``ls''. Typing @kbd{ls} in a command shell is a script way of |
149 telling the computer to list your files. This is comparable to viewing | 157 telling the computer to list your files. This is comparable to viewing |
150 the contents of a folder using a graphical display. | 158 the contents of a folder using a graphical display. |
151 | 159 |
152 The real flexibility is apparent only when you realize that there are | 160 The real flexibility is apparent only when you realize that there are |
153 many, many ways to list your files. Perhaps you want them sorted by | 161 many, many ways to list your files. Perhaps you want them sorted by |
178 | 186 |
179 As of Emacs 21, Eshell is part of the standard Emacs distribution. | 187 As of Emacs 21, Eshell is part of the standard Emacs distribution. |
180 | 188 |
181 @menu | 189 @menu |
182 * Contributors to Eshell:: | 190 * Contributors to Eshell:: |
183 * Installation:: | |
184 @end menu | 191 @end menu |
185 | 192 |
186 @node Contributors to Eshell, Installation, What is Eshell?, What is Eshell? | 193 @node Contributors to Eshell, , What is Eshell?, What is Eshell? |
187 @section Contributors to Eshell | 194 @section Contributors to Eshell |
188 @cindex Contributors | 195 @cindex contributors |
189 @cindex Authors | 196 @cindex authors |
190 | 197 |
191 Contributions to Eshell are welcome. I have limited time to work on | 198 Contributions to Eshell are welcome. I have limited time to work on |
192 this project, but I will gladly add any code you contribute to me to | 199 this project, but I will gladly add any code you contribute to me to |
193 this package. | 200 this package. |
194 | 201 |
215 Alex Schroeder contributed code for interactively querying the user | 222 Alex Schroeder contributed code for interactively querying the user |
216 before overwriting files.@refill | 223 before overwriting files.@refill |
217 | 224 |
218 @item | 225 @item |
219 Sudish Joseph helped with some XEmacs compatibility issues.@refill | 226 Sudish Joseph helped with some XEmacs compatibility issues.@refill |
220 | |
221 @end itemize | 227 @end itemize |
222 | 228 |
223 Apart from these, a lot of people have sent suggestions, ideas, | 229 Apart from these, a lot of people have sent suggestions, ideas, |
224 requests, bug reports and encouragement. Thanks a lot! Without you | 230 requests, bug reports and encouragement. Thanks a lot! Without you |
225 there would be no new releases of Eshell. | 231 there would be no new releases of Eshell. |
226 | 232 |
227 @node Installation, , Contributors to Eshell, What is Eshell? | 233 @node Installation, Bugs and ideas, What is Eshell?, Top |
228 @section Installation | 234 @chapter Installation |
229 @cindex Installation | 235 @cindex installation |
230 | 236 |
231 As mentioned above, Eshell comes preinstalled since Emacs 21. If you're | 237 As mentioned above, Eshell comes preinstalled since Emacs 21. If you're |
232 using Emacs 20.4 or later, or XEmacs 21, you can download the most | 238 using Emacs 20.4 or later, or XEmacs 21, you can download the most |
233 recent version of Eshell from | 239 recent version of Eshell from |
234 @url{http://www.gci-net.com/users/j/johnw/Emacs/eshell.tar.gz}. | 240 @url{http://www.gci-net.com/users/j/johnw/Emacs/eshell.tar.gz}. |
235 | 241 |
236 If you are using Emacs 21, please skip this section. | 242 If you are using Emacs 21, please skip this section. |
237 | 243 |
238 @subsection Short Form | 244 @section Short Form |
239 | 245 |
240 Here's exactly what to do, with no explanation why: | 246 Here's exactly what to do, with no explanation why: |
241 | 247 |
242 @enumerate | 248 @enumerate |
243 @item @samp{M-x load-file RET eshell-auto.el RET} | 249 @item |
244 @item @samp{ESC : (add-to-list 'load-path "<path where Eshell resides>") RET} | 250 @samp{M-x load-file RET eshell-auto.el RET}. |
245 @item @samp{ESC : (add-to-list 'load-path "<path where Pcomplete resides>") RET} | 251 |
246 @item @samp{M-x eshell RET} | 252 @item |
253 @samp{ESC : (add-to-list 'load-path "<path where Eshell resides>") RET}. | |
254 | |
255 @item | |
256 @samp{ESC : (add-to-list 'load-path "<path where Pcomplete resides>") RET}. | |
257 | |
258 @item | |
259 @samp{M-x eshell RET}. | |
247 | 260 |
248 You should see a version banner displayed. | 261 You should see a version banner displayed. |
249 | 262 |
250 @item @samp{ls RET} | 263 @item |
264 @samp{ls RET}. | |
251 | 265 |
252 Confirm that you see a file listing. | 266 Confirm that you see a file listing. |
253 | 267 |
254 @item @samp{eshell-test RET} | 268 @item |
255 | 269 @samp{eshell-test RET}. |
256 Confirm that everything runs correctly. Use `M-x eshell-report-bug' if | 270 |
271 Confirm that everything runs correctly. Use @kbd{M-x eshell-report-bug} if | |
257 not. | 272 not. |
258 | 273 |
259 @item @samp{cd $@{dirname (locate-library "eshell-auto")@} RET} | 274 @item |
260 @item @samp{find-file Makefile RET} | 275 @samp{cd $@{dirname (locate-library "eshell-auto")@} RET}. |
261 @item Edit the Makefile to reflect your site. | 276 |
262 @item @samp{M-x eshell RET} | 277 @item |
263 @item @samp{make install RET} | 278 @samp{find-file Makefile RET}. |
264 @item @samp{find-file $user-init-file RET} | 279 |
265 @item Add the following lines to your @file{.emacs} file: | 280 @item |
281 Edit the Makefile to reflect your site. | |
282 | |
283 @item | |
284 @samp{M-x eshell RET}. | |
285 | |
286 @item | |
287 @samp{make install RET}. | |
288 | |
289 @item | |
290 @samp{find-file $user-init-file RET}. | |
291 | |
292 @item | |
293 Add the following lines to your @file{.emacs} file: | |
266 | 294 |
267 @example | 295 @example |
268 (add-to-list 'load-path "<directory where you install Eshell>") | 296 (add-to-list 'load-path "<directory where you install Eshell>") |
269 (load "eshell-auto") | 297 (load "eshell-auto") |
270 @end example | 298 @end example |
271 | 299 |
272 @item @samp{M-x eshell RET} | 300 @item |
273 @item @samp{customize-option #'eshell-modules-list RET} | 301 @samp{M-x eshell RET}. |
274 @item Select the extension modules you prefer. | 302 |
275 @item Restart Emacs! | 303 @item |
276 @item @samp{M-x info RET m Eshell RET} | 304 @samp{customize-option #'eshell-modules-list RET}. |
305 | |
306 @item | |
307 Select the extension modules you prefer. | |
308 | |
309 @item | |
310 Restart Emacs! | |
311 | |
312 @item | |
313 @samp{M-x info RET m Eshell RET}. | |
277 | 314 |
278 Read the manual and enjoy! | 315 Read the manual and enjoy! |
279 @end enumerate | 316 @end enumerate |
280 | 317 |
281 @subsection Long Form | 318 @section Long Form |
282 | 319 |
283 @enumerate | 320 @enumerate |
284 @item | 321 @item |
285 Before building and installing Eshell, it is important to test that it | 322 Before building and installing Eshell, it is important to test that it |
286 will work properly on your system. To do this, first load | 323 will work properly on your system. To do this, first load the file |
287 @file{eshell-auto}, which will define certain autoloads required to run | 324 @file{eshell-auto}, which will define certain autoloads required to run |
288 Eshell. This can be done using the command @kbd{M-x load-file}, and | 325 Eshell. This can be done using the command @kbd{M-x load-file}, and |
289 then selecting the file @file{eshell-auto.el}. | 326 then selecting the file @file{eshell-auto.el}. |
290 | 327 |
291 @item | 328 @item |
302 Start Eshell from the distributed sources, using default settings, by | 339 Start Eshell from the distributed sources, using default settings, by |
303 typing @kbd{M-x eshell}. | 340 typing @kbd{M-x eshell}. |
304 | 341 |
305 @item | 342 @item |
306 Verify that Eshell is functional by typing @command{ls} followed by | 343 Verify that Eshell is functional by typing @command{ls} followed by |
307 @kbd{RET}. You should have already seen a version banner announcing the | 344 @key{RET}. You should have already seen a version banner announcing the |
308 version number of this release, followed by a prompt. | 345 version number of this release, followed by a prompt. |
309 | 346 |
310 @item | 347 @item |
311 Run the test suite by typing @command{eshell-test} followed by @kbd{RET} | 348 Run the test suite by typing @command{eshell-test} followed by @key{RET} |
312 in the Eshell buffer. It is important that Emacs be left alone while | 349 in the Eshell buffer. It is important that Emacs be left alone while |
313 the tests are running, since extraneous command input may cause some of | 350 the tests are running, since extraneous command input may cause some of |
314 the tests to fail (they were never intended to run in the background). | 351 the tests to fail (they were never intended to run in the background). |
315 If all of the tests pass, Eshell should work just fine on your system. | 352 If all of the tests pass, Eshell should work just fine on your system. |
316 If any of the tests fail, please send e-mail to the Eshell maintainer | 353 If any of the tests fail, please send e-mail to the Eshell maintainer |
322 site. The only things you really have to change are the definitions of | 359 site. The only things you really have to change are the definitions of |
323 @code{lispdir} and @code{infodir}. The elisp files will be copied to | 360 @code{lispdir} and @code{infodir}. The elisp files will be copied to |
324 @code{lispdir}, and the info file to @code{infodir}. | 361 @code{lispdir}, and the info file to @code{infodir}. |
325 | 362 |
326 @item | 363 @item |
327 Type @code{make install} in the directory containing the Eshell sources. | 364 Type @kbd{make install} in the directory containing the Eshell sources. |
328 This will byte-compile all of the @file{.el} files and copy both the | 365 This will byte-compile all of the @file{*.el} files and copy both the |
329 source and compiled versions to the directories specified in the | 366 source and compiled versions to the directories specified in the |
330 previous step. It will also copy the info file, and add a corresponding | 367 previous step. It will also copy the info file, and add a corresponding |
331 entry to your @file{dir} file----if @file{install-info} can be found. | 368 entry to your @file{dir} file----if the program @code{install-info} can |
369 be found on your system. | |
332 | 370 |
333 If you only want to create the compiled elisp files, but don't want to | 371 If you only want to create the compiled elisp files, but don't want to |
334 install them, you can type just @command{make} instead. | 372 install them, you can type just @kbd{make} instead. |
335 | 373 |
336 @item | 374 @item |
337 Add the directory into which Eshell was installed to your | 375 Add the directory into which Eshell was installed to your |
338 @code{load-path} variable. This can be done by adding the following | 376 @code{load-path} variable. This can be done by adding the following |
339 line to your @file{.emacs} file: | 377 line to your @file{.emacs} file: |
358 @item | 396 @item |
359 Restart Emacs. After restarting, customize the variable | 397 Restart Emacs. After restarting, customize the variable |
360 @code{eshell-modules-list}. This variable selects which Eshell | 398 @code{eshell-modules-list}. This variable selects which Eshell |
361 extension modules you want to use. You will find documentation on each | 399 extension modules you want to use. You will find documentation on each |
362 of those modules in the Info manual. | 400 of those modules in the Info manual. |
363 | |
364 @end enumerate | 401 @end enumerate |
365 | 402 |
403 @cindex documentation, printed version | |
404 @cindex printed version of documentation | |
366 If you have @TeX{} installed at your site, you can make a typeset manual | 405 If you have @TeX{} installed at your site, you can make a typeset manual |
367 from @file{eshell.texi}. | 406 from @file{eshell.texi}. |
368 | 407 |
369 @enumerate | 408 @enumerate |
370 @item | 409 @item |
371 Run @TeX{} by typing @samp{texi2dvi eshell.texi}. | 410 Run @TeX{} by typing @kbd{texi2dvi eshell.texi}. (With Emacs 21.1 or |
411 later, typing @kbd{make eshell.dvi} in the @file{man/} subdirectory of | |
412 the Emacs source distribution will do that.) | |
413 | |
372 @item | 414 @item |
373 Convert the resulting device independent file @file{eshell.dvi} to a | 415 Convert the resulting device independent file @file{eshell.dvi} to a |
374 form which your printer can output and print it. If you have a | 416 form which your printer can output and print it. If you have a |
375 postscript printer there is a program, @code{dvi2ps}, which does. There | 417 postscript printer, there is a program, @code{dvi2ps}, which does that; there |
376 is also a program which comes together with @TeX{}, @code{dvips}, which | 418 is also a program which comes together with @TeX{}, @code{dvips}, which |
377 you can use. | 419 you can use. For other printers, use a suitable DVI driver, |
420 e.g., @code{dvilj4} for LaserJet-compatible printers. | |
378 @end enumerate | 421 @end enumerate |
379 | 422 |
380 @c @node Forming commands, Known problems, What is Eshell?, Top | 423 @c @node Forming commands, Known problems, What is Eshell?, Top |
381 @c @chapter Forming commands | 424 @c @chapter Forming commands |
382 | 425 |
425 @c different forms. There are textual arguments, numeric arguments, | 468 @c different forms. There are textual arguments, numeric arguments, |
426 @c even Lisp arguments. Distinguishing among these different types of | 469 @c even Lisp arguments. Distinguishing among these different types of |
427 @c arguments requires some special typing, because the computer needs | 470 @c arguments requires some special typing, because the computer needs |
428 @c very specific directions to understand what you mean. | 471 @c very specific directions to understand what you mean. |
429 | 472 |
430 @node Bugs and ideas, , What is Eshell?, Top | 473 @node Bugs and ideas, Concept Index, Installation, Top |
431 @chapter Bugs and ideas | 474 @chapter Bugs and ideas |
432 @cindex Reporting bugs and ideas | 475 @cindex reporting bugs and ideas |
433 @cindex Bugs, how to report them | 476 @cindex bugs, how to report them |
434 @cindex Author, how to reach | 477 @cindex author, how to reach |
435 @cindex Email to the author | 478 @cindex email to the author |
436 @cindex Known bugs | |
437 @cindex Bugs, known | |
438 @cindex FAQ | 479 @cindex FAQ |
439 @cindex Problems, list of common | 480 @cindex problems, list of common |
440 | 481 |
441 If you find a bug or misfeature, don't hesitate to let me know! Send | 482 If you find a bug or misfeature, don't hesitate to let me know! Send |
442 email to @samp{johnw@@gnu.org}. Feature requests should also be sent | 483 email to @email{johnw@@gnu.org}. Feature requests should also be sent |
443 there. I prefer discussing one thing at a time. If you find several | 484 there. I prefer discussing one thing at a time. If you find several |
444 unrelated bugs, please report them separately. | 485 unrelated bugs, please report them separately. |
445 | 486 |
446 If you have ideas for improvements, or if you have written some | 487 If you have ideas for improvements, or if you have written some |
447 extensions to this package, I would like to hear from you. I hope you | 488 extensions to this package, I would like to hear from you. I hope you |
451 * Known problems:: | 492 * Known problems:: |
452 @end menu | 493 @end menu |
453 | 494 |
454 @node Known problems, , Bugs and ideas, Bugs and ideas | 495 @node Known problems, , Bugs and ideas, Bugs and ideas |
455 @section Known problems | 496 @section Known problems |
497 @cindex known bugs | |
498 @cindex bugs, known | |
456 | 499 |
457 Below is a partial list of currently known problems with Eshell version | 500 Below is a partial list of currently known problems with Eshell version |
458 2.3.2, which is the version distribution with Emacs 21.1. | 501 2.3.2, which is the version distributed with Emacs 21.1. |
459 | 502 |
460 @table @asis | 503 @table @asis |
461 @item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} fails | 504 @item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} fails |
462 | 505 |
463 In fact, piping to a process from a looping construct doesn't work in | 506 In fact, piping to a process from a looping construct doesn't work in |
467 structured command thing is too complicated at present. | 510 structured command thing is too complicated at present. |
468 | 511 |
469 @item Error with @command{bc} in @code{eshell-test} | 512 @item Error with @command{bc} in @code{eshell-test} |
470 | 513 |
471 On some XEmacs system, the subprocess interaction test fails | 514 On some XEmacs system, the subprocess interaction test fails |
472 inexplicably, since @command{bc} works fine at the command prompt. | 515 inexplicably, although @command{bc} works fine at the command prompt. |
473 | 516 |
474 @item @command{ls} in remote directories sometimes fails | 517 @item @command{ls} in remote directories sometimes fails |
475 | 518 |
476 For XEmacs users, using @command{ls} in a remote directory sometimes | 519 For XEmacs users, using @command{ls} in a remote directory sometimes |
477 fails. The reason why has not yet been found. | 520 fails. The reason why has not yet been found. |
481 In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that | 524 In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that |
482 multiple instances of the @file{*Help*} buffer can exist. | 525 multiple instances of the @file{*Help*} buffer can exist. |
483 | 526 |
484 @item Pcomplete sometimes gets stuck | 527 @item Pcomplete sometimes gets stuck |
485 | 528 |
486 When @kbd{TAB}, no completions appear, even though the directory has | 529 You press @key{TAB}, but no completions appear, even though the |
487 them. This behavior is rare. | 530 directory has matching files. This behavior is rare. |
488 | 531 |
489 @item @samp{grep python $<rpm -qa>} doesn't work, but using @samp{*grep} does | 532 @item @samp{grep python $<rpm -qa>} doesn't work, but using @samp{*grep} does |
490 | 533 |
491 This happens because the @code{grep} Lisp function returns immediately, | 534 This happens because the @code{grep} Lisp function returns immediately, |
492 and then the asynchronous @command{grep} process expects to examine the | 535 and then the asynchronous @command{grep} process expects to examine the |
780 @c doesn't show me anything. | 823 @c doesn't show me anything. |
781 @c @item M-RET during a long command doesn't quite work | 824 @c @item M-RET during a long command doesn't quite work |
782 @c Since it keeps the cursor up where the command was invoked. | 825 @c Since it keeps the cursor up where the command was invoked. |
783 @end table | 826 @end table |
784 | 827 |
828 @node Concept Index, Function and Variable Index, Bugs and ideas, Top | |
829 @unnumbered Concept Index | |
830 | |
831 @printindex cp | |
832 | |
833 @node Function and Variable Index, Key Index, Concept Index, Top | |
785 @unnumbered Function and Variable Index | 834 @unnumbered Function and Variable Index |
786 | 835 |
787 @printindex fn | 836 @printindex fn |
788 | 837 |
789 @unnumbered Concept Index | 838 @node Key Index, , Function and Variable Index, Top |
790 | |
791 @printindex cp | |
792 | |
793 @unnumbered Key Index | 839 @unnumbered Key Index |
794 | 840 |
795 @printindex ky | 841 @printindex ky |
796 | |
797 @setchapternewpage odd | |
798 @summarycontents | |
799 @contents | |
800 @bye | 842 @bye |