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)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.

We saw in

  (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

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

  (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':


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


  (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

  (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

  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")
  (find-code-c-d-intro "Extra arguments")
  (find-enode "Browse-URL")

The dired variation

In dired mode each line corresponds to a file