(Re)generate: (find-brxxx-intro)
Source code:  (find-eev "eev-intro.el" "find-brxxx-intro")
More intros:  (find-eev-quick-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") https://tannerlectures.utah.edu/_resources/documents/a-to-z/c/Coetzee99.pdf -> $S/https/tannerlectures.utah.edu/_resources/documents/a-to-z/c/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