\input texinfo
@setfilename eev.info
@settitle Eev.el - a way to record and playback pieces of *NIX oral culture

@c (find-es "texinfo")
@c (progn (texinfo-every-node-update) (texinfo-all-menus-update))


@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top 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.

@menu
* Introduction::                
* Using eev.el::                
* E-script Repositories::       

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Eev Manifesto::               The eev Manifesto, 1999dec18.
* Short Description::           A short description, 2000sep07.

Using eev.el

* Quick and Dirty Tutorial::    
* Eval-last-sexp and Hyperlinks::  
* Eev and Friends::             
* Eeman::                       
* Code-c-d::                    
* Eelatex::                     
* Eeg::                         
* Gdb::                         
* Anchors::                     
* Local Variables::             
* Glyphs::                      

eev and friends

* Shell Configuration::         
* Remote Machines::             

Making an E-script Repository

* Converting to Html::          
* page.tgz::                    

@end detailmenu
@end menu

@c
@c
@c #####
@c #
@c # (chapter): Introduction
@c #
@c #####

@node Introduction, Using eev.el, Top, Top
@comment  node-name,  next,  previous,  up
@chapter 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.

@menu
* Eev Manifesto::               The eev Manifesto, 1999dec18.
* Short Description::           A short description, 2000sep07.
@end menu


@c
@c
@c #####
@c #
@c # (section): The Eev Manifesto
@c #
@c #####

@node Eev Manifesto, Short Description, Introduction, Introduction
@comment  node-name,  next,  previous,  up
@section 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




@c
@c
@c #####
@c #
@c # (section): A short description, 2000sep07
@c #
@c #####

@node Short Description,  , Eev Manifesto, Introduction
@comment  node-name,  next,  previous,  up
@section 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.)






@c
@c
@c #####
@c #
@c # (chapter): Using (and many subsections)
@c #
@c #####

@node Using eev.el, E-script Repositories, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Using eev.el

@menu
* Quick and Dirty Tutorial::    
* Eval-last-sexp and Hyperlinks::  
* Eev and Friends::             
* Eeman::                       
* Code-c-d::                    
* Eelatex::                     
* Eeg::                         
* Gdb::                         
* Anchors::                     
* Local Variables::             
* Glyphs::                      
@end menu

@node Quick and Dirty Tutorial, Eval-last-sexp and Hyperlinks, Using eev.el, Using eev.el
@section A Quick and Dirty Tutorial

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

@node Eval-last-sexp and Hyperlinks, Eev and Friends, Quick and Dirty Tutorial, Using eev.el
@section eval-last-sexp and hyperlinks

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

@c (find-texinode "Definition Commands")
@c (find-texinode "Sample Function Definition")






@defun find-fline fname &rest pos-spec-list
@code{find-fline} makes Emacs visit the file @var{fname} and optionally
go to the position given by @var{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

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

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

@c (find-elnode "Visiting Files")
@c (find-enode "Dired")

For more information on the format of @var{pos-spec-list}, see the
documentation for the function @code{ee-goto-position}; for ways to omit
part of the directory specification, see the documentation for the
function @code{code-c-d}.

The definition of @code{find-fline} is simply:

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


@defun ee-goto-position &optional pos-spec
Go to a certain position in the current buffer is @var{pos-spec} is not
nil.  If @var{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 @var{pos-spec} if nil then do nothing and leave
point where it is.
@end defun

The standard definition for @code{ee-goto-position} is kept deliberately
simple:

@lisp
(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)))
@end lisp

Note that it uses @code{&optional pos-spec} instead of @code{&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 @code{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 @code{ee-goto-position} at [my .emacs]; I'm keeping
it out of eev.el because its code is ugly and obscure).

@node Eev and Friends, Eeman, Eval-last-sexp and Hyperlinks, Using eev.el
@section eev and friends

@menu
* Shell Configuration::         
* Remote Machines::             
@end menu

@node Shell Configuration, Remote Machines, Eev and Friends, Eev and Friends
@subsection Shell Configuration

@node Remote Machines,  , Shell Configuration, Eev and Friends
@subsection Remote Machines

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

@node Eeman, Code-c-d, Eev and Friends, Using eev.el
@section eeman

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

@node Code-c-d, Eelatex, Eeman, Using eev.el
@section code-c-d

@lisp
; (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)
@end lisp

@node Eelatex, Eeg, Code-c-d, Using eev.el
@section eelatex

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

@node Eeg, Gdb, Eelatex, Using eev.el
@section eeg and the Generic Interface

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

@node Gdb, Anchors, Eeg, Using eev.el
@section Gdb

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

@node Anchors, Local Variables, Gdb, Using eev.el
@section Anchors

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

@node Local Variables, Glyphs, Anchors, Using eev.el
@section Local Variables

@node Glyphs,  , Local Variables, Using eev.el
@section Glyphs

@lisp
; (find-angg "glyphs.el")
@end lisp

@node E-script Repositories,  , Using eev.el, Top
@chapter Making an E-script Repository

@menu
* Converting to Html::          
* page.tgz::                    
@end menu

@node Converting to Html, page.tgz, E-script Repositories, E-script Repositories
@section Converting to Html

@node page.tgz,  , Converting to Html, E-script Repositories
@section Page.tgz








@c (progn (texinfo-every-node-update) (texinfo-all-menus-update))
@c (eev "cd ~/TEXINFO; makeinfo eev.texi" nil)
@c (find-node "(/home/root/TEXINFO/eev)Top")
@c (find-enode "Sentences")

@bye

@c Local Variables:
@c ee-comment-prefix: "@c "
@c sentence-end-double-space: t
@c End: