(Re)generate: (find-links-intro)
Source code: (find-eev "eev-intro.el" "find-links-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 is obsolete!
I need to move some parts of it to other intros and then delete it.
See: (find-here-links-intro)
(find-refining-intro)
(find-templates-intro)
(find-links-conv-intro "3. Classification")
(find-links-conv-intro "3. Classification" "regenerate")
1. Functions for templated text
The function that is used to generate templated text from a
string is called `ee-template0'. The function that generates a
templated text from a list of sexps and strings is called
`ee-links-to-string'. The function that generates an "*Elisp
hyperlinks*" buffer from a list of sexps and strings is called
`find-elinks'. They are explained, with examples, in the source
code, at:
(find-eev "eev-wrap.el" "ee-template0")
(find-eev "eev-elinks.el" "find-elinks")
(find-eev "eev-elinks.el" "find-elinks" "ee-links-to-string")
Some functions like `find-latex-links' generate buffers with
elisp hyperlinks at the top, some templated text meant to be
saved to a file at the bottom, and with a call to `ee-copy-rest'
separating the top part from the bottom part. The `ee-copy-rest'
is explained in detail here:
(find-eev "eev-tlinks.el" "ee-copy-rest")
2. `find-here-links'
The most important of the commands that generates buffers with elisp
hyperlinks - "M-h commands", in the terminology explained above - is
`find-here-links', which integrates most of the functionalities of
several more basic M-h commands. We will explain first what it _does_,
then its _usage_.
`find-here-links' is bound to `M-h M-h' to make it very easy to
invoke. If you are reading this then "here" means the buffer
"*(find-links-intro)*", in a certain position. Try to type `M-h M-h';
you will get a buffer like this,
____________________________________________________________
|# See: |
|# (find-links-intro "`find-here-links'") |
|# (find-efunctiondescr 'eev-mode "M-h M-h") |
| |
|# (find-links-intro) |
| |
| |
|--:**- *Elisp hyperlinks* All L1 (Fundamental eev) -|
|____________________________________________________________|
which contains a 3-line header with help links, that we will explain
soon, and then a link to "here", i.e., to the buffer
"*(find-links-intro)*". Note that the link
(find-links-intro)
can be "refined" to, for example,
(find-links-intro "which contains a 3-line header")
using the tricks described in these sections:
(find-eval-intro "Refining hyperlinks")
(find-eval-intro "Producing and refining hyperlinks")
(find-eval-intro "Producing and refining hyperlinks" "`M-h M-2'")
(find-eval-intro "Producing and refining hyperlinks" "`M-h2hy'")
but `find-here-links' by itself only produces "unrefined" links - so
when we say that `find-here-links' produces links to "here" we mean
just "to the current buffer", not "to the a certain position in the
current buffer".
`find-here-links' works for several kinds of "here"s - it works for
intros like this one, for Info pages, for manpages, for files and
directories, for descriptions of Emacs functions and variables, and
for a few other cases. Try the sexps below:
(find-here-links-test '(find-eval-intro))
(find-here-links-test '(find-node "(dir)Top"))
(find-here-links-test '(find-enode "Lisp Eval"))
(find-here-links-test '(find-fline "~/"))
(find-here-links-test '(find-eevfile "eepitch.el"))
(find-here-links-test '(find-efunction 'ee-eval-last-sexp))
(find-here-links-test '(find-efunctiondescr 'ee-eval-last-sexp))
(find-here-links-test '(find-evardescr 'ee-hyperlink-prefix))
(find-here-links-test '(find-efacedescr 'eepitch-star-face))
(find-here-links-test '(find-ecolors "\nred"))
(find-here-links-test '(find-efaces "eepitch-star-face"))
(find-here-links-test '(find-customizegroup 'rcirc))
(find-here-links-test '(find-man "1 cat"))
[^ oops, this test doesn't work on multi-window settings...]
Each one of them tests a different case of `find-here-links',
creating a window setup like this:
______________________________________
| | |
| | target of |
| | sexp |
| this |______________________|
| intro | |
| | result of running |
| | find-here-links on |
| | [target of sexp] |
|_______________|______________________|
The cursor is kept at the left window ("this intro"), so you
can compare the different cases using just <up>, <down>, and M-e.
3. `find-here-links': usage patterns
Typically what happens is this. We are putting our notes - eepitch
blocks, hyperlinks, etc - in a certain file; let's refer to it as the
"e-script". Then we start to navigate for information, and we find
something interesting. We want to add a link pointing to that
"something interesting" to our e-script notes - but for that we need
to produce that sexp hyperlink, and ideally we would like to do that
in a way that does not disturb much our attention. Consider this
diagram [note: it DOES NOT imply that the Emacs frame is split into three
windows - typically we will switch between buffers in a single window]:
______________________________________
| | |
| | something |
| ==> interesting |
| e-script |_________||___________|
| | \/ |
| | result of running |
| <== find-here-links on |
| | [sthing intrstng] |
|_______________|______________________|
and this series of steps:
0. We start navigating from the e-script buffer, and when we
1. find something interesting [in another buffer], we
2. run `find-here-links' at the "something interesting" buffer,
3. identify among the sexps in the find-here-links buffer one that
points to that "something interesting",
4. copy that sexp to the kill-ring,
5. go back to the e-script buffer,
6. insert that sexp into the e-script buffer,
7. execute that sexp to go back to the "something interesting",
8. continue navigating & doing stuff.
At (8) we are essentially back to (1), but we have added to our
e-script buffer a link to "something interesting".
Note that to add refining we need to add a step before (2) and
another one after (3):
1.9. select a string to search for and copy it to the kill-ring,
3.1. refine that sexp using the "string to search for" (with M-h2hy)
[TO DO: explain the keys that I normally use to perform all
this; explain why I am not the right person to optimize these
steps - because I can type these key sequences without thinking,
and step (3) sometimes gives several sexps for us to choose from]
4. ee-hyperlink-prefix
`ee-hyperlink-prefix' is both a variable and a function that
helps us set that variable; it started to an experiment on how to
create an alternative to `M-x customize' and ended up becoming
the inspiration for all the `find-*-links' functions.
If you run `M-x ee-hyperlink-prefix' you should get 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 "// ") |
|# (setq ee-hyperlink-prefix "% ") |
| |
| |
|--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
|___________________________________________________________|
where the first line regenerates the buffer, the second line sets
the variable `ee-hyperlink-prefix' to its current value, and each
one of the lines after the first blank line sets
`ee-hyperlink-prefix' to one of several fixed common values. If
we change the value of `ee-hyperlink-prefix' with one of the
`setq's and execute the first line again we see that all the
prefixes, plus the argument "# " in the second line, change.
Try this, with `M-2 M-e' on each line:
(progn (setq ee-hyperlink-prefix "# ") (ee-hyperlink-prefix))
(progn (setq ee-hyperlink-prefix "% ") (ee-hyperlink-prefix))
5. The first line regenerates the buffer
Most of the "M-h commands" generate buffers with elisp
hyperlinks in which the the first line "regenerates the
buffers". This means two things:
1. You can copy the first line to your notes, and it will work
as a link to that buffer. Here are some examples of these
first lines:
(find-latex-links "/tmp/mytest")
(find-latex-links "~/latextest")
(find-code-pdf-links "/usr/local/texlive/2019/texmf-dist/doc/asymptote/" "{c}")
(find-code-pdf-links "/usr/local/texlive/2019/texmf-dist/doc/asymptote/" "asy")
A good way to compare the results of the two
`find-latex-links' and the two `find-code-pdf-links' sexps
above is to run them with `M-2 M-e'. The prefix `M-2' to
`M-e' makes the "target" of a sexp be displayed in a
second window without switching to it. See:
(find-efunctiondescr 'ee-eval-sexp-eol)
(find-multiwindow-intro "find-2a")
2. You can change the arguments of the sexp in the first line
and run it again, and this will regenerate the buffer with
some modifications. This was explained here:
(find-eev-quick-intro "7.5. `find-latex-links'" "change the \"{stem}\"")
(find-eev-quick-intro "11.1. `find-pdf-links'" "adjust by hand")
[To do: explain how this works in more complex templates.
Example:]
(find-find-links-links)
(find-find-links-links "\\M-u")
(find-find-links-links "\\M-u" "USERTEST")
(find-find-links-links "\\M-u" "USERTEST" "a")
(find-find-links-links "\\M-u" "USERTEST" "a b")
(find-find-links-links "\\M-u" "USERTEST" "a b c")
6. Pointing to where we are now
Several of the `M-h' commands are mainly meant to help us
generate hyperlinks to "where we are now": to the current file,
to the current Info page, to the current `find-*-intro', to an
Emacs function or variable we are inspecting, to the current
buffer, and so on. They don't try to be very smart -
[To do: write this]
(find-efunctiondescr 'eev-mode)
(find-efunctiondescr 'eev-mode "M-h f")
(eek "M-h M-i")
(find-enode "Lisp Eval")
(progn (find-enode "Lisp Eval") (eek "M-h M-i"))
(eek "M-h f ;; find-file-links")
(eek "M-h M-b ;; find-ebuffer-links")
for example, `M-h M-i' generates links to
the current "intro" buffer - like this one - _and_ to the
current Info page (the "i" in `M-h M-i' has two meanings).
Try:
(eek "M-h M-i")
you should get something like this:
___________________________________________________________
|# (find-einfo-links "links") |
| |
|[No "*info*" buffer] |
| |
|# (find-links-intro) |
| |
| |
|--:**- *Elisp hyperlinks* All L1 (Fundamental eev)--|
|___________________________________________________________|
7. The rest of the buffer
Several elisp hyperlinks buffers are composed of two parts: a
series of links at the top, and then a template-generated text
that is mean to be copied to somewhere else. The canonical
example is
(find-eev-update-links)
which ends with stuff that you can copy to your .emacs file to
make Emacs load eev by default. The end of the buffer generated
by `find-eev-update-links' looks more or less like this:
____________________________________________________________
|# (ee-copy-rest 0 '(find-fline "~/.emacs")) |
| |
|;; Load eev2. |
|;; See: (find-file "~/eev/") |
|;; (find-file "~/eev/eev-readme.el") |
|;; Generated by: (find-eev-update-links "~/eev/") |
|;; |
|(add-to-list 'load-path "~/eev/") |
|(require 'eev2-all) ; (find-eev "eev2-all.el") |
|(eev-mode 1) ; (find-eev "eev-mode.el") |
| |
| |
|--:**- *Elisp hyperlinks* Bot L56 (Fundamental eev)---|
|____________________________________________________________|
The line with `ee-copy-rest' is a hack. Its first argument is a
number, that we will call the "skip", and the second is
a (quoted) sexp hyperlink, that we will call the "code". The
rule that defines what is the "rest of the buffer" is this:
Move to the beginning of the next line, then skip (i.e., move
down) more SKIP lines. The rest of the buffer is everything
from that point on.
A sexp like `(ee-copy-rest ...)' does several things:
1) it highlights the rest of the buffer temporarily (like as
with `M-0 M-e'),
2) it copies the rest of the buffer to the kill ring (like as
with `M-w'),
3) it runs CODE to open its target in a window at the right
side (like as with `M-3 M-e')
[To do: add examples - including examples that let us create Lua
scripts etc]