[elpa] externals/eev 4e306ac 04/12: Rewrote `(find-pdf-like-intro)'.

[Stefan Monnier]

branch: externals/eev
commit 4e306acb7aab0e40e87c5d61460bc7f9f1dafd15
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>

    Rewrote `(find-pdf-like-intro)'.
---
 ChangeLog      |  28 ++
 VERSION        |   4 +-
 eev-elinks.el  |  19 +-
 eev-intro.el   | 786 ++++++++++++++++++++++++++++++++++++---------------------
 eev-pdflike.el |   8 +-
 eev-tlinks.el  |  22 +-
 6 files changed, 561 insertions(+), 306 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 87c5a73..f35ec6c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,31 @@
+2019-07-12  Eduardo Ochs  <address@hidden>
+
+       * eev-intro.el (find-pdf-like-intro): rewrote completely.
+
+2019-07-11  Eduardo Ochs  <address@hidden>
+
+       * eev-pdflike.el (ee-find-xpdf-page): added "&rest rest".
+       (ee-find-pdf-text): added "&rest rest".
+       (ee-find-pdftotext-text): added "&rest rest".
+
+2019-07-10  Eduardo Ochs  <address@hidden>
+
+       * eev-intro.el (find-eev-quick-intro): rewrote the section "9.3.
+       Hyperlinks to PDF files" and split it in two; the new section is:
+       "9.4. Hyperlinks to pages of PDF files". The old section 9.4,
+       "9.4. Shorter hyperlinks to PDF files", was renumbered to 9.5 and
+       split into "9.5. Shorter hyperlinks to PDF files" and "9.6. A
+       convention on page numbers".
+
+2019-07-09  Eduardo Ochs  <address@hidden>
+
+       * eev-tlinks.el (find-git-links): small changes.
+
+2019-07-04  Eduardo Ochs  <address@hidden>
+
+       * eev-elinks.el (find-code-pdf-links): show shorter variants of
+       the first sexp when possible.
+
 2019-06-29  Eduardo Ochs  <address@hidden>
 
        * eev-wrap.el (eeit, ee-insert-test, ee-insert-test-lua)
diff --git a/VERSION b/VERSION
index d0f28fc..b64904b 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Sat Jun 29 18:48:47 GMT 2019
-Sat Jun 29 15:48:47 -03 2019
+Fri Jul 12 04:30:42 GMT 2019
+Fri Jul 12 01:30:42 -03 2019
diff --git a/eev-elinks.el b/eev-elinks.el
index b8b07e3..1001cd5 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019jun24
+;; Version:    2019jul12
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-elinks.el>
@@ -947,8 +947,10 @@ See: (find-pdf-like-intro)
   (apply 'find-elinks `(
     (find-pdflike-page-links ,page ,bufname ,offset ,@rest)
     ;; (find-efunction 'find-pdflike-page-links)
-    (find-eev-quick-intro "10.4. Generating short hyperlinks to PDFs")
-    (find-eev-quick-intro "11.1. `find-pdf-links'")
+    ;; (find-eev-quick-intro "10.4. Generating short hyperlinks to PDFs")
+    ;; (find-eev-quick-intro "11.1. `find-pdf-links'")
+    (find-pdf-like-intro "10. Generating a pair with the page number")
+    (find-pdf-like-intro "11. How `M-h M-p' guesses everything")
     ""
     ,@(ee-pdflike-page-links page bufname offset)
     ) rest))
@@ -1328,12 +1330,17 @@ See: (find-here-links-intro \"5. `find-here-links-1'\")"
     (apply 'find-elinks-elisp
      `((find-code-pdf-links ,fname ,c ,@pos-spec-list)
        ;; Convention: the first sexp always regenerates the buffer.
+       ;; Shortened versions of the first sexp:
+       ,(ee-if-prefixp "~/"  "~/"  fname '`(find-code-pdf-links ,fname+ ,c))
+       ,(ee-if-prefixp "$S/" "$S/" fname '`(find-code-pdf-links ,fname+ ,c))
+       ;;
        ;; (find-efunction 'find-code-pdf-links)
        ,(ee-template0 "\
 ;; See: (find-eev-quick-intro \"9.1. `code-c-d'\")
-;;      (find-eev-quick-intro \"9.3. Hyperlinks to PDF files\")
-;;      (find-eev-quick-intro \"9.4. Shorter hyperlinks to PDF files\")
-;;      (find-eev-quick-intro \"11.1. `find-pdf-links'\")
+;;      (find-pdf-like-intro \"3. Hyperlinks to PDF files\")
+;;      (find-pdf-like-intro \"7. Shorter hyperlinks to PDF files\")
+;;      (find-pdf-like-intro \"9. Generating three pairs\")
+;;      (find-pdf-like-intro \"9. Generating three pairs\" \"`M-h M-p'\")
 
 ;; (find-fline {(ee-S (file-name-directory fname))})
 \(code-c-d \"{c}\" \"{(file-name-directory fname)}\")
diff --git a/eev-intro.el b/eev-intro.el
index 55cc0bb..2b3082d 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019jun24
+;; Version:    2019jul12
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -1398,75 +1398,163 @@ For the technical details of the implementation, see 
here:
 
 9.3. Hyperlinks to PDF files
 ----------------------------
-If you run this e-script
+Let's start by downloading a PDF file to use in our examples. If you
+run this e-script
 
  (eepitch-shell)
  (eepitch-kill)
  (eepitch-shell)
-#         https://tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
-mkdir -p $S/https/tannerlectures.utah.edu/_documents/a-to-z/c/
-cd       $S/https/tannerlectures.utah.edu/_documents/a-to-z/c/
-wget -nc  https://tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
+  cd
+  wget -nc https://tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
 
 you will download a local copy of J.M. Coetzee's \"The Lives of
-Animals\" into this directory:
+Animals\" into your home directory. To check that the PDF has been
+downloaded, use:
 
-  (find-fline      \"$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/\")
-  (find-fline \"~/snarf/https/tannerlectures.utah.edu/_documents/a-to-z/c/\")
+  (find-fline \"~/\")
+  (find-fline \"~/\"  \"Coetzee99.pdf\")
+  (find-sh0 \"ls -l ~/Coetzee99.pdf\")
+
+Eev also implements another way, called \"psne\", to download local
+copies of files from the internet. \"Psne-ing\" a URL like
+
+  https://tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
+
+downloads it to a local file with a name like:
 
-The full idea behind these \"local copies\" is explained here:
+       $S/https/tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
+  ~/snarf/https/tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
+
+that is _much_ longer that just \"~/Coetzee99.pdf\", but that has the
+advantage of preserving more information about the URL from which the
+file came. Sometimes this extra information feels clumsy, though.
+Psne-ing is discussed a more advanced tutorial,
 
   (find-psne-intro)
 
-If you have xpdf installed then the second sexp here,
+but let's use the home directory for the moment.
+
+If you have xpdf installed then this sexp
+
+  (find-pdf-page \"~/Coetzee99.pdf\")
 
-  (setq l-o-a 
\"$S/https/tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf\")
-  (find-pdf-page l-o-a)
+should work as a \"hyperlink to the PDF\": it calls xpdf as external
+program - like we did with browsers in section 3.1 - to display the
+PDF file that we downloaded.
 
-should work as a \"hyperlink to the PDF\": it calls xpdf as
-external program to open that PDF file. The main keys of xpdf
-are:
+The main keys of xpdf are:
 
   q         quit xpdf
-  alt-f     toggle full-screen; use twice to fit document to page
   PageDown  scroll down/go to next page
   PageUp    scroll up/go to previous page
-  0         set zoom to 125%
+  arrows    scroll within the current page
   +         zoom in one step
   -         zoom out out step
-  arrows    scroll within the current page
+  0         set zoom to 125%
+  alt-f     toggle full-screen; use twice to fit document to page
+
+Note that `q' \"goes back to Emacs\".
 
-Also, if you have the program pdftotext installed (hint: apt-get
-install poppler-utils!) then this
+If you have the program pdftotext installed - hint: \"apt-get install
+poppler-utils\"! - then you can also display PDFs in another way. This
+sexp
 
-  (find-pdf-text l-o-a)
+  (find-pdf-text \"~/Coetzee99.pdf\")
 
-should work as a \"hyperlink to the text of the PDF\".
+work as a \"hyperlink to the _text_ of the PDF\": it extracts the text
+from the PDF using the program \"pdftotext\" and displays that in an
+Emacs buffer.
 
-You can use these two sexps
 
-  (ee-find-pdf-text l-o-a)
-  (ee-find-pdf-page l-o-a)
 
-to see exactly how the `find-pdf-page' and the `find-pdf-text'
-sexps above invoke xpdf and pdftotext; note that `find-pdf-page'
-uses `find-bgprocess' and `find-pdf-text' uses `find-sh'.
 
-The functions above accept extra arguments, that are interpreted
-as a page number and as strings to look for, but it's easier to
-discuss them using shorter hyperlinks.
+9.4. Hyperlinks to pages of PDF files
+-------------------------------------
+It is possible to create hyperlinks that point to a specific page in a
+PDF file. Compare what happens when you run these sexps:
+
+  (find-pdf-page \"~/Coetzee99.pdf\")
+  (find-pdf-page \"~/Coetzee99.pdf\" 1)
+  (find-pdf-page \"~/Coetzee99.pdf\" 1 \"The Lives of Animals\")
+  (find-pdf-page \"~/Coetzee99.pdf\" 3)
+  (find-pdf-page \"~/Coetzee99.pdf\" 3 \"LECTURE I\")
+  (find-pdf-page \"~/Coetzee99.pdf\" 3 \"LECTURE I\" \"[113]\")
+
+The top three sexps open the PDF at page 1 - the default. The bottom
+three sexps open it at page 3. The arguments after the number are
+ignored by Emacs - they are there to make these links more expressive
+for humans.
+
+The hyperlinks to the text of a PDF interpret the numeric number as a
+page number and the following arguments as strings to search for. Try:
+
+  (find-pdf-text \"~/Coetzee99.pdf\" 1)
+  (find-pdf-text \"~/Coetzee99.pdf\" 1 \"The Lives of Animals\")
+  (find-pdf-text \"~/Coetzee99.pdf\" 3)
+  (find-pdf-text \"~/Coetzee99.pdf\" 3 \"LECTURE I\")
+  (find-pdf-text \"~/Coetzee99.pdf\" 3 \"LECTURE I\" \"[113]\")
+
+For more information about these string arguments, see:
+
+  (find-refining-intro \"1. Pos-spec-lists\")
+
+A pair of sexps like this, in which both point to the same
+position of a PDF,
+
+  (find-pdf-page \"~/Coetzee99.pdf\" 3 \"LECTURE I\" \"[113]\")
+  (find-pdf-text \"~/Coetzee99.pdf\" 3 \"LECTURE I\" \"[113]\")
+
+will be called a `find-pdf'-pair.
+
+Both `find-pdf-page' and `find-pdf-text' invoke external programs -
+but how, exactly? Let's take a look at a hack that shows this. If you
+prepend an \"ee-\" to `find-pdf-page' and `find-pdf-text' sexps, like
+in:
+
+  (ee-find-pdf-page \"~/Coetzee99.pdf\")
+  (ee-find-pdf-page \"~/Coetzee99.pdf\" 3)
+  (ee-find-pdf-text \"~/Coetzee99.pdf\")
+  (ee-find-pdf-text \"~/Coetzee99.pdf\" 3)
 
+you will get sexps that stop just before invoking the external
+programs - they just show how these externals programs _would be_
+invoked, i.e., they show the options that would be passed to them. The
+results of the sexps above will be lists like these:
 
+  (\"xpdf\" \"-fullscreen\" \"~/Coetzee99.pdf\")
+  (\"xpdf\" \"-fullscreen\" \"~/Coetzee99.pdf\" \"3\")
+  (\"pdftotext\" \"-layout\" \"-enc\" \"Latin1\" \"~/Coetzee99.pdf\" \"-\")
+  (\"pdftotext\" \"-layout\" \"-enc\" \"Latin1\" \"~/Coetzee99.pdf\" \"-\")
 
+Note that `ee-find-pdf-text' does not pass the argument \"3\" to
+\"pdftotext\". A sexp like
 
-9.4. Shorter hyperlinks to PDF files
+  (find-pdf-text \"~/Coetzee99.pdf\" 3)
+
+first produces the conversion to text of the full PDF, and then
+finds the page 3 in it by counting formfeeds, as described here:
+
+  (find-enode \"Pages\" \"formfeed\")
+
+In this pair of sexps,
+
+  (find-livesofanimalspage (+ -110 113) \"LECTURE I.\")
+  (find-livesofanimalstext (+ -110 113) \"LECTURE I.\")
+
+
+
+
+
+
+9.5. Shorter hyperlinks to PDF files
 ------------------------------------
 If you run these sexps
 
-  (code-pdf-page \"livesofanimals\" l-o-a)
-  (code-pdf-text \"livesofanimals\" l-o-a -110)
+  (code-pdf-page \"livesofanimals\" \"~/Coetzee99.pdf\")
+  (code-pdf-text \"livesofanimals\" \"~/Coetzee99.pdf\" -110)
 
-then these hyperlinks should work:
+they will define the functions `find-livesofanimalspage' and
+`find-livesofanimalstext', and then these hyperlinks should work:
 
   (find-livesofanimalspage)
   (find-livesofanimalstext)
@@ -1491,20 +1579,59 @@ then these hyperlinks should work:
   (find-livesofanimalspage (+ -110 164) \"last common ground\")
   (find-livesofanimalstext (+ -110 164) \"last common ground\")
 
-The sexps like `(+ -110 113)' are a bit mysterious at first
-sight. We are accessing a PDF that is an excerpt of a book. The
-third page of the PDF has a \"[113]\" at its footer to indicate
-that it is the page 113 of the book. Let's use the terms _page
-number_ and _page label_ to distinguish the two numberings: in
-this case, the page whose page number is 3 is the page whose page
-label is 113. These two sexps
+Hyperlinks like
+
+  (find-livesofanimalspage (+ -110 113) \"LECTURE I.\")
+  (find-livesofanimalstext (+ -110 113) \"LECTURE I.\")
+
+behave roughly as abbreviations for:
+
+  (find-pdf-page \"~/Coetzee99.pdf\" (+ -110 113) \"LECTURE I.\")
+  (find-pdf-text \"~/Coetzee99.pdf\" (+ -110 113) \"LECTURE I.\")
+
+Let's introduce some terminology. Remember that we call a pair of
+sexps like
+
+  (find-pdf-page \"~/Coetzee99.pdf\" (+ -110 113) \"LECTURE I.\")
+  (find-pdf-text \"~/Coetzee99.pdf\" (+ -110 113) \"LECTURE I.\")
+
+a \"`find-pdf'-pair\"; a pair like
+
+  (find-livesofanimalspage (+ -110 113) \"LECTURE I.\")
+  (find-livesofanimalstext (+ -110 113) \"LECTURE I.\")
+
+will be called a \"short `find-pdf'-pair\", and a pair like
+
+  (code-pdf-page \"livesofanimals\" \"~/Coetzee99.pdf\")
+  (code-pdf-text \"livesofanimals\" \"~/Coetzee99.pdf\" -110)
+
+will be called a `code-pdf'-pair.
+
+
+
+
+9.6. A convention on page numbers
+---------------------------------
+The `(+ -110 113)'s in
+
+  (find-livesofanimalspage (+ -110 113) \"LECTURE I.\")
+  (find-livesofanimalstext (+ -110 113) \"LECTURE I.\")
+
+are a bit mysterious at first sight. 
+
+We are accessing a PDF that is an excerpt of a book. The third
+page of the PDF has a \"[113]\" at its footer to indicate that it
+is the page 113 of the book. Let's use the terms _page number_
+and _page label_ to distinguish the two numberings: in this case,
+the page whose page number is 3 is the page whose page label is
+113. These two sexps
 
   (find-livesofanimalspage (+ -110 113))
   (find-livesofanimalspage 3)
 
 are equivalent, but the first one is more human-friendly: the 113
 is a page label, and the -110 is adjustment (we call it the
-\"offset\") to convert the 113 that humans prefer to see intto
+\"offset\") to convert the 113 that humans prefer to see into
 the 3 that xpdf needs to receive.
 
 Note that the sexp
@@ -1535,6 +1662,17 @@ hyperlink to a string in a page of a PDF.
 
 
 
+9.7. Generating links to PDFs
+-----------------------------
+If you run this
+
+  (find-code-pdf-links \"~/Coetzee99.pdf\")
+
+you will get a buffer with lots of hyperlinks, like this:
+
+
+
+
 
 10. Generating short hyperlinks
 ===============================
@@ -1628,7 +1766,7 @@ which is a short hyperlink to the intro.
 10.4. Generating short hyperlinks to PDFs
 -----------------------------------------
 We saw in sections 9.3 and 9.4 that after the right preparations
-the first of these hyperlinks
+the first of these hyperlinks - a \"short `find-pdf'-pair\" -
 
   (find-livesofanimalspage (+ -110 134) \"woke up haggard in the mornings\")
   (find-livesofanimalstext (+ -110 134) \"woke up haggard in the mornings\")
@@ -5462,16 +5600,18 @@ It is meant as both a tutorial and a sandbox.
 
 
 
+Note: this intro is being rewritten!
+Some sections of the main tutorial
 
-Note: this intro needs to be rewritten!
-Ideally it should _complement_ the material in:
-  (find-eev-quick-intro \"9.3. Hyperlinks to PDF files\")
+  (find-eev-quick-intro)
 
+are being moved to here...
 
 
 
-PDF-like documents
-==================
+
+1. PDF-like documents
+=====================
 Let's introduce a bit of (improvised!) terminology: we will say
 that a document is \"PDF-like\" when it is in a format like PDF,
 PostScript, DVI or DJVU - i.e., divided into pages. Emacs has a
@@ -5485,309 +5625,387 @@ PDF-like documents.
 
 
 
-Two test documents
-==================
-The following script creates two PDF-like documents - a DVI and a
-PDF - that we will use in the examples below.
+2. Preparation
+==============
+We need to start by downloading a PDF file to use in our
+examples. If you run this e-script
 
  (eepitch-shell)
  (eepitch-kill)
  (eepitch-shell)
-cd /tmp/
-cat > /tmp/foo.tex <<'%%%'
-\\documentclass[12pt,oneside]{book}
-\\begin{document}
-\\Huge
-\\frontmatter
-a \\newpage
-b \\newpage
-c \\newpage
-\\mainmatter
-\\chapter{One}
-\\newpage foo
-\\chapter{Two}
-\\end{document}
-%%%
-   latex foo.tex
-pdflatex foo.tex
+  cd
+  wget -nc https://tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
 
-In these two documents the page _names_ do not correspond to the
-page _numbers_; the pages are named \"i\", \"ii\", \"iii\",
-\"1\", \"2\", \"3\", but their numbers are 1, 2, 3, 4, 5, 6.
-In a table:
+you will download a local copy of J.M. Coetzee's \"The Lives of
+Animals\" into your home directory. To check that the PDF has been
+downloaded, use:
 
-  number  name  contents
-  ----------------------
-    1        i      a
-    2       ii      b
-    3      iii      c
-    4        1      Chapter 1 - One
-    5        2      foo
-    6        3      Chapter 3 - Two
+  (find-fline \"~/\")
+  (find-fline \"~/\"  \"Coetzee99.pdf\")
+  (find-sh0 \"ls -l ~/Coetzee99.pdf\")
 
+Eev also implements another way, called \"psne\", to download
+local copies of files from the internet.\"Psne-ing\" a URL like
 
+  https://tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
 
+downloads it to a local file with a name like:
 
-Using external viewers
-======================
-The following sexps can be used to open the documents
-\"/tmp/foo.dvi\" and \"/tmp/foo.pdf\" on the first page of
-Chapter 1 - i.e., the page whose number is 4, and whose \"name\"
-is 1 - using two of my favorite viewers, xdvi and xpdf, and a
-low-level function, `find-bgprocess':
+       $S/https/tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
+  ~/snarf/https/tannerlectures.utah.edu/_documents/a-to-z/c/Coetzee99.pdf
 
-  (find-bgprocess '(\"xdvi\" \"+4\" \"/tmp/foo.dvi\"))
-  (find-bgprocess '(\"xpdf\" \"/tmp/foo.pdf\" \"4\"))
+that is _much_ longer that just \"~/Coetzee99.pdf\"; this has the
+advantage of preserving more information about the URL from which
+the file came, but sometimes these longer names feels clumsy.
+Psne-ing is discussed a more advanced tutorial:
 
-Alternatively, we can invoke these viewers like this,
+  (find-psne-intro)
 
-  (find-xdvi-page \"/tmp/foo.dvi\" 4)
-  (find-xpdf-page \"/tmp/foo.pdf\" 4)
+In this tutorial we will use the home directory and the shorter
+file name.
 
-or, as they ignore extra arguments, like this,
 
-  (find-xdvi-page \"/tmp/foo.dvi\" (+ 3 1) \"Chapter 1\")
-  (find-xpdf-page \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
 
-where the `(+ 3 1)' and the \"Chapter 1\" are just to make these
-links more readable by humans. The `3' is what we will call the
-\"offset\" of the document: a quantity that can be added to page
-\"names\" (outside the \"front matter\" of the document) to
-convert them to page \"numbers\".
 
-Let's introduce more terminology. Programs like xdvi and xpdf are
-\"external viewers for PDF-like documents\", but that's too long,
-so let's shorten this to \"external PDF-like viewers\", or
-\"external viewers\", or just \"viewers\"; `find-xdvi-page',
-`find-xpdf-page' and similar functions are \"medium-level viewing
-words\".
+3. Hyperlinks to PDF files
+==========================
+If you have xpdf installed then this sexp
 
+  (find-pdf-page \"~/Coetzee99.pdf\")
 
+should work as a \"hyperlink to the PDF\": it calls xpdf as an
+external program - like we did with browsers in the main tutorial -
 
+  (find-eev-quick-intro \"3.1. Non-elisp hyperlinks\")
+  (find-eev-quick-intro \"3.1. Non-elisp hyperlinks\" \"find-firefox\")
 
-The high-level way
-==================
-File names of PDF-like documents are often very long - especially
-for documents that we have \"psne\"-ed from the web. To avoid
-having to keep copies of these file names everywhere we can use
-`code-c-d'-like words - like these:
+to display the PDF file that we downloaded.
 
-  (code-xdvi \"fd\" \"/tmp/foo.dvi\")
-  (code-xpdf \"fp\" \"/tmp/foo.pdf\")
-  (find-fdpage (+ 3 1) \"Chapter 1\")
-  (find-fppage (+ 3 1) \"Chapter 1\")
+The main keys of xpdf are:
 
-Each medium-level viewing word has an associated code-c-d-like
-word - that creates \"high-level viewing words\". In the example
-above, we used `code-xdvi' to create the high-level viewing word
-`find-fdpage', that invokes `find-xdvi-page', and `code-xpdf' to
-create the high-level viewing word `find-fppage', which invokes
-`find-xpdf-page',
+  q         quit xpdf
+  PageDown  scroll down/go to next page
+  PageUp    scroll up/go to previous page
+  arrows    scroll within the current page
+  +         zoom in one step
+  -         zoom out out step
+  0         set zoom to 125%
+  alt-f     toggle full-screen; use twice to fit document to page
 
-Note that the \"fd\" in `find-fdpage' stands for not only the
-filename - \"/tmp/foo.dvi\" - but also for the medium-level word
-to be used - `find-xdvi-page'; same for \"fp\".
+Note that `q' \"goes back to Emacs\".
 
+If you have the program pdftotext installed - hint: \"apt-get install
+poppler-utils\"! - then you can also display PDFs in another way. This
+sexp
 
+  (find-pdf-text \"~/Coetzee99.pdf\")
 
+work as a \"hyperlink to the _text_ of the PDF\": it extracts the text
+from the PDF using the program \"pdftotext\" and displays that in an
+Emacs buffer.
 
-Default external viewers
-========================
-We saw that for each of the supported formats of PDF-like
-documents - DVI, PostScript, PDF, DJVU - there are medium-level
-and high-level viewing words that use specific programs; for
-example, for \"xpdf\" we have `find-xpdf-page' and `code-xpdf',
-and for \"evince\" we have `find-evince-page' and `code-evince'.
-But for each of the formats we also have words that use the
-current default viewer for that format:
 
-  Format       Medium-level     High-level
-  ----------------------------------------
-  DVI          find-dvi-page    code-dvi
-  PostScript   find-ps-page     code-ps
-  PDF          find-pdf-page    code-pdf
-  DJVU         find-djvu-page   code-djvu
 
-The four `find-<formatname>-page' words above are aliases to
-`find-<viewername>-page' names, and to change a default viewer
-you should use a `defalias' on the `find-', like these:
 
-  (defalias 'find-pdf-page 'find-evince-page)
-  (defalias 'find-pdf-page 'find-xdpf-page)
+4. Hyperlinks to pages of PDF files
+===================================
+It is possible to create hyperlinks that point to a specific page in a
+PDF file. Compare what happens when you run these sexps:
 
-After running a `defalias' like the above all the high-level
-viewing words defined using `code-pdf' will automatically switch
-to the new default viewer (because words defined with `code-pdf'
-call `find-pdf-page').
+  (find-pdf-page \"~/Coetzee99.pdf\")
+  (find-pdf-page \"~/Coetzee99.pdf\" 1)
+  (find-pdf-page \"~/Coetzee99.pdf\" 1 \"The Lives of Animals\")
+  (find-pdf-page \"~/Coetzee99.pdf\" 3)
+  (find-pdf-page \"~/Coetzee99.pdf\" 3 \"LECTURE I\")
+  (find-pdf-page \"~/Coetzee99.pdf\" 3 \"LECTURE I\" \"[113]\")
 
+The top three sexps open the PDF at page 1 - the default. The bottom
+three sexps open it at page 3. The arguments after the number are
+ignored by Emacs - they are there to make these links more expressive
+for humans.
 
+The hyperlinks to the text of a PDF interpret the numeric number as a
+page number and the following arguments as strings to search for. Try:
 
+  (find-pdf-text \"~/Coetzee99.pdf\" 1)
+  (find-pdf-text \"~/Coetzee99.pdf\" 1 \"The Lives of Animals\")
+  (find-pdf-text \"~/Coetzee99.pdf\" 3)
+  (find-pdf-text \"~/Coetzee99.pdf\" 3 \"LECTURE I\")
+  (find-pdf-text \"~/Coetzee99.pdf\" 3 \"LECTURE I\" \"[113]\")
 
-PDF-like documents as text
-==========================
-Some PDF-like documents can be converted to text - usually uglily
-and imprecisely, but the result is often useful anyway - by
-external programs like \"pdftotext\" and \"djvutxt\". The
-medium-level sexps below invoke these programs on the given
-filenames and displays their output in an Emacs buffer:
+For more information about these string arguments, see:
 
-  (find-pdftotext-text \"/tmp/foo.pdf\")
-  (find-djvutxt-text   \"/tmp/foo.djvu\")
+  (find-refining-intro \"1. Pos-spec-lists\")
 
-We can also use the correspondent generic medium-level words,
-that are aliases to the default converters:
+A pair of sexps like this, in which both point to the same
+position of a PDF,
 
-  (find-pdf-text  \"/tmp/foo.pdf\")
-  (find-djvu-text \"/tmp/foo.djvu\")
+  (find-pdf-page \"~/Coetzee99.pdf\" 3 \"LECTURE I\" \"[113]\")
+  (find-pdf-text \"~/Coetzee99.pdf\" 3 \"LECTURE I\" \"[113]\")
 
-As the output of these converters is also divided into pages -
-with formfeeds as separators - it is easy to jump to specific
-pages in the output, and if the first argument after the file
-name is a number it is interpreted as a page number; string
-arguments coming after that are interpreted as strings to be
-search (forward) for. So these links make sense:
+will be called a `find-pdf'-pair.
 
-  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
-  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
 
-and note that the following pair of links make sense too - the
-first one calls an external viewer, the second one opens the
-conversion to text:
 
-  (find-pdf-page \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
-  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
 
-Note that they both point to the same page... The argument
-\"Chapter 1\" is ignored in the first link, but when a pair of
-links like that appear on consecutive lines it is clear for human
-readers that they are both links to the same place, only rendered
-in different ways. Note that the passage from this:
+5. A convention on page numbers
+===============================
+The `(+ -110 113)'s in
 
-  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
+  (find-livesofanimalspage (+ -110 113) \"LECTURE I.\")
+  (find-livesofanimalstext (+ -110 113) \"LECTURE I.\")
 
-to this:
+are a bit mysterious at first sight. 
 
-  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1))
-  (find-pdf-text \"/tmp/foo.pdf\" (+ 3 1) \"Chapter 1\")
+We are accessing a PDF that is an excerpt of a book. The third
+page of the PDF has a \"[113]\" at its footer to indicate that it
+is the page 113 of the book. Let's use the terms _page number_
+and _page label_ to distinguish the two numberings: in this case,
+the page whose page number is 3 is the page whose page label is
+113. These two sexps
 
-is a special case of \"refining hyperlinks\", an idea that we saw
-in:
+  (find-livesofanimalspage (+ -110 113))
+  (find-livesofanimalspage 3)
 
-  (find-eval-intro \"Refining hyperlinks\")
+are equivalent, but the first one is more human-friendly: the 113
+is a page label, and the -110 is adjustment (we call it the
+\"offset\") to convert the 113 that humans prefer to see into
+the 3 that xpdf needs to receive.
 
 
 
 
-High-level hyperlinks to pdf-like documents
-===========================================
-By executing
 
-  (code-pdf      \"fp\" \"/tmp/foo.pdf\")
-  (code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+6. How the external programs are called
+=======================================
+Both `find-pdf-page' and `find-pdf-text' invoke external programs -
+but how, exactly? Let's take a look at a hack that shows this. If
+you prepend an \"ee-\" to `find-pdf-page' and `find-pdf-text' sexps,
+like in:
 
-we can use shorter hyperlinks, like
+  (ee-find-pdf-page \"~/Coetzee99.pdf\")
+  (ee-find-pdf-page \"~/Coetzee99.pdf\" 3)
+  (ee-find-pdf-text \"~/Coetzee99.pdf\")
+  (ee-find-pdf-text \"~/Coetzee99.pdf\" 3)
 
-  (find-fppage (+ 3 1) \"Chapter 1\")
-  (find-fptext (+ 3 1) \"Chapter 1\")
+you will get sexps that stop just before invoking the external
+programs - they just show how these externals programs _would be_
+invoked, i.e., they show the options that would be passed to them. The
+results of the sexps above will be lists like these:
 
-instead of the longer forms with `find-pdf-page' and
-`find-pdf-text'. This works exactly like `code-c-d', as explained
-here:
+  (\"xpdf\" \"-fullscreen\" \"~/Coetzee99.pdf\")
+  (\"xpdf\" \"-fullscreen\" \"~/Coetzee99.pdf\" \"3\")
+  (\"pdftotext\" \"-layout\" \"-enc\" \"Latin1\" \"~/Coetzee99.pdf\" \"-\")
+  (\"pdftotext\" \"-layout\" \"-enc\" \"Latin1\" \"~/Coetzee99.pdf\" \"-\")
 
-  (find-code-c-d-intro)
+Note that `ee-find-pdf-text' does not pass the argument \"3\" to
+\"pdftotext\". A sexp like
+
+  (find-pdf-text \"~/Coetzee99.pdf\" 3)
+
+first produces the conversion to text of the full PDF, and then
+finds the page 3 in it by counting formfeeds, as described here:
+
+  (find-enode \"Pages\" \"formfeed\")
+
+
+
+
+
+7. Shorter hyperlinks to PDF files
+==================================
+If you run these sexps
+
+  (code-pdf-page \"livesofanimals\" \"~/Coetzee99.pdf\")
+  (code-pdf-text \"livesofanimals\" \"~/Coetzee99.pdf\" -110)
+
+they will define the functions `find-livesofanimalspage' and
+`find-livesofanimalstext', and then these hyperlinks should work:
+
+  (find-livesofanimalspage)
+  (find-livesofanimalstext)
+  (find-livesofanimalspage (+ -110 113))
+  (find-livesofanimalstext (+ -110 113))
+  (find-livesofanimalspage (+ -110 113) \"LECTURE I.\")
+  (find-livesofanimalstext (+ -110 113) \"LECTURE I.\")
+  (find-livesofanimalspage (+ -110 127) \"wrong thoughts\")
+  (find-livesofanimalstext (+ -110 127) \"wrong thoughts\")
+  (find-livesofanimalspage (+ -110 132) \"into the place of their victims\")
+  (find-livesofanimalstext (+ -110 132) \"into the place of their victims\")
+  (find-livesofanimalspage (+ -110 134) \"woke up haggard in the mornings\")
+  (find-livesofanimalstext (+ -110 134) \"woke up haggard in the mornings\")
+  (find-livesofanimalspage (+ -110 143) \"Babies have no self-consciousness\")
+  (find-livesofanimalstext (+ -110 143) \"Babies have no self-consciousness\")
+  (find-livesofanimalspage (+ -110 145) \"squirrel doing its thinking\")
+  (find-livesofanimalstext (+ -110 145) \"squirrel doing its thinking\")
+  (find-livesofanimalspage (+ -110 147) \"Rilke's panther\")
+  (find-livesofanimalstext (+ -110 147) \"Rilke's panther\")
+  (find-livesofanimalspage (+ -110 162) \"a grasp of the meaning\")
+  (find-livesofanimalstext (+ -110 162) \"a grasp of the meaning\")
+  (find-livesofanimalspage (+ -110 164) \"last common ground\")
+  (find-livesofanimalstext (+ -110 164) \"last common ground\")
+
+Hyperlinks like
+
+  (find-livesofanimalspage (+ -110 113) \"LECTURE I.\")
+  (find-livesofanimalstext (+ -110 113) \"LECTURE I.\")
+
+behave roughly as abbreviations for:
+
+  (find-pdf-page \"~/Coetzee99.pdf\" (+ -110 113) \"LECTURE I.\")
+  (find-pdf-text \"~/Coetzee99.pdf\" (+ -110 113) \"LECTURE I.\")
+
+
+
+
+8. `find-pdf'-pairs
+===================
+Let's introduce some terminology. Remember that we call a pair of
+sexps like
+
+  (find-pdf-page \"~/Coetzee99.pdf\" (+ -110 113) \"LECTURE I.\")
+  (find-pdf-text \"~/Coetzee99.pdf\" (+ -110 113) \"LECTURE I.\")
+
+a \"`find-pdf'-pair\"; a pair like
+
+  (find-livesofanimalspage (+ -110 113) \"LECTURE I.\")
+  (find-livesofanimalstext (+ -110 113) \"LECTURE I.\")
+
+will be called a \"short `find-pdf'-pair\", as in:
+
+  (find-eev-quick-intro \"9. Shorter hyperlinks\")
+
+and a pair like
+
+  (code-pdf-page \"livesofanimals\" \"~/Coetzee99.pdf\")
+  (code-pdf-text \"livesofanimals\" \"~/Coetzee99.pdf\" -110)
+
+will be called a `code-pdf'-pair.
+
+The \"livesofanimals\" will the called the _stem_. The \"-110\"
+will be called the _offset_.
+
+
+
+
+9. Generating three pairs
+=========================
+Eev has a high-level function that generates at once, for a
+single PDF file, a `find-pdf'-pair, a `code-pdf'-pair, and a
+short `find-pdf'-pair. To see what it produces, try:
+
+  (find-code-pdf-links \"~/Coetzee99.pdf\")
+  (find-code-pdf-links \"~/Coetzee99.pdf\" \"livesofanimals\")
 
-Try these sexps to see the code that the `code-pdf' and the
-`code-pdf-text' above execute:
+`find-code-pdf-links' is somewhat similar to `find-latex-links',
+in this aspect:
 
-  (find-code-pdf      \"fp\" \"/tmp/foo.pdf\")
-  (find-code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
+  (find-eev-quick-intro \"7.5. `find-latex-links'\" \"change the 
\\\"{stem}\\\"\")
 
-There is a wrapping comand for producing these
-`code-pdf'/`code-pdf-text' pairs quickly - `M-P'. Try it here:
+If you run just
 
-  fp /tmp/foo.pdf
+  (find-code-pdf-links \"~/Coetzee99.pdf\")
 
+it will generate a buffer that has \"{c}\"s in several places and
+that follows the convention that \"the first line regenerates the
+buffer\". If you substitute the \"{c}\" in the top sexp by
+\"livesofanimals\" and type `M-e' the buffer will be recreated
+with each \"{c}\" replaced by \"livesofanimals\".
 
+The user-friendly way to run `find-code-pdf-links' is by typing
+`M-h M-p' in Dired mode. If you want to generate the three pairs
+for a file \"~/foo/bar/story.pdf\" then visit the directory
+\"~/foo/bar/\", put the cursor on the line that lists the file
+\"story.pdf\", and type `M-h M-p'. Try it with our test file:
 
+  (find-fline \"~/\"  \"Coetzee99.pdf\")
 
-Producing and refining hyperlinks to pages
+
+
+10. Generating a pair with the page number
 ==========================================
-We also have something like this
+If you type `M-h M-p' and you're not in Dired mode then `M-h M-p'
+will try to generate a short `find-pdf'-pair pointing to the
+current position in the current page of the current PDF
+file (converted to text). The function bound to `M-h M-p' tries
+to guess four things: the stem, the offset, the page number, and
+the string to the be used as a pos-spec. Let's see first a
+situation where everything works. Run the four sexps below and
+type `M-h M-p':
+
+  (code-pdf-page \"livesofanimals\" \"~/Coetzee99.pdf\")
+  (code-pdf-text \"livesofanimals\" \"~/Coetzee99.pdf\" -110)
+  (kill-new \"wrong thoughts\")
+  (find-livesofanimalstext (+ -110 127) \"wrong thoughts\")
 
-  (find-eval-intro \"Producing and refining hyperlinks\")
+You will get an elisp hyperlinks buffer whose middle links are
+four short `find-pdf'-pairs, all pointing to the current page:
+
+  # (find-livesofanimalspage 17)
+  # (find-livesofanimalstext 17)
+  # (find-livesofanimalspage (+ -110 127))
+  # (find-livesofanimalstext (+ -110 127))
+
+  # (find-livesofanimalspage 17 \"wrong thoughts\")
+  # (find-livesofanimalstext 17 \"wrong thoughts\")
+  # (find-livesofanimalspage (+ -110 127) \"wrong thoughts\")
+  # (find-livesofanimalstext (+ -110 127) \"wrong thoughts\")
+
+The second and the fourth pairs use \"(+ -110 127)\" instead of
+\"17\" as the page number; the third and the fourth pairs point
+to the string \"wrong thoughts\" in the page.
+
+
+
+
+11. How `M-h M-p' guesses everything
+====================================
+The method that `M-h M-p' uses to guess the stem, the offset, the
+page and the pos-spec is so error-prone and gives unexpected
+results so often that it's worth to describe it in detail.
+
+  1. The stem is taken from the global variable `ee-page-c'.
+
+  2. Every call to a function like `find-xxxtext' sets
+     `ee-page-c' to \"xxx\" - for example, a call to
+     `find-livesofanimalstext' sets `ee-page-c' to
+     \"find-livesofanimalstext\". So `ee-page-c' usually holds
+     the stem of the last function of the form `find-xxxtext'
+     that was run.
+
+  3. The offset is taken from the global variable
+     `ee-page-offset'.
+
+  4. A call to, say, `find-livesofanimalstext', sets
+     `ee-page-offset' to the offset that was declared here:
+
+       (code-pdf-text \"livesofanimals\" \"~/Coetzee99.pdf\" -110)
+
+     So `ee-page-offset' usually holds the offset of the last
+     function of the form `find-xxxtext' that was run.
+
+  5. The page number is obtained by counting the number of
+     formfeeds between the beginning of the buffer and the
+     current position. If there are 16 formfeeds then the current
+     page is 17.
+
+  6. The pos-spec - \"wrong thoughts\" in the example - is the
+     string in the top of the kill ring. See:
+
+       (find-refining-intro \"2. Refining hyperlinks\" \"kill-new\")
+
+If you want to see an example where `M-h M-p' guesses everything
+wrong you can type `M-h M-p' here... as we're not in Dired mode
+`M-h M-p' will think that we're in the conversion to text of
+\"livesofanimals\", in page 1, and it will generate hyperlinks to
+that page of the book!
+
+
+
+12. Another way to generate `code-pdf'-pairs
+============================================
+\[Explain M-P]
 
-for pdf-like documents, that will let us produce hyperlinks to
-the current page of the current pdf-like document very quickly,
-but it depends on several hacks.
-
-Note that the functions `code-pdf', `code-pdf-text',
-`find-xxxpage', `find-xxxtext', set the global variables
-`ee-page-c', `ee-page-fname', and `ee-page-offset'. You can
-inspect their definitions with:
-
-  (find-code-pdf      \"fp\" \"/tmp/foo.pdf\")
-  (find-code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
-
-Here's how these variables are used. Try this:
-
-  (code-pdf      \"fp\" \"/tmp/foo.pdf\")
-  (code-pdf-text \"fp\" \"/tmp/foo.pdf\" 3)
-  (kill-new \"Two\")
-  (eek \"M-h M-p\")
-
-You should get a page with several hyperlinks to the \"current
-page\" of the current pdf-like document, including some like
-these:
-
-  (find-fppage 1)
-  (find-fptext 1)
-  (find-fppage (+ 3 -2))
-  (find-fptext (+ 3 -2))
-
-  (find-fppage 1 \"Two\")
-  (find-fptext 1 \"Two\")
-  (find-fppage (+ 3 -2) \"Two\")
-  (find-fptext (+ 3 -2) \"Two\")
-
-Where did the \"fp\", the \"1\", the \"3\", the \"-2\" and the
-\"Two\" above come from?
-
-The page number, which in the links above is sometimes \"1\",
-sometimes \"(+ 3 -2)\", is obtained by counting the number of
-formfeeds before point; this makes sense only when we are
-visiting the buffer generated by \"(find-fptext ...)\". The
-\"fp\" is taken from the variable `ee-page-c', which was set by
-`(code-pdf-text \"fp\" ...)' or by `(find-fptext ...)'; same for \"3\",
-which is taken from the variable `ee-page-offset'. Finally, the \"Two\"
-is the last kill, from the top of the kill-ring; we usually set it by
-selecting a region of text from the `(find-fptext ...)' buffer and
-typing `M-w'.
-
-An alternative way to produce hyperlinks to pages, which, as the hack
-above, also uses `ee-page-c' and `ee-page-offset', is to prepare a
-series of lines with a page number followed by a text that will play a
-similar role to the \"last kill\", and then type `M-Q' on each line. Try
-this below, by first executing the `code-pdf-text' then typing four
-`M-Q's.
-
-  (code-pdf      \"debt\" \"~/books/graeber__debt.pdf\")
-  (code-pdf-text \"debt\" \"~/books/graeber__debt.pdf\" 8)
-
-   1 1 On The Experience of Moral Confusion
-  21 2 The Myth of Barter
-  43 3 Primordial Debts
-  73 4 Cruelty and Redemption
-
-It is usually not hard to produce such page-number-plus-text
-lines for `M-Q' from the table of contents of a book. The ones
-above were extracted from
-
-  (find-debttext 7 \"Contents\")
-
-with a bit of fiddling by hand and keyboard macros. Keyboard
-macros are VERY useful; if you don't use them yet, see:
-
-  (find-enode \"Keyboard Macros\")
 " rest)))
 
 ;; (find-pdf-like-intro)
diff --git a/eev-pdflike.el b/eev-pdflike.el
index 394ce8a..9f00ea0 100644
--- a/eev-pdflike.el
+++ b/eev-pdflike.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019jun24
+;; Version:    2019jul11
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-pdflike.el>
@@ -306,7 +306,7 @@ newline are spurious - and replaces them by \"(ff)\"."
         (code-xxxpdf-family "xpdf-page")
 
 (defvar ee-find-xpdf-page-options '("-fullscreen"))
-(defun  ee-find-xpdf-page (fname &optional page)
+(defun  ee-find-xpdf-page (fname &optional page &rest rest)
   `("xpdf"
     ,@ee-find-xpdf-page-options
     ,fname
@@ -346,10 +346,10 @@ newline are spurious - and replaces them by \"(ff)\"."
 
 (defvar ee-pdftotext-program "pdftotext")
 
-(defun ee-find-pdf-text (fname)
+(defun ee-find-pdf-text (fname &rest rest)
   `(,ee-pdftotext-program "-layout" "-enc" "Latin1" ,(ee-expand fname) "-"))
 
-(defun ee-find-pdftotext-text (fname)
+(defun ee-find-pdftotext-text (fname &rest rest)
   `(,ee-pdftotext-program "-layout" "-enc" "Latin1" ,(ee-expand fname) "-"))
 
 
diff --git a/eev-tlinks.el b/eev-tlinks.el
index 8a0713f..b900c72 100644
--- a/eev-tlinks.el
+++ b/eev-tlinks.el
@@ -1058,32 +1058,34 @@ echo     '{url}' >> ~/.psne.log
        (find-fline ,dir)
        ""
        ,(ee-template0 "\
+# {url}
+
  (eepitch-shell)
  (eepitch-kill)
  (eepitch-shell)
 # rm -Rfv {dir}
 cd      {ee-git-dir}
-git clone --depth 1 {url}
+git clone {url}
 cd      {dir}
-git pull --depth 1
+
+# git pull --depth 1
 # git pull
+# git reset
+# git clean -dfx
+# git reset --hard
+
 # (find-fline \"{ee-git-dir}\")
 # (find-fline \"{dir}\")
+# (find-gitk  \"{dir}\")
 
 # (code-c-d \"{c}\" \"{dir}\")
 # (find-{c}file \"\")
-# (find-gitk \"{dir}\")
-
-git clean -dfx
-git reset --hard
-
-git pull
 ")
      )
    pos-spec-list)))
 
-;; Test by typing `M-h g' on this git url:
-;; https://github.com/kikito/inspect.lua
+;; Test:
+;; (find-git-links "https://github.com/kikito/inspect.lua"; "inspectlua")