(Re)generate: (find-edit-index-intro)
Source code:  (find-efunction 'find-edit-index-intro)
More intros:  (find-eev-quick-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.

This is a tutorial for:
  (find-eev "eev-hydras.el")
that is a module of eev that is not loaded by default.
To test it you will need the package "hydra", from ELPA,
and this `require':
  (require 'eev-hydras)
This will define `M-x ei' as an alias. See:
  (find-eev "eev-hydras.el" "ei")

0. Introduction

These sections of the basic tutorial (find-eev-quick-intro "8.3. Creating index/section anchor pairs") (find-eev-quick-intro "8.4. Creating e-script blocks") explain how to create "index/section anchor pairs", but they say that the "index" line should be moved to the index at the top of the file _by hand_. "Moving the index line to the index" is a process that takes many steps, and even after years of practice I would still commit mistakes very often when doing it. Here we will see a way to perform it very quickly, with a sequence of keys like this one: M-x ei RET kopli0q The obvious way of implementing "moving the index line to the index" would be by defining a function that would perform the many steps involved in this process, and that would check for many possible kinds of errors, and handle them correctly... but that turned out to be too hard. When we run `M-x ei', that is defined as an alias - see: (find-eev "eev-hydras.el" "ei") it actives a hydra that interprets the letters in kopli0q as these "commands": <k>ill line <o>ther window <p>revious anchor eva<l> <i>insert <0> `C-x 0' <q>uit In my QWERTY keyboard I can type the letters in `kopli0' very quickly with my right hand, as its keys are arranged like this: 0 i o p k l I can do that without taking my eyes off the screen - yes, I am a VERY bad typist! But read this: (find-refining-intro "5. Pointing to anchors") (find-refining-intro "5. Pointing to anchors" "but I don't touch-type") and if anything fails I can recognize it immediately, and I can fix it with "undo"s in the right way. Also, after the <i> I sometimes type some <,>s and <.>s to adjust the indentation; this will be explained in the next section.

1. Testing the hydra

In this tutorial "the hydra" will mean `ee-edit-index-hydra'. Typing `M-x ei' will activate the hydra. When it is active you will see a message in the echo area showing its main keys. `q' will "quit" that hydra, and deactivate it. Some keys that the hydra don't understand will also quit it. The hydra understands the keys <up>, <down>, <,>, and <.>, among others. It interprets <up> and <down> in the obvious way, and it interprets <,> and <.> as commands that reindent a `(to ...)' by adding or deleting tabs before the "(". Test this here, aaa (to "bbb") cccc (to "dddd") ee (to "fffff") and use the hydra to align the three `(to ...)'s.

2. An index

This is an index, # «.foo» (to "foo") # «.bar» (to "bar") followed by two "e-script blocks" created with `M-B'. See: (find-eev-quick-intro "8. Anchors") (find-eev-quick-intro "8. Anchors" "`M-B'") (find-eev-quick-intro "8.4. Creating e-script blocks") ##### # # foo # 2021may20 # ##### # «foo» (to ".foo") ##### # # bar # 2021may20 # ##### # «bar» (to ".bar")

3. An exercise

Here is an exercise. 1. Use `M-B' to convert the line with "plic" below into an e-script block, as explained here: (find-eev-quick-intro "8.4. Creating e-script blocks") plic 2. Put the point on the "index line" above - that is the one that looks like this, # <.plic> (to "plic") but with green double angle brackets instead of "<>"s - and type this, and watch what happens in each step: C-l M-x ei RET kopli0q The actions associated to "kopli0q" are: <k>ill the current line switch to the sec<o>nd window move backwards to the line of the <p>revious anchor eva<l> the current line - that has a `to' pointing to the index <i>nsert, i.e., yank, the last kill after this line <0>: run `C-x 0' to delete the window that shows the index <q>uit the hydra. 3. Do the same for the "bletch" below: bletch but now also use <,>s, <.>s, and <up>s and <down>s between the <i> and the <0> to align all the `(to ...)'s in the index.

4. `M-x ei' is fragile

Look at the source code of the hydra that `M-x ei' calls: (find-eev "eev-hydras.el" "ee-edit-index-hydra") Several of the actions are defined with `eek'. For example, the action of "o" is: ("o" (eek "C-x 1 C-x 3 C-x o")) This is considered fragile - because it won't work if any of these key sequences has been redefined - and a bad programming style. I could have used this instead: ;; (find-estring (format-kbd-macro (kbd "C-x 1 C-x 3 C-x o") 'verbose)) ("o" (delete-other-windows) (split-window-right) (other-window 1)) but the "fragile" style above is usually good enough for quick hacks - `M-x ei' is a quick hack -, and it gives the readers the feeling that they can write their own hydras as quick hacks, too.