(Re)generate: (find-eepitch-intro)
Source code:  (find-eev "eev-intro.el" "find-eepitch-intro")
More intros:  (find-eval-intro)
              (find-wrap-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial (for eepitch) and a sandbox.



The motivation for eepitch: taking notes and redoing
====================================================
Suppose that we have to do some reasonably complex task using a
shell, and that we want to take notes of what we do because we
might have to do something similar later.

The two usual ways to interact with a shell are:

  1) through a _script_, that is, by preparing in advance all
     commands to be executed, putting them in a script file, and
     then running that file,

  2) _interactively_, by typing the commands one by one on a
     shell prompt.

Suppose that we have to discover which commands to run as we go;
that rules out preparing a script beforehand, so we need to use
the shell interactively. After issuing the right commands, the
two usual ways to retrieve what we did are:

  a) through the _shell history_, which records the last commands
     that the shell received,

  b) by looking at the full _transcript_ of our interaction with
     the shell.

The way (a) gets a list of commands, without comments, that can
be then saved into a text editor; the way (b) may require some
tricky editing to isolate the commands from their outputs.

Eepitch.el implements a simple alternative way of interacting
with shells (and other shell-like programs) while keeping notes.
It has only one essential key binding, <F8>, which is better
explained through the executable example in the next section, and
two unessential features, <M-T> and "*", which will be
explained later.



The main key: <F8>
==================
Emacs can run a shell in a buffer, and it can split its frame
into windows, like this:
   ___________________
  |         |         |
  |   our   |    a    |
  |  notes  |  shell  |
  |         |  buffer |
  |_________|_________|

The usual way to use a shell buffer is to move the cursor there
and type commands into its prompt; the eepitch-y way is to leave
the cursor at the "notes" buffer, write the commands for the
shell there, and send these commands to the shell with <F8>.

Here's what <F8> does:

  When we type <F8> on a line that starts with a red
  star ("*"), it executes the rest of the line as Lisp, and
  moves down; when we type <F8> on a line that does not start
  with a "*", it makes sure that the "target buffer" is being
  displayed (the "target" is usually the buffer called
  "*shell*"), it "send"s the current line to the target
  buffer, and moves down.

  "Sending the current line to the target buffer" means copying
  the contents of the current line to the target - as if the user
  had typed that line there by hand -, then "typing" a <RET> at
  the target buffet.

Please try that in the example after this paragraph, by typing
<F8> six times starting at the first line that says
"* (eepitch-shell)". The three red star lines at the top will
create a target buffer, destroy it, and create it again; the
other three lines will send commands to the target shell.

* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
echo "We are at: $PWD"
cd /tmp/
echo "We changed to: $(pwd)"




Other targets
=============
Just like `(eepitch-shell)' creates a shell buffer and sets the
eepitch target to it, `(eepitch-python)' creates a buffer with a
Python interpreter and uses it as the eepitch target. Try:

* (eepitch-python)
* (eepitch-kill)
* (eepitch-python)
def square (x):
    return x*x

print(square(5))

  We can use several targets at the time, alternating between them.
  For example:

* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
echo Hello... > /tmp/o

* (eepitch-python)
* (eepitch-kill)
* (eepitch-python)
print(open("/tmp/o").read())

* (eepitch-shell)
echo ...and bye >> /tmp/o

* (eepitch-python)
print(open("/tmp/o").read())


  There is a (much) more advanced example of working with several
  targets here:

  (find-prepared-intro "An `ee' for Python")





More on eepitch-kill
====================
Note that `(eepitch-kill)' kills the _current_ target, that may
or may not be a shell buffer, a Python interaction buffer, etc...
That explains the first line in blocks like:

* (eepitch-python)
* (eepitch-kill)
* (eepitch-python)

and:

* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)

by running the first `(eepitch-python)' we can be sure that the
following `(eepitch-kill)' will kill the Python buffer, not the
shell buffer! And the last `(eepitch-python)' in the block of
three lines will then create a new Python interaction buffer,
erasing all definitions done in previous sessions.




Creating eepitch blocks: <M-T>
==============================
Write just "shell" or "python" in a line, then type
<M-T> (i.e., meta-shift-t) there. The line will be turned into
three - an "* (eepitch-xxx)", an "* (eepitch-kill)", and an
"* (eepitch-xxx)". We call these blocks of three lines
"eepitch blocks". Try this below, converting the "shell" into
an eepitch block for starting a shell.

shell
pwd
cd /tmp/
pwd




Red stars
=========
Eepitch.el sets the glyph for the char 15 to a red star in the
standard display table. In layman's terms: eepitch.el tells Emacs
that the character 15 should be displayed as a red star. The
character 15 corresponds to control-O, whose default
representation on screen would be "^O". You can enter a
literal ^O in a buffer by typing C-q C-o.



For more information
====================
On hyperlinks:               (find-eval-intro)
On keys similar to <M-T>:    (find-wrap-intro)
An older text about eepitch:
  (find-eev "eepitch.readme")
  (find-eev "eepitch.readme" "the-trivial-case")
  (find-eev "eepitch.readme" "red-stars")
  (find-eev "eepitch.readme" "eepitch-blocks")
  (find-eev "eepitch.readme" "eepitch-blocks")
Many functions like `eepitch-shell':
  (find-efunction 'eepitch-bash)
What functions can generate target buffers:
  (find-eevfile "eepitch.el" "shell-like sexp")
  (find-efunction 'eepitch)