(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_.
Is is meant as both a tutorial and a sandbox.



Note: this intro is being rewritten!
Ideally it should _complement_ the material in:
  (find-eev-quick-intro "3. Elisp hyperlinks")








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

[To do: explain this convention with examples; explain the conventions for the "variants of the first line"] (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]