(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")




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





. `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)} {>}")




. `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")



. 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")





. `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://anggtwu.net/eev-current/eev-elinks.el.html
  http://anggtwu.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://anggtwu.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://anggtwu.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")