;;; eev-intro.el --- intro scripts for eev

;; Copyright (C) 2012 Free Software Foundation, Inc.
;;
;; This file is (not yet?) part of GNU eev.
;;
;; GNU eev 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.
;;
;; GNU eev is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
;;
;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
;; Version:    2012nov29
;; Keywords:   e-scripts
;;
;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
;;       htmlized: <http://angg.twu.net/eev-current/eev-intro.el.html>
;;       See also: <http://angg.twu.net/eev-current/eev-readme.el.html>
;;                 <http://angg.twu.net/eev-intros/find-eev-intro.html>
;;                                                (find-eev-intro)

;;; Commentary:
;;
;; To use this, simply execute any of the sexps below:
;;   (find-eev-intro)
;;   (find-eval-intro)
;;   (find-eepitch-intro)
;;   (find-wrap-intro)
;;   (find-code-c-d-intro)



;; Quick index:
;; \253.find-eev-intro\273            (to "find-eev-intro")
;; \253.find-eval-intro\273           (to "find-eval-intro")
;; \253.find-eepitch-intro\273        (to "find-eepitch-intro")
;; \253.find-wrap-intro\273           (to "find-wrap-intro")
;; \253.find-links-intro\273          (to "find-links-intro")
;; \253.find-code-c-d-intro\273       (to "find-code-c-d-intro")
;; \253.find-psne-intro\273           (to "find-psne-intro")
;; \253.find-brxxx-intro\273          (to "find-brxxx-intro")
;; \253.find-eejump-intro\273         (to "find-eejump-intro")
;; \253.find-pdf-like-intro\273       (to "find-pdf-like-intro")
;; \253.find-audiovideo-intro\273     (to "find-audiovideo-intro")
;; \253.find-multiwindow-intro\273    (to "find-multiwindow-intro")
;; \253.find-rcirc-intro\273          (to "find-rcirc-intro")
;; \253.find-templates-intro\273      (to "find-templates-intro")
;; \253.find-anchors-intro\273        (to "find-anchors-intro")
;; \253.find-prepared-intro\273       (to "find-prepared-intro")
;; \253.find-bounded-intro\273        (to "find-bounded-intro")
;; \253.find-channels-intro\273       (to "find-channels-intro")
;; \253.find-videos-intro\273         (to "find-videos-intro")

;; \253.find-defun-intro\273          (to "find-defun-intro")
;; \253.find-emacs-intro\273          (to "find-emacs-intro")

;; See: (find-anchors-intro)

;; Ignore this - this is a temporary hack to make the htmlization in
;; <http://angg.twu.net/eev-intros/> work better...
;; (find-angg "eev-intros/")
;; (find-angg "eev-intros/README")
' (fooi-re "Source code:  (find-efunction '\\([!-~]*\\))"
           "Source code:  (find-eev \\\\\"eev-intro.el\\\\\" \\\\\"\\1\\\\\")")




;;;                       _       _             
;;;   ___  _____   __    (_)_ __ | |_ _ __ ___  
;;;  / _ \/ _ \ \ / /____| | '_ \| __| '__/ _ \ 
;;; |  __/  __/\ V /_____| | | | | |_| | | (_) |
;;;  \___|\___| \_/      |_|_| |_|\__|_|  \___/ 
;;;                                             
;; This works as an index.
;; (find-intro-links "eev")
;; \253find-eev-intro\273  (to ".find-eev-intro")

(defun find-eev-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-eev-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-eev-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-eev-intro\")
Main intros:  (find-eval-intro)
              (find-eepitch-intro)
              (find-wrap-intro)
Index to the source files: (find-eev \"eev2-all.el\")
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.


Here is a list of all the available sandbox-y tutorials that
explain parts and concepts of eev, listed in (a kind of)
recommended reading order:

   0. (find-eev-intro)
   1. (find-eval-intro)
   2. (find-eepitch-intro)
   3. (find-wrap-intro)
   4. (find-links-intro)
   5. (find-eejump-intro)
   6. (find-code-c-d-intro)
   7. (find-psne-intro)
   9. (find-brxxx-intro)
  10. (find-pdf-like-intro)
  11. (find-audiovideo-intro)
  12. (find-anchors-intro)
  13. (find-multiwindow-intro)
  14. (find-rcirc-intro)
  15. (find-templates-intro)
  16. (find-prepared-intro)
  17. (find-bounded-intro)
  18. (find-channels-intro)
  19. (find-videos-intro)

Items 1 and 2 should give you a good grasp of the main ideas -
namely, that _elisp hyperlinks and interactive scripts can be
embedded anywhere_. The other tutorials mainly show how to make
these ideas pervasive.

The last item above is an index of the video tutorials, with
scripts for downloading local copies of them and links to
important positions in the videos.

There are also these two, ahem, \"things\", that I use in
workshops, but that are not very eev-specific:

   A. (find-emacs-intro)
   B. (find-defun-intro)




The README
==========
The README for eev2 is an elisp file,

  (find-eev \"eev-readme.el\")

that contains an easy way of installing eev - in either a
temporary directory or in a permanent one - and initial
instructions for trying the main keys. ***HIGHLY RECOMMENDED***!



Installing eev
==============
The instructions below are adapted from:

  (find-eev-update-links \"/tmp/eev/\")
    and:   (find-eev \"eev-readme.el\")

You should download the tarball with all the elisp files, unpack
it somewhere - doing something like this (here you can use F8 if
you already have eev installed),

* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
rm -Rv /tmp/eev/
mkdir  /tmp/eev/
cd     /tmp/eev/
wget http://angg.twu.net/eev-current/eev2.tgz
tar -xvzf eev2.tgz

and then evaluate these sexps (type C-x C-e at the end of each
line):

  (add-to-list 'load-path \"/tmp/eev/\")
  (require 'eev2-all)
  (eev-mode 1)

This will turn on eev-mode - which just activates a few
keybindings. To understand the main ideas, please follow these
two tutorials:

  (find-eval-intro)
  (find-eepitch-intro)

To turn off eev-mode, run `(eev-mode 0)'.
To toggle, use `M-x eev-mode'.



The keybindings
===============
`eev-mode' defines its own meanings for lots of meta-shift-letter
key combinations - which are not normally used by Emacs - and,
besides that, only for:

  `M-e'    (find-eval-intro \"`M-e'\")
  `M-k'    (find-eval-intro \"`M-k'\")
  `M-j'    (find-eejump-intro \"\\neejump\\n\")
  `M-h'    (find-links-intro \"Elisp hyperlinks buffers\")
  `<f8>'   (find-eepitch-intro \"The main key: <F8>\")

For the full lists of keybindings, see:

  (find-efunctiondescr        'eev-mode)
  (find-eminormodekeymapdescr 'eev-mode)
  (find-efunctiondescr        'eev-avadj-mode)
  (find-eminormodekeymapdescr 'eev-avadj-mode)
" rest)))

;; (find-eev-intro)








;;;                  _ 
;;;   _____   ____ _| |
;;;  / _ \ \ / / _` | |
;;; |  __/\ V / (_| | |
;;;  \___| \_/ \__,_|_|
;;;                    
;; \253find-eval-intro\273  (to ".find-eval-intro")
;; (find-intro-links "eval")
;; (find-TH "eev-article" "hyperlinks")
;;      http://angg.twu.net/eev-article.html#hyperlinks
;;   file:///home/edrx/TH/L/eev-article.html#hyperlinks
;; (find-TH "eev-article" "forward-and-back")
;; (find-efunction 'eek-eval-last-sexp)


(defun find-eval-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-eval-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-eval-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-eval-intro\")
More intros:  (find-eev-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.



The standard way to evaluate Lisp: `C-x C-e'
============================================
The most important idea in Emacs is that Lisp code can appear
anywhere, and you can evaluate a Lisp expression (a \"sexp\") by
placing the cursor (the \"point\") just after it and typing `C-x
C-e'; the result is then displayed in the echo area. Try it in
the line below, with the point in the three different indicated
positions - you should get different results.

  (+ (* 2 3) (* 4 5))
            ^       ^^
            |       | \\
            6      20  26



The end of line and `M-e'
=========================
A common operation is to move the point to the end of the current
line, then run `C-x C-e'. That can be done with `C-e C-x C-e',
but eev-mode implements a shorthand for it: `M-e'. Try it here:

  (+ (* 2 3)
     (* 4 5)
     )

`M-e' accepts several different numeric prefixes that alter its
behavior. We are only interested in one of them now - `M-0 M-e'
highlights the sexp for a fraction of a second insted of
executing it. Try it above.

In some rare occasions we might want to run something like `M-e'
but without moving to the end of the line first. Eev-mode
implements a key binding for that: `M-E' (meta-shift-e). As an
exercise, try to use `M-0 M-E' at several positions below, to
hightlight the subsexps `(* 2 3)', `(* 4 5)', and `4'.

  (+ (* 2 3) (* 4 5))




What to execute, and in what order
==================================
Note that the order of evaluation may be important:

  (setq a 5)
  (setq a 6)
  (* a a)

By executing `(setq a 5)' and then `(* a a)' above we get 25,
by executing `(setq a 6)' and then `(* a a)' we get 36 - the
current value of `a' is the one of the last `setq' executed.

An exercise: edit the three sexps above to introduce a
`(setq a 22)', then use that sexp and the `(* a a)' to calculate
the square of 22.

MORAL: Elisp code can appear anywhere in any Emacs buffer, but it
is _passive by default_. It only gets executed if we move the
point to the right positions and type `C-x C-e', `M-e', or
similar keys. Sexps can be executed any number of times, in any
order, and can be edited and modified.




Elisp hyperlinks
================
Some Emacs functions can be used as hyperlinks. When sexps like

  (find-file \"/tmp/\")
  (info \"(emacs)Lisp Eval\")
  (describe-function 'find-file)
  (find-function     'find-file)
  (man \"cat\")

are executed they \"open a new page\" - actually, they create a
new buffer, or reuse it if it already exists - and it is usually
possible to \"go back\" by killing the new buffer. However for
some functions, like `man', which by default open a manpage in
another window, \"going back\" would mean something different.

Eev defines several functions to let us use sexps as hyperlinks.
The main conventions on these functions are:

  1) their names start with \"find-\",

  2) calls to them can be \"refined\" with a pos-spec (this will
     be discussed below),

  3) they open the new buffer in the current window (to make it
     easier to \"go back\" after following them - see the next
     section),

  4) they don't display much output in the echo area,

  5) when they create temporary buffers with lots of sexps then:

     a) the first sexp in that buffer is one that can regenerate
        that buffer when executed,

     b) all the sexps are prefixed with the string stored in the
        variable `ee-hyperlink-prefix', to let these sexps be
        pasted into scripts as comments (see below).

Note that sometimes the most obvious name for a hyperlink
function starting with `find-' is already taken by Emacs - for
example, `find-file' and `find-function'. In those cases eev use
other names: `find-fline', `find-efunction', etc. Here are the
eev versions of the links above:

  (find-fline \"/tmp/\")
  (find-node \"(emacs)Lisp Eval\")
  (find-efunctiondescr 'find-file)
  (find-efunction      'find-file)
  (find-man \"cat\")




Going back
==========
Web browsers let you follow a hyperlink and then \"go back\".
There are different ways of going back - if you opened the new
page on a new window or tab, then going back means deleting the
new window or tab (or just switching to the old window/tab); if
you opened the new page on the same window/tab, then you need to
use the \"back\" button.

Eev-mode defines two keys for \"going back\": `M-k', that kills
the current buffer, and `M-K', that just hides it (\"buries\" it
in the bottom of the list of all buffers). Try following the link
below by <M-e>, then deleting its buffer with `M-k' to go back:

  (find-node \"(emacs)Shell\")

In some cases we know that we may want to go \"forward\" again
after going back, and we may not want to delete the target buffer
- for example, because it would take a while to rebuild it again,
or because we would lose the position of the point there. Most
hyperlink functions in eev are able to reuse a buffer that
\"looks like\" the desired target buffer; the test for
lookalikeness is based on the name of the buffer only. Try to
follow the links below with `M-e', then come back to this buffer
with `M-k', then follow them again. Then try the same thing with
`M-K' instead of `M-k', to see the difference - in the `find-sh'
example below the \"sleep\" takes one second to run, so
revisiting the existing output buffer after a `M-K' is much
quicker than recreating it anew.

  (find-man \"1 bash\")
  (find-sh \"sleep 1; echo 'This was run at:'; date\")




Refining hyperlinks
===================
Most hyperlinks functions defined by eev can be \"refined\" by
the addition of extra arguments. These extra arguments are called
a \"pos-spec\" (or a \"pos-spec-list\") and they specify a
position in the target buffer. The first argument means a certain
line number, when it is a number, or the first occurrence of a
certain string, when it is a string. Try:

  (find-node \"(emacs)Command Index\")
  (find-node \"(emacs)Command Index\" \"eval-last-sexp\")

Further arguments mean either \"move down n lines\" or \"search
for the next occurrence of a string\", depending on whether they
are numbers or strings. Try:

  (find-sh \"seq 2095 2115\")
  (find-sh \"seq 2095 2115\" \"2100\")
  (find-sh \"seq 2095 2115\" \"2100\" \"9\")
  (find-sh \"seq 2095 2115\" \"2100\" 2)



Pos-spec-lists
==============
The optional arguments that refine a hyperlink form what we call
a \"pos-spec-list\". For example, the pos-spec-list here has two
elements,

  (find-sh \"seq 2095 2115\" \"2100\" \"9\")

and in most cases an empty pos-spec-list, like this,

  (find-sh \"seq 2095 2115\")

means: \"if the target buffer already exists then just open it\"
- so that following that hyperlink would jump to the current
position of the point in that buffer.

Pos-spec-lists are usually interpreted by the function
`ee-goto-position'. The first argument is interpreted in a
special way, according to its type:

    string -> jump to the first occurrence of
              that string in the buffer
    number -> jump to the n-th like

and the other arguments are interpreted (recursively) by
`ee-goto-rest':

    string -> jump to the next occurence of that string
    number -> move down n lines
    list   -> evaluate the list

If you want to add support for more complex pos-spec-lists, just
replace `ee-goto-rest' with your own extended version.



Anchors and pages
=================
\[See:\] (find-anchors-intro)

Some hyperlink functions, like `find-efunction' and
`find-evariable', jump to specific positions in buffers - the
beginning of the definition of a function or a variable in the
source code - even when their pos-spec-lists are empty, so they
process the extra arguments with just `ee-goto-rest'.

Other hyperlink functions transform the first argument of a
pos-spec-list in a special way it if is a string - for example,
in `find-available', which is based on `find-Package',

  (find-available \"bash\")
  (find-available \"bash\" \"bash-doc\")

the argument \"bash\" is converted to \"\\nPackage: bash\\n\",
and the two hyperlinks above jump to the description of the
package \"bash\" in the list of the available packages in a
Debian system.

The functions based on `find-anchor' transform an initial string
argument in the pos-spec-list by running `ee-format-as-anchor' on
it [TODO: document this], and the ones based on
`ee-goto-position-page' jump to the n-th \"page\" of a buffer if
the first argument of the pos-spec-list is a number, n; for
exemple, if n is 234 that will jump to the 233-th formfeed (233
and not 234 because the page 1 is before the first formfeed). For
more on \"pages\", see:

  (find-pdf-like-intro \"PDF-like documents as text\")




Producing and refining hyperlinks
=================================
If you are on an Info page, typing `M-h M-i' will create a
temporary buffer containing a header - which we will discuss
later - and several (possibly equivalent) links to that info
page. Something like this:
   ________________________________________________________
  |;; (find-einfo-links)                                   |
  |                                                        |
  |;; (info \"(emacs)Misc Buffer\")                          |
  |;; (find-node \"(emacs)Misc Buffer\")                     |
  |;; (find-enode \"Misc Buffer\")                           |
  |                                                        |
  |                                                        |
  |--:**-  *Elisp hyperlinks*   All L1     (Fundamental)---|
  |________________________________________________________|

These links are meant to be cut & pasted - possibly after
refining them to make them more precise. Let's look first at the
two key sequences that make refining much easier. Remember that
`M-w' (`kill-ring-save') is roughly correspondent to what is
called \"copy\" is most modern interfaces, and `C-y' (`yank') is
roughly correspondent to \"paste\". Both `M-w' and `C-y' operate
on Emacs's \"kill ring\", and to make our examples trivial to
follow we will first put a string on the kill ring:

  (kill-new \"C-y\")
  (car kill-ring)

Now let's see how refine hyperlinks quickly. `M-h M-2' duplicates
the current line; we will use that to refine a copy of a working
hyperlink, instead of working directly on the original, and
risking breaking it. And `M-h M-y' refines the hyperlink on the
current line by adding a string - the top element in the kill
ring - to its sexp. Try this below; you should be able to convert

  (find-enode \"Kill Ring\")
  (find-enode \"Yanking\")

into

  (find-enode \"Kill Ring\")
  (find-enode \"Kill Ring\" \"C-y\")
  (find-enode \"Yanking\")
  (find-enode \"Yanking\" \"C-y\")

with few keystrokes, as you can leave the Meta key pressed. The
full key sequence for duplicating and refining is `M-h M-2 M-h
M-y', but we can think of it as `M-h2hy'.

Now try a more serious exercise: follow the `(find-enode ...)'
hyperlink below, copy a word or two from its contents to the kill
ring with `M-w', then generate the temporary buffer with
hyperlinks to that Info page with `M-h M-i', then duplicate one
of its hyperlinks with `M-h M-2', refine it with `M-h M-y', and
copy the result to this sandbox with `M-w' (or `C-w') and `C-y'.
As this is a long sequence of instructions, it is better to run
`C-x 1 C-x 2' or `C-x 1 C-x 3' before following the hyperlink, to
keep the instructions visible.

  (find-enode \"Command Index\")




What else?
==========
Eev-mode defines several other key sequences similar to `M-h
M-i'. You can get the full list here:

  (find-efunctiondescr 'eev-mode)
  (find-efunctiondescr 'eev-mode \"M-h f\")

Try also this:

  (find-efunction-links 'eev-mode)

and for other tutorials like this one, try:

  (find-wrap-intro)
  (find-eepitch-intro)

\[To do: explain M-x ee-hyperlink prefix and how to embed
hyperlinks in scripts]
" rest)))

;; (find-eval-intro)



;;;                  _ _       _           _       _             
;;;   ___  ___ _ __ (_) |_ ___| |__       (_)_ __ | |_ _ __ ___  
;;;  / _ \/ _ \ '_ \| | __/ __| '_ \ _____| | '_ \| __| '__/ _ \ 
;;; |  __/  __/ |_) | | || (__| | | |_____| | | | | |_| | | (_) |
;;;  \___|\___| .__/|_|\__\___|_| |_|     |_|_| |_|\__|_|  \___/ 
;;;           |_|                                                
;;
;; \253find-eepitch-intro\273  (to ".find-eepitch-intro")
;; (find-intro-links "eepitch")
;; (find-eev "eepitch.readme")

(defun find-eepitch-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-eepitch-intro)*"))
    (apply 'find-estring "\
\(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)
" rest)))

;; (find-eepitch-intro)

;; (find-pytutnode "Methods of File Objects")




;;;                                 _       _             
;;; __      ___ __ __ _ _ __       (_)_ __ | |_ _ __ ___  
;;; \ \ /\ / / '__/ _` | '_ \ _____| | '_ \| __| '__/ _ \ 
;;;  \ V  V /| | | (_| | |_) |_____| | | | | |_| | | (_) |
;;;   \_/\_/ |_|  \__,_| .__/      |_|_| |_|\__|_|  \___/ 
;;;                    |_|                                
;;
;; (find-intro-links "wrap")
;; \253find-wrap-intro\273  (to ".find-wrap-intro")

(defun find-wrap-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-wrap-intro)*"))
    (apply 'find-estring-lv "\
\(Re)generate: (find-wrap-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-wrap-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



Eepitch and eev
===============
Eepitch defines only two keys - <F8> and <M-T> - and <M-T> is a
particular case of something more general: \"wrapping commands\", that
follow these conventions:


Eepitch has two basic keys - <F8> and <M-T> - and <M-T> is a
particular case of something much more general. Eev-mode defines
several `wrapping commands', all of which follow these conventions:

  1) they are bound to meta-shift-letter keys (M-T, M-F, M-M, ...),
  2) they transform the current line and then move down,
  3) they produce Lisp code meant to be executed with `M-e' or `F8',
  4) they are listed at:
       (find-efunctiondescr 'eev-mode \"M-F\")
  5) their keybindings are only available when eev-mode is turned on
     (except for <M-T>).

To understand how they work, please follow the instructions below and
try them here. Note that this buffer is a sandbox, and it can be
recreated by executing the sexp \"(find-wrap-intro)\" at the top.

Note that the wrapping commands are all bound to key sequences of
the form meta-SHIFT-letter - don't forget the shift!!!



<M-T>: produce an eepitch block
===============================
If you type <M-T> on a line containing just the word \"shell\" you get
three lines, like this:

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

We call a block of three lines like this an \"eepitch block\", and
eepitch blocks can be used to set up interactions with external
programs. Try typing <M-T> on the lines that say \"shell\" and \"python\"
below, and use them to send some lines to bash and to a python
interpreter (with <F8>):

bash
export PS1='$PWD% '
cd /tmp/
function ee () { set -v; . /tmp/ee.sh; set +v; }
rm -v /tmp/ee.sh
cat > /tmp/ee.sh <<'%%%'
  echo Hello
  cd /etc/
%%%
cat   /tmp/ee.sh
bash  /tmp/ee.sh
ee

python
square = lambda x: x*x
square(5)



<M-F>: hyperlink to a file or a directory
=========================================
If you type <M-F> on the lines below,

/etc/
/tmp/
~/
~/.emacs

you get hyperlinks like these:

# (find-fline \"/etc/\")
# (find-fline \"/tmp/\")
# (find-fline \"~/\")
# (find-fline \"~/.emacs\")



<M-S>: hyperlink to the output of a shell command
=================================================
If you type <M-S> on a line containing a shell command you get a
hyperlink that starts with `find-sh', and that when followed opens a
temporary buffer with the output of that shell command, like these:

  # (find-sh \"find --help\")
  # (find-sh \"find /etc | sort\")
  # (find-sh \"find /etc -type d | sort\")
  # (find-sh \"find /etc -type d -maxdepth 1 | sort\")
  # (find-sh \"find /etc -type d -maxdepth 2 | sort\")

Try it here:

dict smop
dict 'minor detail'

If you have the packages dict, dictd and dict-jargon installed
these hyperlinks will show you the meaning of the expressions
\"smop\" and \"minor detail\".

  # (find-sh \"dict smop\")
  # (find-sh \"dict 'minor detail'\")



<M-M>: hyperlink to a manpage
=============================
Try <M-M> here:

1 tac



All wrapping functions
======================
Below is a list of all wrapping functions, with tests and
hyperlinks:

  (eek \"2*<down> M-A <down> ;;; Test eewrap-anchor\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-anchor\")
;; <anchor>

  (eek \"2*<down> M-C <down> ;;; Test eewrap-code-c-d\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-code-c-d\")
foo /tmp/foobar/

  (eek \"2*<down> M-D <down> ;;; Test eewrap-debian\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-debian\")
bash

  (eek \"2*<down> M-F <down> ;;; Test eewrap-find-fline\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-find-fline\")
/tmp/foobar/

  (eek \"2*<down> M-J <down> ;;; Test eewrap-eejump\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-eejump\")
422 (find-eev-intro \"find-wrap-intro\")

  (eek \"2*<down> M-J <down> ;;; Test eewrap-eejump\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-eejump\")
42

  (eek \"2*<down> M-M <down> ;;; Test eewrap-man\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-man\")
1 tac

  (eek \"2*<down> M-R <down> ;;; Test eewrap-rm/mkdir/cd\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-rm/mkdir/cd\")
/tmp/foo/

  (eek \"2*<down> M-S <down> ;;; Test eewrap-sh\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-sh\")
seq 1 20

  (eek \"2*<down> M-T <down> ;;; Test eewrap-eepitch\")
   Source:  (find-eev \"eepitch.el\"  \"eewrap-eepitch\")
python

  (eek \"2*<down> M-V <down> ;;; Test eewrap-audiovideo\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-audiovideo\")
slimetutorial /tmp/slime-tutorial.mp4

  (eek \"2*<down> M-Z <down> ;;; Test eewrap-zsh\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-zsh\")
echo $SHELL

  (eek \"2*<down> <<eewrap-eewrap>> <down> ;;; Test eewrap-eewrap\")
   Source:  (find-eev \"eev-wrap.el\" \"eewrap-eewrap\")
U user-defined a b c



# Local Variables:
# coding:           raw-text-unix
# ee-anchor-format: \"\253%s\273\"
# End:
" rest)))

;; (find-wrap-intro)




;;;  _ _       _        
;;; | (_)_ __ | | _____ 
;;; | | | '_ \| |/ / __|
;;; | | | | | |   <\__ \
;;; |_|_|_| |_|_|\_\___/
;;;                     
;; (find-intro-links "links")
;; \253find-links-intro\273  (to ".find-links-intro")

(defun find-links-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-links-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-links-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-links-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.




What is a hyperlink?
====================
In a previous tutorial - (find-eval-links) - we saw that several
kinds of sexps can be used as hyperlinks. For example, these:

  (find-fline \"/tmp/\")
  (find-node \"(emacs)Lisp Eval\")
  (find-efunctiondescr 'find-file)
  (find-efunction      'find-file)
  (find-man \"cat\")

Hyperlinks in web browser _usually_ take us to a different page,
or to a different position in the same page, and in those cases
it is possible to go back to previous position from there; but
sometimes hyperlinks - or webpage buttons - are associated to
Javascript code, and \"following the link\" then means executing
that code. Web browsers try to make it impossible to have
hyperlinks or webpages that will send out your private
information, or that will put your system in a unusable state.
Security is web browsers is achieved by restricting what the
scripts in a page can do.

Sexp hyperlinks, in contrast, can do essentially anything - and,
instead of _security_, they have _transparency_. The code that a
sexp hyperlink will execute is visible, and users are supposed to
know that sexp hyperlinks with `find-fline', `find-node',
`find-efunctiondescr', etc, are very safe - but the ones that
start with `find-sh' may not be. It is possible to write
something like:

  (find-sh \"<code that deletes all your e-mails>\")

but it is not possible to hide that action behind an
innocent-looking button that says \"click for a larger image\".

So, _any_ elisp sexp can be _used_ as a sexp hyperlink; but
people are only going to follow a sexp hyperlink if they can more
or less predict (quickly!) what that hyperlink is going to do...
Readability is important, and eev implements several families of
\"basic\" functions for building hyperlinks with. They are
described in details in these source files,

  (find-eev \"eev-blinks.el\")
  (find-eev \"eev-plinks.el\")
  (find-eev \"eev-elinks.el\")
  (find-eev \"eev-tlinks.el\")
  (find-eev \"eev-anchors.el\")

and we will explain most of their ideas and hyperlink functions
below. But some hyperlink functions, like the `find-eev' above,
are what we call \"shorter hyperlinks\", and they will be
described in these other, more advanced, tutorials:

  (find-code-c-d-intro)
  (find-pdf-like-intro)
  (find-audiovideo-intro)




Kinds of hyperlink functions
============================
Eev defines _many_ functions that can be used as hyperlinks. In
order to explain them here we will categorize them into:

  1) Basic functions, that depend on very few other features from
     eev, but that may call complex Emacs features more or less
     directly; these are defined in:
       (find-eev \"eev-blinks.el\")
     and will be described below.

  2) Low-level functions, like `find-bgprocess' and
     `find-callprocess', that invoke external processes. These are
     defined in:
       (find-eev \"eev-plinks.el\")
     they are rarely called directly, so we will not document
     them here - see the source.

  3) Functions that create \"*Elisp hyperlinks*\" buffers. They
     will be explained below, and they are defined in these two
     source files:
       (find-eev \"eev-elinks.el\")
       (find-eev \"eev-tlinks.el\")

     3a) The ones in eev-elinks.el are all somewhat similar to
         `find-ekey-links'. Each one of them is invoked by a key
         sequence starting with `M-h', and the buffers that they
         generate consist almost only of hyperlinks. We call them
         \"`find-e*-links' functions\". Try:
              (eek \"M-h M-k <down>\")
           (find-ekey-links [down])

     3b) The ones in eev-tlinks.el generate more complex buffers,
         often involving string templates. They are intended to
         be invoked by sexps, like this:
           (find-eev-update-links)
           (find-eev-update-links \"{replace-this-by-a-dir}\")
         We call these functions \"`find-*-links' functions\".

  5) `find-*-intro' functions, that create sandbox-y tutorials
     like this one. They are similar to the `find-*-links'
     functions, but much simpler. The full list of `find-*-intro'
     tutorials can be found here:
       (find-eev-intro)

  6) \"Shorter hyperlinks\", that are generated by calls to
     `code-c-d', `code-xpdf', `code-audio', `code-video', etc.
     These will be described elsewhere, at:
       (find-code-c-d-intro)
       (find-pdf-like-intro)
       (find-audiovideo-intro)
     Each of these `code-*' functions has an associated
     `find-code-*' function for debugging, that shows the code
     that the corresponding `code-*' would execute. Try:
       (find-code-c-d      \"{c}\" \"{dir}\")
       (find-code-c-d      \"{c}\" \"{dir}\" \"{infofile}\" :anchor :gz)
       (find-code-xpdf     \"{c}\" \"{path-to-pdf-file}\")
       (find-code-pdf-text \"{c}\" \"{path-to-pdf-file}\")
       (find-code-audio    \"{c}\" \"{path-to-audio-file}\")
       (find-code-video    \"{c}\" \"{path-to-video-file}\")

  6) `to' - which is the only function in eev that does not start
     with either `find-' or `ee' - and other hyperlinks to
     anchors. See:
       (find-anchors-intro)




Elisp hyperlinks buffers
========================
Eev-mode defines several keybindings that start with `M-h' - the
full list is here,

  (find-efunctiondescr 'eev-mode \"M-h\")
  (find-efunctiondescr 'eev-mode \"generate pages with lists of hyperlinks\")

and most of them generate temporary buffers called \"*Elisp
hyperlinks*\", obeying these conventions:

  1) those buffers contain mostly hyperlink sexps, meant to be
     edited and copied-and-pasted to other, more permanent
     places,

  2) those buffers are read-write to let those sexps be edited
     and \"refined\" in the sense of:

       (find-eval-intro \"Producing and refining hyperlinks\")

  3) the top sexp regenerates the buffer,

  4) if the top sexp is followed by other sexps that invoke the
     same function then those sexps regenerate the buffer with
     other parameters,

\[To do: explain how nil arguments are treated\]

Examples and tests:

  (eek \"M-h f\")
  (eek \"M-h M-f find-file RET\")
  (eek \"M-h M-k <down>\")
  (eek \"M-h M-v line-move-visual RET\")
  (eek \"M-h M-d bash RET\")
  (find-eev-update-links)
  (ee-hyperlink-prefix)





Basic functions
===============
The \"basic\" hyperlink functions are all defined in:
  (find-eev \"eev-blinks.el\")
Here we will show an example of use of each one - follow the
links to the source code for more information.

    From: (find-eev \"eev-blinks.el\" \"find-fline\")
  (find-fline \"~/\")
  (find-node  \"(emacs)Top\")

    From: (find-eev \"eev-blinks.el\" \"find-wottb\")
  (find-efunctiondescr 'next-line)
  (find-ekeydescr      [down])
  (find-evariabledescr 'line-move-visual)
  (find-eapropos       \"^find-.*-links\")
  (find-efunctiond     'next-line)
  (find-ecolors)
  (find-efacedescr     'default)
  (find-efaces)

    From: (find-eev \"eev-blinks.el\" \"find-ebufferandpos\")
  (find-efunction 'next-line)
  (find-evariable 'line-move-visual)

    From: (find-eev \"eev-blinks.el\" \"find-ebuffer\")
  (find-ebuffer \"*Messages*\")

    From: (find-eev \"eev-blinks.el\" \"find-eoutput\")
  (find-estring \"a\\nb\\nc\\n\")
  (find-estring-elisp \"(dotimes (i 10) (insert \\\"\\\\na\\\"))\")
  (find-estring-elisp \"(defun square (a) (* a a))\")

    From: (find-eev \"eev-blinks.el\" \"find-sh\")
  (find-sh   \"seq 2095 2100\")
  (find-sh0  \"seq 2095 2100\")
  (find-sh00 \"seq 2095 2100\")

    From: (find-eev \"eev-blinks.el\" \"find-man\")
  (find-man \"1 cat\")

    From: (find-eev \"eev-blinks.el\" \"find-w3m\")
  (find-w3m \"http://www.emacswiki.org/\")

    From: (find-eev \"eev-blinks.el\" \"find-Package\")
  (find-status         \"bash\")
  (find-available      \"bash\")
  (find-grep-status    \"bash\")
  (find-grep-available \"bash\")

    From: (find-eev \"eev-blinks.el\" \"find-epp\")
  (find-epp '(apply (lambda (a) (* a a)) 5))
  (find-functionpp 'find-efunction)

    From: (find-eev \"eev-blinks.el\" \"find-einternals\")
  (find-ekeymapdescr isearch-mode-map \"toggle-regexp\")
  (find-eminorkeymapdescr 'eev-mode)
  (find-einsert '((32 255) 10 (8592 9167)))
  (find-etpat)
  (find-etpat0)



`find-e*-links'
===============
The `find-e*-links' functions are probably going to be your main
source of hyperlinks - they are very easy to invoke, and they
generate buffers with links that you can copy and paste to other
places.

  From: (find-eev \"eev-elinks.el\" \"find-efunction-links\")
  Test: (find-efunction-links 'next-line)
                (eek \"M-h M-f next-line\")

  From: (find-eev \"eev-elinks.el\" \"find-evariable-links\")
  Test: (find-evariable-links 'line-move-visual)
                (eek \"M-h M-v line-move-visual\")
  
  From: (find-eev \"eev-elinks.el\" \"find-ekey-links\")
   and: (find-eev \"eev-elinks.el\" \"find-elongkey-links\")
  Test: (find-ekey-links \"\\C-x2\")
        (find-elongkey-links \"C-x 2\")
              (eek \"M-h M-k C-x 2\")
       
  From: (find-eev \"eev-elinks.el\" \"find-einfo-links\")
  Test: (progn (find-enode \"Lisp Eval\") (find-einfo-links))
        (progn (find-enode \"Lisp Eval\") (eek \"M-h M-i\"))

  From: (find-eev \"eev-elinks.el\" \"find-file-links\")
  Test: (code-c-d \"abc\"   \"/a/b/c/\")
        (code-c-d \"abcd\"  \"/a/b/c/d/\")
        (code-c-d \"abcde\" \"/a/b/c/d/e/\")
        (find-file-links  \"/a/b/c/d/e/f\")
        (find-file-links \"~/tmp/foo\")
        (find-file-links \"$S/http/foo/bar/\")
  
  From: (find-eev \"eev-elinks.el\" \"find-grep-links\")
  Test: [harder, as it involves grep-history]

  From: (find-eev \"eev-elinks.el\" \"find-ekbmacro-links\")
  Test: [to be written]

  From: (find-eev \"eev-elinks.el\" \"ee-hyperlink-prefix\")
  Test: (ee-hyperlink-prefix)

  From: (find-eev \"eev-elinks.el\" \"find-color-links\")
  Test: (find-ecolor-links \"sienna\")

  (find-efunctiondescr 'eev-mode)



Other `find-*-links' functions
==============================
See: (find-eev \"eev-tlinks.el\")

  (find-eev \"eev-tlinks.el\" \"find-find-links-links\")
  (find-eev \"eev-tlinks.el\" \"find-intro-links\")
  (find-eev \"eev-tlinks.el\" \"find-pdflikedef-links\")
  (find-eev \"eev-tlinks.el\" \"find-eev-header-links\")

  (find-eev \"eev-tlinks.el\" \"find-debpkg-links\")
  (find-eev \"eev-tlinks.el\" \"find-eev-update-links\")
  (find-eev \"eev-tlinks.el\" \"find-newhost-links\")
  (find-eev \"eev-tlinks.el\" \"find-dhmake-links\")
  (find-eev \"eev-tlinks.el\" \"find-youtubedl-links\")
  (find-eev \"eev-tlinks.el\" \"find-upload-links\")



Medium-level `find-exxx-links'
============================

  (find-efunction-links 'find-efunction-links)
  (find-evariable-links 'ee-hyperlink-prefix)
  (find-ekey-links    \"\\M-h\\M-f\")
  (find-elongkey-links \"M-h M-f\")
  (find-ebuffer-links \"eev-intro.el\")

  (find-file-links \"~/eev-current/eev-intro.el\")
  (find-einfo-links)
  (find-debpkg-links \"bash\")



TO DO: organize this
====================

  A lispish interface for customizing a variable.
  Important note: this is just a proof-of-concept thing at the
  moment, implemented for just one variable, using a function with
  the same name of the variable. No generality at all!
 
  Running M-x ee-hyperlink-prefix produces a buffer like this:
     ________________________________________________________ 
    |# (ee-hyperlink-prefix)                                 |
    |# (setq ee-hyperlink-prefix \"# \")                       |
    |                                                        |
    |# (setq ee-hyperlink-prefix \"# \")                       |
    |# (setq ee-hyperlink-prefix \";; \")                      |
    |# (setq ee-hyperlink-prefix \"-- \")                      |
    |# (setq ee-hyperlink-prefix \"% \")                       |
    |                                                        |
    |                                                        |
    |--:**  *Elisp hyperlinks*   All L10    (Fundamental)----|
    |________________________________________________________|
 
  Note that in this interface instead of questions and buttons we
  have sexps that can be changed and executed, and that the second
  of those sexps (see the source code below) contains the current
  value of the variable ee-hyperlink-prefix. The first sexp - as
  always in these lists of hyperlinks - contains a sexp that
  regenerates the buffer; changing the value of the variable
  ee-hyperlink-prefix and then running the first sexp again will
  generate the buffer again with the new value of
  ee-hyperlink-prefix; for example, the result can be this:
     ________________________________________________________ 
    |;; (ee-hyperlink-prefix)                                |
    |;; (setq ee-hyperlink-prefix \";; \")                     |
    |                                                        |
    |;; (setq ee-hyperlink-prefix \"# \")                      |
    |;; (setq ee-hyperlink-prefix \";; \")                     |
    |;; (setq ee-hyperlink-prefix \"-- \")                     |
    |;; (setq ee-hyperlink-prefix \"% \")                      |
    |                                                        |
    |                                                        |
    |--:**  *Elisp hyperlinks*   All L10    (Fundamental)----|
    |________________________________________________________|
 


  Example: running `M-x find-debpkg-links' when the
  point is over the word \"bash\" runs this sexp,
    (find-debpkg-links \"bash\")
  which creates a temporary buffer like this:
 
   ___________________________________________________________________________ 
  |# (find-debpkg-links \"bash\")                                               |
  |                                                                           |
  |# (find-available \"bash\")                                                  |
  |                                                                           |
  |# (find-status   \"bash\")                                                   |
  |# (find-vldifile \"bash.list\")                                              |
  |# (find-udfile   \"bash/\")                                                  |
  |                                                                           |
  |# (find-vldifile \"bash.preinst\")                                           |
  |# (find-vldifile \"bash.postinst\")                                          |
  |# (find-vldifile \"bash.prerm\")                                             |
  |# (find-vldifile \"bash.postrm\")                                            |
  |# (find-vldifile \"bash.conffiles\")                                         |
  |# (find-vldifile \"bash.md5sums\")                                           |
  |                                                                           |
  |http://packages.debian.org/bash                                            |
  |http://packages.debian.org/src:bash                                        |
  |http://ftp.debian.org/debian/pool/main/b/bash/                             |
  |http://backports.org/debian/pool/main/b/bash/                              |
  |http://bugs.debian.org/cgi-bin/pkgreport.cgi?which=pkg&data=bash&archive=no|
  |                                                                           |
  |                                                                           |
  |                                                                           |
  |                                                                           |
  |--:**  *Elisp hyperlinks*   All L1     (Fundamental)-----------------------|
  |___________________________________________________________________________|
" rest)))

;; (find-links-intro)

;; (find-eevfile "eev-template.el" "defun find-efunction-links")





;;;                _                          _       _       _             
;;;   ___ ___   __| | ___        ___       __| |     (_)_ __ | |_ _ __ ___  
;;;  / __/ _ \ / _` |/ _ \_____ / __|____ / _` |_____| | '_ \| __| '__/ _ \ 
;;; | (_| (_) | (_| |  __/_____| (_|_____| (_| |_____| | | | | |_| | | (_) |
;;;  \___\___/ \__,_|\___|      \___|     \__,_|     |_|_| |_|\__|_|  \___/ 
;;;                                                                         
;; \253find-code-c-d-intro\273  (to ".find-code-c-d-intro")

(defun find-code-c-d-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-code-c-d-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-code-c-d-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-code-c-d-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



Avoiding full path names
========================
Suppose that you have downloaded (\"psne\"-ed) this URL,

  http://www.lua.org/ftp/lua-5.1.4.tar.gz

with `M-x brep' - see:

  (find-psne-intro)

and you unpacked that tarball into the directory ~/usrc/ (I
prefer to use that instead of /usr/src/) with:

  tar -C ~/usrc/ -xvzf $S/http/www.lua.org/ftp/lua-5.1.4.tar.gz

Now you can access some directories and files of the unpacked
tarball with:

  (find-fline \"~/usrc/lua-5.1.4/\")
  (find-fline \"~/usrc/lua-5.1.4/src/\")
  (find-fline \"~/usrc/lua-5.1.4/src/lstrlib.c\")
  (find-fline \"~/usrc/lua-5.1.4/test/\")
  (find-fline \"~/usrc/lua-5.1.4/test/README\")
  (find-fline \"~/usrc/lua-5.1.4/doc/\")
  (find-w3m   \"~/usrc/lua-5.1.4/doc/contents.html\")

but it's a bit clumsy to have to use the \"~/usrc/lua-5.1.4/\"
every time, so eev provides a nice way to define shorthands. We
want to be able to write just this instead of the sexps above,

  (find-lua51file \"\")
  (find-lua51file \"src/\")
  (find-lua51file \"src/lstrlib.c\")
  (find-lua51file \"test/\")
  (find-lua51file \"test/README\")
  (find-lua51file \"doc/\")
  (find-lua51w3m  \"doc/contents.html\")

and here the directory \"~/usrc/lua-5.1.4/\" became a mnemonic
\"lua51\" in the middle of the names of some functions.

We will call these sexps with \"lua51\" \"shorter hyperlinks\".



Shorter hyperlinks
==================
How can we generate the definitions for `find-lua51file' and
`find-lua51w3m' from just the strings \"lua51\" and
\"~/usrc/lua-5.1.4/\"? Try this:

  (find-code-c-d \"lua51\" \"~/usrc/lua-5.1.4/\")

you will get a temporary buffer with a lot of Lisp code -
including a definition for `find-lua51file' and another one for
`find-lua51w3m'. That Lisp code has not been executed yet; the
function `find-code-c-d' is just for debugging, and we can regard
it as a hyperlink to the code that this sexp would execute:

  (code-c-d \"lua51\" \"~/usrc/lua-5.1.4/\")
  
So, to define a family of functions including `find-lua51file'
and `find-lua51w3m', for a given \"mnemonic\" - \"lua51\" in this
case - and a given \"directory\" - \"~/usrc/lua-5.1.4/\" - we run
this:

  (code-c-d \"lua51\" \"~/usrc/lua-5.1.4/\")

which generates a block of Lisp code, as a string, and evaluates
it. Note: the original (and rather confusing) terminology for the
\"mnemonic\" was \"code\"; that's why the \"c\" in `code-c-d'.



Extra arguments to `code-c-d'
=============================
`code-c-d' supports extra arguments - for example, this works:

  (find-code-c-d \"el\" \"~/usrc/emacs/lisp/\" :info \"elisp\")

Look at the end of the generated code and you will see that it
has a definition for `find-elnode' - such that

  (find-elnode \"Constant Variables\")

is a shorthand (a \"shorter hyperlink\") for:

  (find-node \"(elisp)Constant Variables\")

What is important to understand here is how these definitions
with extra arguments are structured - so that you will be able to
understand the source code when you need to. Both `code-c-d' and
`find-code-c-d' are defined with a `&rest' in their argument
lists, like this (**NOTE: do not execute these defuns!**):

  (defun      code-c-d (c d &rest rest) ...)
  (defun find-code-c-d (c d &rest rest) ...)

and they both invoke `ee-code-c-d', which does all the template
work and returns a big string; `ee-code-c-d' passes its `rest'
argument to a recursive function called `ee-code-c-d-rest', and
for each one of the suported keywords there is a corresponding
function, also recursive; for `:info' it is called
`ee-code-c-d-:info'. Their specifications are like this:

  (defun   ee-code-c-d (c d &rest rest) ...)
  (defun   ee-code-c-d-rest      (rest) ...)
  (defun   ee-code-c-d-:info (manual &rest rest) ...)

and one very non-obvious trick is used to make the code short.
When `ee-code-c-d-rest' and `ee-code-c-d-:info' are run they can
access the values the `c' and the `d' that were passed to
`ee-code-c-d' (due to dynamic scoping), so `c' and `d' do not
need to be passed down explicitly as arguments.




Other similar functions
=======================
See: (find-brxxx-intro)
     (find-pdf-like-intro)
     (find-audiovideo-intro)
" rest)))

;; (find-TH "eev-article")
;; (find-TH "eev-article" "shorter-hyperlinks")
;; (find-code-c-d-intro)





;;;                             _       _             
;;;  _ __  ___ _ __   ___      (_)_ __ | |_ _ __ ___  
;;; | '_ \/ __| '_ \ / _ \_____| | '_ \| __| '__/ _ \ 
;;; | |_) \__ \ | | |  __/_____| | | | | |_| | | (_) |
;;; | .__/|___/_| |_|\___|     |_|_| |_|\__|_|  \___/ 
;;; |_|                                               
;;
;; \253find-psne-intro\273  (to ".find-psne-intro")
;; (find-TH "eev-article" "local-copies")
;; (find-angg ".emacs" "brep")
;; (find-eev "eev-browse-url.el" "find-psne-links")
;; (find-eev "eev-browse-url.el" "brep")

(defun find-psne-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-psne-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-psne-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-psne-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.




Local copies of files from the internet
=======================================
Emacs knows how to fetch files from the internet, but for most
purposes it is better to use local copies. Suppose that the
environment variable $S is set to ~/snarf/; then running this

* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
  mkdir -p $S/http/www.gnu.org/software/emacs/
  cd       $S/http/www.gnu.org/software/emacs/
  wget      http://www.gnu.org/software/emacs/emacs-paper.html
  echo     'http://www.gnu.org/software/emacs/emacs-paper.html' >> ~/.psne.log

  # (find-fline \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
  # (find-w3m   \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")

creates a local copy of `emacs-paper.html' inside ~/snarf/http/
and appends the URL to the file ~/.psne.log. The two lines in
comments are hyperlinks to the local copy; The `find-fline' opens
it as a file in the obvious way, and `find-w3m' opens it \"as
HTML\", using a text-mode web browser called w3m that can be run
either in standalone mode or inside Emacs; `find-w3m' uses w3m's
Emacs interface, and it accepts extra arguments, which are
treated as a pos-spec-list.



The old way: psne
=================
A long time ago eev used to include a shell function called
`psne' that ran all that with a single command. This:

  psne http://www.gnu.org/software/emacs/emacs-paper.html

would run the `mkdir', the `cd', the `wget' and the `echo' above.

If psne were just a shell script then it wouldn't be able to
change the current directory for the calling shell, so it had to
be defined as shell function instead of a script, and the user
had to patch his ~/.bashrc (or ~/.zshrc, or whatever) to install
the definition for psne and make it available. That was VERY
clumsy.

From now on we will use \"psne\" as a verb: to psne a URL means
to download a local copy of it into the right place, change to
its directory and save its name into the file \"~/.psne.log\".




The new way: M-x brep
=====================
Try to run this:

  (find-psne-links \"http://www.gnu.org/software/emacs/emacs-paper.html\")

or, equivalently, put the point on the URL below and then run
`M-x brep':

  http://www.gnu.org/software/emacs/emacs-paper.html

You will get a temporary buffer for psne-ing the URL above. It
will contain a `mkdir', a `cd', a `wget' and an `echo', plus an
eepitch block and some elisp hyperlinks, and it can be executed
with `F8's. Moral of the story: the \"new\" way to download a
local copy of a url is to put the point on it, then run `M-x
brep', then execute the resulting e-script. This does not require
any patching of rcfiles, as the shell-function version of `psne'
used to do.



The environment variable $S
===========================
If when eev is loaded by Emacs the environment variable $S is
unset, it will be set to a default value - namely, to the
expansion of \"$HOME/snarf\". Processes started from Emacs, such
as shells created with `eepitch-shell' or `find-sh', or external
terminals created by sexps like

  (find-bgprocess \"xterm\")
  (find-bgprocess \"gnome-terminal\")
  (find-bgprocess \"eterm\")

will then inherit that value. Try it:

  (getenv \"S\")
  (find-sh0 \"echo $S\")

* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
echo $S

Try also to create an external shell not from Emacs - for
example, from your window manager's list of available
applications, or from a text-mode login - and run \"echo $S\"
there: you will notice that $S is unset.

Old versions of eev used to require the user to run a script that
would patch his rcfiles (i.e., ~/.bashrc, ~/.zshrc, etc) to set
$S on startup. That turned out to be unreliable - it was better
to teach people how to distinguish those processes that inherit
$S from Emacs from those that don't, and let the experts patch
their rcfiles by hand.



`browse-url' and friends
========================
If you place the point on the URL below

  http://www.gnu.org/software/emacs/emacs-paper.html

and run `M-x browse-url', Emacs will make an external browser
visit the remote version of that URL. One (bad) way to visit the
local copy of that URL is to modify the URL above by hand to
adjust it to your value of $S, until you obtain something like
this:

  file:///home/edrx/snarf/http/www.gnu.org/software/emacs/emacs-paper.html

and then run `M-x browse-url' on it.

One - rather primitive - way of visiting the local copy of that
URL with find-file is to modify the URL by hand, replacing its
\"http://\" with n \"$S/http/\", and then visit that file. For
example:

                http://www.gnu.org/software/emacs/emacs-paper.html
   (find-file \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")
  (find-fline \"$S/http/www.gnu.org/software/emacs/emacs-paper.html\")

If you put the point on the URL and run `M-x brfl' on it you will
visit the local copy \"as a file\", with `find-file' /
`find-fline'. Visiting URLs - or their local copies - is
something that we do so frequently that we need ways to do that
with few keystrokes, which is why `brfl' has a short - and
cryptic - name. The conventions are:

  \"br\" is the common prefix for all the browse-url-like
       functions in eev,
  \"f\"  means to use `find-fline' (or, equivalently, `find-file'),
  \"l\"  is an optional suffix meaning to use the local copy.

The details on how to create these \"brxxx functions\" are here:
  (find-brxxx-intro)

" rest)))

;; (find-enode "Command Index" "browse-url")
;; (find-efunction 'browse-url)
;; (find-elnode "System Environment")
;; (find-enode "Environment")
;; (find-eevfile \"eev.el\" \"$HOME/snarf\")

;; (find-psne-intro)




;;;  _                                _       _             
;;; | |__  _ ____  ____  ____  __    (_)_ __ | |_ _ __ ___  
;;; | '_ \| '__\ \/ /\ \/ /\ \/ /____| | '_ \| __| '__/ _ \ 
;;; | |_) | |   >  <  >  <  >  <_____| | | | | |_| | | (_) |
;;; |_.__/|_|  /_/\_\/_/\_\/_/\_\    |_|_| |_|\__|_|  \___/ 
;;;                                                         
;; \253find-brxxx-intro\273  (to ".find-brxxx-intro")

(defun find-brxxx-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-brxxx-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-brxxx-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-brxxx-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



\[Note: these intros refer to the code in \"eev-code.el\", that
is not yet loaded by default!]


Introduction
============
Suppose that `plic' is a function that expects a file name, and
`pluc' is a function that expects a URL; to make these ideas more
concrete, suppose that these are typical calls to them,

  (plic \"/foo/bar/b\")
  (pluc \"http://a/b\")

and that both `plic' and `pluc' invoke external programs to visit
the given file name or url - `plic' opens a file with a PDF
viewer, and `pluc' makes a certain web browser open the given
URL. And suppose that both `plic' and `pluc' are just Emacs
\"functions\", not \"commands\" - remember that \"commands\" are
the things that can be invoked with `M-x'.

We saw in

  (find-psne-intro)

that by \"psne-ing\" the URL \"http://a/b\" we create a local
copy of its contents in \"$S/http/a/b\". Emacs has a family of
`browse-url' functions, briefly described in:

  (find-enode \"Browse-URL\")

We will soon see in detail how we can create families of
\"browse-url-like\" commands associated to each function like
`plic' or `pluc'. Briefly, if we run

  (code-brurl  'pluc :remote 'brpluc :local 'brplucl)
  (code-brfile 'plic                 :local 'brplicl)

we create commands `brpluc', `brplucl', and `brplicl', that can
be invoked when the point is on a URL to visit either that URL or
the local copy of its contents with `pluc' or `plic'; by
convention, the `brxxx' commands that end with \"l\" operate on
the local copy, and all of them start with \"br\" and have short
\(and unfortunately often cryptic) names, as they're meant to be
invokeable with few keystrokes.



A test
======
All commands created by calls to `code-brurl' and `code-brfile'
display a message in the echo acrea that explain which function
like `pluc' or `plic' they invoked, with what argument, and what
result it returned. We can use that to understand them better.
Run this,

  (defun pluc (url)      url)
  (defun plic (filename) filename)
  (code-brurl  'pluc :remote 'brpluc :local 'brplucl)
  (code-brfile 'plic                 :local 'brplicl)

and now with the point on the URL below

  http://a/b

type `M-x brpluc', `M-x brplucl', and `M-x brplicl'. You should
see messages like this in your echo area:

  (pluc \"http://a/b\") -> \"http://a/b\"
  (pluc \"file:///home/edrx/snarf/http/a/b\") -> \"file:///home/edrx/snarf/http/a/b\"
  (plic \"/home/edrx/snarf/http/a/b\") -> \"/home/edrx/snarf/http/a/b\"



The dired variation
===================

In dired mode each line corresponds to a file


" rest)))

;; (find-brxxx-intro)
;; (find-brxxx-intro "M-x brpluc")




;;;             _                       
;;;   ___  ___ (_)_   _ _ __ ___  _ __  
;;;  / _ \/ _ \| | | | | '_ ` _ \| '_ \ 
;;; |  __/  __/| | |_| | | | | | | |_) |
;;;  \___|\___|/ |\__,_|_| |_| |_| .__/ 
;;;          |__/                |_|    
;;
;; (find-elnode "Defining Commands")
;; (find-enode "Arguments")
;;              (find-TH "emacs"    "eejump")
;;    http://angg.twu.net/emacs.html#eejump
;; file:///home/edrx/TH/L/emacs.html#eejump
;; \253find-eejump-intro\273  (to ".find-eejump-intro")

(defun find-eejump-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-eejump-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-eejump-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-eejump-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



The problem
===========
Suppose that we have several files that we are working on, and we
want a quick way to jump to (i.e., to visit) any of them with
very few keystrokes; moreover,

  1) we want our list of files to be preserved between one Emacs
  session and another,

  2) we know that each \"visit a file\" command will correspond
  to an elisp hyperlink.

One quick solution would be to put the list of elisp hyperlinks
in a file, and make the key `M-j' open that file. But then
jumping to a file in that list becomes a two-step process: type
`M-j', move the point to the right line, type `M-e'. This would
be similar to what happens when we use one of the `find-e*'
commands, for example `find-efunction':

  (find-efunction 'find-efunction)
     (eek \"M-h M-f find-efunction\")

Those intermediate steps - seeing the list, locating visually the
right line, moving to it - are distracting, so we want to add new
items to our wishlist:

  3) it should be possible to jump straight to any of the files
  in the list, and with very few keystrokes,

  4) the list should be stored in a format that lets us see
  quickly which are the keystrokes for accessing each item - so
  that we won't need to memorize anything,

  5) the list should be easy to modify,

  6) it should be possible to assign shorter key sequences to
  files we visit more often,

  7) the source code must be very simple.


  
A miniature
===========
My original solution was this: I used only one keybinding, `M-j',
that acted differently when invoked with different numeric
prefixes; when invoked as `M-1 M-j' it opened a certain file,
when invoked with `M-2 M-j' it opened another, and so on, and
when it was invoked with an unrecognized prefix or with no prefix
it jumped to its definition in my ~/.emacs. Its code was like
this (**NOTE: do not execute these defuns**):

  ;; eejump-simplified (`M-j'):
  ;; M-1 M-j opens a certain file,
  ;; M-2 M-j opens another file,
  ;; when the argument is 11, 22, 33 or 44 do something special,
  ;; like changing the font;
  ;; with no argument or with an unrecognized argument jump to the
  ;; definition of eejump in ~/.emacs; then we can see which numbers
  ;; correspond to which actions (the source is the documentation!), and
  ;; we can change the definition if needed - just run `M-e' at the
  ;; right place to make the changes apply.
  ;;
  \(global-set-key (kbd \"M-j\") 'eejump-simplified)
  \(defun eejump-simplified (arg) (interactive \"P\")
    (cond ((eq arg 1) (find-file \"~/NOTES\"))
          ((eq arg 2) (find-file \"~/otherfile.txt\"))
          ;;
          ((eq arg 11) (set-frame-font \"fixed\"))
          ((eq arg 22) (set-frame-font \"terminus-16\"))
          ((eq arg 33) (set-frame-font \"terminus-bold-16\"))
          ((eq arg 44) (set-frame-font \"10x20\"))
          (t (find-function 'eejump-simplified))))

except that my definition became huge with time as I added to it
more entries for files (and other actions!) that I used often,
and also entries that were used not so often...

All the \"options\" - i.e., all the `(eq arg nnn)' lines - had to
be together in a single very big defun, and there was no way to
add new options temporarily...




Families
========
Let's use a shorthand for key sequences: for example, `M-123j'
instead of `M-1 M-2 M-3 M-j'.

I tend to assign related numbers to related files. For example, I
use the prefix \"5\" for things that are Emacs-related: `M-5j'
visits my .emacs, `M-555j' visits the directory with all of eev's
elisp files, and `M-51j', `M-52j', etc, visit specific eev source
files that I happen to be working on. Also, I use the prefix
\"7\" for things related to LaTeX. So, the \"5*\" family is
composed of Emacs-related files, and the \"7*\" family of
LaTex-related files.

The definition of `eejump-simplified' given above does not
satisfy these two (new!) wishlist items:

  8) it should be possible to jump to the definition of the
  \"5*\" family by typing something like `M-5678j', where
  \"5678\" is a non-assigned number that starts with the \"5*\"
  prefix,

  9) it should be possible to convert a number/hyperlink pair
  very easily into to the code that assigns that elisp hyperlink
  as the desired behavior for that number - and it should be
  possible to do that both permanently (think in changing the
  definition of `eejump-simplified' in your .emacs) and
  temporarily (i.e., for the current Emacs session only).



eejump
======
The definition of `eejump' that comes with eev is a bit more
complex than the one given above, and it will not be shown
here (it involves a tricky recursive function) but it satisfies
the 9 wishlist items above. It works in this way: if you type,
say, `M-123j', then:

  a) if `eejump-123' is defined, then execute it;
  b) otherwise, if `eejump-12*' is defined, execute it;
  c) otherwise, if `eejump-1*' is defined, execute it;
  d) otherwise, if `eejump-*' is defined, execute it,

and if `eejump-*' also is not defined, you get an error.

Here is a block of \"defun\"s that defines (trivial) meanings for
\"91\", \"92\", \"991\", and \"992\", plus targets for the \"9*\"
family and for the \"99*\" family; it also has two tests in
comments that will be very important for an explanation below.
Let's refer as that, in this section and the next ones, as \"the
block of six defuns (plus four tests)\".

  (defun eejump-9* () (find-efunction 'eejump-9*))
  (defun eejump-91 () (message \"M-91j\"))
  (defun eejump-92 () (message \"M-92j\"))
  (defun eejump-99* () (find-efunction 'eejump-99*))
  (defun eejump-991 () (message \"M-991j\"))
  (defun eejump-992 () (message \"M-992j\"))
  ;; (find-function-noselect 'eejump-9*)
  ;; (find-function-noselect 'eejump-99*)
  ;; (find-efunction 'eejump-9*)
  ;; (find-efunction 'eejump-99*)

Try to evaluate each of the sexps above with `M-e', then try to
run things like `M-92j' and `M-992j' - they should work - and
then something like `M-99876j'; that will not work, you'll get an
error like \"Don't know where `eejump-99*' is defined\"...



eejump blocks
=============
Let's a call a sequence of defuns for eejumps with the same
prefix, like this, starting with a `(defun eejump-<prefix>* ...)',

  (defun eejump-99* () (find-efunction 'eejump-99*))
  (defun eejump-991 () (message \"M-991j\"))
  (defun eejump-992 () (message \"M-992j\"))

an \"eejump block\".

There are two sample eejump blocks in eejump.el, for the prefixes
\"\" and \"5\", starting at:

  (find-eev \"eejump.el\" \"eejump-*\")
  (find-eev \"eejump.el\" \"eejump-5*\")

You should probably copy them to your .emacs, and then start
modifying them.




Making an `eejump-nn*' work
===========================
If you execute a line like 

  (defun eejump-9* () (find-efunction 'eejump-9*))

then Emacs will only record that `eejump-9*' has been defined in
this buffer - and thus will be able to jump to its definition
when you type something like `M-987j' - if two conditions are
met:

  a) the defun is executed with `M-x eval-region', `M-x
     eval-buffer', or some variant of `load' or `require' (`M-e'
     will not do!),

  b) the buffer with the definition is associated to a file; see
     these two pages of the Emacs manuals

       (find-enode \"Buffers\" \"visiting\")
       (find-elnode \"Buffer File Name\")

    if that concept is not totally familiar to you.

So, as an experiment, copy the block with six defuns and four
tests above to some buffer associated to a file, mark it, and
execute it with `M-x eval-region'. Now the tests should work -
and key sequences like `M-987j' should also work, and should jump
to the right places. See also:

  (find-elnode \"Where Defined\")



Producing `eejump-nnn's and `eejump-nnn*'s
==========================================
Look again to the block of six \"defun\"s above. Now type `M-J'
on each of the six lines below:

  9
  91 (message \"M-91j\")
  92 (message \"M-92j\")
  99
  991 (message \"M-991j\")
  992 (message \"M-992j\")

you will notice that you've just generated a block of defuns like
the one in the previous section! `M-J' works like this: it tries
to split the current line into \"words\" separated by whitespace,
but producing a maximum of two \"words\" (the 2nd, 3rd, etc
\"words\" as treated as a single \"word\"); if the second word is
empty, then `M-J' produces a definition for an `eejump-nnn*'; if
it is not empty, then `M-J' produces a definition for an
`eejump-nnn', treating the second \"word\" as a sexp.

Note that `M-J' is quite dumb - it doesn't check if the first
\"word\" is a number, nor if the second is a sexp. Use it with
care! Try using `M-J' on the \"a b ...\" lines below - you will
get useless definitons.

  a  b  c  d
  a  b  c
  a  b
  a




Permanent and temporary
=======================
If you create a block like the block of six defuns above in your
.emacs file then you'll be attributing a \"permanent\" meaning to
`M-91j', ..., `M-992j', and if you create it in a file that is
not evaluated in every Emacs session (and execute it, of course),
then you'll be attributing just a \"temporary\" meaning to
`M-91j', ..., `M-992j'.




# Local Variables:
# coding:           raw-text-unix
# ee-anchor-format: \"%s\"
# End:
" rest)))

;; (find-eejump-intro)




;;;            _  __       _ _ _        
;;;  _ __   __| |/ _|     | (_) | _____ 
;;; | '_ \ / _` | |_ _____| | | |/ / _ \
;;; | |_) | (_| |  _|_____| | |   <  __/
;;; | .__/ \__,_|_|       |_|_|_|\_\___|
;;; |_|                                 
;;
;; \253find-pdf-like-intro\273  (to ".find-pdf-like-intro")

(defun find-pdf-like-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-pdf-like-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-pdf-like-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-pdf-like-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



PDF-like documents
==================
Let's introduce a bit of (improvised!) terminology: we will say
that a document is \"PDF-like\" when it is in a format like PDF,
PostScript, DVI or DJVU - i.e., divided into pages. Emacs has a
standard mode for viewing PDF-like documents,

  (find-enode \"Document View\")

but we will see a more eev-like way of pointing to pages of
PDF-like documents.



Two test documents
==================
The following script creates two PDF-like documents - a DVI and a
PDF - that we will use in the examples below.

* (eepitch-shell)
* (eepitch-kill)
* (eepitch-shell)
cd /tmp/
cat > /tmp/foo.tex <<'%%%'
\\documentclass[12pt,oneside]{book}
\\begin{document}
\\Huge
\\frontmatter
a \\newpage
b \\newpage
c \\newpage
\\mainmatter
\\chapter{One}
\\newpage foo
\\chapter{Two}
\\end{document}
%%%
   latex foo.tex
pdflatex foo.tex

In these two documents the page _names_ do not correspond to the
page _numbers_; the pages are named \"i\", \"ii\", \"iii\",
\"1\", \"2\", \"3\", but their numbers are 1, 2, 3, 4, 5, 6.
In a table:

  number  name  contents
  ----------------------
    1        i      a
    2       ii      b
    3      iii      c
    4        1      Chapter 1 - One
    5        2      foo
    6        3      Chapter 3 - Two



Using external viewers
======================
The following sexps can be used to open the documents
\"/tmp/foo.dvi\" and \"/tmp/foo.pdf\" on the first page of
Chapter 1 - i.e., the page whose number is 4, and whose \"name\"
is 1 - using two of my favorite viewers, xdvi and xpdf, and a
low-level function, `find-bgprocess':

  (find-bgprocess '(\"xdvi\" \"+4\" \"/tmp/foo.dvi\"))
  (find-bgprocess '(\"xpdf\" \"/tmp/foo.pdf\" \"4\"))

Alternatively, we can invoke these viewers like this,

  (find-xdvi-page \"/tmp/foo.dvi\" 4)
  (find-xpdf-page \"/tmp/foo.pdf\" 4)

or, as they ignore extra arguments, like this,

  (find-xdvi-page \"/tmp/foo.dvi\" (+ 3 1) \"Chapter 1\")
  (find-xpdf-page \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")

where the `(+ 3 1)' and the \"Chapter 1\" are just to make these
links more readable by humans. The `3' is what we will call the
\"offset\" of the document: a quantity that can be added to page
\"names\" (outside the \"front matter\" of the document) to
convert them to page \"numbers\".

Let's introduce more terminology. Programs like xdvi and xpdf are
\"external viewers for PDF-like documents\", but that's too long,
so let's shorten this to \"external PDF-like viewers\", or
\"external viewers\", or just \"viewers\"; `find-xdvi-page',
`find-xpdf-page' and similar functions are \"medium-level viewing
words\".



The high-level way
==================
File names of PDF-like documents are often very long - especially
for documents that we have \"psne\"-ed from the web. To avoid
having to keep copies of these file names everywhere we can use
some `code-c-d'-like words - like this:

  (code-xdvi \"fd\" \"/tmp/foo.dvi\")
  (find-fdpage (+ 3 1) \"Chapter 1\")

Each medium-level viewing word has an associated code-c-d-like
word - that creates \"high-level viewing words\". In the example
above, we used `code-xdvi' to create the high-level viewing word
`find-fdpage', that invokes `find-xdvi-page'.

Note that the \"fd\" in `find-fdpage' stands for not only the
filename - \"/tmp/foo.dvi\" - but also for the medium-level word
to be used - `find-xdvi-page'.



Default external viewers
========================
We saw that for each of the supported formats of PDF-like
documents - DVI, PostScript, PDF, DJVU - there are medium-level
and high-level viewing words that use specific programs; for
example, for \"xpdf\" we have `find-xpdf-page' and `code-xpdf',
and for \"evince\" we have `find-evince-page' and `code-evince'.
But for each of the formats we also have words that use the
current default viewer for that format:

  Format       Medium-level     High-level
  ----------------------------------------
  DVI          find-dvi-page    code-dvi
  PostScript   find-ps-page     code-ps
  PDF          find-pdf-page    code-pdf
  DJVU         find-djvu-page   code-djvu

The four `find-<formatname>-page' words above are aliases to
`find-<viewername>-page' names, and to change a default viewer
you should use a `defalias' on the `find-', like these:

  (defalias 'find-pdf-page 'find-evince-page)
  (defalias 'find-pdf-page 'find-xdpf-page)

After running a `defalias' like the above all the high-level
viewing words defined using `code-pdf' will automatically switch
to the new default viewer (becuase words defined with `code-pdf'
call `find-pdf-page').



PDF-like documents as text
==========================
Some PDF-like documents can be converted to text - usually uglily
and imprecisely, but the result is often useful anyway - by
external programs like \"pdftotext\" and \"djvutxt\". The
medium-level sexps below invoke these programs on the given
filenames and displays their output in an Emacs buffer:

  (find-pdftotext-text \"/tmp/foo.pdf\")
  (find-djvutxt-text   \"/tmp/foo.djvu\")

We can also use the correspondent generic medium-level words,
that are aliases to the default converters:

  (find-pdf-text  \"/tmp/foo.pdf\")
  (find-djvu-text \"/tmp/foo.djvu\")

As the output of these converters is also divided into pages -
with formfeeds as separators - it is easy to jump to specific
pages in the output, and if the first argument after the file
name is a number it is interpreted as a page number; string
arguments coming after that are interpreted as strings to be
search (forward) for. So these links make sense:

  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")

and note that the following pair of links make sense too - the
first one calls an external viewer, the second one opens the
conversion to text:

  (find-pdf-page \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")

Note that they both point to the same page... The argument
\"Chapter 1\" is ignored in the first link, but when a pair of
links like that appear on consecutive lines it is clear for human
readers that they are both links to the same place, only rendered
in different ways. Note that the passage from this:

  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))

to this:

  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")

is a special case of \"refining hyperlinks\", an idea that we saw
in:

  (find-eval-intro \"Refining hyperlinks\")

and this can be done




Producing and refining hyperlinks to pages
==========================================
The idea of

  (find-eval-intro \"Producing and refining hyperlinks\")



Etc
===

  (find-efunction 'find-djvutotext)
  (find-efunction 'find-pdftotext)

  (defalias 'find-pdftotext-text 'find-pdftotext)
  (defalias 'find-pdf-text 'find-pdftotext-text)
  (defalias 'find-pdf-page 'find-xpdf-page)
" rest)))

;; (find-pdf-like-intro)




;;;                  _ _         __      _     _            
;;;   __ _ _   _  __| (_) ___   / /_   _(_) __| | ___  ___  
;;;  / _` | | | |/ _` | |/ _ \ / /\ \ / / |/ _` |/ _ \/ _ \ 
;;; | (_| | |_| | (_| | | (_) / /  \ V /| | (_| |  __/ (_) |
;;;  \__,_|\__,_|\__,_|_|\___/_/    \_/ |_|\__,_|\___|\___/ 
;;;                                                         
;; \253find-audiovideo-intro\273 (to ".find-audiovideo-intro")
;; (find-intro-links "audiovideo")

(defun find-audiovideo-intro (&rest pos-spec-list) (interactive)
  (let ((ee-buffer-name "*(find-audiovideo-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-audiovideo-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-audiovideo-intro\")
More intros:  (find-eev-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



NOT YET WRITTEN, sorry!
But you can see examples of how to put this to work here:

  (find-videos-intro)

The source code for the audio/video functions may be (somewhat)
readable:

  (find-eev \"eev-audiovideo.el\")



Time offsets
============
Links to audio and video files are similar to links to pdf-like
documents, but instead of page numbers we use \"time offsets\" to
refer to positions. Time offsets are strings like 1:23, 12:34, or
1:23:45.



`time-from-bol'
===============
The \"time-from-bol\" is the first time offset from the beginning
of line, in the current line. Some lines have a time-from-bol,
the others don't. Some interesting hacks operate on the
time-from-bol - some reopen the last opened audio or video file
in the position specified by the time-from-bol, some others
adjust the time-from-bol with keys that are easy to type.



The audio/video adjust mode
===========================
One interesting hack (in a somewhat preliminary state) is the
\"eev audio/video adjust mode\", a minor mode that when on
actives some keybindings that operate on the time-from-bol...

  (find-eminorkeymapdescr 'eev-avadj-mode)

  (eev-avadj-mode 1)

  With eev-adj-mode turned on, try M-- and M-+ (or M-=) with
  point on the line below:
  ;; 9:23 comment
 
  (eev-avadj-mode 0)

See the source:

  (find-eev \"eev-audiovideo.el\")
  (find-eev \"eev-audiovideo.el\" \"eev-avadj-mode\")


" pos-spec-list)))

;; (find-audiovideo-intro)





;;;                  _ _   _          _           _               
;;;  _ __ ___  _   _| | |_(_)_      _(_)_ __   __| | _____      __
;;; | '_ ` _ \| | | | | __| \ \ /\ / / | '_ \ / _` |/ _ \ \ /\ / /
;;; | | | | | | |_| | | |_| |\ V  V /| | | | | (_| | (_) \ V  V / 
;;; |_| |_| |_|\__,_|_|\__|_| \_/\_/ |_|_| |_|\__,_|\___/ \_/\_/  
;;;                                                               
;; \253find-multiwindow-intro\273 (to ".find-multiwindow-intro")
;; (find-intro-links "multiwindow")

(defun find-multiwindow-intro (&rest pos-spec-list) (interactive)
  (let ((ee-buffer-name "*(find-multiwindow-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-multiwindow-intro)
Source code:  (find-efunction 'find-multiwindow-intro)
More intros:  (find-eev-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.




Introduction
============
In many situations - for example, when we want to script a
debugger, or to test programs that have to talk to one another,
or to control several external machines simultaneously - the
default window setup for eepitch, which is this,

   ____________________
  |          |         |
  |          |         |
  |  script  |  shell  |
  |          |         |
  |          |         |
  |__________|_________|

is not enough; other setups, like these,

   ______________________
  |          |           |        _________________________ 
  |          |  shell A  |       |            |            |
  |          |___________|       |   script   |     GDB    |
  |  script  |           |       |            |            |
  |          |  shell B  |       |____________|____________|
  |          |___________|       |            |            |
  |          |           |       |   program  |   program  |
  |          |  shell C  |       |     I/O    |    source  |
  |__________|___________|       |____________|____________|

may be necessary. Eev comes with a few _low-level_ tools for
creating these setups; they are not very smart, but they should
be easy to understand and to tweak - and I have the impression
that ideas for good high-level tools will only come from
practical experimentation.



`find-wset'
===========
Suppose that we are in a buffer A, and we want to create a window
configuration with A at the left, and with the buffers B and C
stacked on one another at the right. That is:

   ___________           ___________ 
  |           |         |     |     |
  |           |         |     |  B  |
  |     A     |   -->   |  A  |_____|
  |           |         |     |     |
  |           |         |     |  C  |
  |___________|         |_____|_____|

To do that from the keyboard we could type this:

  C-x 3   C-x o   C-x b B RET   C-x 2   C-x o   C-x b C RET

You can try that here (the initial `C-x 1' is an extra, for
convenience):

  (eek \"C-x 1         ;; delete-other-windows
        C-x 3         ;; split-window-horizontally (left/right)
        C-x o         ;; other-window              (-> right)
        C-x b B RET   ;; switch to the buffer `B'
        C-x 2         ;; split-window-vertically   (upper/lower)
        C-x o         ;; other-window              (-> lower right)
        C-x b C RET   ;; switch to the buffer `C'
        \")

We can write something equivalent to that as a `progn', in a way
that makes it easy to replace later the `C-x b B RET' and the
`C-x b C RET' by arbitrary sexp hyperlinks. We get:

  (progn (eek \"C-x 1 C-x 3 C-x o\")
         (find-ebuffer \"B\")
         (eek \"C-x 2 C-x o\")
         (find-ebuffer \"C\")
         (eek \"C-x o\")
         )

When I started to rewrite my window configurations into that form
I realized that the `eek's were being used in a very limited way
- they only invoked a very small repertoire of window commands,
all of them starting with `C-x'. So maybe I should have an
interpreter for a simple language of window commands and sexp
hyperlinks, in the which window setup above could be expressed
like this:

  `(\"13o\"
    (find-ebuffer \"B\")
    \"2o\"
    (find-ebuffer \"C\")
    \"o\"
   )

`find-wset' supports something like that, but with all the window
command strings collapsed into a single one, with \"_\"s meaning
\"execute the next sexp from the sexp list\". The corresponding
call to `find-wset' is:

  (find-wset \"13o_2o_o\" '(find-ebuffer \"B\") '(find-ebuffer \"C\"))

For the full list of supported window command characters - and
how to extend it - see the source:

  (find-eev \"eev-multiwindow.el\")




Several eepitch targets
=======================
If we try to build a window setup like this one, with two eepitch
targets, with just `find-wset', we will run into problems -

   ________________________
  |          |             |
  |          |   *shell*   |
  |  script  |_____________|
  |          |             |
  |          |  *shell 2*  |
  |__________|_____________|

because `(eepitch-shell)' and `(eepitch-shell2)' try to create a
shell buffer and put it in an _another_ window, not the one we
are in... one solution is to call the `(eepitch-*)' sexps inside
an `ee-here', like this:

  (ee-here '(eepitch-shell))
  (ee-here '(eepitch-shell2))

where `ee-here' is a hack that runs a sexp in a way that
preserves the current window configuration, then switches the
buffer in the current selected window to the current eepitch
target. We can use this to create the window setting above,

  (find-wset \"13o2_o_o\"
             ' (ee-here '(eepitch-shell))
             ' (ee-here '(eepitch-shell2))
             )

This is too long - and would make a very bad one-liner - but a
workaround is easy:




Adding support for new characters in `find-wset'
================================================
The standard characters supported by `find-wset' are these:

  char  action                       key
  ---- ---------------------------- ---------
  `1'  `delete-other-windows'       (C-x C-1)
  `2'  `split-window-vertically'    (C-x C-2)
  `3'  `split-window-horizontally'  (C-x C-3)
  `s'  `split-window-sensibly'
  `o'  `other-window'               (C-x o)
  `+'  `balance-windows'            (C-x +)
  `_'  execute the next sexp

but the action of each one is defined in a different function,
and to add support for a new character, say, `=', we just need to
define a function with the right name - in this case,
`find-wset-='.

The source code is simple enough, so take a look:

  (find-eev \"eev-multiwindow.el\" \"find-wset-_\")
  (find-eev \"eev-multiwindow.el\" \"find-wset-=\")
  (find-eev \"eev-multiwindow.el\" \"find-wset-!\")

Note that `find-wset-!' restarts an eepitch target, while
`find-wset-=' will reuse an eepitch target if its buffer already
exists.




Eepitch to two targets
======================
Examples:

* (defun eepitch2  (s1 s2) (find-wset \"13o2=o=o\" s1 s2))
* (defun eepitch2! (s1 s2) (find-wset \"13o2!o!o\" s1 s2))
* (eepitch2! '(eepitch-shell) '(eepitch-shell2))

See: (find-prepared-intro)

  [Example at find-prepared-intro]




Executing key sequences at other windows
========================================
It is possible to use multi-window settings, together with the
trick that `<f8>' on a red star line executes it as Lisp and
moves down, to create tutorials for Emacs modes. An example:



A tutorial for Info mode
========================
Here's a mini-tutorial for Info mode, demonstrating how to
navigate in Info using the usual movement keys, plus TAB,
<backtab>, RET, l (last), u (up), n (next), p (prev), q (quit),
C-h i, and the digits 1-9. Note that the display in Info mode is
like this:

   ____________________________________________
  |Next: Nonincremental Search,  Up: Search    | <- next/prev/up
  | (emacs)Top > Search > Incremental Search   | <- breadcrumbs
  |                                            |
  | 19.1 Incremental Search                    | <- section number /
  |                                            |    node name (long)
  |  (...)                                     |
  |                                            |
  |--:%%-  *info* (emacs) Incremental Search   |
  |____________________________________________|

Here:

** Define some hacks
* (defun ow (n) (other-window n))
* (defun eeoe (code) (ow 1) (prog1 (eval code) (ow -1)))
* (defun eeok (keystr) (eeoe `(eek ,keystr)))
*
** Prepare the windows
* (ee-kill-buffer \"*info*\")
* (find-wset \"1so_o\" '(find-enode \"Search\"))
*
** The arrows (and other movent keys) work as expected.
** Watch the cursor in the Info window...
* (eeok \"3*<down>\")
* (eeok \"10*<right>\")
*
** TAB and <backtab> move to the next and to the previous link.
** Note that they consider all the links in a page, not only
** the ones in menus - including the breadcrumb links at the top.
* (eeok \"TAB       ;; Info-next-reference\")
* (eeok \"TAB       ;; Info-next-reference\")
* (eeok \"TAB       ;; Info-next-reference\")
* (eeok \"TAB       ;; Info-next-reference\")
* (eeok \"TAB       ;; Info-next-reference\")
* (eeok \"<backtab> ;; Info-prev-reference\")
* (eeok \"<backtab> ;; Info-prev-reference\")
* (eeok \"<backtab> ;; Info-prev-reference\")
* (eeok \"<backtab> ;; Info-prev-reference\")
*
** RET follows a link, l (last) goes back.
** Watch the section number: 19 -> 32.3.6 -> 19.
* (eeok \"RET       ;; Info-follow-nearest-node\")
* (eeok \"l         ;; Info-history-back\")
*
** The digits 1-9 can be used to go straight to subsections.
** For example, a `4' would follow the 4th _menu_ link -
** ignoring the non-menu links.
** Watch the section number: 19 -> 19.1 -> 19.1.1.
* (eeok \"1         ;; Info-nth-menu-item\")
* (eeok \"1         ;; Info-nth-menu-item\")
*
** The keys `u', `n', `p' (up, next, and prev) move through the
** tree structure. Watch the section number:
** 19.1.1 -u-> 19.1 -u-> 19 -n-> 20 -n-> 21 -p-> 20 -p-> 19
* (eeok \"u         ;; Info-up\")
* (eeok \"u         ;; Info-up\")
* (eeok \"n         ;; Info-next\")
* (eeok \"n         ;; Info-next\")
* (eeok \"p         ;; Info-prev\")
* (eeok \"p         ;; Info-prev\")
*
** `q' leaves Info mode - more precisely, it buries the info buffer.
** `C-h i' goes back to the Info buffer (or restarts info). 
* (eeok \"q         ;; Info-exit\")
* (eeok \"C-h i     ;; info\")

" pos-spec-list)))

;; (find-multiwindow-intro)



;;;           _          
;;;  _ __ ___(_)_ __ ___ 
;;; | '__/ __| | '__/ __|
;;; | | | (__| | | | (__ 
;;; |_|  \___|_|_|  \___|
;;;                      
;; \253find-rcirc-intro\273 (to ".find-rcirc-intro")
;; (find-intro-links "rcirc")

(defun find-rcirc-intro (&rest pos-spec-list) (interactive)
  (let ((ee-buffer-name "*(find-rcirc-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-rcirc-intro)
Source code:  (find-efunction 'find-rcirc-intro)
More intros:  (find-eev-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.

Not yet!
========
See: (find-eev \"eepitch.el\" \"eepitch-freenode\")
" pos-spec-list)))

;; (find-rcirc-intro)





;;;  _                       _       _            
;;; | |_ ___ _ __ ___  _ __ | | __ _| |_ ___  ___ 
;;; | __/ _ \ '_ ` _ \| '_ \| |/ _` | __/ _ \/ __|
;;; | ||  __/ | | | | | |_) | | (_| | ||  __/\__ \
;;;  \__\___|_| |_| |_| .__/|_|\__,_|\__\___||___/
;;;                   |_|                         
;;
;; \253find-templates-intro\273 (to ".find-templates-intro")
;; (find-intro-links "templates")

(defun find-templates-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-templates-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-templates-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-templates-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.


`ee-template0'
==============
\(find-code-c-d-intro \"The innards: templates\")

The innards: templates
======================
Several functions in eev besides `code-c-d' work by replacing
some substrings in \"templates\"; they all involve calls to
either the function `ee-template0', which is simpler, or to
`ee-template', which is much more complex.

The function `ee-template0' receives a single argument - a
string, in which each substring surrounded by `{...}'s is to be
replaced, and replaces each `{...}' by the result of evaluating
the `...' in it. For example:

  (ee-template0 \"a{(+ 2 3)}b\")
            --> \"a5b\"

Usually the contents of each `{...}' is the name of a variable,
and when the result of evaluating a `{...}' is a string the
replacement does not get `\"\"'s.

The function `ee-template' receives two arguments, a list and a
template string, and the list describes which `{...}' are to be
replaced in the template string, and by what. For example, here,

  (let ((a \"AA\")
        (b \"BB\"))
    (ee-template '(a
                   b
                   (c \"CC\"))
      \"_{a}_{b}_{c}_{d}_\"))

      --> \"_AA_BB_CC_{d}_\"

the \"{d}\" is not replaced. Note that the list (a b (c \"CC\"))
contains some variables - which get replaced by their values -
and a pair, that specifies explicitly that every \"{c}\" should
be replaced by \"CC\".




Templated buffers
=================
Introduction
Conventions:
  the first line regenerates the buffer,
  buffer names with \"**\"s,
  (find-evariable 'ee-buffer-name)
  code

`find-elinks'
=============
Variant: `find-elinks-elisp'

`find-e*-links'
===============
\(find-eev \"eev-elinks.el\")

`find-*-intro'
==============

`eewrap-*'
==========

Experiments
===========
\(find-efunction 'find-youtubedl-links)
\(find-efunction 'ee-hyperlinks-prefix)
\(find-efunction 'find-newhost-links)
\(find-efunction 'find-eface-links)
  Note that there is no undo.
" rest)))

;; (find-templates-intro)



;; \253find-anchors-intro\273 (to ".find-anchors-intro")
;; (find-intro-links "anchors")

(defun find-anchors-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-anchors-intro)*"))
    (apply 'find-estring-lv "\
\(Re)generate: (find-anchors-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-anchors-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



Introduction: `ee-anchor-format' and `to'
=========================================
A hyperlink like

  (to \"foo\")

jumps to the first occurrence of the string \"\253foo\273\" in the
current buffer. The way to convert from \"foo\" to \"\253foo\273\" is
controlled by the variable `ee-anchor-format', and the sexp
`(to \"foo\")' is roughly equivalent the third sexp below:

                            ee-anchor-format
                    (format ee-anchor-format \"foo\")
  (ee-goto-position (format ee-anchor-format \"foo\"))

We will call strings in `\253\273's _anchors_, and we will say
that `(to \"foo\")' jumps \"to the anchor `foo'\".

Anchors can be used to create sections and indexes, as we shall
see soon - but due to some old design decisions that I was never
able to find good alternatives for, this tutorial needs to start
with a BIG WARNING.



WARNING: some glyphs need raw-text-unix
=======================================
The best way to make anchors stand out is to use colored glyphs
for them - just like we made `^O's appear as red star glyphs for
eepitch, as described here:

  (find-eepitch-intro \"\\nRed stars\\n\")

For historical reasons, the glyphs for `\253' and `\273' defined in

  (find-eev \"eev-anchors.el\")

use the characters 171 and 187; as far as I know, these
characters are only \"safe\" - in the sense that Emacs will not
try to convert them to anything else - in unibyte buffers. The
best way to make sure that anchors with `\253\273's will work in a
certain file is to put a \"Local Variables:\" section at the end
of it, as has been done in this buffer - and use that to set both
the file coding to raw-text-unix and the value of
`ee-anchor-format' to \"\253%s\273\".

Note that if you change a \"Local Variables:\" section by hand
you will probably have to either reload the file or run `M-x
normal-mode' to make the new settings take effect.



Indexes
=======
In a situation like this,

  \253one\273   (to \"two\")
  \253two\273   (to \"one\")

we have two anchors, and typing `M-e' at the line with the anchor
\"one\" takes us to the line with the anchor \"two\", and typing
`M-e' at the line with the anchor \"two\" takes us to the line
with the anchor \"one\". In a situation like this we say that the
anchors \"one\" and \"two\" _point to one another_.

In a case like this,

  \253.three\273   (to \"three\")
   \253three\273  (to \".three\")

where the names of two anchors pointing to one another differ by
an initial dot, we will say that the anchor \".three\" is the
\"index anchor\", and the anchor \"three\" is the \"section
anchor\"; and one way to create an index for a file is to group
all the index anchors together. For an example, see:

  (find-eev \"eev-intro.el\" \".find-eev-intro\")




Creating index/section anchor pairs
===================================
Use `M-A' (`eewrap-anchor'). Note that this has been briefly
mentioned here:

  (find-wrap-intro \"All wrapping functions\")

It will convert a line with a syntax like

  comment-prefix <anchor-name>

into:

  comment-prefix \253.anchor-name\273 (to \"anchor-name\")
  comment-prefix \253anchor-name\273 (to \".anchor-name\")

where comment-prefix is any string and anchor-name is a string
without `<>'s. Note that the `<>'s, which are easy to type, are
converted into `\253\273's, which are harder.



find-anchor
===========
\(find-eev \"eev-anchors.el\")
\(find-eev \"eev-anchors.el\" \"find-anchor\")


code-c-d and :anchor
====================
\(find-eev \"eev-code.el\" \"ee-code-c-d-:anchor\")


L
# Local Variables:
# coding:           raw-text-unix
# ee-anchor-format: \"\253%s\273\"
# End:
" rest)))

;; (find-anchors-intro)




;;;                                          _ 
;;;  _ __  _ __ ___ _ __   __ _ _ __ ___  __| |
;;; | '_ \| '__/ _ \ '_ \ / _` | '__/ _ \/ _` |
;;; | |_) | | |  __/ |_) | (_| | | |  __/ (_| |
;;; | .__/|_|  \___| .__/ \__,_|_|  \___|\__,_|
;;; |_|            |_|                         
;;
;; \253find-prepared-intro\273  (to ".find-prepared-intro")
;; (find-eev "eev-bounded.el")

(defun find-prepared-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-prepared-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-prepared-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-prepared-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.


Prepared shells
===============
Long before eepitch had been created, eev had another way -
technically much simpler, but clumsier from the user's point of
view - to send commands to external shells (and other shell-like
programs; but to simplify we will say just \"shells\"). Here is
an overview of how it worked: if the user marked the three lines
below,

  rm -Rv /tmp/foo
  mkdir  /tmp/foo/
  cd     /tmp/foo/

and typed `M-x eev' (which stood for \"Emacs-execute-verbosely\")
then Emacs would save those three lines into a temporary script
file, usually \"~/.eev/ee.sh\"; that would be just half of
\"sending commands to an external shell\", and for the other half
the user would have to go to an external prepared shell - that
would usually be running in an xterm, and totally independent
from Emacs - and type \"ee\" there. The shell had to be
\"prepared\" in the sense that it would understand the \"ee\"
command correctly, as meaning: \"execute the commands in the
temporary script as if the user were typing them at the prompt\".
Technically, that would mean that instead of calling
\"~/.eev/ee.sh\" as a shell script its contents would be
\"sourced\" - i.e., executed in the current shell context - and
in verbose mode.

Usually we would prepare bash by patching the file ~/.bashrc and
putting the definition for \"ee\" there. We will discuss how to
do that later; now let's test a simple environment in which `M-x
eev' and \"ee\" work. First execute these two sexps:

  (make-directory \"~/.eev/\" 'force)
  (eev \"rm -Rv /tmp/foo\\nmkdir  /tmp/foo/\\ncd     /tmp/foo/\\n\")

Now run this script

* (eepitch-bash)
* (eepitch-kill)
* (eepitch-bash)
export PS1='$PWD# '
function ee () { set -v; . ~/.eev/ee.sh; set +v; }



`ee'
====
\[Explain how several interpreters can be programmed to accept
an `ee' command to execute temporary scripts\]

  http://angg.twu.net/eev-article.html#making-progs-receive-cmds

  (find-eev \"eev-langs.el\")
  (find-eev \"eev-bounded.el\")
  (find-eev \"eev-rctool\")




An `ee' for Python
==================
Here is a simple way to make Python execute commands saved in a
temporary script when the user types `ee()' (note that it is not
just `ee' - the `()' is needed). We will show first an example in
which the temporary script is prepared by running \"cat\" from a
shell - then we will explain a more user-friendly way to save a
region from the current buffer as the temporary script.

Note that the demo below uses `find-wset', which is an
advanced (i.e., hackish) feature explained here:

  (find-multiwindow-intro)


* (ee-kill-buffer \"*shell*\")
* (ee-kill-buffer \"*python*\")
* (find-wset \"13o2=o=o\" '(eepitch-shell) '(eepitch-python))
* (eepitch-python)
import os
def ee():
  execfile(os.getenv(\"HOME\")+\"/.eev/ee.py\", globals())

* (eepitch-shell)
cat > ~/.eev/ee.py <<'%%%'
print(1+2)
%%%

* (eepitch-python)
ee()

* (eepitch-shell)
cat > ~/.eev/ee.py <<'%%%'
def foo (x):
    return x*x

print foo(5)
%%%

* (eepitch-python)
ee()
print(foo(6))



`eepy'
======
The function `eev' receives three parameters, called `s', `e', and
`altfile'; `e' and `altfile' are optional, and `s' should be either a
string or a number. When `s' is a string, then the commands to be
saved into the temporary script are taken from `s'; the numeric case
will be discussed later.

A call to

  (eev \"print(1+2)\" nil \"~/.eev/ee.py\")

writes \"print(1+2)\" (with an added trailing newline, but that's
a technical detail) into the \"alternative file\"
\"~/.eev/ee.py\" - the default would be \"~/.eev/ee.sh\". We can
that to simplify our demo a bit:

* (eek \"C-x 1\")
* (eepitch-python)
* (eepitch-kill)
* (eepitch-python)
import os
def ee():
  execfile(os.getenv(\"HOME\")+\"/.eev/ee.py\", globals())

* (eev \"print(1+2)\" nil \"~/.eev/ee.py\")
ee()
* (eev \"def foo (x):\\n    return x*x\\n\\nprint foo(5)\" nil \"~/.eev/ee.py\")
ee()
print(foo(6))


  In the example below the first line defines a `eepy' in a
  simplistic way:

* (defun eepy (s &optional e) (eev s e \"~/.eev/ee.py\"))
* (eek \"C-x 1\")
* (eepitch-python)
* (eepitch-kill)
* (eepitch-python)
import os
def ee():
  execfile(os.getenv(\"HOME\")+\"/.eev/ee.py\", globals())

* (eepy \"print(1+2)\")
ee()
* (eepy \"def foo (x):\\n    return x*x\\n\\nprint foo(5)\")
ee()
print(foo(6))




`M-x eepy' and `M-x eev'
========================
Now let's define a more realistic `eepy' - one that can also be
called interactively. We want `M-x eepy' to save the current
_region_ into the temporary script; `eepy' has to be a _command_,
and we will use the argument \"r\" to its `interactive' clause,
to make the function `eepy' receive two numbers - the start and
the end of the region - and it will pass these two numbers to
`eev'.

  (defun eepy (s &optional e)
  \"Save the region between S and E (or the string S) into ~/.eev/ee.py .\"
    (interactive \"r\")
    (eev s e \"~/.eev/ee.py\"))

When the first argument, `s', to `eev', is a number, not a
string, then `eev' expects the second argument, `e', to also be a
number - and then `s' and `e' are considered as the extremities
of a region of text in the current buffer. This idea - that the
first argument can be either a string or a number - comes from:

  (find-efunctiondescr 'write-region \"If START is a string\")

But try these:

  (ee-se-to-string         \"foo\" nil)
  (ee-se-to-string-with-nl \"foo\" nil)
  (ee-se-to-string         \"foo\\n\" nil)
  (ee-se-to-string-with-nl \"foo\\n\" nil)
  (ee-se-to-string         (- (point) 5) (point))
  (ee-se-to-string-with-nl (- (point) 5) (point))
  (ee-se-to-string         (point) (- (point) 5))
  (ee-se-to-string-with-nl (point) (- (point) 5))




\[Garbage:\]

  (find-elnode \"Defining Commands\")
  (find-defun-intro \"\\ninteractive\\n\")
  (find-efunction 'eev)

" rest)))

;; (find-prepared-intro)

;; (find-bashnode "Bourne Shell Builtins" "current shell context")




;;;  _                           _          _ 
;;; | |__   ___  _   _ _ __   __| | ___  __| |
;;; | '_ \ / _ \| | | | '_ \ / _` |/ _ \/ _` |
;;; | |_) | (_) | |_| | | | | (_| |  __/ (_| |
;;; |_.__/ \___/ \__,_|_| |_|\__,_|\___|\__,_|
;;;                                           
;; \253find-bounded-intro\273 (to ".find-bounded-intro")
;; (find-intro-links "bounded")
(defun find-bounded-intro (&rest pos-spec-list) (interactive)
  (let ((ee-buffer-name "*(find-bounded-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-bounded-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-bounded-intro\")
More intros:  (find-eev-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.


Note that you need to understand the concept of \"prepared
shells\" quite well to be able to use this... see:

  (find-prepared-intro)


Bounded regions
===============
Bad news: I've been using this feature very little, and I have
not adapted the old, crappy docs to \"intro\" format yet... =\\

\(find-eev \"eev-bounded.el\")
\(find-eev \"eev-langs.el\")
\(find-TH \"eev-article.blogme\" \"delimited-regions\")
http://angg.twu.net/eev-article.blogme.html#delimited-regions
" pos-spec-list)))

;; (find-bounded-intro)




;;;       _                            _     
;;;   ___| |__   __ _ _ __  _ __   ___| |___ 
;;;  / __| '_ \ / _` | '_ \| '_ \ / _ \ / __|
;;; | (__| | | | (_| | | | | | | |  __/ \__ \
;;;  \___|_| |_|\__,_|_| |_|_| |_|\___|_|___/
;;;                                          
;; \253find-channels-intro\273 (to ".find-channels-intro")
;; (find-intro-links "channels")

(defun find-channels-intro (&rest pos-spec-list) (interactive)
  (let ((ee-buffer-name "*(find-channels-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-channels-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-channels-intro\")
More intros:  (find-eev-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.


Introduction
============
Before eepitch had been invented, eev had two other ways to send
commands to external shell-like programs: one that involved
saving the commands to a temporary script file, then telling the
external program to execute them - see:

  (find-prepared-intro \"\\n`ee'\\n\")

and another one, that was mostly used to control external
programs running in dedicated xterms. You can see an animation
demonstrating it - and an explanation of what each line does -
here:

  http://angg.twu.net/eev-current/anim/channels.anim.html
  http://angg.twu.net/eev-current/doc/shot-f9.png



How to set it up
================
\[To be written\]

                 ssh edrx@other.machine
  eegchannel A   ssh edrx@other.machine
  (find-prepared-intro \"\\n`ee'\\n\")
  (find-eev \"anim/channels.anim\")
" pos-spec-list)))

;; (find-channels-intro)




;;;        _     _                
;;; __   _(_) __| | ___  ___  ___ 
;;; \ \ / / |/ _` |/ _ \/ _ \/ __|
;;;  \ V /| | (_| |  __/ (_) \__ \
;;;   \_/ |_|\__,_|\___|\___/|___/
;;;                               
;; \253find-videos-intro\273 (to ".find-videos-intro")
;; (find-intro-links "videos")

(defun find-videos-intro (&rest pos-spec-list) (interactive)
  (let ((ee-buffer-name "*(find-videos-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-videos-intro)
Source code:  (find-efunction 'find-videos-intro)
More intros:  (find-eev-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



Introduction
============
I am producing a series of videos about eev - each one gets
uploaded to Youtube to make it very easy to find, but (unless I'm
mistaken) Youtube reduces the resolution of the original videos
and makes them blurry and almost unreadable. If you are
interested in watching them the best thing to do is to fetch
local copies of the hi-res .mp4 files, by following the e-scripts
below.

The idea of \"local copies\" is explained here:

  (find-psne-intro)

and you can create hyperlinks to specific positions in the local
copies of the videos using the ideas from here (oops, there isn't
much there yet...):

  (find-audiovideo-intro)





Video2: An introduction to eev2 (2012nov11)
===========================================
At youtube: http://www.youtube.com/watch?v=doeyn5MOaB8
            http://www.youtube.com/watch?v=doeyn5MOaB8&t=43m20s
Hi-res mp4: http://angg.twu.net/eev-videos/video2.mp4
            (93212837 bytes, 89MB. Duration: 52:55)

Download and watch with:

* (eepitch-shell2)
* (eepitch-kill)
* (eepitch-shell2)
mkdir -p $S/http/angg.twu.net/eev-videos/
cd       $S/http/angg.twu.net/eev-videos/
wget  -c 'http://angg.twu.net/eev-videos/video2.mp4'
echo     'http://angg.twu.net/eev-videos/video2.mp4' >> ~/.psne.log

# (find-video             \"$S/http/angg.twu.net/eev-videos/video2.mp4\")
# (code-video \"eevvideo2\" \"$S/http/angg.twu.net/eev-videos/video2.mp4\")
# (find-eevvideo2)
# (find-eevvideo2 \"43:20\" \"eepitch with two targets\")




Video2pt: Uma introducao ao eev2 (2012nov15)
=============================================
This is a version in Portuguese of the video above.
It is slightly longer than the version in English because it's
intended mostly for non-Emacsers, so some things are explained
\(much) more slowly...

At youtube: http://www.youtube.com/watch?v=yztYD9Y7Iz4
            http://www.youtube.com/watch?v=yztYD9Y7Iz4&t=1h07m40s
Hi-res mp4: http://angg.twu.net/eev-videos/video2pt.mp4
            (128228339 bytes, 122MB. Duration: 1:09:42)

Download and watch with:

* (eepitch-shell2)
* (eepitch-kill)
* (eepitch-shell2)
mkdir -p $S/http/angg.twu.net/eev-videos/
cd       $S/http/angg.twu.net/eev-videos/
wget  -c 'http://angg.twu.net/eev-videos/video2pt.mp4'
echo     'http://angg.twu.net/eev-videos/video2pt.mp4' >> ~/.psne.log

# (find-video               \"$S/http/angg.twu.net/eev-videos/video2pt.mp4\")
# (code-video \"eevvideo2pt\" \"$S/http/angg.twu.net/eev-videos/video2pt.mp4\")
# (find-eevvideo2pt)
# (find-eevvideo2pt \"1:07:40\" \"eepitch pro shell e pro Python\")





Btw: these are my first attempts at recording videos!... Let's
just not discuss whether they are embarassing or not, ok? 8-|
" pos-spec-list)))

;; (find-videos-intro)


;; A preliminary experiment (in Portuguese, and quite bad):
;;   Introducao ao eev2 (preliminar, 2012oct28)
;;   http://www.youtube.com/watch?v=1XtbM0D6leM








;;;      _       __             
;;;   __| | ___ / _|_   _ _ __  
;;;  / _` |/ _ \ |_| | | | '_ \ 
;;; | (_| |  __/  _| |_| | | | |
;;;  \__,_|\___|_|  \__,_|_| |_|
;;;                             
;; \253find-defun-intro\273  (to ".find-defun-intro")
;; (find-intro-links "defun")

(defun find-defun-intro (&rest rest) (interactive)
  (let ((ee-buffer-name "*(find-defun-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-defun-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-defun-intro\")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.


\[At present this is just a _skeleton_ for a tutorial on defining
functions in Lisp...]



Simple examples
===============

  (* 5 5)
  (* 6 6)
  (defun foo (a) (* a a))
  (foo 5)
  (foo 6)

  (+ 5 5)
  (defun foo (a) (+ a a))
  (foo 5)

  (symbol-function 'foo)
  ((lambda (a) (* a a)) 5)
  ((lambda (a) (+ a a)) 5)

See:
  (find-elnode \"Function Cells\")
  (find-elnode \"Defining Functions\")



Several arguments
=================

  (defun foo (a b) (+ (* a a) (* b b)))
  (foo 10 2)
  (foo 5)
  (defun foo () (+ (* 2 3) (* 4 5)))
  (foo 10 2)
  (foo 5)
  (foo)



progn and prog1
===============
The body of a \"defun\" works like a \"progn\".
See: (find-elnode \"Index\" \"* progn:\")

  (defun foo (a b)         (* a b))
  (defun foo (a b) (+ a b) (* a b))
  (defun foo (a b) (* a b) (+ a b))
  (defun foo (a b)         (+ a b))
  (foo 5 6)

  (progn   (* 5 6) (+ 5 6))
  (progn \"ignored\" (+ 5 6) \"result\")
  (progn)

  (prog1   (* 5 6) (+ 5 6))
  (prog1 \"result\" (+ 5 6) \"ignored\")
  (prog1)



Docstrings
==========
Note that a string in a (progn ...) does nothing - unless it is
the last BODY-FORM.

But see: (find-elnode \"Documentation\")

Try:

  (defun foo (a b) \"IGNORED\" (+ a b))
  (defun foo (a b) \"This is the description of `foo'\" (+ a b))
  (defun foo (a b) \"This is the docstring of `foo'\" (+ a b))
  (defun foo (a b) \"This function returns (* A B). Note the italics!\" (+ a b))
  (find-efunctiondescr 'foo)



&optional and &rest
===================
See: (find-elnode \"Argument List\")
Try:

  (defun foo (a &optional b c) (list \"a,b,c:\" a b c))
  (foo 11 22 33)
  (foo 11 22)
  (foo 11)
  (foo)
  (foo 11 22 33 44)

  (defun foo (a &optional b c &rest r) (list \"a,b,c,r:\" a b c r))
  (foo 11 22 33 44 55 66)
  (foo 11 22 33 44 55)
  (foo 11 22 33 44)
  (foo 11 22 33)
  (foo 11 22)
  (foo 11)
  (foo)

  (defun foo (a &rest r) (list \"a,r:\" a r))
  (foo 11 22 33 44)
  (foo 11 22 33)
  (foo 11 22)
  (foo 11)
  (foo)



A tool: my-insert
=================
See: (find-elnode \"Formatting Strings\")
Try:

  (format \"<%s>\" \"hello\")
  (format \"<%s>\" \"123\")
  (format \"<%s>\" 123)
  (format \"<%s>\" 'hello)
  (format \"<%s>\" '(+ 2 3))

  (format \"<%S>\" \"hello\")
  (format \"<%S>\" \"123\")
  (format \"<%S>\" 123)
  (format \"<%S>\" 'hello)
  (format \"<%S>\" '(+ 2 3))

Now define:

  (defun my-insert (obj)
    \"Print (insert) OBJ in the current buffer.\"
    (insert (format \"\\n  ;; \\\\--> %S\" obj)))

Try:

  (my-insert 123)
  (my-insert \"123\")
  (my-insert \"hello\")
  (my-insert 'hello)
  (my-insert '(+ 2 3))
  (my-insert nil)
  (my-insert '())
  (my-insert ())

See also:
  (find-elnode \"Character Type\")
  (find-elnode \"Basic Char Syntax\")
  (find-elnode \"Basic Char Syntax\" \"?\\\\n\")
  (find-elnode \"General Escape Syntax\")



interactive
===========
Not all Emacs functions are callable with `M-x' - only those that
are \"commands\" are callable in this way. And only \"commands\"
can be bound to keys...

See:
  (find-elnode \"Defining Functions\" \"the first two of the BODY-FORMS\")
  (find-elnode \"Defining Commands\")
  (find-elnode \"Command Overview\")

When you execute an `(interactive ...)' it does nothing - it
simply ignores its arguments (which aren't even evaluated!) and
returns nil. But just as 


  (defun my-insert (obj) (insert (format \"\\n  ;; \\\\--> %S\" obj)))

  (find-efunctiondescr 'interactive)

  (eek \"M-x foo\")
  (commandp 'foo)

  (defun foo (&rest rest) (interactive) (bar rest))
  (eek \"M-x foo\")

  (defun foo (&rest rest)                   (bar rest))
  (defun foo (&rest rest) (interactive \"P\") (bar rest))
  (eek \"            M-x foo\")
  (eek \"M-1         M-x foo\")
  (eek \"M-1 M-2 M-3 M-x foo\")
  (eek \"M-- M-2 M-3 M-x foo\")

  (defun foo (&rest rest) (interactive \"R\") (bar rest))
  (eek \"M-x foo\")


" rest)))

;; (find-defun-intro)
;; (find-defun-intro "&rest")
;; (find-defun-intro "\ninteractive\n")
;; (find-defun-intro "Defining Commands")



;;;                                      _       _             
;;;   ___ _ __ ___   __ _  ___ ___      (_)_ __ | |_ _ __ ___  
;;;  / _ \ '_ ` _ \ / _` |/ __/ __|_____| | '_ \| __| '__/ _ \ 
;;; |  __/ | | | | | (_| | (__\__ \_____| | | | | |_| | | (_) |
;;;  \___|_| |_| |_|\__,_|\___|___/     |_|_| |_|\__|_|  \___/ 
;;;                                                            
;; \253find-emacs-intro\273 (to ".find-emacs-intro")
;; (find-intro-links "emacs")

(defun find-emacs-intro (&rest pos-spec-list) (interactive)
  (let ((ee-buffer-name "*(find-emacs-intro)*"))
    (apply 'find-estring "\
\(Re)generate: (find-emacs-intro)
Source code:  (find-eev \"eev-intro.el\" \"find-emacs-intro\")
More intros:  (find-eev-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.


Basic keys (eev)
================
The most basic keys of eev are:
  M-e   - to follow a hyperlink, see: (find-eval-intro \"Elisp hyperlinks\")
  M-k   - to go back,            see: (find-eval-intro \"\\nGoing back\")
  M-j   - to jump to certain predefined places - in particular,
         `M-j' takes you to the list of jump targets in (find-eev \"eejump.el\")
        `M-2j' takes you to this help page.
        `M-5j' takes you to: (find-eev-intro)
         See: (find-eejump-intro \"Families\")


Files, Buffers, Windows, Frames, Display, etc
=============================================
Emacs can edit several files at the same time, each one
in a \"buffer\".

  (find-enode \"Files\")
  (find-enode \"Buffers\")
  (find-enode \"Windows\")
  (find-enode \"Frames\")

The display of Emacs looks like this (asciified):
                                        __ _ _
              ______________emacs_______\\/|-|X|
          /  |                                 |  \\
          |  | bla.                            |  | Emacs
Window    |  |                                 |  | calls this
managers  |  |                                 |  | a \"window\".
call      |  |                                 |  /
this a    |  |--:** foo.txt  (Fundamental) ----|  <-- Its \"modeline\".
\"window\". /  |                                 |  \\
Emacs     \\  | bla bla.                        |  | Another
calls     |  | bleh                            |  | window.
this a    |  |                                 |  |
\"frame\".  |  |                                 |  /
          |  |--:** bar.txt  (Fundamental) ----|  <-- Its modeline.
          \\  |Find file: ~/bletch.txt_ ________|  <-- The minibuffer.

The bottom line of a frame is sometimes the \"echo area\",
sometimes the \"minibuffer\". The minibuffer acts like a
window when it is active, and `C-x o' can be used to move
from it to the \"normal windows\" and back. You can also
use the mouse to move between windows.

  (find-enode \"Echo Area\")
  (find-enode \"Minibuffer\")
  (find-enode \"Other Window\")



Basic keys (Emacs)
==================
\(find-enode \"Keys\" \"key sequence\")
\(find-enode \"User Input\" \"`Control-a'\" \"usually written `C-a'\")
\(find-enode \"User Input\" \"<META> key\")
\(find-enode \"Completion\" \"<TAB>\")

C-g   keyboard-quit             (find-enode \"Quitting\" \"`C-g'\")
M-x   execute-extended-command  (find-enode \"M-x\" \"Running Commands by Name\")



Cancelling commands
===================
`C-g' can be used to interrupt incomplete key sequences -
but in a few cases you may need to switch to the minibuffer,
then issue `C-g' there. This is important (and difficult for
beginners). Let's see this in details.

In graphic terminals Emacs can display cursors for all windows -
including non-selected windows. Let's represent a non-active
cursor in our ascii diagrams as a `.', and always put a ` '
after a cursor drawn in the minibuffer.

Compare these three diagrams:

   ______________      ______________      ______________ 
  |              |    |              |    |              |
  | ab_          |    | ab.          |    | ab_          |
  |              |    |              |    |              |
  |              |    |              |    |              |
  |--:** a.txt --|    |--:** a.txt --|    |--:** a.txt --|
  |C-x 4_________|    |M-x find-fi_ _|    |M-x find-fi. _|

        (A)                 (B)                 (C)

Note that:

  A1) When the minibuffer is NOT ACTIVE, the bottom line of the
      frame is just an \"echo area\" - and it doesn't have a
      cursor (diagram A above).

  A2) Some key sequences - for example, `C-x 4' - are prefixes,
      and after typing them we are in the middle of an incomplete
      command. If we take too long to complete them, Emacs
      displays the already typed keys in the echo area - without
      a cursor.

  A3) We can use `C-g' (keyboard-quit) to interrupt an incomplete
      key sequence.

  B1) When the minibuffer is ACTIVE then it behaves as a window,
      and it has a cursor - usually active, as in diagram B
      above.

  B2) Some key sequences - for example, `M-x find-fi' - are
      incomplete commands in another sense, and after we type
      them the minibuffer will be active, with the cursor there.

  B3) We can use `C-g' (keyboard-quit) to interrupt a command
      that is expecting input in the minibuffer - but only when
      the cursor is there.

  C1) In the diagram C above we have switched to another window
      while the minibuffer was still active... THIS IS WHERE
      PEOPLE USUALLY GET LOST. As the cursor is in the top
      window, a `C-g' will not abort the `M-x' in the minibuffer,
      and issueing other key sequences that would use the
      minibuffer - like, for example, another `M-x', or `C-x C-f'
      - gives this (cryptic) error:

        Command attempted to use minibuffer while in minibuffer

      The cleanest solution is to switch to the minibuffer, with
      either `C-x o' or the mouse, and then issue a `C-g' there.



Undoing
=======
See:
C-/    -- undo    (find-enode \"Basic Undo\")
                  (find-enode \"Undo\")





M-x     -- execute-extended-command     (find-enode \"M-x\")
            more about the minibuffer:  (find-enode \"Minibuffer\")
TAB     -- for completion:              (find-enode \"Completion\")
           for indentation:             (find-enode \"Indentation\")
           in programming modes:        (find-enode \"Basic Indent\")

C-x o   -- other-window                      (find-enode \"Other Window\")
C-x 0   -- delete-window                     (find-enode \"Change Window\")
C-x 1   -- delete-other-windows (\"1 window\") (find-enode \"Change Window\")
C-x 2   -- split-window-vertically (Abv/Blw) (find-enode \"Split Window\")
C-x 3   -- split-window-horizontally   (L|R) (find-enode \"Split Window\")

                                        (find-enode \"Dired\")
C-x C-f -- find-file                    (find-enode \"Visiting\")
C-x C-s -- save-buffer                  (find-enode \"Saving\")
C-x C-c -- save-buffers-kill-emacs      (find-enode \"Saving\")
C-x b   -- switch-to-buffer             (find-enode \"Select Buffer\")
C-x k   -- kill-buffer                  (find-enode \"Kill Buffer\")

                                        (find-enode \"Mark\")
C-SPC   -- set-mark-command             (find-enode \"Setting Mark\")
C-x C-x -- exchange-point-and-mark      (find-enode \"Setting Mark\" \"C-x C-x\")
C-w     -- kill-region     (cut)        (find-enode \"Other Kill Commands\")
M-w     -- kill-ring-save  (copy)       (find-enode \"Kill Ring\")
C-y     -- yank            (paste)      (find-enode \"Kill Ring\")

C-a     -- beginning-of-line            (find-enode \"Moving Point\")
C-e     -- end-of-line                  (find-enode \"Moving Point\")
M-<     -- beginning-of-buffer          (find-enode \"Moving Point\")
M->     -- end-of-buffer                (find-enode \"Moving Point\")

M-q     -- fill-paragraph               (find-enode \"Fill Commands\")

C-s     -- isearch-forward              (find-enode \"Incremental Search\")
C-r     -- isearch-backward             (find-enode \"Incremental Search\")
M-C-s   -- isearch-forward-regexp       (find-enode \"Regexp Search\")
M-C-r   -- isearch-backward-regexp      (find-enode \"Regexp Search\")
M-%     -- query-replace                (find-enode \"Replace\")

C-x (   -- start-kbd-macro              (find-enode \"Keyboard Macros\")
C-x )   -- end-kbd-macro                (find-enode \"Keyboard Macros\")
C-x e   -- call-last-kbd-macro          (find-enode \"Keyboard Macros\")
" pos-spec-list)))

;; (find-emacs-intro)
;; (find-TH "emacs" "short-emacs-tutorial")




(provide 'eev-intro)


L
;; Local Variables:
;; coding:            raw-text-unix
;; ee-anchor-format:  "\253%s\273"
;; no-byte-compile:   t
;; End: