Eev.el
******

Eev.el is a small Emacs Lisp package that lets you interact with the machine in a more convenient way, recording everything you do, adding comments and hyperlinks, and of course, being able to play it all back later. Read on.

Introduction
************

This section is very incomplete...  at this time it's just a collection of generic introductory texts.

BTW, the reason why the code for eev.el is so small is that it is just a small hack built on top of Emacs, which already provides all the functionality that eev needs.  Learning eev, so, is essentially the same as learning Emacs, only from slightly different (and hopefully more productive and less scaring) point of view.

The Eev Manifesto
=================

I)

Do you remember your first Unix days, when you were always asking yourself questions like "how do I compile this?", "how do I install this stuff?", "and now, how do I run it?", "how do I generate html from this file?"?

Do you remember how you marvelled at the first time you ran a "make" on a package and you saw echoed each of the commands that were used to generate binaries and docs from the source? Have you had the same feeling I've had, that by understanding those commands we would have access to the tricks that the owner of the package knew, and that we'd learn which were the "important" programs and in what way the experts used them?

II)

Everybody is fluent in only a small fraction of all Unix commands.  If you could "listen" to how the Unix gurus "speak" to their machines you would learn which "words" are related to solving a particular task, and learn how they fit in "sentences".  By checking the "dictionary entries" for them (i.e., manpages, info pages, READMEs, source code, etc) you could learn the real meaning of them.  But then you'd be learning Unix by immersion, from real use, instead of having to rely only on "textbooks", "dictionaries" and sometimes "Rosetta stones", "graffitis on toilet walls" and "old newspapers".

The fact is that you can make a record of how you "speak" Unix, and more, you can become a lot more productive if you do so.  Many tasks consist on short fixed sequences of commands: connecting to your ISP via modem, unpacking a source package and recompiling it, printing a text file in two-column mode, and so on.  The trick is that with some functions defined in eev.el you can write these sequences of commands in a plain text file, then mark a block of this file with your editor (which must be Emacs for this to work), then tell a shell to execute only the commands in that block; in this way you can easily execute only portions of what would otherwise have to be a monolythic script; this is great for when you're not sure if everything works, or if you just want to do some steps.  Also, it would be easy to change bits of the "script" before execution, as you'll be doing things from inside an editor.

There is also another trick.  Scripts allow "comments", that is, lines that are not executed; generally the convention is that lines that start with "#" are comments. So we can place lines like these in a script:

# (find-enode "Picture" "C-c c-c")

The expression "(find-enode "Picture")" is an Emacs command (in Lisp) that means: open the "info page" called "Picture", from the Emacs manual, treating it as a file; then place the cursor after the first occurrence of the string "C-c c-c" there.  To execute this command, i.e., to make emacs go to that point on that page, you just have to put the cursor after the ")" and type C-x C-e.  There are many other similar commands, that will open specific files or specific manpages, with various ways of searching.  These "hyperlinks" are especially interesting if you want to record from where you got some piece of information relevant to the "script" you're writing; this is very useful, for example, on "scripts" you haven't finished and on which you plan to work more someday, or on scripts you want to send to someone.

Just as hyperlinks have many flavors, the function that executes a block also has variants: a block can be executed by the Tcl interpreter instead of the shell, or can be run through LaTeX, just to pick some examples.  See the docs on eev.el.

III)

I have placed essentially all my "scripts" written in this way (I call them "e-scripts") in a public place.  They contain almost everything I know about Unix.

If you like this idea, please get in touch, send comments, ask questions -- about e-scripts or questions whose answer could become an e-script chunk -- or send me your e-scripts when you have some, or even ask for help on setting up your own e-script collection or e-script public site...  anything! By asking good questions you can help me make the documentation get better.

I really want to make this e-scripts idea spread. Learning Unix -- or simply more Unix -- could be made easier for everybody...  please help! E-scripts are funnier to use, and easier to write, than texts that tell everything in terms of "press this, do that".  A lot of effort and money are being invested now on these kinds of text, and they're often very depressing.  Let's try to save the world from them, at least a bit, and maybe this money will be directed to better things.  And teaching people Unix tricks will be both easier and funnier.

Eduardo Ochs, 1999dec18.

edrx@inx.com.br http://angg.twu.net/emacs.html

A short description, 2000sep07
==============================

Eev.el is a simple Emacs Lisp library that lets you treat portions of a text file as shell commands, chunks of code for programming languages or as hyperlinks; its intention is to let people record into plain ASCII files their interaction with the computer, and to let them edit and play back any block of code in those files easily.  The hyperlinks can point to places in manpages, Info pages and text or HTML files, and they are seen as comments by all programming languages; using them you can place pointers to all relevant online sources of information inside the code.

These notefiles (called "e-scripts") look like a crossing between HOWTOs, scripts and the history lists of some shells, and they get written almost automatically when you interact with the system via eev. By writing such files and making them available you help disseminating the UNIX "oral culture", and other people won't need to wait for your packages or to look over your shoulder to understand how you use the machine and learn your tricks.

News:

The depency on weird characters ("glyphs") was removed and now eev.el will work on X and on any terminal; lots of comments and docstrings were added to the source, and there is now a tutorial.

(Note: I wrote this short description for the third release of eev.el at www.freshmeat.net; the first paragraph was accepted without modifications by the editors but the second one was simply dropped out, and eev ended up being sold as dead fish at the market just like any common useless program.  Like the thief in Peter Greenaway's "The Cook, the Thief, his Wife and her Lover", the system destroys everything it touches.)

Using eev.el
************

A Quick and Dirty Tutorial
==========================

     ; (find-es "escripts" "eev-quick-inst")
     ; (find-es "escripts" "eev-tutorial")

eval-last-sexp and hyperlinks
=============================

     ; (describe-function 'find-fline)
     ; (describe-function 'ee-goto-position)
     ; (find-angg "eev.el" "find-")

 -- Function: find-fline fname &rest pos-spec-list
     find-fline makes Emacs visit the file FNAME and optionally go to the position given by POS-SPEC-LIST.  This function is often used as a hyperlink: if you place the point at the end of a line like one of those below

          # (find-fline "/etc/resolv.conf")
          # (find-fline "~root/")
          # (find-fline "$HOME/.emacs" 25)

     and type `C-x C-e' Emacs will visit (i.e., open) the corresponding file.

     For more information on the format of POS-SPEC-LIST, see the documentation for the function ee-goto-position; for ways to omit part of the directory specification, see the documentation for the function code-c-d.

     The definition of find-fline is simply:

          (defun find-fline (fname &rest pos-spec-list)
            (find-file (substitute-in-file-name fname))
            (apply 'ee-goto-position pos-spec-list))

 -- Function: ee-goto-position &optional pos-spec
     Go to a certain position in the current buffer is POS-SPEC is not nil.  If POS-SPEC is a string, search for its first occurence, starting from the beginning of the accessible area; if it is a number, go to that line; if POS-SPEC if nil then do nothing and leave point where it is.

The standard definition for ee-goto-position is kept deliberately simple:

     (defun ee-goto-position (&optional pos-spec)
       (if pos-spec (goto-char (point-min)))
       (if (numberp pos-spec)
           (forward-line (1- pos-spec)))
       (if (stringp pos-spec)
           (search-forward pos-spec)))

Note that it uses &optional pos-spec instead of &rest pos-spec-list, which means that it will work with one argument or none but will give an error if invoked with more that one argument; all the standard functions that call it directly can pass longer lists of arguments to ee-goto-position, though, and you may redefine it to interpret these longer lists of arguments in any way that you like (you may find an extended ee-goto-position at [my .emacs]; I'm keeping it out of eev.el because its code is ugly and obscure).

eev and friends
===============

Shell Configuration
-------------------

Remote Machines
---------------

     ; (describe-function 'ee-write-string)
     ; (find-e20node "Remote Files")
     ; (find-efile "ange-ftp.el")

eeman
=====

     ; (find-angg "eev.el" "eeman")
     ; (describe-function 'eeman)

code-c-d
========

     ; (find-angg "eev.el" "code-c-d")
     ; (find-angg "eev.el" "code-c-d-explan1")
     ; (find-angg "eev.el" "code-c-d-explan2")
     ; (find-angg "eev.el" "code-c-d-examples")
     ; (describe-function 'code-c-d)
     ; (describe-function 'icode-c-d)

eelatex
=======

     ; (find-angg "eev.el" "eelatex")
     ; (describe-variable 'ee-delimiter-percent)

eeg and the Generic Interface
=============================

     ; (find-angg "eev.el" "generic")
     ; (describe-function 'eeg)
     ; (describe-variable 'ee-file-generic)

Gdb
===

     ; (find-angg "eev.el" "gdb")
     ; (find-angg ".gdbinit")
     ; (find-angg ".emacs" "gdbk-mode")

Anchors
=======

     ; (find-angg "eev.el" "variables")
     ; (find-angg "eev.el" "find-anchor")
     ; (describe-variable 'ee-anchor-format)

Local Variables
===============

Glyphs
======

     ; (find-angg "glyphs.el")

Making an E-script Repository
*****************************

Converting to Html
==================

Page.tgz
========