Warning: this is an htmlized version!
The original is across this link,
and the conversion rules are here.
(Re)generate: (find-brxxx-intro)
Source code:  (find-eev "eev-intro.el" "find-brxxx-intro")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



Introduction
============
We saw in

  (find-psne-intro)
  (find-psne-intro "M-x brep")
  (find-psne-intro "M-x brfl")
  (find-psne-intro "`browse-url' and friends")

that we can use `M-x brep' to download local copies of files from
the internet, and that `M-x brfl' on a URL runs `find-fline' on
the local copy of that URL. `brep' and `brfl' are
"`browse-url'-like functions" defined by eev; we will refer to
them, and to other such functions, as "brxxx-functions". Every
brxxx-function is an interactive interface to some "base
function"; for `brep' and `brfl' we have:

    brxxx-function   base function
    --------------   -------------
         brep        find-psne-links
         brfl        find-fline

What we will see here is how `code-brfile' and `code-brurl' -
which are somewhat similar to `code-c-d' - can be used to define
brxxx-functions from base functions.




A first example
===============
Let's define two trivial base functions, one that expects a URL,
and another one that expects a file name:

  (defun foo-url  (url)      (format "Got URL: %s"      url))
  (defun foo-file (filename) (format "Got filename: %s" filename))

Note that they don't do much - they just return explanatory
strings.

These two calls,

  (code-brurl  'foo-url  :remote 'brshowu :local 'brshowul)
  (code-brfile 'foo-file                  :local 'brshowfl)

define three brxxx-functions: `brshowu' and `brshowul' for the
base function `foo-url', and `brshowfl' for the base function
`foo-file'. You can inspect the definitions by running these
sexps,

  (find-code-brurl  'foo-url  :remote 'brshowu :local 'brshowul)
  (find-code-brfile 'foo-file                  :local 'brshowfl)

and you can test what `foo-url', `foo-file', `brshowu',
`brshowul', and `brshowfl' do by running the sexps below.

  (foo-url "http://a/b")
    => "Got URL: http://a/b"

  (foo-file "/c/d/e/f")
    => "Got filename: /c/d/e/f"

  (brshowu  "http://a/b")
    => `(foo-url "http://a/b") -> "Got URL: http://a/b"'

  (brshowul "http://a/b")
    => `(foo-url "file:///home/edrx/snarf/http/a/b") ->
        "Got URL: file:///home/edrx/snarf/http/a/b"'

  (brshowfl "http://a/b")
    => `(foo-file "/home/edrx/snarf/http/a/b") ->
        "Got filename: /home/edrx/snarf/http/a/b"'

Now let's go to what matters. Put the point on the URL below, and
run `M-x brshowu', `M-x brshowul' and `M-x brshowfl':

  http://a/b

you will see that `brshowu', `brshowul', and `brshowfl' can be
called interactively, and when they are called interactively they
use as their argument either the URL around point, or something
obtained from it - the local file name or a local URL associated
to that URL.




The conversions
===============
One underlying idea behind all this is that we have two
conversion functions, one from URLs to file names, and another
from (absolute) file names to URLs starting with "file:///".
They work like this:

  http://a/b  ->  $S/http/a/b  ->  file:///home/edrx/snarf/http/a/b
                       /tmp/c  ->  file:///tmp/c

try:

  (ee-url-to-fname "http://a/b")
  (ee-fname-to-url "/tmp/c")
  (ee-url-to-local-url "http://a/b")

Now execute the sexps below (with `M-2 M-e') to examine the code
that calls to `code-brurl' and `code-brfile' generate and
execute:

  (find-code-brurl  'foo-url  :remote 'brshowu :local 'brshowul)
  (find-code-brfile 'foo-file                  :local 'brshowfl)






Naming conventions for brxxx-functions
======================================
By convention, each name for a brxxx-function is composed of a
prefix, a stem, and a suffix. The prefix is always "br", the
stem is a mnemonic for the base function, and the suffix is
either "", "l", or "d", meaning:

  ""   - use the URL without changes
  "l"  - use the local copy
  "d"  - dired variation (see below)

Here are the stems for some of the brxxx-functions defined by
eev:

  Base function       receives   stem
  -------------       --------   ----
  find-psne-links     URL        "ep"
  browse-url-firefox  URL        "m"
  find-googlechrome   URL        "g"
  find-w3m   	      URL        "w"
  find-fline          file name  "f"
  find-audio          file name  "audio"
  find-video          file name  "video"
  find-xpdf-page      file name  "xpdf"
  find-evince-page    file name  "evince"
  find-xdvi-page      file name  "xdvi"
  find-djvu-page      file name  "djvu"
  find-pdf-text       file name  "pdftext"
  find-djvu-text      file name  "djvutext"

In our example with `foo-url' and `foo-file' we had:

  Base function       receives   stem
  -------------       --------   ----
  foo-url             URL        showu
  foo-file            file name  showf




Calling `code-brurl' and `code-brfile'
======================================

  (code-brurl '<U-function>
                   :remote 'br<stem>   :local 'br<stem>l   :dired 'br<stem>d)
                   \---------------/   \---------------/   \----------------/
                       optional              optional             optional

  (code-brfile '<F-function>           :local 'br<stem>l   :dired 'br<stem>d)
                                       \---------------/   \----------------/
                                             optional             optional

This, like many other parts of eev, is a hack with a very concise
calling syntax - so we will see an example first, and then
dissect it to understand precisely how it works. If you are
curious about the inspirations behind it, here they are:

  (find-code-c-d-intro)
  (find-code-c-d-intro "find-code-c-d")
  (find-code-c-d-intro "Extra arguments")
  (find-enode "Browse-URL")



The dired variation
===================

In dired mode each line corresponds to a file