(Re)generate: (find-code-c-d-intro)
Source code:  (find-eev "eev-intro.el" "find-code-c-d-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 needs to be rewritten!
Ideally it should _complement_ the material in:
  (find-eev-quick-intro "9. Shorter hyperlinks")
  (find-eev-quick-intro "9.1. `code-c-d'")



. Avoiding full path names
Suppose that you have downloaded ("psne"-ed) this URL,

  http://www.lua.org/ftp/lua-5.1.4.tar.gz

with `M-x brep' - see:

  (find-psne-intro)

and you unpacked that tarball into the directory ~/usrc/ (I
prefer to use that instead of /usr/src/) with:

  tar -C ~/usrc/ -xvzf $S/http/www.lua.org/ftp/lua-5.1.4.tar.gz

Now you can access some directories and files of the unpacked
tarball with:

  (find-fline "~/usrc/lua-5.1.4/")
  (find-fline "~/usrc/lua-5.1.4/src/")
  (find-fline "~/usrc/lua-5.1.4/src/lstrlib.c")
  (find-fline "~/usrc/lua-5.1.4/test/")
  (find-fline "~/usrc/lua-5.1.4/test/README")
  (find-fline "~/usrc/lua-5.1.4/doc/")
  (find-w3m   "~/usrc/lua-5.1.4/doc/contents.html")

but it's a bit clumsy to have to use the "~/usrc/lua-5.1.4/"
every time, so eev provides a nice way to define shorthands. We
want to be able to write just this instead of the sexps above,

  (find-lua51file "")
  (find-lua51file "src/")
  (find-lua51file "src/lstrlib.c")
  (find-lua51file "test/")
  (find-lua51file "test/README")
  (find-lua51file "doc/")
  (find-lua51w3m  "doc/contents.html")

and here the directory "~/usrc/lua-5.1.4/" became a mnemonic
"lua51" in the middle of the names of some functions.

We will call these sexps with "lua51" "shorter hyperlinks".



. Shorter hyperlinks
How can we generate the definitions for `find-lua51file' and
`find-lua51w3m' from just the strings "lua51" and
"~/usrc/lua-5.1.4/"? Try this:

  (find-code-c-d "lua51" "~/usrc/lua-5.1.4/")

you will get a temporary buffer with a lot of Lisp code -
including a definition for `find-lua51file' and another one for
`find-lua51w3m'. That Lisp code has not been executed yet; the
function `find-code-c-d' is just for debugging, and we can regard
it as a hyperlink to the code that this sexp would execute:

  (code-c-d "lua51" "~/usrc/lua-5.1.4/")

So, to define a family of functions including `find-lua51file'
and `find-lua51w3m', for a given "mnemonic" - "lua51" in this
case - and a given "directory" - "~/usrc/lua-5.1.4/" - we run
this:

  (code-c-d "lua51" "~/usrc/lua-5.1.4/")

which generates a block of Lisp code, as a string, and evaluates
it. Note: the original (and rather confusing) terminology for the
"mnemonic" was "code"; that's why the "c" in `code-c-d'.



. Extra arguments to `code-c-d'
`code-c-d' supports extra arguments - for example, this works:

  (find-code-c-d "el" "~/usrc/emacs/lisp/" :info "elisp")

Look at the end of the generated code and you will see that it
has a definition for `find-elnode' - such that

  (find-elnode "Constant Variables")

is a shorthand (a "shorter hyperlink") for:

  (find-node "(elisp)Constant Variables")

What is important to understand here is how these definitions
with extra arguments are structured - so that you will be able to
understand the source code when you need to. Both `code-c-d' and
`find-code-c-d' are defined with a `&rest' in their argument
lists, like this (**NOTE: do not execute these defuns!**):

  (defun      code-c-d (c d &rest rest) ...)
  (defun find-code-c-d (c d &rest rest) ...)

and they both invoke `ee-code-c-d', which does all the template
work and returns a big string; `ee-code-c-d' passes its `rest'
argument to a recursive function called `ee-code-c-d-rest', and
for each one of the supported keywords there is a corresponding
function, also recursive; for `:info' it is called
`ee-code-c-d-:info'. Their specifications are like this:

  (defun   ee-code-c-d (c d &rest rest) ...)
  (defun   ee-code-c-d-rest      (rest) ...)
  (defun   ee-code-c-d-:info (manual &rest rest) ...)

and one very non-obvious trick is used to make the code short.
When `ee-code-c-d-rest' and `ee-code-c-d-:info' are run they can
access the values the `c' and the `d' that were passed to
`ee-code-c-d' (due to dynamic scoping), so `c' and `d' do not
need to be passed down explicitly as arguments.

Try:

  (find-code-c-d      "CODE" "/DIR/" :info "INFO")




. Other similar functions
See: (find-brxxx-intro)
     (find-pdf-like-intro)
     (find-audiovideo-intro)

Try: (find-code-pdf      "CODE" "FILE.pdf")
     (find-code-pdf-text "CODE" "FILE.pdf")
     (find-code-audio    "CODE" "FILE.mp3")
     (find-code-video    "CODE" "FILE.mp4")