(Re)generate: (find-brxxx-intro)
Source code: (find-eev "eev-intro.el" "find-brxxx-intro")
More intros: (find-eev-quick-intro)
(find-eev-intro)
(find-psne-intro)
(find-pdf-like-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.
This intro expands an idea that was mentioned briefly at:
(find-eev-quick-intro "3.1. Non-elisp hyperlinks")
and combines it with the idea of "local copies" from:
(find-psne-intro "the second way")
(find-psne-intro "1. Local copies of files from the internet")
(find-psne-intro "5. `browse-url' and friends")
At this moment the best explanation of these ideas in here:
(find-eev "eev-brxxx.el" ";;; Commentary:")
in the source code. I need to rewrite this intro!
[Video links:]
(find-eevtemplvideo "9:17" "3. The function that defines brep")
(find-eevtemplvideo "9:38" "`code-brurl' is a variant of `code-c-d'")
(find-eevtemplvideo "10:07" "find-code-url shows the code instead of executing it")
(find-eevtemplvideo "11:26" "this is explained in the main tutorial")
(find-eevtemplvideo "12:12" "accept extra arguments")
(find-eevtemplvideo "12:34" "if we run just this")
(find-eevtemplvideo "12:40" "one of the reasons for using text: comments")
(find-eevtemplvideo "13:03" "if we run just this with extra arguments")
(find-eevtemplvideo "14:10" "code-brurl executes this code here")
1. Introduction
We saw in
(find-eev-quick-intro "3.1. Non-elisp hyperlinks")
that eev defines some functions with names starting with `br'
that are similar to `browse-url', and we saw in
(find-psne-intro "the second way")
(find-psne-intro "1. Local copies of files from the internet")
(find-psne-intro "3. The new way: M-x brep")
how to create local copies of files; after downloading a local
copy of, say,
http://www.gnu.org/software/emacs/emacs-paper.html
into
$S/http/www.gnu.org/software/emacs/emacs-paper.html
you can open the local copy by running `M-x browse-url', `M-x brg'
or `M-x brff' on the "file:///" URL below,
file:///home/edrx/snarf/http/www.gnu.org/software/emacs/emacs-paper.html
but note that the "file:///" URL has an "edrx" - my username
- in the middle of the file name, so this only works without
changes if you use "edrx" as your username...
2. The `l' variants
After creating `brg' and `brff' I created variants of them that
would open the local copy of the URL at point instead of the
original URL - or, more precisely, that would open the result of
applying `ee-url-to-local-url' to the original URL. Try:
(ee-url-to-local-url
"http://www.gnu.org/software/emacs/emacs-paper.html")
These variants were called `brgl' and `brffl' - I used the
convention that the suffix `l' meant "use the local copy".
3. The `d' variants
After creating `brgl' and `brffl' I realized that it would be
easy to create variants of them that would work in dired mode.
If we visit a directory - for example, this one,
(find-fline "$S/http/www.gnu.org/software/emacs/")
and we put the point in a line with an HTML on it - for example,
on the line with the "emacs-paper.html" - then typing `M-x
brgd' there converts the full pathname of the file at point to a
"file:///" URL, like this,
$S/http/www.gnu.org/software/emacs/emacs-paper.html
-> file:///home/edrx/snarf/http/www.gnu.org/software/emacs/emacs-paper.html
and opens the resulting "file:///" url with `brg'.
The suffix `d' means "use the file in this line in dired".
4. `brxxx'-functions
`browse-url' has several variants, with names like
`browse-url-firefox' and `browse-url-chromium', that open the URL
at point using specific programs. See:
(find-epackage 'browse-url)
(find-enode "Browse-URL")
We say that `brg', `brgl' and `brgd' are "`brxxx'-functions"
with "base function" `find-googlechrome'; `brgl' is the `l' (or
"local") variant, and `brgd' is the `d' (or "dired") variant;
`brg' is sometimes called the "remote" variant.
5. `code-brurl'
Remember that `code-c-d' generates lisp code and executes it, and
that `find-code-c-d' generates the same lisp code as `code-c-d'
but displays it instead of executing it; this was explained, with
examples, here:
(find-eev-quick-intro "9.1. `code-c-d'")
(find-eev-quick-intro "9.1. `code-c-d'" "find-code-c-d")
Eev has a function called `code-brurl' that works like `code-c-d'
and that creates several `brxxx'-functions with the same base
function. To understand what the `code-brurl' sexp below does,
;; From:
;; (find-eev "eev-brxxx.el" "code-brxxxs")
;; (find-eev "eev-brxxx.el" "code-brxxxs" "brg")
(code-brurl 'find-googlechrome :remote 'brg :local 'brgl :dired 'brgd)
We run:
(find-code-brurl 'find-googlechrome :remote 'brg :local 'brgl :dired 'brgd)
Note that the base function in this example is
`find-googlechrome', that is a function that expects a URL.
6. `code-brfile'
We saw how to create `brxxx'-functions using `find-googlechrome'
as the base function; remember that `find-googlechrome' is a
function that expects a URL.
If we download a local copy of a PDF, like we did here,
(find-pdf-like-intro "2. Preparation")
http://anggtwu.net/TannerLectures/Coetzee99.pdf
-> $S/http/anggtwu.net/TannerLectures/Coetzee99.pdf
then it makes sense to have a `brxxx'-function, called `brpdfl',
that we can run on the "https://" URL above, and that will open
the "$S/https/" file corresponding to the URL using
`find-pdf-page'... but `find-pdf-page' is a function that expects
a filename, not a URL, so `code-brurl' wouldn't work...
What we want can be done by the sexp below:
;; From:
;; (find-eev "eev-pdflike.el" "code-brxxxs")
;; (find-eev "eev-pdflike.el" "code-brxxxs" "brpdfl")
(code-brfile 'find-pdf-page :local 'brpdfl :dired 'brpdfd)
To understand what it does, run:
(find-code-brfile 'find-pdf-page :local 'brpdfl :dired 'brpdfd)
and read the docstrings.
Note that in the previous section we had a ":remote 'brg", that
defined a remote variant. It doesn't make sense to apply
`find-pdf-page' to a remote URL, so we don't have a ":remote"
here.
Old stuff:
(TODO: revise it!)
7. Old introduction
We saw in
(find-psne-intro)
(find-psne-intro "M-x brep")
(find-psne-intro "M-x brfl")
(find-psne-intro "5. `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.
8. 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.
9. 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)
10. 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
11. 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")
12. The dired variation
In dired mode each line corresponds to a file