32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1 \input texinfo @c -*-texinfo-*-
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
2 @c %**start of header
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
3 @setfilename ../info/eshell
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
4 @settitle Eshell: The Emacs Shell
|
47737
|
5 @synindex vr fn
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
6 @c %**end of header
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
7
|
47737
|
8 @copying
|
|
9 This manual is for Eshell, the Emacs shell.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
10
|
54836
|
11 Copyright @copyright{} 1999, 2000, 2001, 2002, 2004 Free Software Foundation, Inc.
|
47737
|
12
|
|
13 @quotation
|
37404
|
14 Permission is granted to copy, distribute and/or modify this document
|
|
15 under the terms of the GNU Free Documentation License, Version 1.1 or
|
|
16 any later version published by the Free Software Foundation; with no
|
|
17 Invariant Sections, with the Front-Cover texts being ``A GNU
|
|
18 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
|
|
19 license is included in the section entitled ``GNU Free Documentation
|
|
20 License'' in the Emacs manual.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
21
|
37404
|
22 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
|
|
23 this GNU Manual, like GNU software. Copies published by the Free
|
|
24 Software Foundation raise funds for GNU development.''
|
|
25
|
|
26 This document is part of a collection distributed under the GNU Free
|
|
27 Documentation License. If you want to distribute this document
|
|
28 separately from the collection, you can do so by adding a copy of the
|
|
29 license to the document, as described in section 6 of the license.
|
47737
|
30 @end quotation
|
|
31 @end copying
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
32
|
47737
|
33 @dircategory Emacs
|
|
34 @direntry
|
|
35 * Eshell: (eshell). A command shell implemented in Emacs Lisp.
|
|
36 @end direntry
|
|
37
|
|
38 @setchapternewpage on
|
|
39
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
40 @titlepage
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
41 @sp 4
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
42 @c The title is printed in a large font.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
43 @center @titlefont{User's Guide}
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
44 @sp
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
45 @center @titlefont{to}
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
46 @sp
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
47 @center @titlefont{Eshell: The Emacs Shell}
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
48 @ignore
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
49 @sp 2
|
33020
|
50 @center release 2.4
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
51 @c -release-
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
52 @end ignore
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
53 @sp 3
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
54 @center John Wiegley
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
55 @c -date-
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
56
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
57 @page
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
58 @vskip 0pt plus 1filll
|
47737
|
59 @insertcopying
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
60 @end titlepage
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
61
|
32542
|
62 @contents
|
|
63
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
64 @c ================================================================
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
65 @c The real text starts here
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
66 @c ================================================================
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
67
|
47737
|
68 @ifnottex
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
69 @node Top, What is Eshell?, (dir), (dir)
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
70 @top Eshell
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
71
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
72 This manual documents Eshell, a shell-like command interpretor
|
33020
|
73 implemented in Emacs Lisp. It invokes no external processes except for
|
|
74 those requested by the user. It is intended to be a functional
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
75 replacement for command shells such as @command{bash}, @command{zsh},
|
33020
|
76 @command{rc}, or @command{4dos}; since Emacs itself is capable of
|
|
77 handling the sort of tasks accomplished by those tools.
|
|
78 @c This manual is updated to release 2.4 of Eshell.
|
47737
|
79 @end ifnottex
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
80
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
81 @menu
|
35588
|
82 * What is Eshell?:: A brief introduction to the Emacs Shell.
|
|
83 * Installation:: For users of Emacs 20 and XEmacs.
|
49600
|
84 * Command basics:: The basics of command usage.
|
|
85 * Commands::
|
|
86 * Arguments::
|
|
87 * Input/Output::
|
|
88 * Process control::
|
|
89 * Extension modules::
|
|
90 * Extras and Goodies::
|
35588
|
91 * Bugs and ideas:: Known problems, and future ideas.
|
49600
|
92 * Concept Index::
|
|
93 * Function and Variable Index::
|
|
94 * Key Index::
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
95 @end menu
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
96
|
45862
|
97 @node What is Eshell?
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
98 @chapter What is Eshell?
|
32542
|
99 @cindex what is Eshell?
|
|
100 @cindex Eshell, what it is
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
101
|
33020
|
102 Eshell is a @dfn{command shell} written in Emacs Lisp. Everything it
|
35588
|
103 does, it uses Emacs' facilities to do. This means that Eshell is as
|
33020
|
104 portable as Emacs itself. It also means that cooperation with Lisp code
|
|
105 is natural and seamless.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
106
|
33020
|
107 What is a command shell? To properly understand the role of a shell,
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
108 it's necessary to visualize what a computer does for you. Basically, a
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
109 computer is a tool; in order to use that tool, you must tell it what to
|
36508
|
110 do---or give it ``commands.'' These commands take many forms, such as
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
111 clicking with a mouse on certain parts of the screen. But that is only
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
112 one form of command input.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
113
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
114 By far the most versatile way to express what you want the computer to
|
36508
|
115 do is by using an abbreviated language called @dfn{script}. In
|
|
116 script, instead of telling the computer, ``list my files, please'',
|
|
117 one writes a standard abbreviated command word---@samp{ls}. Typing
|
|
118 @samp{ls} in a command shell is a script way of telling the computer
|
|
119 to list your files.@footnote{This is comparable to viewing the
|
|
120 contents of a folder using a graphical display.}
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
121
|
33020
|
122 The real flexibility of this approach is apparent only when you realize
|
|
123 that there are many, many different ways to list files. Perhaps you
|
|
124 want them sorted by name, sorted by date, in reverse order, or grouped
|
|
125 by type. Most graphical browsers have simple ways to express this. But
|
|
126 what about showing only a few files, or only files that meet a certain
|
|
127 criteria? In very complex and specific situations, the request becomes
|
|
128 too difficult to express using a mouse or pointing device. It is just
|
|
129 these kinds of requests that are easily solved using a command shell.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
130
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
131 For example, what if you want to list every Word file on your hard
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
132 drive, larger than 100 kilobytes in size, and which hasn't been looked
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
133 at in over six months? That is a good candidate list for deletion, when
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
134 you go to clean up your hard drive. But have you ever tried asking your
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
135 computer for such a list? There is no way to do it! At least, not
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
136 without using a command shell.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
137
|
33020
|
138 The role of a command shell is to give you more control over what your
|
|
139 computer does for you. Not everyone needs this amount of control, and
|
|
140 it does come at a cost: Learning the necessary script commands to
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
141 express what you want done. A complicated query, such as the example
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
142 above, takes time to learn. But if you find yourself using your
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
143 computer frequently enough, it is more than worthwhile in the long run.
|
33020
|
144 Any tool you use often deserves the time spent learning to master it.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
145 @footnote{For the understandably curious, here is what that command
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
146 looks like: But don't let it fool you; once you know what's going on,
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
147 it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.}
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
148
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
149 As of Emacs 21, Eshell is part of the standard Emacs distribution.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
150
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
151 @menu
|
33020
|
152 * Contributors to Eshell:: People who have helped out!
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
153 @end menu
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
154
|
45862
|
155 @node Contributors to Eshell
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
156 @section Contributors to Eshell
|
32542
|
157 @cindex contributors
|
|
158 @cindex authors
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
159
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
160 Contributions to Eshell are welcome. I have limited time to work on
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
161 this project, but I will gladly add any code you contribute to me to
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
162 this package.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
163
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
164 The following persons have made contributions to Eshell.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
165
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
166 @itemize @bullet
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
167 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
168 Eli Zaretskii made it possible for Eshell to run without requiring
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
169 asynchronous subprocess support. This is important for MS-DOS, which
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
170 does not have such support.@refill
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
171
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
172 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
173 Miles Bader contributed many fixes during the port to Emacs 21.@refill
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
174
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
175 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
176 Stefan Monnier fixed the things which bothered him, which of course made
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
177 things better for all.@refill
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
178
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
179 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
180 Gerd Moellmann also helped to contribute bug fixes during the initial
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
181 integration with Emacs 21.@refill
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
182
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
183 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
184 Alex Schroeder contributed code for interactively querying the user
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
185 before overwriting files.@refill
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
186
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
187 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
188 Sudish Joseph helped with some XEmacs compatibility issues.@refill
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
189 @end itemize
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
190
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
191 Apart from these, a lot of people have sent suggestions, ideas,
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
192 requests, bug reports and encouragement. Thanks a lot! Without you
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
193 there would be no new releases of Eshell.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
194
|
45862
|
195 @node Installation
|
32542
|
196 @chapter Installation
|
|
197 @cindex installation
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
198
|
33020
|
199 As mentioned above, Eshell comes preinstalled as of Emacs 21. If you're
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
200 using Emacs 20.4 or later, or XEmacs 21, you can download the most
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
201 recent version of Eshell from
|
48786
|
202 @url{http://www.gci-net.com/users/j/johnw/Emacs/packages/eshell.tar.gz}.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
203
|
33020
|
204 However, if you are using Emacs 21, you may skip this section.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
205
|
32542
|
206 @section Short Form
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
207
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
208 Here's exactly what to do, with no explanation why:
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
209
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
210 @enumerate
|
32542
|
211 @item
|
|
212 @samp{M-x load-file RET eshell-auto.el RET}.
|
|
213
|
|
214 @item
|
|
215 @samp{ESC : (add-to-list 'load-path "<path where Eshell resides>") RET}.
|
|
216
|
|
217 @item
|
|
218 @samp{ESC : (add-to-list 'load-path "<path where Pcomplete resides>") RET}.
|
|
219
|
|
220 @item
|
|
221 @samp{M-x eshell RET}.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
222
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
223 You should see a version banner displayed.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
224
|
32542
|
225 @item
|
|
226 @samp{ls RET}.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
227
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
228 Confirm that you see a file listing.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
229
|
32542
|
230 @item
|
|
231 @samp{eshell-test RET}.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
232
|
32542
|
233 Confirm that everything runs correctly. Use @kbd{M-x eshell-report-bug} if
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
234 not.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
235
|
32542
|
236 @item
|
|
237 @samp{cd $@{dirname (locate-library "eshell-auto")@} RET}.
|
|
238
|
|
239 @item
|
|
240 @samp{find-file Makefile RET}.
|
|
241
|
|
242 @item
|
|
243 Edit the Makefile to reflect your site.
|
|
244
|
|
245 @item
|
|
246 @samp{M-x eshell RET}.
|
|
247
|
|
248 @item
|
|
249 @samp{make install RET}.
|
|
250
|
|
251 @item
|
|
252 @samp{find-file $user-init-file RET}.
|
|
253
|
|
254 @item
|
|
255 Add the following lines to your @file{.emacs} file:
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
256
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
257 @example
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
258 (add-to-list 'load-path "<directory where you install Eshell>")
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
259 (load "eshell-auto")
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
260 @end example
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
261
|
32542
|
262 @item
|
|
263 @samp{M-x eshell RET}.
|
|
264
|
|
265 @item
|
|
266 @samp{customize-option #'eshell-modules-list RET}.
|
|
267
|
|
268 @item
|
|
269 Select the extension modules you prefer.
|
|
270
|
|
271 @item
|
|
272 Restart Emacs!
|
|
273
|
|
274 @item
|
|
275 @samp{M-x info RET m Eshell RET}.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
276
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
277 Read the manual and enjoy!
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
278 @end enumerate
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
279
|
32542
|
280 @section Long Form
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
281
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
282 @enumerate
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
283 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
284 Before building and installing Eshell, it is important to test that it
|
32542
|
285 will work properly on your system. To do this, first load the file
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
286 @file{eshell-auto}, which will define certain autoloads required to run
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
287 Eshell. This can be done using the command @kbd{M-x load-file}, and
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
288 then selecting the file @file{eshell-auto.el}.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
289
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
290 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
291 In order for Emacs to find Eshell's files, the Eshell directory must be
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
292 added to the @code{load-path} variable. This can be done within Emacs by
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
293 typing:
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
294
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
295 @example
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
296 ESC : (add-to-list 'load-path "<path where Eshell resides>") RET
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
297 ESC : (add-to-list 'load-path "<path where Pcomplete resides>") RET
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
298 @end example
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
299
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
300 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
301 Start Eshell from the distributed sources, using default settings, by
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
302 typing @kbd{M-x eshell}.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
303
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
304 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
305 Verify that Eshell is functional by typing @command{ls} followed by
|
32542
|
306 @key{RET}. You should have already seen a version banner announcing the
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
307 version number of this release, followed by a prompt.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
308
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
309 @item
|
32542
|
310 Run the test suite by typing @command{eshell-test} followed by @key{RET}
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
311 in the Eshell buffer. It is important that Emacs be left alone while
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
312 the tests are running, since extraneous command input may cause some of
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
313 the tests to fail (they were never intended to run in the background).
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
314 If all of the tests pass, Eshell should work just fine on your system.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
315 If any of the tests fail, please send e-mail to the Eshell maintainer
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
316 using the command @kbd{M-x eshell-report-bug}.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
317
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
318 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
319 Edit the file @file{Makefile} in the directory containing the Eshell
|
35588
|
320 sources to reflect the location of certain Emacs directories at your
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
321 site. The only things you really have to change are the definitions of
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
322 @code{lispdir} and @code{infodir}. The elisp files will be copied to
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
323 @code{lispdir}, and the info file to @code{infodir}.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
324
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
325 @item
|
32542
|
326 Type @kbd{make install} in the directory containing the Eshell sources.
|
|
327 This will byte-compile all of the @file{*.el} files and copy both the
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
328 source and compiled versions to the directories specified in the
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
329 previous step. It will also copy the info file, and add a corresponding
|
32542
|
330 entry to your @file{dir} file----if the program @code{install-info} can
|
|
331 be found on your system.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
332
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
333 If you only want to create the compiled elisp files, but don't want to
|
32542
|
334 install them, you can type just @kbd{make} instead.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
335
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
336 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
337 Add the directory into which Eshell was installed to your
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
338 @code{load-path} variable. This can be done by adding the following
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
339 line to your @file{.emacs} file:
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
340
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
341 @example
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
342 (add-to-list 'load-path "/usr/local/share/emacs/site-lisp/eshell")
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
343 @end example
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
344
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
345 The actual directory on your system may differ.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
346
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
347 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
348 To install Eshell privately, edit your @file{.emacs} file; to install
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
349 Eshell site-wide, edit the file @file{site-start.el} in your
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
350 @file{site-lisp} directory (usually
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
351 @file{/usr/local/share/emacs/site-lisp} or something similar). In
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
352 either case enter the following line into the appropriate file:
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
353
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
354 @example
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
355 (load "eshell-auto")
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
356 @end example
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
357
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
358 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
359 Restart Emacs. After restarting, customize the variable
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
360 @code{eshell-modules-list}. This variable selects which Eshell
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
361 extension modules you want to use. You will find documentation on each
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
362 of those modules in the Info manual.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
363 @end enumerate
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
364
|
32542
|
365 @cindex documentation, printed version
|
|
366 @cindex printed version of documentation
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
367 If you have @TeX{} installed at your site, you can make a typeset manual
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
368 from @file{eshell.texi}.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
369
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
370 @enumerate
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
371 @item
|
32542
|
372 Run @TeX{} by typing @kbd{texi2dvi eshell.texi}. (With Emacs 21.1 or
|
|
373 later, typing @kbd{make eshell.dvi} in the @file{man/} subdirectory of
|
|
374 the Emacs source distribution will do that.)
|
|
375
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
376 @item
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
377 Convert the resulting device independent file @file{eshell.dvi} to a
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
378 form which your printer can output and print it. If you have a
|
32542
|
379 postscript printer, there is a program, @code{dvi2ps}, which does that; there
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
380 is also a program which comes together with @TeX{}, @code{dvips}, which
|
32542
|
381 you can use. For other printers, use a suitable DVI driver,
|
|
382 e.g., @code{dvilj4} for LaserJet-compatible printers.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
383 @end enumerate
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
384
|
45862
|
385 @node Command basics
|
35588
|
386 @chapter Basic overview
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
387
|
35588
|
388 A command shell is a means of entering verbally-formed commands. This
|
|
389 is really all that it does, and every feature described in this manual
|
|
390 is a means to that end. Therefore, it's important to take firm hold on
|
|
391 exactly what a command is, and how it fits in the overall picture of
|
|
392 things.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
393
|
33020
|
394 @menu
|
|
395 * Commands verbs:: Commands always begin with a verb.
|
|
396 * Command arguments:: Some verbs require arguments.
|
|
397 @end menu
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
398
|
45862
|
399 @node Commands verbs
|
33020
|
400 @section Commands verbs
|
|
401
|
|
402 Commands are expressed using @dfn{script}, a special shorthand language
|
35588
|
403 computers can understand with no trouble. Script is an extremely simple
|
|
404 language; oddly enough, this is what makes it look so complicated!
|
|
405 Whereas normal languages use a variety of embellishments, the form of a
|
|
406 script command is always:
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
407
|
33020
|
408 @example
|
36508
|
409 @var{verb} [@var{arguments}]
|
33020
|
410 @end example
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
411
|
33020
|
412 The verb expresses what you want your computer to do. There are a fixed
|
|
413 number of verbs, although this number is usually quite large. On the
|
|
414 author's computer, it reaches almost 1400 in number. But of course,
|
|
415 only a handful of these are really necessary.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
416
|
33020
|
417 Sometimes, the verb is all that's written. A verb is always a single
|
35588
|
418 word, usually related to the task it performs. @command{reboot} is a
|
36508
|
419 good example. Entering that on GNU/Linux will reboot the
|
|
420 computer---assuming you have sufficient privileges.
|
33020
|
421
|
35588
|
422 Other verbs require more information. These are usually very capable
|
|
423 verbs, and must be told specifically what to do. The extra information
|
|
424 is given in the form of @dfn{arguments}. For example, the
|
|
425 @command{echo} verb prints back whatever arguments you type. It
|
|
426 requires these arguments to know what to echo. A proper use of
|
33020
|
427 @command{echo} looks like this:
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
428
|
33020
|
429 @example
|
36508
|
430 echo This is an example of using echo!
|
33020
|
431 @end example
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
432
|
35588
|
433 This script command causes the computer to echo back: ``This is an
|
36508
|
434 example of using echo!''
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
435
|
35588
|
436 Although command verbs are always simple words, like @command{reboot} or
|
|
437 @command{echo}, arguments may have a wide variety of forms. There are
|
|
438 textual arguments, numerical arguments---even Lisp arguments.
|
|
439 Distinguishing these different types of arguments requires special
|
|
440 typing, for the computer to know exactly what you mean.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
441
|
45862
|
442 @node Command arguments
|
33020
|
443 @section Command arguments
|
|
444
|
35588
|
445 Eshell recognizes several different kinds of command arguments:
|
|
446
|
|
447 @enumerate
|
|
448 @item Strings (also called textual arguments)
|
|
449 @item Numbers (floating point or integer)
|
|
450 @item Lisp lists
|
|
451 @item Lisp symbols
|
|
452 @item Emacs buffers
|
|
453 @item Emacs process handles
|
|
454 @end enumerate
|
|
455
|
35667
|
456 Most users need to worry only about the first two. The third, Lisp lists,
|
35588
|
457 occur very frequently, but almost always behind the scenes.
|
|
458
|
|
459 Strings are the most common type of argument, and consist of nearly any
|
|
460 character. Special characters---those used by Eshell
|
35667
|
461 specifically---must be preceded by a backslash (@samp{\}). When in doubt, it
|
|
462 is safe to add backslashes anywhere and everywhere.
|
35588
|
463
|
|
464 Here is a more complicated @command{echo} example:
|
|
465
|
|
466 @example
|
36508
|
467 echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar
|
35588
|
468 @end example
|
|
469
|
|
470 Beyond this, things get a bit more complicated. While not beyond the
|
|
471 reach of someone wishing to learn, it is definitely beyond the scope of
|
|
472 this manual to present it all in a simplistic manner. Get comfortable
|
|
473 with Eshell as a basic command invocation tool, and learn more about the
|
|
474 commands on your system; then come back when it all sits more familiarly
|
|
475 on your mind. Have fun!
|
|
476
|
45862
|
477 @node Commands
|
35588
|
478 @chapter Commands
|
|
479
|
|
480 @menu
|
49600
|
481 * Invocation::
|
|
482 * Completion::
|
|
483 * Aliases::
|
|
484 * History::
|
|
485 * Scripts::
|
45862
|
486 * Built-ins::
|
35588
|
487 @end menu
|
|
488
|
37283
|
489 Essentially, a command shell is all about invoking commands---and
|
|
490 everything that entails. So understanding how Eshell invokes commands
|
|
491 is the key to comprehending how it all works.
|
|
492
|
45862
|
493 @node Invocation
|
35588
|
494 @section Invocation
|
|
495
|
37283
|
496 Unlike regular system shells, Eshell never invokes kernel functions
|
|
497 directly, such as @code{exec(3)}. Instead, it uses the Lisp functions
|
|
498 available in the Emacs Lisp library. It does this by transforming the
|
|
499 command you specify into a callable Lisp form.@footnote{To see the Lisp
|
|
500 form that will be invoked, type: @samp{eshell-parse-command "echo
|
|
501 hello"}}
|
|
502
|
|
503 This transformation, from the string of text typed at the command
|
|
504 prompt, to the ultimate invocation of either a Lisp function or external
|
|
505 command, follows these steps:
|
|
506
|
|
507 @enumerate
|
|
508 @item Parse the command string into separate arguments.
|
49600
|
509 @item
|
37283
|
510 @end enumerate
|
|
511
|
45862
|
512 @node Completion
|
35588
|
513 @section Completion
|
|
514
|
45862
|
515 @node Aliases
|
35588
|
516 @section Aliases
|
|
517
|
45862
|
518 @node History
|
35588
|
519 @section History
|
|
520
|
45862
|
521 Eshell knows a few built-in variables:
|
|
522
|
|
523 @table @code
|
|
524
|
|
525 @item $+
|
|
526 @vindex $+
|
|
527 This variable always contains the current working directory.
|
|
528
|
|
529 @item $-
|
|
530 @vindex $-
|
|
531 This variable always contains the previous working directory (the
|
|
532 current working directory from before the last @code{cd} command).
|
|
533
|
|
534 @end table
|
|
535
|
|
536 @node Scripts
|
35588
|
537 @section Scripts
|
|
538
|
|
539
|
45862
|
540 @node Built-ins
|
|
541 @section Built-in commands
|
|
542
|
|
543 Here is a list of built-in commands that Eshell knows about:
|
|
544
|
|
545 @table @code
|
|
546
|
|
547 @item cd
|
|
548 @findex cd
|
|
549 This command changes the current working directory. Usually, it is
|
|
550 invoked as @samp{cd foo} where @file{foo} is the new working
|
|
551 directory. But @code{cd} knows about a few special arguments:
|
|
552
|
|
553 When it receives no argument at all, it changes to the home directory.
|
|
554
|
|
555 Giving the command @samp{cd -} changes back to the previous working
|
|
556 directory (this is the same as @samp{cd $-}).
|
|
557
|
45867
|
558 The command @samp{cd =} shows the directory stack. Each line is
|
|
559 numbered.
|
45862
|
560
|
|
561 With @samp{cd =foo}, Eshell searches the directory stack for a
|
|
562 directory matching the regular expression @samp{foo} and changes to
|
|
563 that directory.
|
|
564
|
45867
|
565 With @samp{cd -42}, you can access the directory stack by number.
|
|
566
|
45862
|
567 @end table
|
|
568
|
|
569
|
|
570 @node Arguments
|
35588
|
571 @chapter Arguments
|
|
572
|
|
573 @menu
|
49600
|
574 * The Parser::
|
|
575 * Variables::
|
|
576 * Substitution::
|
|
577 * Globbing::
|
|
578 * Predicates::
|
35588
|
579 @end menu
|
|
580
|
45862
|
581 @node The Parser
|
35588
|
582 @section The Parser
|
|
583
|
45862
|
584 @node Variables
|
35588
|
585 @section Variables
|
|
586
|
45862
|
587 @node Substitution
|
35588
|
588 @section Substitution
|
|
589
|
45862
|
590 @node Globbing
|
35588
|
591 @section Globbing
|
|
592
|
45862
|
593 @node Predicates
|
35588
|
594 @section Predicates
|
|
595
|
|
596
|
45862
|
597 @node Input/Output
|
35588
|
598 @chapter Input/Output
|
|
599
|
45862
|
600 @node Process control
|
35588
|
601 @chapter Process control
|
|
602
|
|
603
|
45862
|
604 @node Extension modules
|
35588
|
605 @chapter Extension modules
|
|
606
|
|
607 @menu
|
49600
|
608 * Writing a module::
|
|
609 * Module testing::
|
|
610 * Directory handling::
|
|
611 * Key rebinding::
|
|
612 * Smart scrolling::
|
|
613 * Terminal emulation::
|
|
614 * Built-in UNIX commands::
|
35588
|
615 @end menu
|
|
616
|
45862
|
617 @node Writing a module
|
35588
|
618 @section Writing a module
|
|
619
|
45862
|
620 @node Module testing
|
35588
|
621 @section Module testing
|
|
622
|
45862
|
623 @node Directory handling
|
35588
|
624 @section Directory handling
|
|
625
|
45862
|
626 @node Key rebinding
|
35588
|
627 @section Key rebinding
|
|
628
|
45862
|
629 @node Smart scrolling
|
35588
|
630 @section Smart scrolling
|
|
631
|
45862
|
632 @node Terminal emulation
|
35588
|
633 @section Terminal emulation
|
|
634
|
45862
|
635 @node Built-in UNIX commands
|
35588
|
636 @section Built-in UNIX commands
|
|
637
|
|
638
|
45862
|
639 @node Extras and Goodies
|
35588
|
640 @chapter Extras and Goodies
|
|
641
|
45862
|
642 @node Bugs and ideas
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
643 @chapter Bugs and ideas
|
32542
|
644 @cindex reporting bugs and ideas
|
|
645 @cindex bugs, how to report them
|
|
646 @cindex author, how to reach
|
|
647 @cindex email to the author
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
648 @cindex FAQ
|
32542
|
649 @cindex problems, list of common
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
650
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
651 If you find a bug or misfeature, don't hesitate to let me know! Send
|
32542
|
652 email to @email{johnw@@gnu.org}. Feature requests should also be sent
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
653 there. I prefer discussing one thing at a time. If you find several
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
654 unrelated bugs, please report them separately.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
655
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
656 If you have ideas for improvements, or if you have written some
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
657 extensions to this package, I would like to hear from you. I hope you
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
658 find this package useful!
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
659
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
660 @menu
|
49600
|
661 * Known problems::
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
662 @end menu
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
663
|
45862
|
664 @node Known problems
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
665 @section Known problems
|
32542
|
666 @cindex known bugs
|
|
667 @cindex bugs, known
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
668
|
35588
|
669 Below is complete list of known problems with Eshell version 2.4.1,
|
|
670 which is the version included with Emacs 21.1.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
671
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
672 @table @asis
|
53171
|
673 @item Documentation incomplete
|
|
674
|
33020
|
675 @item Differentiate between aliases and functions
|
|
676
|
|
677 Allow for a bash-compatible syntax, such as:
|
|
678
|
|
679 @example
|
|
680 alias arg=blah
|
33022
|
681 function arg () @{ blah $* @}
|
33020
|
682 @end example
|
|
683
|
|
684 @item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
685
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
686 In fact, piping to a process from a looping construct doesn't work in
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
687 general. If I change the call to @code{eshell-copy-handles} in
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
688 @code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
689 to work, but the output occurs after the prompt is displayed. The whole
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
690 structured command thing is too complicated at present.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
691
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
692 @item Error with @command{bc} in @code{eshell-test}
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
693
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
694 On some XEmacs system, the subprocess interaction test fails
|
32542
|
695 inexplicably, although @command{bc} works fine at the command prompt.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
696
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
697 @item Eshell does not delete @file{*Help*} buffers in XEmacs 21.1.8+
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
698
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
699 In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
700 multiple instances of the @file{*Help*} buffer can exist.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
701
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
702 @item Pcomplete sometimes gets stuck
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
703
|
32542
|
704 You press @key{TAB}, but no completions appear, even though the
|
|
705 directory has matching files. This behavior is rare.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
706
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
707 @item @samp{grep python $<rpm -qa>} doesn't work, but using @samp{*grep} does
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
708
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
709 This happens because the @code{grep} Lisp function returns immediately,
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
710 and then the asynchronous @command{grep} process expects to examine the
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
711 temporary file, which has since been deleted.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
712
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
713 @item Problem with C-r repeating text
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
714
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
715 If the text @emph{before point} reads "./run", and you type @kbd{C-r r u
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
716 n}, it will repeat the line for every character typed.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
717
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
718 @item Backspace doesn't scroll back after continuing (in smart mode)
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
719
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
720 Hitting space during a process invocation, such as @command{make}, will
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
721 cause it to track the bottom of the output; but backspace no longer
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
722 scrolls back.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
723
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
724 @item It's not possible to fully @code{unload-feature} Eshell
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
725
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
726 @item Menu support was removed, but never put back
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
727
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
728 @item Using C-p and C-n with rebind gets into a locked state
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
729
|
46918
|
730 This happened a few times in Emacs 21, but has been unreproducible
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
731 since.
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
732
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
733 @item If an interactive process is currently running, @kbd{M-!} doesn't work
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
734
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
735 @item Use a timer instead of @code{sleep-for} when killing child processes
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
736
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
737 @item Piping to a Lisp function is not supported
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
738
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
739 Make it so that the Lisp command on the right of the pipe is repeatedly
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
740 called with the input strings as arguments. This will require changing
|
33020
|
741 @code{eshell-do-pipeline} to handle non-process targets.
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
742
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
743 @item Input redirection is not supported
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
744
|
33020
|
745 See the above entry.
|
|
746
|
35588
|
747 @item Problem running @command{less} without arguments on Windows
|
33020
|
748
|
|
749 The result in the Eshell buffer is:
|
|
750
|
|
751 @example
|
|
752 Spawning child process: invalid argument
|
|
753 @end example
|
|
754
|
|
755 Also a new @command{less} buffer was created with nothing in it@dots{}
|
|
756 (presumably this holds the output of @command{less}).
|
|
757
|
|
758 If @command{less.exe} is invoked from the Eshell command line, the
|
|
759 expected output is written to the buffer.
|
|
760
|
33030
|
761 Note that this happens on NT-Emacs 20.6.1 on Windows 2000. The term.el
|
|
762 package and the supplied shell both use the @command{cmdproxy} program
|
|
763 for running shells.
|
33020
|
764
|
|
765 @item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp}
|
|
766
|
|
767 @item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be
|
|
768
|
33030
|
769 @item @samp{mv @var{dir} @var{file}.tar} does not remove directories
|
33020
|
770
|
|
771 This is because the tar option --remove-files doesn't do so. Should it
|
|
772 be Eshell's job?
|
|
773
|
|
774 @item Bind @code{standard-output} and @code{standard-error}
|
|
775
|
|
776 This would be so that if a Lisp function calls @code{print}, everything
|
|
777 will happen as it should (albeit slowly).
|
|
778
|
|
779 @item When an extension module fails to load, @samp{cd /} gives a Lisp error
|
|
780
|
|
781 @item If a globbing pattern returns one match, should it be a list?
|
|
782
|
|
783 @item Make sure syntax table is correct in Eshell mode
|
|
784
|
|
785 So that @kbd{M-DEL} acts in a predictable manner, etc.
|
|
786
|
|
787 @item Allow all Eshell buffers to share the same history and list-dir
|
|
788
|
|
789 @item There is a problem with script commands that output to @file{/dev/null}
|
|
790
|
|
791 If a script file, somewhere in the middle, uses @samp{> /dev/null},
|
|
792 output from all subsequent commands is swallowed.
|
|
793
|
|
794 @item Split up parsing of text after @samp{$} in @file{esh-var.el}
|
|
795
|
|
796 Make it similar to the way that @file{esh-arg.el} is structured.
|
|
797 Then add parsing of @samp{$[?\n]}.
|
|
798
|
|
799 @item After pressing @kbd{M-RET}, redisplay before running the next command
|
|
800
|
|
801 @item Argument predicates and modifiers should work anywhere in a path
|
|
802
|
|
803 @example
|
|
804 /usr/local/src/editors/vim $ vi **/CVS(/)/Root(.)
|
|
805 Invalid regexp: "Unmatched ( or \\("
|
|
806 @end example
|
|
807
|
|
808 With @command{zsh}, the glob above expands to all files named
|
|
809 @file{Root} in directories named @file{CVS}.
|
|
810
|
33022
|
811 @item Typing @samp{echo $@{locate locate@}/bin<TAB>} results in a Lisp error
|
33020
|
812
|
|
813 Perhaps it should interpolate all permutations, and make that the
|
|
814 globbing result, since otherwise hitting return here will result in
|
|
815 ``(list of filenames)/bin'', which is never valuable. Thus, one could
|
33022
|
816 @command{cat} only C backup files by using @samp{ls $@{identity *.c@}~}.
|
33020
|
817 In that case, having an alias command name @command{glob} for
|
|
818 @command{identity} would be useful.
|
|
819
|
|
820 @item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp
|
|
821
|
|
822 @item Create @code{eshell-expand-file-name}
|
|
823
|
|
824 This would use a data table to transform things such as @samp{~+},
|
|
825 @samp{...}, etc.
|
|
826
|
|
827 @item Abstract @file{em-smart.el} into @file{smart-scroll.el}
|
|
828
|
|
829 It only really needs: to be hooked onto the output filter and the
|
|
830 pre-command hook, and to have the input-end and input-start markers.
|
36508
|
831 And to know whether the last output group was ``successful.''
|
33020
|
832
|
|
833 @item Allow for fully persisting the state of Eshell
|
|
834
|
|
835 This would include: variables, history, buffer, input, dir stack, etc.
|
|
836
|
|
837 @item Implement D as an argument predicate
|
|
838
|
|
839 It means that files beginning with a dot should be included in the
|
|
840 glob match.
|
|
841
|
|
842 @item A comma in a predicate list should mean OR
|
|
843
|
|
844 At the moment, this is not supported.
|
|
845
|
|
846 @item Error if a glob doesn't expand due to a predicate
|
|
847
|
|
848 An error should be generated only if @code{eshell-error-if-no-glob} is
|
|
849 non-nil.
|
|
850
|
|
851 @item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur
|
|
852
|
|
853 @item Create @code{eshell-auto-accumulate-list}
|
|
854
|
|
855 This is a list of commands for which, if the user presses @kbd{RET}, the
|
|
856 text is staged as the next Eshell command, rather than being sent to the
|
|
857 current interactive process.
|
|
858
|
|
859 @item Display file and line number if an error occurs in a script
|
|
860
|
|
861 @item @command{wait} doesn't work with process ids at the moment
|
|
862
|
|
863 @item Enable the direct-to-process input code in @file{em-term.el}
|
|
864
|
|
865 @item Problem with repeating @samp{echo $@{find /tmp@}}
|
|
866
|
|
867 With smart display active, if @kbd{RET} is held down, after a while it
|
|
868 can't keep up anymore and starts outputting blank lines. It only
|
|
869 happens if an asynchronous process is involved@dots{}
|
|
870
|
|
871 I think the problem is that @code{eshell-send-input} is resetting the
|
|
872 input target location, so that if the asynchronous process is not done
|
|
873 by the time the next @kbd{RET} is received, the input processor thinks
|
|
874 that the input is meant for the process; which, when smart display is
|
|
875 enabled, will be the text of the last command line! That is a bug in
|
|
876 itself.
|
|
877
|
|
878 In holding down @kbd{RET} while an asynchronous process is running,
|
|
879 there will be a point in between termination of the process, and the
|
|
880 running of @code{eshell-post-command-hook}, which would cause
|
|
881 @code{eshell-send-input} to call @code{eshell-copy-old-input}, and then
|
|
882 process that text as a command to be run after the process. Perhaps
|
|
883 there should be a way of killing pending input between the death of the
|
|
884 process, and the @code{post-command-hook}.
|
|
885
|
|
886 @item Allow for a more aggressive smart display mode
|
|
887
|
|
888 Perhaps toggled by a command, that makes each output block a smart
|
|
889 display block.
|
|
890
|
|
891 @item Create more meta variables
|
|
892
|
|
893 @table @samp
|
|
894 @item $!
|
|
895 The reason for the failure of the last disk command, or the text of the
|
|
896 last Lisp error.
|
|
897
|
|
898 @item $=
|
|
899 A special associate array, which can take references of the form
|
|
900 @samp{$=[REGEXP]}. It indexes into the directory ring.
|
|
901 @end table
|
|
902
|
|
903 @item Eshell scripts can't execute in the background
|
|
904
|
33030
|
905 @item Support zsh's ``Parameter Expansion'' syntax, i.e. @samp{$@{@var{name}:-@var{val}@}}
|
33020
|
906
|
|
907 @item Write an @command{info} alias that can take arguments
|
|
908
|
|
909 So that the user can enter @samp{info chmod}, for example.
|
|
910
|
|
911 @item Create a mode @code{eshell-browse}
|
|
912
|
|
913 It would treat the Eshell buffer as a outline. Collapsing the outline
|
|
914 hides all of the output text. Collapsing again would show only the
|
|
915 first command run in each directory
|
|
916
|
|
917 @item Allow other revisions of a file to be referenced using @samp{file@{rev@}}
|
|
918
|
|
919 This would be expanded by @code{eshell-expand-file-name} (see above).
|
|
920
|
|
921 @item Print ``You have new mail'' when the ``Mail'' icon is turned on
|
|
922
|
|
923 @item Implement @kbd{M-|} for Eshell
|
|
924
|
|
925 @item Implement input redirection
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
926
|
33020
|
927 If it's a Lisp function, input redirection implies @command{xargs} (in a
|
|
928 way@dots{}). If input redirection is added, also update the
|
|
929 @code{file-name-quote-list}, and the delimiter list.
|
|
930
|
33030
|
931 @item Allow @samp{#<@var{word} @var{arg}>} as a generic syntax
|
33020
|
932
|
|
933 With the handling of @emph{word} specified by an
|
|
934 @code{eshell-special-alist}.
|
|
935
|
35588
|
936 @item In @code{eshell-veal-using-options}, allow a @code{:complete} tag
|
33020
|
937
|
|
938 It would be used to provide completion rules for that command. Then the
|
|
939 macro will automagically define the completion function.
|
|
940
|
|
941 @item For @code{eshell-command-on-region}, apply redirections to the result
|
|
942
|
|
943 So that @samp{+ > 'blah} would cause the result of the @code{+} (using
|
|
944 input from the current region) to be inserting into the symbol
|
|
945 @code{blah}.
|
|
946
|
|
947 If an external command is being invoked, the input is sent as standard
|
|
948 input, as if a @samp{cat <region> |} had been invoked.
|
|
949
|
|
950 If a Lisp command, or an alias, is invoked, then if the line has no
|
|
951 newline characters, it is divided by whitespace and passed as arguments
|
|
952 to the Lisp function. Otherwise, it is divided at the newline
|
|
953 characters. Thus, invoking @code{+} on a series of numbers will add
|
|
954 them; @code{min} would display the smallest figure, etc.
|
|
955
|
|
956 @item Write @code{eshell-script-mode} as a minor mode
|
|
957
|
|
958 It would provide syntax, abbrev, highlighting and indenting support like
|
|
959 @code{emacs-lisp-mode} and @code{shell-mode}.
|
|
960
|
|
961 @item In the history mechanism, finish the @command{bash}-style support
|
|
962
|
|
963 This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate
|
|
964 from @samp{!:1*}.
|
|
965
|
|
966 @item Support the -n command line option for @command{history}
|
|
967
|
|
968 @item Implement @command{fc} in Lisp
|
|
969
|
|
970 @item Specifying a frame as a redirection target should imply the currently active window's buffer
|
|
971
|
33030
|
972 @item Implement @samp{>@var{func-or-func-list}}
|
33020
|
973
|
|
974 This would allow for an ``output translators'', that take a function to
|
|
975 modify output with, and a target. Devise a syntax that works well with
|
46918
|
976 pipes, and can accommodate multiple functions (i.e., @samp{>'(upcase
|
33020
|
977 regexp-quote)} or @samp{>'upcase}).
|
|
978
|
|
979 @item Allow Eshell to read/write to/from standard input and output
|
|
980
|
|
981 This would be optional, rather than always using the Eshell buffer.
|
|
982 This would allow it to be run from the command line (perhaps).
|
|
983
|
|
984 @item Write a @command{help} command
|
|
985
|
33030
|
986 It would call subcommands with @option{--help}, or @option{-h} or
|
|
987 @option{/?}, as appropriate.
|
33020
|
988
|
|
989 @item Implement @command{stty} in Lisp
|
|
990
|
33030
|
991 @item Support @command{rc}'s matching operator, e.g. @samp{~ (@var{list}) @var{regexp}}
|
33020
|
992
|
|
993 @item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list}
|
|
994
|
|
995 Using @command{bg} on a process that is already in the background does
|
|
996 nothing. Specifying redirection targets replaces (or adds) to the list
|
|
997 current being used.
|
|
998
|
|
999 @item Have @command{jobs} print only the processes for the current shell
|
|
1000
|
|
1001 @item How can Eshell learn if a background process has requested input?
|
|
1002
|
|
1003 @item Support @samp{2>&1} and @samp{>&} and @samp{2>} and @samp{|&}
|
|
1004
|
|
1005 The syntax table for parsing these should be customizable, such that the
|
|
1006 user could change it to use rc syntax: @samp{>[2=1]}.
|
|
1007
|
|
1008 @item Allow @samp{$_[-1]}, which would indicate the last element of the array
|
|
1009
|
|
1010 @item Make @samp{$x[*]} equal to listing out the full contents of @samp{x}
|
|
1011
|
|
1012 Return them as a list, so that @samp{$_[*]} is all the arguments of the
|
|
1013 last command.
|
|
1014
|
|
1015 @item Copy ANSI code handling from @file{term.el} into @file{em-term.el}
|
|
1016
|
|
1017 Make it possible for the user to send char-by-char to the underlying
|
|
1018 process. Ultimately, I should be able to move away from using term.el
|
|
1019 altogether, since everything but the ANSI code handling is already part
|
33030
|
1020 of Eshell. Then, things would work correctly on MS-Windows as well
|
|
1021 (which doesn't have @file{/bin/sh}, although @file{term.el} tries to use
|
|
1022 it).
|
33020
|
1023
|
|
1024 @item Make the shell spawning commands be visual
|
|
1025
|
|
1026 That is, make (@command{su}, @command{bash}, @command{telnet},
|
|
1027 @command{rlogin}, @command{rsh}, etc.) be part of
|
|
1028 @code{eshell-visual-commands}. The only exception is if the shell is
|
|
1029 being used to invoke a single command. Then, the behavior should be
|
|
1030 based on what that command is.
|
|
1031
|
33030
|
1032 @item Create a smart viewing command named @command{open}
|
33020
|
1033
|
|
1034 This would search for some way to open its argument (similar to opening
|
|
1035 a file in the Windows Explorer).
|
|
1036
|
|
1037 @item Alias @command{read} to be the same as @command{open}, only read-only
|
|
1038
|
|
1039 @item Write a @command{tail} command which uses @code{view-file}
|
|
1040
|
|
1041 It would move point to the end of the buffer, and then turns on
|
|
1042 auto-revert mode in that buffer at frequent intervals---and a
|
|
1043 @command{head} alias which assums an upper limit of
|
|
1044 @code{eshell-maximum-line-length} characters per line.
|
|
1045
|
|
1046 @item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search}
|
|
1047
|
35588
|
1048 @item Write mesh.c
|
33020
|
1049
|
|
1050 This would run Emacs with the appropriate arguments to invoke Eshell
|
|
1051 only. That way, it could be listed as a login shell.
|
|
1052
|
|
1053 @item Use an intangible @code{PS2} string for multi-line input prompts
|
|
1054
|
|
1055 @item Auto-detect when a command is visual, by checking @code{TERMCAP} usage
|
|
1056
|
|
1057 @item The first keypress after @kbd{M-x watson} triggers `eshell-send-input'
|
|
1058
|
|
1059 @item Make @kbd{/} electric
|
|
1060
|
|
1061 So that it automatically expands and corrects pathnames. Or make
|
|
1062 pathname completion for Pcomplete auto-expand @samp{/u/i/std<TAB>} to
|
|
1063 @samp{/usr/include/std<TAB>}.
|
|
1064
|
|
1065 @item Write the @command{pushd} stack to disk along with @code{last-dir-ring}
|
|
1066
|
|
1067 @item Add options to @code{eshell/cat} which would allow it to sort and uniq
|
|
1068
|
|
1069 @item Implement @command{wc} in Lisp
|
|
1070
|
|
1071 Add support for counting sentences, paragraphs, pages, etc.
|
|
1072
|
|
1073 @item Once piping is added, implement @command{sort} and @command{uniq} in Lisp
|
|
1074
|
|
1075 @item Implement @command{touch} in Lisp
|
|
1076
|
|
1077 @item Implement @command{comm} in Lisp
|
|
1078
|
|
1079 @item Implement an @command{epatch} command in Lisp
|
|
1080
|
|
1081 This would call @code{ediff-patch-file}, or @code{ediff-patch-buffer},
|
|
1082 depending on its argument.
|
|
1083
|
|
1084 @item Have an option such that @samp{ls -l} generates a dired buffer
|
|
1085
|
|
1086 @item Write a version of @command{xargs} based on command rewriting
|
|
1087
|
|
1088 That is, @samp{find X | xargs Y} would be indicated using @samp{Y
|
|
1089 $@{find X@}}. Maybe @code{eshell-do-pipelines} could be changed to
|
|
1090 perform this on-thy-fly rewriting.
|
|
1091
|
|
1092 @item Write an alias for @command{less} that brings up a @code{view-mode} buffer
|
|
1093
|
33030
|
1094 Such that the user can press @key{SPC} and @key{DEL}, and then @key{q}
|
49600
|
1095 to return to Eshell. It would be equivalent to:
|
33020
|
1096 @samp{X > #<buffer Y>; view-buffer #<buffer Y>}.
|
|
1097
|
|
1098 @item Make @code{eshell-mode} as much a full citizen as @code{shell-mode}
|
|
1099
|
|
1100 Everywhere in Emacs where @code{shell-mode} is specially noticed, add
|
|
1101 @code{eshell-mode} there.
|
|
1102
|
|
1103 @item Permit the umask to be selectively set on a @command{cp} target
|
|
1104
|
|
1105 @item Problem using @kbd{M-x eshell} after using @code{eshell-command}
|
|
1106
|
|
1107 If the first thing that I do after entering Emacs is to run
|
|
1108 @code{eshell-command} and invoke @command{ls}, and then use @kbd{M-x
|
|
1109 eshell}, it doesn't display anything.
|
|
1110
|
|
1111 @item @kbd{M-RET} during a long command (using smart display) doesn't work
|
|
1112
|
|
1113 Since it keeps the cursor up where the command was invoked.
|
|
1114
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1115 @end table
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1116
|
45862
|
1117 @node Concept Index
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1118 @unnumbered Concept Index
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1119
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1120 @printindex cp
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1121
|
45862
|
1122 @node Function and Variable Index
|
32542
|
1123 @unnumbered Function and Variable Index
|
|
1124
|
|
1125 @printindex fn
|
|
1126
|
45862
|
1127 @node Key Index
|
32450
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1128 @unnumbered Key Index
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1129
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1130 @printindex ky
|
99899af1ec94
Added the beginnings of proper Eshell documentation.
John Wiegley <johnw@newartisans.com>
parents:
diff
changeset
|
1131 @bye
|
52401
|
1132
|
|
1133 @ignore
|
|
1134 arch-tag: 776409ba-cb15-42b9-b2b6-d2bdc7ebad01
|
|
1135 @end ignore
|