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



This intro is being rewritten!
The prerequisites for understand this are:
  (find-elisp-intro)
  (find-links-conv-intro "3. Classification")




1. Introduction

In dec/2019 I sent this e-mail to the eev mailing list: https://lists.gnu.org/archive/html/eev/2019-12/msg00001.html It was a kind of a call for help. It contained a very brief explanation of how the "templated" functions of eev, like `find-ekey-links' and `find-latex-links', are implemented, and showed how people can write their own templated functions as quick hacks. If you want to learn how to _use_ templated functions, start by: (find-eev-quick-intro "4.2. `find-ekey-links' and friends") (find-eev-quick-intro "7.5. `find-latex-links'") If you want to look at the source code of the existing templated functions, take a look at: (find-eev "eev-elinks.el") (find-eev "eev-tlinks.el") (find-links-intro "3. Elisp hyperlinks buffers conventions") This tutorial is for people who want to learn how to _write_ their own templated functions. To learn how to write your own templated functions you need to: 1) learn how to use `ee-template0' by reading its source code and playing with examples in the source and here, 2) learn how to use `find-elinks' - same thing, 3) learn how to use `find-find-links-links-new'.

2. `ee-template0'

See: (find-efunction 'ee-template0) (find-eev "eev-template0.el") Try: (ee-template00 "a{(+ 2 3)}b") (let ((hi "Here: ") (a 22) (b 33)) (ee-template00 "{hi}{a}+{b}={(+ a b)}")) (defun foo (a b) (ee-template00 "{a}+{b}={(+ a b)}")) (foo 22 33) (ee-template0 "{<} a{(+ 2 3)} {>}")

3. `find-elinks'

See: (find-efunction 'find-elinks) (find-eev "eev-elinks.el" "find-elinks") Now try these examples. They are multi-line versions with comments of the examples in the source file. (find-elinks '((a sexp) "a string") ) Now try these examples. They are longer, multi-line versions of the examples in the source file. (find-elinks '((a sexp) "a string") ) (find-elinks '((a sexp) "a string") "st") (find-elinks '((a sexp) "a string") "st" "i") (find-elinks '((a sexp) (another sexp) (sexps get comment signs) (strings in sexps: "foo bar") (newlines in strings in sexps get backslashed: "\n") (ticks in sexps: 'a '(b c)) (nils in sexps: nil () (nil nil)) "a string" "another string" "strings don't get comment signs" "empty strings become empty lines" "" "newlines in strings\nbecome real newlines" "nils are dropped:" nil "see?" "" (another sexp) ) ) Normally the first argument to `find-elinks' is backquoted. See: (find-elnode "Backquote") Try: `(foo ,(+ 2 3) bar) `(foo ,'(+ 2 3) bar) `(foo ,(list 2 3) bar) `(foo ,@(list 2 3) bar) See: (find-eev "eev-elinks.el" "find-efunction-links") The first argument to `find-elinks' is called LIST. Elements of LIST that are sexps are converted to strings using `ee-HS'. See: (find-eev "eev-wrap.el" "ee-S")

4. Skels

Many functions in eev have comments that start with ";; Skel:", like this: ;; Skel: (find-find-links-links-new "fossil" "url subdir c" "") A comment like that before a function means that I wrote that function by first running that sexp and then modifying the code that that sexp generated, that was a "skeleton". Try: (find-find-links-links-new "fossil" "url subdir c" "") (find-eev "eev-tlinks.el" "find-fossil-links") (find-eevgrep "grep --color -nH --null -e Skel: *.el")

5. `find-find-links-links'

(Note: `find-find-links-links' is obsolete, and is superseded by `find-find-links-links-new') ALL my `find-*-links' started as quick hacks. SOME of them were useful enough to deserve being cleaned up. A FEW of them ended up in: http://angg.twu.net/eev-current/eev-elinks.el.html http://angg.twu.net/eev-current/eev-tlinks.el.html (find-eev "eev-elinks.el") (find-eev "eev-tlinks.el") ...but there are lots of other `find-*-links' functions in: http://angg.twu.net/.emacs.templates.html They are trivial to write. I start with a skeleton that I obtain by running `M-x find-find-links-links', and then I modify the first line in that buffer, regenerate, modify, regenerate, and so on until happy. Run each of the sexps below with `M-2 M-e' to compare the buffers that they generate: (find-find-links-links "{k}" "{stem}" "{args}") (find-find-links-links "\\M-u" "{stem}" "{args}") (find-find-links-links "\\M-u" "macports" "{args}") (find-find-links-links "\\M-u" "macports" "pkgname") (find-find-links-links "\\M-u" "macports" "pkgname anotherarg") So: start by running something like (find-find-links-links "\\M-u" "macports" "pkgname") (find-find-links-links "\\M-u" "homebrew" "pkgname") then copy the (define-key eev-mode-map "\M-h\M-u" 'find-macports-links) (defun find-macports-links (&optional pkgname &rest pos-spec-list) "Visit a temporary buffer containing hyperlinks for foo." (interactive) (setq pkgname (or pkgname "{pkgname}")) (apply 'find-elinks `((find-macports-links ,pkgname ,@pos-spec-list) ;; Convention: the first sexp always regenerates the buffer. (find-efunction 'find-macports-links) "" ,(ee-template0 "\ ") ) pos-spec-list)) ;; Test: (find-macports-links ___) to your notes, replace the `(interactive)' by (interactive (list (ee-debpkgname-ask))) and start adding things to the string in (ee-template0 "..."). I will try to update this intro in the next days: (find-templates-intro) http://angg.twu.net/eev-intros/find-templates-intro.html Etc: (find-links-conv-intro) (find-links-conv-intro "3. Classification") (find-eev "eev-tlinks.el" "find-find-links-links") (find-eev "eev-tlinks.el" "find-intro-links") (find-eev "eev-wrap.el" "find-eewrap-links")