Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

Added documentation files.

  • Loading branch information...
commit 728ad1af4913add4df8a41d02519c996cd609284 1 parent d8eea43
@jwiegley jwiegley authored
Showing with 1,789 additions and 0 deletions.
  1. +674 −0 COPYING
  2. +69 −0 FEATURES
  3. +109 −0 INSTALL
  4. +937 −0 NEWS
@@ -0,0 +1,674 @@
+ Version 3, 29 June 2007
+ Copyright (C) 2007 Free Software Foundation, Inc. <>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+ Preamble
+ The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+ The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works. By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users. We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors. You can apply it to
+your programs, too.
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+ To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights. Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received. You must make sure that they, too, receive
+or can get the source code. And you must show them these terms so they
+know their rights.
+ Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+ For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software. For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+ Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so. This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software. The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable. Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products. If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+ Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary. To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+ The precise terms and conditions for copying, distribution and
+modification follow.
+ 0. Definitions.
+ "This License" refers to version 3 of the GNU General Public License.
+ "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+ "The Program" refers to any copyrightable work licensed under this
+License. Each licensee is addressed as "you". "Licensees" and
+"recipients" may be individuals or organizations.
+ To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy. The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+ A "covered work" means either the unmodified Program or a work based
+on the Program.
+ To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+ To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies. Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+ An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License. If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+ 1. Source Code.
+ The "source code" for a work means the preferred form of the work
+for making modifications to it. "Object code" means any non-source
+form of a work.
+ A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+ The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form. A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+ The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities. However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work. For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+ The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+ The Corresponding Source for a work in source code form is that
+same work.
+ 2. Basic Permissions.
+ All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met. This License explicitly affirms your unlimited
+permission to run the unmodified Program. The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work. This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+ You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force. You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright. Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+ Conveying under any other circumstances is permitted solely under
+the conditions stated below. Sublicensing is not allowed; section 10
+makes it unnecessary.
+ 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+ No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+ When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+ 4. Conveying Verbatim Copies.
+ You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+ You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+ 5. Conveying Modified Source Versions.
+ You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+ a) The work must carry prominent notices stating that you modified
+ it, and giving a relevant date.
+ b) The work must carry prominent notices stating that it is
+ released under this License and any conditions added under section
+ 7. This requirement modifies the requirement in section 4 to
+ "keep intact all notices".
+ c) You must license the entire work, as a whole, under this
+ License to anyone who comes into possession of a copy. This
+ License will therefore apply, along with any applicable section 7
+ additional terms, to the whole of the work, and all its parts,
+ regardless of how they are packaged. This License gives no
+ permission to license the work in any other way, but it does not
+ invalidate such permission if you have separately received it.
+ d) If the work has interactive user interfaces, each must display
+ Appropriate Legal Notices; however, if the Program has interactive
+ interfaces that do not display Appropriate Legal Notices, your
+ work need not make them do so.
+ A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit. Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+ 6. Conveying Non-Source Forms.
+ You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+ a) Convey the object code in, or embodied in, a physical product
+ (including a physical distribution medium), accompanied by the
+ Corresponding Source fixed on a durable physical medium
+ customarily used for software interchange.
+ b) Convey the object code in, or embodied in, a physical product
+ (including a physical distribution medium), accompanied by a
+ written offer, valid for at least three years and valid for as
+ long as you offer spare parts or customer support for that product
+ model, to give anyone who possesses the object code either (1) a
+ copy of the Corresponding Source for all the software in the
+ product that is covered by this License, on a durable physical
+ medium customarily used for software interchange, for a price no
+ more than your reasonable cost of physically performing this
+ conveying of source, or (2) access to copy the
+ Corresponding Source from a network server at no charge.
+ c) Convey individual copies of the object code with a copy of the
+ written offer to provide the Corresponding Source. This
+ alternative is allowed only occasionally and noncommercially, and
+ only if you received the object code with such an offer, in accord
+ with subsection 6b.
+ d) Convey the object code by offering access from a designated
+ place (gratis or for a charge), and offer equivalent access to the
+ Corresponding Source in the same way through the same place at no
+ further charge. You need not require recipients to copy the
+ Corresponding Source along with the object code. If the place to
+ copy the object code is a network server, the Corresponding Source
+ may be on a different server (operated by you or a third party)
+ that supports equivalent copying facilities, provided you maintain
+ clear directions next to the object code saying where to find the
+ Corresponding Source. Regardless of what server hosts the
+ Corresponding Source, you remain obligated to ensure that it is
+ available for as long as needed to satisfy these requirements.
+ e) Convey the object code using peer-to-peer transmission, provided
+ you inform other peers where the object code and Corresponding
+ Source of the work are being offered to the general public at no
+ charge under subsection 6d.
+ A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+ A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling. In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage. For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product. A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+ "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source. The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+ If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information. But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+ The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed. Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+ Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+ 7. Additional Terms.
+ "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law. If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+ When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it. (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.) You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+ Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+ a) Disclaiming warranty or limiting liability differently from the
+ terms of sections 15 and 16 of this License; or
+ b) Requiring preservation of specified reasonable legal notices or
+ author attributions in that material or in the Appropriate Legal
+ Notices displayed by works containing it; or
+ c) Prohibiting misrepresentation of the origin of that material, or
+ requiring that modified versions of such material be marked in
+ reasonable ways as different from the original version; or
+ d) Limiting the use for publicity purposes of names of licensors or
+ authors of the material; or
+ e) Declining to grant rights under trademark law for use of some
+ trade names, trademarks, or service marks; or
+ f) Requiring indemnification of licensors and authors of that
+ material by anyone who conveys the material (or modified versions of
+ it) with contractual assumptions of liability to the recipient, for
+ any liability that these contractual assumptions directly impose on
+ those licensors and authors.
+ All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10. If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term. If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+ If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+ Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+ 8. Termination.
+ You may not propagate or modify a covered work except as expressly
+provided under this License. Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+ However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+ Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+ Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+ 9. Acceptance Not Required for Having Copies.
+ You are not required to accept this License in order to receive or
+run a copy of the Program. Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance. However,
+nothing other than this License grants you permission to propagate or
+modify any covered work. These actions infringe copyright if you do
+not accept this License. Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+ 10. Automatic Licensing of Downstream Recipients.
+ Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License. You are not responsible
+for enforcing compliance by third parties with this License.
+ An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations. If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+ You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License. For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+ 11. Patents.
+ A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based. The
+work thus licensed is called the contributor's "contributor version".
+ A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version. For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+ Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+ In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement). To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+ If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients. "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+ If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+ A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License. You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+ Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+ 12. No Surrender of Others' Freedom.
+ If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all. For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+ 13. Use with the GNU Affero General Public License.
+ Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work. The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+ 14. Revised Versions of this License.
+ The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+ Each version is given a distinguishing version number. If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation. If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+ If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+ Later license versions may give you additional or different
+permissions. However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+ 15. Disclaimer of Warranty.
+ 16. Limitation of Liability.
+ 17. Interpretation of Sections 15 and 16.
+ If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+ How to Apply These Terms to Your New Programs
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+ <one line to give the program's name and a brief idea of what it does.>
+ Copyright (C) <year> <name of author>
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ GNU General Public License for more details.
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <>.
+Also add information on how to contact you by electronic and paper mail.
+ If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+ <program> Copyright (C) <year> <name of author>
+ This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License. Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+ You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+ The GNU General Public License does not permit incorporating your program
+into proprietary programs. If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library. If this is what you want to do, use the GNU Lesser General
+Public License instead of this License. But first, please read
@@ -0,0 +1,69 @@
+Here are some of the fun things that Eshell can do, for those too
+impatient for manuals!
+- First off, Eshell should work anywhere that Emacs does. Eshell uses
+ no external processes -- only Emacs Lisp functions. So if
+ `directory-files' returns a list of filenames on your VAX, then
+ Eshell's implementation of ls should too.
+- Lisp functions can be called using either Lisp or Eshell syntax.
+ Take the `+' function, for example:
+ /tmp $ (+ 1 2)
+ 3
+ /tmp $ + 1 2
+ 3
+ In the first case, the Lisp expression is simply handed to the Lisp
+ interpretor. In the second case, the arguments are parsed by
+ Eshell, and converted to numbers because they look like numbers.
+ The argument list is then passed to `+'.
+- Several things return lists as their result. Globbing and command
+ interpolation are good examples. This means you can pass these
+ lists to Lisp functions that can deal with lists.
+ For example, the `length' function, if passed a list, will return
+ the number of items in the list. And since a globbing pattern
+ always returns a list, here is a way to tell how many files match a
+ glob:
+ /tmp $ length *.el
+ Finding out the same information on UNIX requires two process
+ invocations:
+ /tmp $ ls -1 *.el | wc -l
+ This version can also be used with Eshell, but it's more complex,
+ and more expensive.
+- Command interpolations result in lists as well. Each element of the
+ list represents one line of the command's output.
+ /tmp $ length ${egrep johnw /etc/passwd}
+- To review all occurances of a regexp anywhere in the command outputs
+ of the current Eshell session, enter:
+ /tmp $ occur REGEXP
+- Instead of "find . -print | xargs grep REGEXP", you can use Eshell's
+ recursive globbing syntax, which is taken from zsh:
+ /tmp $ grep REGEXP **/*(.) # grep all normal files
+ This command will also display the grep hits in a "*grep*" buffer,
+ allowing you to type C-x ` to visit the locations of the hits. The
+ "(.)" at the end of the glob pattern is an argument predicate, which
+ constrains the resulting list to only those entries for which
+ `file-regular-p' returns true.
+- bash-style history references (!, C-r, C-p, etc).
+- Supports 4nt's history reference style of typing the beginning of a
+ command, and then hitting up arrow to see all the commands beginning
+ with that text.
+- There are a lot of other things, but I'm always so tired when I get
+ to this point.
@@ -0,0 +1,109 @@
+Installing Eshell
+Here's exactly what to do, with no explanation why.
+ 1. M-x load-file RET eshell-auto.el RET
+ 2. ESC : (add-to-list 'load-path "<path where Eshell resides>") RET
+ 3. ESC : (add-to-list 'load-path "<path where Pcomplete resides>") RET
+ 4. M-x eshell RET ; should see a version banner displayed
+ 5. ls RET ; confirm that you see a file listing
+ 6. eshell-test RET ; confirm that everything runs correctly
+ ; use `M-x eshell-report-bug' if not
+ 7. cd ${dirname (locate-library "eshell-auto")} RET
+ 8. find-file Makefile RET
+ 9. [edit the Makefile to reflect your site]
+ 10. M-x eshell RET
+ 11. make install RET
+ 12. find-file $user-init-file RET
+ 13. [add the following lines to your .emacs file]
+ (add-to-list 'load-path "<directory where you install Eshell>")
+ (load "eshell-auto")
+ 14. M-x eshell RET
+ 15. customize-option #'eshell-modules-list RET
+ 16. [select the extension modules you prefer]
+ 17. [restart Emacs!]
+ 18. M-x info RET m Eshell RET ; read the manual and enjoy!
+ 1. Before building and installing Eshell, it is important to test
+ that it will work properly on your system. To do this, first load
+ `eshell-auto', which will define certain autoloads required to run
+ Eshell. This can be done using the command `M-x load-file', and
+ then selecting the file "eshell-auto.el".
+ 2. In order for Emacs to find Eshell's files, the Eshell directory
+ must be added to the `load-path' variable. This can be done
+ within Emacs by typing:
+ ESC : (add-to-list 'load-path "<path where Eshell resides>") RET
+ ESC : (add-to-list 'load-path "<path where Pcomplete resides>") RET
+ 2. Start Eshell from the distributed sources, using default settings,
+ by typing `M-x eshell'.
+ 3. Verify that Eshell is functional by typing "ls" followed by RET.
+ You should have already seen a version banner announcing the
+ version number of this release, followed by a prompt.
+ 4. Run the test suite by typing "eshell-test" followed by RET in the
+ Eshell buffer. It is important that Emacs be left alone while the
+ tests are running, since extraneous command input may cause some
+ of the tests to fail (they were never intended to run in the
+ background). If all of the tests pass, Eshell should work just
+ fine on your system. If any of the tests fail, please send e-mail
+ to the Eshell maintainer using the command `M-x eshell-report-bug'.
+ 5. Edit the file `Makefile' in the directory containing the Eshell
+ sources to reflect the location of certain Emacs dircetories at
+ your site. The only things you really have to change are the
+ definitions of `lispdir' and `infodir'. The elisp files will be
+ copied to `lispdir', and the info file to `infodir'.
+ 6. Type `make install' in the directory containing the Eshell
+ sources. This will byte-compile all of the `.el' files and copy
+ both the source and compiled versions to the directories specified
+ in the previous step. It will also copy the info file, and add a
+ corresponding entry to your "dir" file -- if install-info can be
+ found.
+ If you only want to create the compiled elisp files, but don't
+ want to install them, you can type just `make' instead.
+ 7. Add the directory into which Eshell was installed to your
+ `load-path' variable. This can be done by adding the following
+ line to your .emacs file:
+ (add-to-list 'load-path "/usr/local/share/emacs/site-lisp/eshell")
+ The actual directory on your system may differ.
+ 8. To install Eshell privately, edit your .emacs file; to install
+ Eshell site-wide, edit the file `site-start.el' in your site-lisp
+ directory (usually `/usr/local/share/emacs/site-lisp' or something
+ similar). In either case enter the following line into the
+ appropriate file:
+ (load "eshell-auto")
+ 9. Restart Emacs. After restarting, customize the variable
+ `eshell-modules-list'. This variable selects which Eshell
+ extension modules you want to use. You will find documentation on
+ each of those modules in the Info manual.
+10. Read the Info manual. Although Eshell behaves like most ordinary
+ shells, it has other advanced features and Lisp integration
+ facilities that require a more thorough presentation than these
+ meager notes.
+How to make typeset documentation from eshell.doci
+ If you have TeX installed at your site, you can make a typeset
+manual from `eshell.doci' by typing "make eshell.dvi". If you prefer
+a postscript version of this file, use "make" instead.
937 NEWS
@@ -0,0 +1,937 @@
+-*- mode: text; outline-layout: (1 :) -*-
+This is the NEWS file for Eshell, a command shell written in Emacs
+Please note that proper documentation is still on its way.
+* Changes in 2.4.2:
+** This is just a bug fix release, following 2.4.1 after about six
+ months.
+* Changes in 2.4:
+** Primarily a performance release, in addition to a few slight
+ changes in avaliable configuration variables:
+** There is a distinction made between "simple" and "complex"
+ functions. Complex functions are likely to cause modifications to
+ the running Eshell command form, and thus require a form of
+ evaluation that simulates Scheme continuations. This uses three
+ times as much memory as using plain `eval', which is entirely
+ sufficient for "simple" commands such as ls, cp, mv, etc.
+ NOTE: If you write a command named eshell/NAME, which must throw
+ either `eshell-defer' or `eshell-replace-command', you must add
+ NAME to `eshell-complex-commands'.
+** `ls' now uses `eshell-ls-exclude-hidden' to indicate that files
+ beginning with a dot should be excluded.
+** `eshell-glob-show-progress' is now nil by default, since it slows
+ down recursive glob processing so much.
+** ange-ftp is no longer required to compile Eshell, which broke
+ XEmacs users in 2.3.2.
+** `eshell-ls-initial-args' is new, and should be used instead of
+ command aliases to introduce a common argument (such as -h).
+** Command aliases and smart scrolling are both very slow and memory
+ consumptive, although not much can be done about this. For
+ complicated commands that themselves run slowly, the percentile
+ impact is little. But for quick, simple commands such as cd, ls,
+ etc., command aliases should definitely be avoided. And while
+ smart scrolling (eshell-smart) is quite useful, it should be run on
+ fast machines to be fully appreciated.
+** The new option `eshell-stringify-t' determines whether Lisp `t'
+ should be rendered as `t', or not at all. The truth of an
+ expression can still be determined using:
+ file-exists-p FILE && echo true
+** Added a new option `eshell-default-target-is-dot', which if non-nil
+ states that the default target of cp/mv/ln is the current
+ directory, which mirrors the behavior of most DOS shells.
+* Changes in 2.3.2:
+** More bug fixes. Greatly improved remote directory support, since
+ now nearly all file attributes can be viewed.
+* Changes in 2.3.1:
+** This a bug fix release, in preparation for inclusion as part of
+ Emacs 21.
+** One little feature, however, did sneak in: C-c C-y in the Eshell
+ buffer will repeat the last argument entered. With a numeric
+ prefix, it will repeat that many arguments.
+* Changes in 2.3:
+** The control flow commands: if, unless, while, until: now test the
+ exit code of external processes against 0 for truth, and the value
+ of Lisp forms against t. Before, they would only check to see if
+ the test expression generated output.
+** Because the Elisp manual declares that C-c LETTER bindings be left
+ to the user, several of Eshell's command mode bindings had to be
+ changed. The equivalences are:
+ 2.2 2.3
+ ----- -------
+ C-c e C-c M-v
+ C-c p C-c M-i
+ C-c h C-c M-o
+ C-c b C-c M-b
+ C-c l C-c M-l
+ C-c ? C-c M-q,
+ C-c m C-c M-m
+ C-c i C-c M-h
+** Added support for a ksh feature: "cd OLD NEW". This will replace
+ OLD with NEW in the current directory name (the name returned by
+ `pwd' specifically), and then attempt to change to that directory.
+** Added a syntax convenience for short-circuited commands:
+ file-exists-p file.cpp && echo file exists
+ file-exists-p file.cpp || echo file does not exist
+ These operators test either the return code of the Lisp function on
+ the left-hand side (to determine if it's non-nil), or the exit code
+ of an external function (testing for 0), whichever is appropriate.
+ The precedence for these operators is lower than sequencing (;) and
+ backgrounding (&), but higher than redirection (>) and piping (|).
+ Within themselves, they are strictly left to right. In this sense,
+ it acts on a chain of success and failure, continuing to the next
+ part of the chain only if the operator would allow it.
+** Added three new configuration variables:
+ eshell-mv-overwrite-files
+ eshell-cp-overwrite-files
+ eshell-ln-overwrite-files
+ The default for all three is t. If nil, a --force argument (-f) is
+ required before any of the three commands will overwrite anything.
+ This is different from --interactive (-i), which queries before
+ destruction.
+* Changes in 2.2:
+** Added a "FEATURES" file to the distribution, which gives a brief
+ overview of the features offered by Eshell.
+** When `eshell-command' is invoked, the minibuffer is put into
+ eshell-mode, making all of your preferred Eshell keybindings
+ available (such as completion).
+ To bind M-! to use eshell-command, customize the variable
+ `eshell-prefer-to-shell'.
+** If both the `eshell-history' and `eshell-rebind' are in use, C-r
+ and C-s now behave similarly to bash. In 2.1, it was necessary to
+ enter a full regexp in the minibuffer before searching would
+ begin. Now it's incremental, using isearch.
+** All of the optional Eshell extension modules are now named
+ "em-NAME.el". Required modules are named "esh-NAME.el". This
+ prevents name collisions from occuring on filesystems with 8.3 name
+ limits.
+** New conditional constructs: if, unless, while and until. They can
+ be used in any of the following fashions:
+ if (string-match "gumby" (system-name)) {
+ echo true
+ } else {
+ echo false
+ }
+ while {/sbin/ifconfig | egrep ppp0} {
+ echo connected via ppp
+ }
+** New ls option implemented: -I GLOB. Used to exclude files matching
+ GLOB from the listing.
+** New list argument modifiers: (:i/REGEXP/) strips all elements not
+ matching REGEXP. (:x/REGEXP/) strips all elements that do match
+ the REGEXP. Other delimiters can also be used: (:i,REGEXP,).
+** Extended the file-time predicate, so that a file can be used as a
+ comparison basis. Example: "ls *(a+'file.c')" displays files
+ accessed before "file.c" was last accessed.
+** The eshell-xtra extension module now offers some cl (Emacs Common
+ Lisp) convenience functions. They make it much easier to perform
+ complex manipulations on list arguments. Since glob patterns and
+ command substitutions both yield list values, they can be very
+ useful. To enable eshell-xtra, customize the variable
+ `eshell-options-list'.
+ # Return results of glob, minus happy.el. The same as:
+ # *.el~happy.el
+ remove happy.el *.el
+ # Remove all duplicate lines from command results. The same as:
+ # egrep johnw /etc/passwd | uniq
+ remove-duplicates ${egrep johnw /etc/passwd}
+ # Replace a given list element with another. The same as:
+ # *.el(:s/em-ls\.el/happy.el/)
+ substitute happy.el em-ls.el *.el
+ # Return element value if member of a list. This is roughly
+ # equivalent to:
+ # echo *.el | egrep "^happy.el$" | uniq
+ find happy.el *.el
+ # Count the number of times a string appears in a list.
+ # Equivalent to:
+ # echo *.el | egrep "^happy.el$" | wc -l
+ count happy.el *.el
+ # Combine two lists, eliminating duplicates. Roughly equivalent
+ # to (difference is that the result is always sorted):
+ # echo *.el e* | sort | uniq
+ union *.el e*
+ # Return overlapping members of two lists. Roughly equivalent
+ # to:
+ # comm -12 $<printnl *.el(:o:u)> $<printnl e*(:o:u)>
+ intersection *.el e*
+ # Return members unique to the first list. Roughly equivalent
+ # to:
+ # comm -23 $<printnl *.el(:o:u)> $<printnl e*(:o:u)>
+ set-difference *.el e*
+ # Return all members that don't overlap. Roughly equivalent to:
+ # append ${comm -23 $<printnl *.el(:o:u)> $<printnl e*(:o:u)>}
+ # ${comm -13 $<printnl *.el(:o:u)> $<printnl e*(:o:u)>}
+ set-exclusive-or *.el e*
+** cp and mv now support moving and copying of directories. With mv,
+ this happens whenever a directory name is given as a source. With
+ cp, it requires using either the -R or -a switch.
+ Please be careful when using these options. A good backup policy
+ is always worth the trouble, and until Eshell has been in active
+ use for a few years, I wouldn't want to start moving directories
+ around without a backup.
+** Copying and moving directly TO a tar archive is allowed. It
+ creates the archive if it doesn't exist, and updates it if it does
+ (removing the filesystem entries in the case of mv). Note that
+ this happens only with multiple sources, or a single directory
+ source.
+ If the archive name ends in ".tgz", ".tz2", ".taz", ".taZ",
+ ".tar.gz", ".tar.bz2", or ".tar.Z", it will be
+ compressed/decompressed appropriately. Using "-v" after the
+ command name also works, for displaying the filenames as they are
+ copied/moved:
+ cp -v some_dir some_dir.tar.bz2
+** Implemented `du' in Lisp. If an external version of `du' is
+ present, it is always used instead, since the Lisp version is much
+ slower, and blocks Emacs while it's running.
+** Implemented `time' in Lisp. It only displays elapsed wall-clock
+ time, since Emacs doesn't provide facilities for determining the
+ user/kernel time consumed by a subprocess. Its usefulness lies in
+ the fact that it can show the elapsed time of Lisp function calls,
+ and it's available on all operating systems.
+** If a `grep' command is neither redirected, nor part of a command
+ pipeline, it's output will occur in a `*grep*' buffer, allowing the
+ user to use C-x ` to move to the source of each hit. The applies
+ to the whole grep family: egrep, fgrep, agrep, and glimpse.
+ Disable by customizing `eshell-plain-grep-behavior'.
+** If a `diff' command is neither redirected, nor part of a command
+ pipeline -- and if diff-mode.el is loaded -- the command's output
+ will occur in a separate buffer in diff-mode, allowing the user to
+ use C-x ` to move to each source difference.
+ Disable by customizing `eshell-plain-diff-behavior'.
+** If a `locate' command is neither redirected, nor part of a command
+ pipeline -- and if diff-mode.el is loaded -- the command's output
+ will occur in a separate buffer in locate-mode.
+ Disable by customizing `eshell-plain-locate-behavior'.
+** If a `make' command is sent to the background and not redirected,
+ it's output will appear in a `*compilation*', allowing the user to
+ enter C-x ` to view the source of each error.
+** New list argument modifier ':u'. This removes any contiguous
+ duplicate strings in the list. Used after ':o', it's the same as
+ "sort | uniq". Example:
+ echo **/*.c(:o:u) # returns uniq'd list of all .c files
+** Arguments to `which' that are preceded by an asterix `*', will
+ bypass alias lookup. This makes it possible to find out what the
+ alias will invoke.
+** Three new globbing constructs: #?, #* and #+, which correspond to
+ the ?, * and + regular expressions. To show the correlation:
+ glob regexp
+ ---- ------
+ * .*
+ ? .
+ #* *
+ #+ +
+ #? ?
+ ## + # zsh compatible
+ # * # zsh compatible
+** Changed the syntax of variable name quoting. The new syntax is:
+ $VAR-NAME # interpolate the value of `VAR-NAME'
+ $'VAR'-NAME # interpolate `VAR', followed by "-NAME"
+ $"VAR"-NAME # (same)
+ $"VA$VAR"-NAME # interpolate `VAR' into "VA?", then interpolate
+ into "?-NAME". This syntax can be nested.
+ Previously the argument "$<LOGNAME>-name" would have interpolated
+ the value of $LOGNAME into the argument, yielding something like
+ "johnw-name".
+** New syntax for temporary data interpolation. Example:
+ xdu -n $<du -k>
+ This invokes the command "du -k", copies the result to a temp file,
+ then passes the name of that temp file as an argument to `xdu'.
+ Once `xdu' completes, the temp file is deleted.
+ This syntax is quite similar to "<{command}" in bash, except that
+ Emacs doesn't permit writing to named pipes.
+ This is also useful with commands that need multiple generated
+ inputs:
+ comm -23 $<cd ~/src; printnl **/*.c(:o:u)> \
+ $<cd /usr/src; printl **/*.c(:o:u)>
+ This command will display all the .c files in "~/src" that are not
+ in "/usr/src", with `comm' the only external process invoked.
+** New commands: C-c ? and C-c m. These two popup quick help buffers
+ showing the various glob predicate and argument modifier
+ characters. All those characters were too easy to forget.
+** Using the '@' predicate with globs containing directories now
+ works. Example: "ls -d *(^@)" (anywhere containing directories).
+** Corrected the behavior of "ls -L".
+** rm, cp, mv and ln now support "-i" (--interactive), which queries
+ before overwriting/deleting any files. This is the default when
+ the user id is 0.
+** Line splitting in command result interpolation now works. This
+ makes the following possible:
+ length {listify {egrep blah FILE}}
+ This invokes "egrep blah FILE", interpolating the result as a Lisp
+ list, with each element a line of the output. The above command
+ will report how many hits were found. Note that the `listify' is
+ required here, since if egrep finds only one match, it will return
+ it as a string, not a list.
+** New configuration variable `eshell-virtual-targets'. Allows the
+ user to specify new virtual targets, such as "/dev/kill" and
+ "/dev/null".
+** New virtual target "/dev/eshell". Anything output to this
+ pseudo-device will be displayed in the Eshell window as normal
+ output from the command. Useful on operating systems without
+ "tee", since it lets you both view the command output, and redirect
+ it somewhere else:
+ ls > blah > /dev/eshell ; output goes to both "blah" and display
+** New configuration variable `eshell-kill-processes-on-exit'. It can
+ be set to one of: t, ask, every, nil. These settings mean:
+ t - kill all processes spawned by an Eshell buffer when it is
+ killed/exited.
+ ask - same operation as t, but ask the user before doing so.
+ every - some operation as ask, but query for every single process.
+ nil - don't kill processes on exit. They will be killed only if
+ Emacs itself is killed, or if the user kills/exits them.
+ This is the default, and matches the behavior of 2.1.
+** New configuration hook `eshell-first-time-mode-hook', which is
+ called at the same time as `eshell-mode-hook' (just before it), but
+ only once per Emacs session.
+** Added '#*' '.#*' files to the `eshell-ls-backup-regexp'.
+** Added '.bz2' files to the `eshell-ls-archive-regexp'.
+** The "echo" command now takes a "-n" flag, which causes it to
+ generate a newline after the printed text.
+** New module `esh-toggle', which provides the global commands
+ `eshell-toggle' and `eshell-toggle-cd'.
+To use these functions, simply type `M-x eshell-toggle'. With a
+prefix argument, it is the same as calling `eshell-toggle-cd', which
+emits a "cd $default-directory" immediately after switching.
+If `eshell-toggle' is called once, it will bring up Eshell in another
+window. If called twice in succession, it will take up the whole
+frame. After doing anything in the Eshell buffer, calling
+`eshell-toggle' yet again will restore the window configuration that
+was extent before the first call.
+** Improved support for XEmacs 21.1 and 21.2.
+* Changes in 2.1:
+** Eshell has been split into several functional "modules".
+ There are base modules, which define the core of Eshell, and
+ extension modules, whose use is entirely optional. See the
+ variable `eshell-modules-list'.
+** comint.el is no longer used. The functionality that Eshell had been
+ using is now divided between eshell-mode.el, eshell-hist.el,
+ eshell-cmpl.el and eshell-io.el. Most of that code is now
+ radically altered from its original form.
+** there is complete documentation available, using a prototype
+ embedded documentation system called "texidoc". texidoc.el is
+ included with the distribution of Eshell, but is not yet ready for
+ general consumption.
+** pushd, popd and dirs are provided in the extension module
+ `eshell-dirs'.
+** `cd', as defined in the extension module `eshell-dirs', can accept
+ parent directory references of the form "...", where each
+ additional "." refers to the next highest directory.
+** recursive globbing, similar to zsh, is provided in the extension
+ module `eshell-glob'. The syntax is "**/*.c", which means matches
+ all of the C files in the current directory and below. Symbolic
+ links are not traversed. To traverse them, use three asterices:
+ "***/*.c".
+** argument predicates and modifiers are provided in the extension
+ module `eshell-pred'. The syntax is to suffix the argument with
+ "(PREDS)" or "(:MOD:MOD)", or any combination. The allowable
+ predicates follow zsh syntax, whereas the allowable modifiers
+ follow bash's history argument modifier syntax. Thus, the command
+ "echo alpha(:s/al/be/)" would yield the string "bepha".
+ The history code and globbing rely upon this extension module to
+ provide globbing predicates and history argument modifiers. If it
+ is not used, those facilities won't be available. See the Info
+ manual for a fuller description of predicates and modifiers, and
+ how to use them. They are comprehensive enough to replace the use
+ of "find ... | xargs <cmd>" in most cases.
+** the version info banner displayed at login is part of a
+ sample extension module named `eshell-banner'. It can be
+ de-selected by disabling the use of that module. If authors choose
+ to write their on Eshell extension modules, they should copy this
+ file ("eshell-banner.el") as a starting point.
+** command aliases are provided in the extension module
+ `eshell-alias'. These aliases are intended for simplicity, and
+ persist immediately (i.e., no customization of Lisp variable is
+ necesary in order to use them). The only caveat, and difference
+ from other shells, is that argument expansion must always be
+ provided by specifying '$*' somewhere in the alias string. A
+ typical use might be: "alias ll 'ls -l $*'"
+** argument parsing has complete changed in structure. It is now much
+ easier for extension modules to extend the capability of the parser
+ for their own needs. See `eshell-dirs' for an example, which
+ extends the parser to properly handle filenames beginning with a
+ tilde character, such as "cat ~johnw/.emacs".
+** several more UNIX commands are now implemented in Lisp, in the
+ extension module `eshell-unix': basename, cat, cp, date, dirname,
+ ln, man, mkdir, mv and rmdir.
+** the extension module `eshell-basic' defines some of the more basic
+ shell commands, which are typically builtins in most shells: echo,
+ umask, version, etc.
+** programmable, context-aware completion is available using the
+ extension module `eshell-cmpl'. This is accomplished by taking
+ advantage of the functionality in the `pcomplete' module, which is
+ included with the standard Eshell distribution.
+** history code, which is almost entirely bash compatible, is provided
+ in the extension module `eshell-hist'.
+** rebinding of command keys while editing command input is provided
+ in the extension module `eshell-rebind'. For example, this causes
+ C-u to delete the current input text, rather than act as the
+ universal argument prefix -- but only while editing command input.
+ This is done to make Eshell feel more like a standard system
+ shell. Once the point moves away from the command input text (C-c
+ C-p is the typical way to do this), C-u takes on its normal
+ meaning.
+ The keys which get rebound, and their definition, are fully
+ customizable.
+** execution of Eshell scripts is provided in the extension module
+ `eshell-script'. The interpretor should be named
+ "/usr/local/bin/eshell", which is not offered with this
+ release. Eshell itself can execute such scripts, however, since it
+ evaluates them within the currently running Emacs.
+** a new form of smart output display is provided in the extension
+ module `eshell-smart'. See the Info manual for more details, since
+ an accurate description of what "smart" means in this case is
+ somewhat difficult to describe.
+** a test suite is now included with Eshell, which is runnable by
+ typing `M-x eshell-test'. However, this test can only be run
+ against non-byte-compiled sources. For efficiency sake, all of the
+ testing code is removed during byte-compilation.
+** a few other niceties, such as implementing `expr' in terms of the
+ calc package, or defining `make' to use compilation-mode whenever
+ the user invokes it asynchronously, are provided in the extension
+ module `eshell-xtra'.
+** cd now maintains its own "directory ring", which remembers the last
+ `eshell-last-dir-ring-size' places that Eshell has been to. The
+ syntax is:
+ cd - ; go to last location (swap top of ring and current)
+ cd -4 ; go to 4th from last location
+ cd =bcc ; go to last location containing regexp "bcc"
+ cd = ; show list of locations
+ If `eshell-last-dir-unique' is non-nil, this ring will never contain
+ duplicate items.
+** if an alias command like "ls" doesn't recognize a specified option,
+ it will defer to the external version (searched for on the PATH).
+** improved the "history" alias to be more like bash; specifically,
+ there is support for the -r, -w and -a options.
+** removed all dependencies on font-lock. eshell now does its own
+ buffer highlighting.
+** added full support for colorized ls output. To disable this
+ feature, set `eshell-ls-use-colors' to nil.
+** fixed a bug which was causing filter overruns when using pipes
+ and processes that generate a lot of output (like "find" with
+ "xargs").
+** removed `eshell-ls-default-args'. The proper way to pass default
+ arguments to ls is by using a command alias.
+** fixed a bug which prevented Eshell's ls from displaying very large
+ file sizes.
+* Changes in 1.5:
+** eshell now uses comint directly, rather than duplicating that
+ code.
+For this to work, you will need an updated copy of comint, which can
+no longer be found.
+** optimized handling of output from a subprocess. In cases where
+ both standard output and standard error are both headed for the
+ "*eshell*" buffer (which is most of the time), the comint filter is
+ used directly, bypassing eshell's redirection code.
+** there is a new user variable, `eshell-visual-commands'. If any
+ command name matches a member of this list, it will be executed
+ using "term", and started in a new buffer. When that process exits
+ -- and if you were viewing that buffer at the time -- it will
+ return you to eshell.
+** fixed "/dev/null". It now dumps output once again (before, it
+ would give an error about trying to change the value of the
+ constant symbol "nil").
+** fixed a problem with subcommands that was causing "echo
+ ${whoami}" not to work.
+** implemented a simple version of "history" that mimics the
+ behavior of bash's same command. None of the command switches are
+ supported, however, nor can an alternate history file be specified.
+ Yet.
+** if `eshell-input-ring-file-name' is non-nil (and it now defaults
+ to "~/.history"), eshell will write out the current command history
+ whenever the eshell buffer is killed.
+** the "exit" alias will bury the eshell buffer; but it does not
+ kill it (for the time being, there are some problems with trying to
+ do that, while at the same time keep everything sane).
+** after a call to `eshell-print', the display is now refreshed --
+ with consquent result that some of the lisp functions are now
+ visibly slower, although you can at least now see that they're
+ doing something. Setting `eshell-refresh-interval' to a higher
+ value will make the functions run faster, but it will also make
+ them seem a little choppier (no frequent updates). Setting this to
+ a really high number will match the functionality of 1.4.
+** if a "foreground" process is active, pressing RETURN will send
+ the current string to that process; if there are multiple
+ foreground processes active, the user will be prompted for which
+ one. Note that eshell echos locally, so the app you're using (such
+ as telnet) may have to turn echoing off.
+** executables are searched for along the PATH, not the `exec-path'.
+ Also, specifying a relative executable name now works (before,
+ saying "src/ls", even if it was there, would not work).
+** added an alias for "export" which behaves just as in bourne
+ shell. That is, you can now add to the path by saying:
+ export PATH=$PATH:/usr/local/bin"
+** fixed a bug which made it impossible to say "echo $exec-path",
+ and was causing $_ to be inaccessible.
+** "ls -l" (the alias version, written in Lisp) now shows symbolic
+ link targets. "ls -r" correctly reverses the file list. "ls -t"
+ sorts by mod time. Ganging up options ("ls -ltr") now also works.
+** before calling start-process, use `expand-file-name' on the
+ program name, so that relative paths are seen as absolute
+** looking up the command interpretor got broken again in 1.4
+** fixed problem where you couldn't cd to a directory with a numeric
+ name
+** `eshell-kill-alias' was reversing its arguments, so that "kill -9
+ PROC" wasn't working.
+** fixed a problem in `eshell-argument-syntax-list', that was
+ causing process references (e.g., #<process ispell>) to cause a
+ syntax error.
+** if output continues to generate from a subprocess, and you move
+ point to another window or frame, eshell will now scroll to the end
+ of the buffer. In 1.4, it would freeze the point of display at the
+ location you were last at when leaving the window.
+** protected a reference to `transient-mark-mode' with a call to
+ `boundp', in case it's not bound yet.
+** "date" now calls (current-time-string). If you want the other
+ functions of the date command, call it with an explicit path, such
+ as /bin/date. In the future, I'll make "date" an alias, and just
+ call the real "date" if the alias doesn't recognize any of the
+ command line switches.
+** beyond these features and bugs, there were several other, smaller
+ bugs fixed. Thanks to everyone who submitted feedback, and
+ provided test cases. Most everything else on my TODO list is
+ either a major bug, requiring redesign, or a new feature.
+* Changes in 1.4
+** `eshell-funcalln' was incorrectly calling `eshell-apply' rather
+ than `eshell-applyn'.
+** Pipes and subcommands were totally broken by the rewrite of the
+ output handling code. And subcommands were even changing the main
+ eshell buffer! So that's all working again.
+** Always go the end of the current line when RETURN is pressed.
+** Fixed a serious problem with globbing patterns and disk commands.
+** Process interaction, when there is only one non-background
+ process active, now works as expected again.
+* Changes in 1.3
+** The variable `eshell-cd-shows-directory' now control whether
+ "cd" will report the directory name it changes to.
+** The "alias" command didn't even really work, but now it's
+ fixed.
+** Removed dependency on `dired-replace-in-string' and
+ `dired-glob-regexp'.
+** If a variable is not found, it's value evaluates to "". If a
+ command cannot be found, it prints "name not found", as rc does
+ (rc: the Other Shell [read like 'the Other Woman'] :).
+** "ls" has been implemented in Lisp. Remove it from the list of
+ aliases if you still want to use the disk-based version. If there
+ are flags which my implementation does not recognize, it will
+ revert to the disk based version.
+** "rm" has been implemented to call the Lisp function
+ `delete-file'. If the argument is a buffer or process, it will
+ kill it. If it is a symbol, it will delete it.
+** If `cd' is given an ange-ftp file name, and then a disk
+ command is run from that directory, eshell will call
+ `shell-command' so that the command is run via "rsh" on the remote
+ machine.
+** Command aliases take a new second argument which allows you
+ specify what kind of alias you're defining. So it's now possible
+ to define an alias as '("ll" command "ls -l").
+** The history and input handling code was copied directly over from
+ comint, rather than being reimplemented. The only changes I had to
+ make were due to the fact that comint assumes that the current
+ buffer always has exactly one underlying process associated with
+ it. So although it's ugly to block move that much code, rather
+ than just reuse it in place, at least for this version eshell
+ supports comint's code for history and input navigation:
+*** !! accesses last command
+*** !command searches for last command, with option of command
+ being a ;; regexp
+*** !?<TAB> causes the current line to be replaced with that
+ history ;; element
+*** M-p M-n walk through the history list
+*** If RETURN is pressed at a previous location in the eshell
+ buffer (i.e., before `eshell-output-mark'), repeat the command
+ text at the bottom before executing it.
+*** Note: numerical references to history sub-elements are
+ currently ignored.
+* Changes in 1.2
+** Fixed some bugs with list flattening, `eshell-echo' and
+ `eshell-dos-to-unix'.
+** Removed "grep" alias. Too troublesome and confusing.
+** Giving a prefix argument to C-RET (send string to process),
+ will cause Emacs to read the input as a password. Also, a newline
+ is now automatically appended to the string sent.
+** Fixed many bugs dealing with aliases and foreign command
+ interpretors. How did all those bugs creep in? :)
+** The "dos2unix" alias no longer untabifies your files.
+** Added aliases for "setq" and "if". More to come...
+** Added some bindings to provide some compatibility with what
+ comint users expect.
+** Accessing history is now possible with "!command". The last
+ command is available using "!!". If `eshell-history-by-regexp' is
+ non-nil, you can use "!regexp", which will match anywhere with the
+ line, requiring "!^regexp" to emulate the default behavior.
+** "cd -" will return to the last directory visited.
+** Variable referencing is now supported. It takes many forms:
+*** $VARIABLE name of an environment or Lisp variable
+*** $ALSO-VAR "-" is considered part of a name
+*** $<MYVAR>-TOO only "MYVAR" is part of the variable name
+*** $#VARIABLE length of the value of VARIABLE
+*** $(lisp)
+Returns result of lisp evaluation. Note: Used alone like this, it is
+identical to just saying (lisp); but with the variable expansion form,
+the result may be interpolated a larger string, like "$(lisp)/other".
+*** ${command}
+Returns the value of an eshell subcommand. See the note above
+regarding lisp evaluations. The same applies here.
+*** $ANYVAR[10]
+Attempts to return the 10th element of ANYVAR. If ANYVAR's value is a
+string, it will be split in order to make it a list. The splitting
+will occur at whitespace.
+*** $ANYVAR[: 10]
+Just like above, except that splitting occurs at the colon now.
+*** $ANYVAR[: 10 20 ]
+Like above, but instead of returning just a string, it now returns a
+list of two elements. If the result is being interpolated into a
+larger string, this list will be flattened into one big string, with
+each element separated by a space.
+*** $ANYVAR["\\\\" 10]
+Separate on backslash characters. Actually, the first argument -- if
+it doesn't have the form of a number, or plain variable name -- is
+just a regular expression. So if you did want to split on numbers,
+you could say:
+ $ANYVAR["[0-9]+" 10 20].
+*** $ANYVAR[hello]
+Does an assoc with ANYVAR, expecting it to be an alist.
+*** $#ANYVAR[hello]
+Returns the length of the element of the alist ANYVAR who car is equal
+to "hello"
+*** Thus, you can now do crazy things like:
+ 1+ ${egrep johnw /etc/passwd}[: $pu-index] > 'uid-after-me
+And return the value of the `pu-index'th element of your passwd entry
+(let's assuming it's set to 2, the user id), increment it by one, and
+then store this integer in the Lisp variable `uid-after-me'.
+** $_ is defined (via an alias) as the arguments for the last
+ command. If referenced plainly, it refers to the last argument of
+ the last argument. If referenced as an array, it will return the
+ Nth argument of the last command.
+* Changes in 1.1
+** Fixed a bug which made some of the defcustom forms unusable.
+** `esh' is an alias for `eshell-subcommand', making it easier to
+ run eshell commands synchronously from lisp forms.
+** Fixed some erroneous ways that files were being separated and
+ globbed. Failed globs get passed as the glob string.
+** Special characters in filenames are now quoted when doing name
+ completion.
+** Eshell outputs a short banner message on startup, announcing the
+ version. Set `eshell-display-banner-p' to nil to turn this off.
+** Removed the troublesome global variables that were being used
+ for capturing the output from the subcommands.
+** Outputting to 'nil, or the pseudo-name "/dev/null", will drop
+ output.
+** Using ";;" means three empty commands now, instead of the
+ unknown token ";;".
+** The process interaction functions, such as C-c C-c, now always
+ use the currently running sub-process if eshell has invoked only
+ one. Otherwise, it prompts from among all running processes in
+ Emacs.
+** Changed C-c RET to just C-RET.
+** Emacs-lisp-mode is run before switching the major mode to
+ eshell, so that any hooks (like starting eldoc mode) work as you
+ would expect for a lisp mode.
+* Changes in 1.0 (from the first pre-release version 0.2)
+** Simplified the code a great deal, and broke it down into several
+ more functions.
+** Now uses `dired-glob-regexp', instead of duplicating that code.
+** Redirection is possible to multiple targets. They will all
+ receive the same output.
+** Redirection of files, buffers or processes, using the Emacs
+ syntax #<buffer NAME> or #<process NAME>. If
+ `eshell-buffer-shorthand' is nil, you can even redirect into a lisp
+ variable using the syntax: 'name.
+** If you redirect within a pipe, the output will still go to the
+ pipe, eliminating the need for "tee". To prevent this behavior,
+ set `eshell-always-to-pipe' to nil.
+** When redirecting to a buffer, the operator ">>>" will cause the
+ redirection to insert at the current location of point in that
+ buffer. Beware of the asynchronous nature of the subprocess,
+ though, since it will continue inserting at point, even if point
+ moves around.
+** ~, ~user, and /:/path (to prevent environment variable
+ substitution) are now supported.
+** You can turn off the bogus nature of "&" by setting
+ `eshell-support-ampersand' to nil.
+** There is now extensive support for aliases, and redefinition of
+ commands.
+You can either replace the definition of a command, or alter it. You
+can also modify the output which comes from the command, and still
+have it show up in all the places the user specified redirections to.
+** Synchronous subcommands are supported, and can be used either to
+ generate output, or to substitute for an argument.
+The syntax used is similar to rc, except that no whitespace is allowed
+after the initial brace. This is so that users can avoid the tedium
+of quoting all the time.
+ echo {cd; ls} ; echos contents of home directory
+ echo {+ 1 3} ; print `t', since sub-expr yields non-nil
+ {+ 1 3} ; evalute in a subcommand, and print result
+** Synchronous chaining of commands is supported, using ";":
+ ls; ls -l; ls; ls -l ; appears in the order you expect
+** There is a series of functions behind C-c now, for the purposes
+ of interrupting processes.
+** You can use C-c p and C-c b to insert named references to
+ process and buffers.
+** When a subprocess asks a question, you cannot answer it just by
+ typing into the eshell buffer, since there's no way to know for
+ certain which asynchronous subprocess you intend for the string to
+ go to. Instead, use C-c RET, select the name of the process, and
+ then enter your string in the minibuffer.

0 comments on commit 728ad1a

Please sign in to comment.
Something went wrong with that request. Please try again.