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



Note: this intro needs to be rewritten!
Ideally it should _complement_ the material in:
  (find-eev-quick-intro "6.3. Creating eepitch blocks: `M-T'")
  (find-eev-quick-intro "8.3. Creating index/section anchor pairs")
  (find-eev-quick-intro "8.4. Creating e-script blocks")





. 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:

  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.

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
Try this:

  (find-eaproposf "eewrap")

It will show a temporary buffer with hyperlinks like this one,

  (find-efunction 'eewrap-find-fline)

that points to the definition of `eewrap-find-fline'. Each
definition of an `eewrap-*' function is preceded by a header that
contains two lines like these ones:

  ;; Skel: (find-eewrap-links "F" "find-fline" "fname")
  ;; Test: (find-eewraptest-links "find-fline" "/tmp/foo")

The `find-eewraptest-links' goes to a temporary buffer that
contains a test like this one,

  ;; (eek "<down> <<eewrap-find-fline>>")
/tmp/foo

that demonstrates a typical use of that `eewrap-*' function.
Here are all the tests copied to a single place:

  ;; M-A:  (find-efunction 'eewrap-anchor)
  ;; Test: (find-eewraptest-links "anchor" "# <foo>")
  ;;       (eek "<down> <<eewrap-anchor>>")
  # <foo>

  ;; M-C:  (find-efunction 'eewrap-code-c-d)
  ;; Test: (find-eewraptest-links "code-c-d" "CCC /DIR/")
  ;;       (eek "<down> <<eewrap-code-c-d>>")
  CCC /DIR/

  ;; M-D:  (find-efunction 'eewrap-debian)
  ;; Test: (find-eewraptest-links "debian" "bash")
  ;;       (eek "<down> <<eewrap-debian>>")
bash

  ;; M-J:    (find-efunction 'eewrap-eejump)
  ;; Test 1: (find-eewraptest-links "eejump" "42   (find-fline \"~/TODO\")")
  ;;         (eek "<down> <<eewrap-eejump>>")
  42   (find-fline "~/TODO")

  ;; M-J:    (find-efunction 'eewrap-eejump)
  ;; Test 2: (find-eewraptest-links "eejump" "todo (find-fline \"~/TODO\")")
  ;;         (eek "<down> <<eewrap-eejump>>")
  todo (find-fline "~/TODO")

  ;; M-F:  (find-efunction 'eewrap-find-fline)
  ;; Test: (find-eewraptest-links "find-fline" "/tmp/foo")
  ;;       (eek "<down> <<eewrap-find-fline>>")
  /tmp/foo

  ;; M-M:  (find-efunction 'eewrap-man)
  ;; Test: (find-eewraptest-links "man" "1 tac")
  ;;       (eek "<down> <<eewrap-man>>")
1 tac

  ;; M-P:  (find-efunction 'eewrap-pdflike)
  ;; Test: (find-eewraptest-links "pdflike" "o /tmp/o.pdf")
  ;;       (eek "<down> <<eewrap-pdflike>>")
  o /tmp/o.pdf

  ;; M-R:  (find-efunction 'eewrap-rm/mkdir/cd)
  ;; Test: (find-eewraptest-links "rm/mkdir/cd" "/tmp/foo/")
  ;;       (eek "<down> <<eewrap-rm/mkdir/cd>>")
/tmp/foo/

  ;; M-S:  (find-efunction 'eewrap-sh)
  ;; Test: (find-eewraptest-links "sh" "dict smop")
  ;;       (eek "<down> <<eewrap-sh>>")
dict smop

  ;; M-T:  (find-efunction 'eewrap-eepitch)
  ;; Test: (find-eewraptest-links "eepitch" "shell")
  ;;       (eek "<down> <<eewrap-eepitch>>")
shell

  ;; M-V:  (find-efunction 'eewrap-audiovideo)
  ;; Test: (find-eewraptest-links "audiovideo" "ovideo /tmp/o.mp4")
  ;;       (eek "<down> <<eewrap-audiovideo>>")
  ovideo /tmp/o.mp4

  ;; M-Z:  (find-efunction 'eewrap-zsh)
  ;; Test: (find-eewraptest-links "zsh" "echo $SHELL")
  ;;       (eek "<down> <<eewrap-zsh>>")
echo $SHELL

  ;; M-#:  (find-efunction 'eewrap-two-eepitches)
  ;; Test: (find-eewraptest-links "two-eepitches" "shell python")
  ;;       (eek "<down> <<eewrap-two-eepitches>>")
  shell python

The bindings for `M-Z' and `M-#' are not active by default. See:

  (find-eev "eev-mode.el" "eev-mode-map-set" "M-Z" "eewrap-zsh")
  (find-eev "eev-mode.el" "eev-mode-map-set" "M-#" "eewrap-two-eepitches")





. Wrapping functions generate hyperlinks
...this is a slogan - a huge idea, in a very shortened form. In its
full form, that would be:

  (Some) wrapping function provide one of the basic ways to produce
  elisp hyperlinks quickly; the second basic way, which is a bit more
  complex conceptually, is via Elisp hyperlinks buffers. This, and the
  whole rationale behind generating and using elisp hyperlinks, is
  explained here:

    (find-links-intro "Elisp hyperlinks buffers")

The "some" in beginning of the long version of the slogan, above, is
because a few of the wrapping commands, for example, <M-T> and <M-R>,
are used to produce things that are not hyperlinks - usually other
kinds of scripts.