[elpa] externals/eev 8601bc8 28/64: Small changes in eev-brxxx.el

[Stefan Monnier]

branch: externals/eev
commit 8601bc8af315f28597f05519ff6e091b3e700ac8
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>

    Small changes in eev-brxxx.el
---
 ChangeLog    |  7 ++++-
 README.md    | 34 ++++++++++++++++++------
 VERSION      |  4 +--
 eev-brxxx.el | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++---------
 eev-intro.el | 17 ++++++++++--
 eev-wrap.el  |  4 +--
 6 files changed, 123 insertions(+), 27 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 7918d1d..e2250da 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2019-01-29  Eduardo Ochs  <address@hidden>
 
+       * eev-wrap.el (ee-wrap-pdflike): use `code-pdf-page' instead of
+       `code-xpdf'.
+
+       * eev-brxxx.el: added comments.
+
        * eev-load.el: new file.
 
        * eev-intro.el (find-eev-quick-intro): Added two new sections:
@@ -13,7 +18,7 @@
        (code-xxxpdftext-family): new function.
        (code-xxxpdf-alias): new function.
 
-       * eev-pdflike-old.el: new file.
+       * eev-pdflike-old.el: new file - see above.
 
        * eev-rcirc.el (find-freenode-2a): new function.
        (find-freenode-links): rewrote completely.
diff --git a/README.md b/README.md
index 65e8cac..9661032 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,39 @@
-This is a README.md file for eev, written in a hurry - in 2013aug26 -
-just to make github happy! You can find an online version of the
-interactive tutorials for eev at:
+This is the README.md file for eev.
 
-  http://angg.twu.net/eev-intros/find-eev-intro.html
+I used to call eev a "tool for automating almost everything" and "my
+project to save the world with Free Software". In more concrete terms,
+eev is a library for Emacs that lets us create _executable logs_ of
+what we do in a format that is reasonably easy to read and to modify,
+and that lets us "play back" those logs step by step in any order.
 
-Besides that the best introductions to eev are these two videos,
+The tutorial at
 
-  Eepitch: a way to control shell-like programs from Emacs
+  http://angg.twu.net/eev-intros/find-eev-quick-intro.html
+
+explains the main ideas of eev - elisp hyperlinks, a way to control
+shell-like programs ("eepitch"), and sandboxed tutorials (the
+"find-xxx-intro"s) - quite clearly in its first sections. I've been
+using it to teach Emacs and GNU/Linux to beginners.
+
+Besides that tutorial the best introductions to eev are these videos:
+
+  Eepitch: a way to control shell-like programs from Emacs (2013)
   http://www.youtube.com/watch?v=Lj_zKC5BR64
 
-  An introduction to eev2
+  An introduction to eev2 (2012)
   http://www.youtube.com/watch?v=doeyn5MOaB8
 
-and the main URL for eev is this:
+The video about eepitch has a very nice demonstration of controlling
+two shell-like programs at once - watch its first two minutes.
+Note: I made it before implementing the "find-xxx-intro"s, that in the
+last few years became a central feature in eev.
+
+The main URLs for eev are these:
 
   http://angg.twu.net/#eev
+  http://angg.twu.net/eev-intros/find-eev-quick-intro.html
 
+The "quick intro" has installation instructions.
 
 Cheers! =)
   Eduardo Ochs
diff --git a/VERSION b/VERSION
index 621b09e..7ce726c 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Tue Jan  8 03:16:53 GMT 2019
-Tue Jan  8 01:16:53 -02 2019
+Tue Jan 29 14:34:37 GMT 2019
+Tue Jan 29 12:34:37 -02 2019
diff --git a/eev-brxxx.el b/eev-brxxx.el
index 002f983..2070a9b 100644
--- a/eev-brxxx.el
+++ b/eev-brxxx.el
@@ -1,6 +1,6 @@
 ;;; eev-brxxx.el -- define families of browse-url-like functions.
 
-;; Copyright (C) 2012 Free Software Foundation, Inc.
+;; Copyright (C) 2012,2019 Free Software Foundation, Inc.
 ;;
 ;; This file is (not yet?) part of GNU eev.
 ;;
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2013sep07
+;; Version:    2019jan29
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-brxxx.el>
@@ -34,11 +34,64 @@
 
 ;;; Commentary:
 
-(require 'eev-code)                    ; (find-eev "eev-code.el")
+;; See: (find-eev-quick-intro "3.1. Non-elisp hyperlinks")
+;;      (find-psne-intro "Local copies")
+;;      (find-brxxx-intro)
+;;
+;; The main functions here are `code-brurl' and `code-brfile', that
+;; lets us mass-define "brxxx functions" based on a given function
+;; that expects urls - in the case of `code-brurl' - or on a function
+;; that expects file names - in the case of `code-brfile'.
+;;
+;; Try these tests to see the kind of code that is generated:
+;;
+;;   (find-code-brurl  'find-foo :remote 'brfoo :local 'brfool :dired 'brfood)
+;;   (find-code-brfile 'find-bar                :local 'brbarl :dired 'brbard)
+;;
+;; The functions `brfoo', `brfool' and `brbarl' operate on the
+;; url-at-point, and the functions `brfood' and `brbard' operate on
+;; the file at the current line and only work in dired mode. The
+;; functions `brfool' and `brbarl' call `find-foo' and `find-bar' on
+;; the _local copy_ of the url that they receive, like this:
+;;
+;;   (brfool "http://some/url";)
+;;     --> (find-foo (ee-url-to-local-url "http://some/url";))
+;;     --> (find-foo (concat "file://" (ee-expand "$S/http/some/url")))
+;;
+;;   (brbarl "http://some/url";)
+;;     --> (find-bar (ee-url-to-fname "http://some/url";))
+;;     --> (find-bar (ee-expand "$S/http/some/url"))
+;;
+;; Try the sexps above with:
+;;
+;;   (defun find-foo (url)   (find-2a nil '(find-estring url)))
+;;   (defun find-bar (fname) (find-2a nil '(find-estring fname)))
+;;   (code-brurl  'find-foo :remote 'brfoo :local 'brfool :dired 'brfood)
+;;   (code-brfile 'find-bar                :local 'brbarl :dired 'brbard)
+;;
+;; The idea of local copies is explained here:
+;;
+;;   (find-psne-intro "Local copies")
+;;
+;;
+;;
+;; This file, i.e.: (find-eev "eev-brxxx.el")
+;; supersedes:      (find-eev "eev-browse-url.el")
+;; but eev-browse-url.el still has some nice comments that I would
+;; like to bring here.
+
+
+;; �.code-brurl�               (to "code-brurl")
+;; �.ee-code-brurl-rest�       (to "ee-code-brurl-rest")
+;; �.code-brfile�              (to "code-brfile")
+;; �.ee-code-brfile-rest�      (to "ee-code-brfile-rest")
+;; �.code-brxxxs�              (to "code-brxxxs")
+
 
-(autoload 'browse-url-interactive-arg "browse-url")
 
+(require 'eev-code)                    ; (find-eev "eev-code.el")
 
+(autoload 'browse-url-interactive-arg "browse-url")
 
 
 ;;;                                    _                 
@@ -47,8 +100,6 @@
 ;;; | (_| (_) | | | \ V /  __/ |  \__ \ | (_) | | | \__ \
 ;;;  \___\___/|_| |_|\_/ \___|_|  |___/_|\___/|_| |_|___/
 ;;;                                                      
-;; See: (find-brxxx-intro)
-
 ;; Here we define some conversion functions that are used by
 ;; `code-brurl' and `code-brfile'.
 ;;
@@ -117,7 +168,7 @@ This should be made smarter - file:// urls should be 
returned unchanged."
 ;;;                                                     
 ;; (find-tail-call-links "brurl" "f")
 
-;; code-brurl: top-level functions
+;; �code-brurl� (to ".code-brurl")
 ;;
 (defun      code-brurl (f &rest rest)
   "Define a family of brxxx functions from a function that operates on URLs"
@@ -130,6 +181,7 @@ This should be made smarter - file:// urls should be 
returned unchanged."
 ;; {(ee-S `(find-code-brurl ',f ,@(mapcar 'ee-add-quote rest)))}
 ")  (ee-code-brurl-rest rest)))
 
+;; �ee-code-brurl-rest� (to ".ee-code-brurl-rest")
 ;; Support for extra arguments
 ;;
 (defun ee-code-brurl-rest (rest)
@@ -185,6 +237,7 @@ This should be made smarter - file:// urls should be 
returned unchanged."
 ;;;                                                     
 ;; (find-tail-call-links "brfile" "f")
 
+;; �code-brfile� (to ".code-brfile")
 ;; code-brfile: top-level functions
 ;;
 (defun      code-brfile (f &rest rest)
@@ -198,6 +251,7 @@ This should be made smarter - file:// urls should be 
returned unchanged."
 ;; {(ee-S `(find-code-brfile ',f ,@(mapcar 'ee-add-quote rest)))}
 ")  (ee-code-brfile-rest rest)))
 
+;; �ee-code-brfile-rest� (to ".ee-code-brfile-rest")
 ;; Support for extra arguments
 ;;
 (defun ee-code-brfile-rest (rest)
@@ -224,9 +278,16 @@ This should be made smarter - file:// urls should be 
returned unchanged."
                              ({f} fname))))
 ")  (ee-code-brfile-rest rest)))
 
-;; Tests:
-;; (find-code-brurl  'pluc :remote 'brpluc :local 'brplucl :dired 'brplucd)
-;; (find-code-brfile 'plic                 :local 'brplicl :dired 'brplicd)
+
+
+
+;;;                _            _                               
+;;;   ___ ___   __| | ___      | |__  _ ____  ____  ____  _____ 
+;;;  / __/ _ \ / _` |/ _ \_____| '_ \| '__\ \/ /\ \/ /\ \/ / __|
+;;; | (_| (_) | (_| |  __/_____| |_) | |   >  <  >  <  >  <\__ \
+;;;  \___\___/ \__,_|\___|     |_.__/|_|  /_/\_\/_/\_\/_/\_\___/
+;;;                                                             
+;; �code-brxxxs� (to ".code-brxxxs")
 
 ;; See:
 ;; (find-eev "eev-blinks.el" "find-w3m")
@@ -246,6 +307,7 @@ This should be made smarter - file:// urls should be 
returned unchanged."
 
 
 (defun find-googlechrome (url) (find-bgprocess `("google-chrome" ,url)))
+(defun find-firefox      (url) (find-bgprocess `("firefox"       ,url)))
 
 
 ;; These are defined elsewhere.
@@ -278,7 +340,5 @@ This should be made smarter - file:// urls should be 
returned unchanged."
 
 ;; Local Variables:
 ;; coding:            raw-text-unix
-;; ee-anchor-format:  "�%s�"
-;; ee-anchor-format:  "defun %s "
 ;; no-byte-compile:   t
 ;; End:
diff --git a/eev-intro.el b/eev-intro.el
index f6c5dc0..3ec0828 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -6081,8 +6081,21 @@ This will make emacs invoke the default browser on that 
URL. See:
 
   (find-enode \"Browse-URL\")
 
-Eev defines several functions similar to `browse-url', but they are
-presently considered advanced features. See:
+Eev defines several functions similar to `browse-url'. These elisp
+hyperlinks
+
+  (find-firefox      \"http://www.lua.org/start.html\";)
+  (find-googlechrome \"http://www.lua.org/start.html\";)
+
+invoke \"firefox\" and \"google-chrome\" respectively on the given URL;
+note that the \"firefox\" in a Debian-based system is usually a free
+derivative of Firefox, and that \"google-chrome\" does not come
+installed by default because it is \"gratis\" but not free. Also,
+
+  M-x brff   -- runs `find-firefox' on the URL at point,
+  M-x brg    -- runs `find-googlechrome' on the URL at point.
+
+For more on the \"brxxx functions\" of eev, see:
 
   (find-brxxx-intro)
 
diff --git a/eev-wrap.el b/eev-wrap.el
index 3a05bc8..78da0a9 100644
--- a/eev-wrap.el
+++ b/eev-wrap.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2017jul31
+;; Version:    2019jan29
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-wrap.el>
@@ -324,7 +324,7 @@ have to run an \"undo\"."
   "An internal function used by `eewrap-pdflike'."
   (ee-template0 "\
 ;; (find-fline {(ee-S (file-name-directory fname))})
-\(code-xpdf     \"{stem}\" \"{fname}\")
+\(code-pdf-page \"{stem}\" \"{fname}\")
 \(code-pdf-text \"{stem}\" \"{fname}\")
 ;; \(find-{stem}page)
 ;; \(find-{stem}text)