Rationalize `org-link-(un)escape'

* contrib/lisp/org-contacts.el (org-contacts-vcard-format):
* contrib/lisp/org-link-edit.el (org-link-edit--link-data):
* contrib/lisp/org-notmuch.el (org-notmuch-search-store-link):
(org-notmuch-search-follow-link):
(org-notmuch-tree-follow-link):
* lisp/org-docview.el (org-docview-export):
* lisp/org-element.el (org-element-link-parser):
* lisp/org-lint.el (org-lint-link-to-local-file):
* lisp/org-protocol.el (org-protocol-split-data):
(org-protocol-parse-parameters):
* lisp/org.el (org-open-at-point):
(org-display-inline-images):
* lisp/ox-ascii.el (org-ascii-link):
* lisp/ox-html.el (org-html-link):
* lisp/ox-latex.el (org-latex--inline-image):
(org-latex-link):
* lisp/ox-publish.el (org-publish-resolve-external-link):
* lisp/ox.el (org-export-custom-protocol-maybe):
(org-export-resolve-fuzzy-link): Do not call `org-link-unescape' when
the link is obtained through the parser or as a user input.
* doc/org-manual.org (Link Format): Document escape syntax.

See <http://lists.gnu.org/r/emacs-orgmode/2019-02/msg00320.html>

contrib/lisp/org-contacts.el

@@ -1013,7 +1013,7 @@ to do our best."
 			(setq phones-list (org-contacts-remove-ignored-property-values ignore-list (org-contacts-split-property tel)))
 			(setq result "")
 			(while phones-list
-			  (setq result (concat result  "TEL:" (org-link-unescape (org-contacts-strip-link (car phones-list))) "\n"))
+			  (setq result (concat result  "TEL:" (org-contacts-strip-link (org-link-unescape (car phones-list))) "\n"))
 			  (setq phones-list (cdr phones-list)))
 			result))
 	    (when bday

contrib/lisp/org-link-edit.el

@@ -101,7 +101,7 @@ The list includes
        ((looking-at org-plain-link-re)
         (list (match-beginning 0)
               (match-end 0)
-              (org-link-unescape (match-string-no-properties 0))
+              (match-string-no-properties 0)
               nil))
        (t
         (error "What am I looking at?"))))))

contrib/lisp/org-notmuch.el

@@ -105,8 +105,7 @@ Can link to more than one message, if so all matching messages are shown."
 (defun org-notmuch-search-store-link ()
   "Store a link to a notmuch search or message."
   (when (eq major-mode 'notmuch-search-mode)
-    (let ((link (concat "notmuch-search:"
-			(org-link-escape notmuch-search-query-string)))
+    (let ((link (concat "notmuch-search:" notmuch-search-query-string))
 	  (desc (concat "Notmuch search: " notmuch-search-query-string)))
       (org-store-link-props :type "notmuch-search"
 			    :link link
@@ -121,14 +120,14 @@ Can link to more than one message, if so all matching messages are shown."
 (defun org-notmuch-search-follow-link (search)
   "Follow a notmuch link by displaying SEARCH in notmuch-search mode."
   (require 'notmuch)
-  (notmuch-search (org-link-unescape search)))
+  (notmuch-search search))
 
 
 
 (defun org-notmuch-tree-follow-link (search)
   "Follow a notmuch link by displaying SEARCH in notmuch-tree mode."
   (require 'notmuch)
-  (notmuch-tree (org-link-unescape search)))
+  (notmuch-tree search))
 
 (provide 'org-notmuch)
 

lisp/org-docview.el

@@ -56,11 +56,11 @@
 
 (defun org-docview-export (link description format)
   "Export a docview link from Org files."
-  (let* ((path (if (string-match "\\(.+\\)::.+" link) (match-string 1 link)
-		 link))
-         (desc (or description link)))
+  (let ((path (if (string-match "\\(.+\\)::.+" link) (match-string 1 link)
+		link))
+        (desc (or description link)))
     (when (stringp path)
-      (setq path (org-link-escape (expand-file-name path)))
+      (setq path (expand-file-name path))
       (cond
        ((eq format 'html) (format "<a href=\"%s\">%s</a>" path desc))
        ((eq format 'latex) (format "\\href{%s}{%s}" path desc))

lisp/org-element.el

@@ -3102,8 +3102,8 @@ Assume point is at the beginning of the link."
 	(setq contents-begin (match-beginning 3))
 	(setq contents-end (match-end 3))
 	(setq link-end (match-end 0))
-	;; RAW-LINK is the original link.  Expand any
-	;; abbreviation in it.
+	;; RAW-LINK is the original link.  Decode any encoding.
+	;; Expand any abbreviation in it.
 	;;
 	;; Also treat any newline character and associated
 	;; indentation as a single space character.  This is not
@@ -3114,9 +3114,10 @@ Assume point is at the beginning of the link."
 	;; [[shell:ls *.org]], which defeats Org's focus on
 	;; simplicity.
 	(setq raw-link (org-link-expand-abbrev
-			(replace-regexp-in-string
-			 "[ \t]*\n[ \t]*" " "
-			 (match-string-no-properties 1))))
+			(org-link-unescape
+			 (replace-regexp-in-string
+			  "[ \t]*\n[ \t]*" " "
+			  (match-string-no-properties 1)))))
 	;; Determine TYPE of link and set PATH accordingly.  According
 	;; to RFC 3986, remove whitespaces from URI in external links.
 	;; In internal ones, treat indentation as a single space.

lisp/org-lint.el

@@ -558,8 +558,8 @@ Use :header-args: instead"
 (defun org-lint-link-to-local-file (ast)
   (org-element-map ast 'link
     (lambda (l)
-      (when (equal (org-element-property :type l) "file")
-	(let ((file (org-link-unescape (org-element-property :path l))))
+      (when (equal "file" (org-element-property :type l))
+	(let ((file (org-element-property :path l)))
 	  (and (not (file-remote-p file))
 	       (not (file-exists-p file))
 	       (list (org-element-property :begin l)

lisp/org-protocol.el

@@ -298,11 +298,9 @@ SEPARATOR is specified or SEPARATOR is nil, assume \"/+\".  The
 results of that splitting are returned as a list."
   (let* ((sep (or separator "/+\\|\\?"))
          (split-parts (split-string data sep)))
-    (if unhexify
-	(if (fboundp unhexify)
-	    (mapcar unhexify split-parts)
-	  (mapcar 'org-link-unescape split-parts))
-      split-parts)))
+    (cond ((not unhexify) split-parts)
+	  ((fboundp unhexify) (mapcar unhexify split-parts))
+	  (t (mapcar #'org-link-unescape split-parts)))))
 
 (defun org-protocol-flatten-greedy (param-list &optional strip-path replacement)
   "Transform PARAM-LIST into a flat list for greedy handlers.
@@ -382,11 +380,8 @@ If INFO is already a property list, return it unchanged."
 	      result)
 	  (while data
 	    (setq result
-		  (append
-		   result
-		   (list
-		    (pop data)
-		    (org-link-unescape (pop data))))))
+		  (append result
+			  (list (pop data) (pop data)))))
 	  result)
       (let ((data (org-protocol-split-data info t org-protocol-data-separator)))
 	(if default-order

lisp/org.el

@@ -10286,7 +10286,7 @@ a link."
        ((eq type 'timestamp) (org-follow-timestamp-link))
        ((eq type 'link)
 	(let ((type (org-element-property :type context))
-	      (path (org-link-unescape (org-element-property :path context))))
+	      (path (org-element-property :path context)))
 	  ;; Switch back to REFERENCE-BUFFER needed when called in
 	  ;; a temporary buffer through `org-open-link-from-string'.
 	  (with-current-buffer (or reference-buffer (current-buffer))
@@ -10319,8 +10319,7 @@ a link."
 			   (cond ((not option) nil)
 				 ((string-match-p "\\`[0-9]+\\'" option)
 				  (list (string-to-number option)))
-				 (t (list nil
-					  (org-link-unescape option)))))))))
+				 (t (list nil option))))))))
 	     ((functionp (org-link-get-parameter type :follow))
 	      (funcall (org-link-get-parameter type :follow) path))
 	     ((member type '("coderef" "custom-id" "fuzzy" "radio"))
@@ -18828,7 +18827,7 @@ boundaries."
 			      (match-end 0))
 			   (match-string 2)))))))
 	    (when (and path (string-match-p file-extension-re path))
-	      (let ((file (expand-file-name (org-link-unescape path))))
+	      (let ((file (expand-file-name path)))
 		(when (file-exists-p file)
 		  (let ((width
 			 ;; Apply `org-image-actual-width' specifications.

lisp/ox-ascii.el

@@ -1600,8 +1600,9 @@ INFO is a plist holding contextual information."
 	  ;; Don't know what to do.  Signal it.
 	  (_ "???"))))
      (t
-      (let ((raw-link (org-link-unescape
-		       (org-element-property :raw-link link))))
+      (let ((raw-link (concat (org-element-property :type link)
+			      ":"
+			      (org-element-property :path link))))
 	(if (not (org-string-nw-p desc)) (format "<%s>" raw-link)
 	  (concat (format "[%s]" desc)
 		  (and (not (plist-get info :ascii-links-to-notes))

lisp/ox-html.el

@@ -3018,7 +3018,7 @@ INFO is a plist holding contextual information.  See
 	 (path
 	  (cond
 	   ((member type '("http" "https" "ftp" "mailto" "news"))
-	    (url-encode-url (org-link-unescape (concat type ":" raw-path))))
+	    (url-encode-url (concat type ":" raw-path)))
 	   ((string= type "file")
 	    ;; During publishing, turn absolute file names belonging
 	    ;; to base directory into relative file names.  Otherwise,
@@ -3172,18 +3172,18 @@ INFO is a plist holding contextual information.  See
 		(format (org-export-get-coderef-format path desc)
 			(org-export-resolve-coderef path info)))))
      ;; External link with a description part.
-     ((and path desc) (format "<a href=\"%s\"%s>%s</a>"
-			      (org-html-encode-plain-text path)
-			      attributes
-			      desc))
+     ((and path desc)
+      (format "<a href=\"%s\"%s>%s</a>"
+	      (org-html-encode-plain-text path)
+	      attributes
+	      desc))
      ;; External link without a description part.
-     (path (let ((path (org-html-encode-plain-text path)))
-	     (format "<a href=\"%s\"%s>%s</a>"
-		     path
-		     attributes
-		     (org-link-unescape path))))
+     (path
+      (let ((path (org-html-encode-plain-text path)))
+	(format "<a href=\"%s\"%s>%s</a>" path attributes path)))
      ;; No path, only description.  Try to do something useful.
-     (t (format "<i>%s</i>" desc)))))
+     (t
+      (format "<i>%s</i>" desc)))))
 
 ;;;; Node Property
 

lisp/ox-latex.el

@@ -2344,8 +2344,7 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
 LINK is the link pointing to the inline image.  INFO is a plist
 used as a communication channel."
   (let* ((parent (org-export-get-parent-element link))
-	 (path (let ((raw-path (org-link-unescape
-				(org-element-property :path link))))
+	 (path (let ((raw-path (org-element-property :path link)))
 		 (if (not (file-name-absolute-p raw-path)) raw-path
 		   (expand-file-name raw-path))))
 	 (filetype (file-name-extension path))
@@ -2502,8 +2501,9 @@ INFO is a plist holding contextual information.  See
 		(cond ((member type '("http" "https" "ftp" "mailto" "doi"))
 		       (concat type ":" raw-path))
 		      ((string= type "file")
-		       (org-export-file-uri (org-link-unescape raw-path)))
-		      (t raw-path)))))
+		       (org-export-file-uri raw-path))
+		      (t
+		       raw-path)))))
     (cond
      ;; Link type is handled by a special function.
      ((org-export-custom-protocol-maybe link desc 'latex))
@@ -2558,7 +2558,7 @@ INFO is a plist holding contextual information.  See
       (format (org-export-get-coderef-format path desc)
 	      (org-export-resolve-coderef path info)))
      ;; External link with a description part.
-     ((and path desc) (format "\\href{%s}{%s}" (org-link-unescape path) desc))
+     ((and path desc) (format "\\href{%s}{%s}" path desc))
      ;; External link without a description part.
      (path (format "\\url{%s}" path))
      ;; No path, only description.  Try to do something useful.

lisp/ox-publish.el

@@ -1173,7 +1173,7 @@ references with `org-export-get-reference'."
 	   (with-current-buffer (find-file-noselect file)
 	     (org-with-point-at 1
 	       (let ((org-link-search-must-match-exact-headline t))
-		 (org-link-search (org-link-unescape search) nil t))
+		 (org-link-search search nil t))
 	       (and (org-at-heading-p)
 		    (org-string-nw-p (org-entry-get (point) "CUSTOM_ID"))))))))
    ((not org-publish-cache)
@@ -1186,8 +1186,7 @@ references with `org-export-get-reference'."
     (let* ((filename (file-truename file))
 	   (crossrefs
 	    (org-publish-cache-get-file-property filename :crossrefs nil t))
-	   (cells
-	    (org-export-string-to-search-cell (org-link-unescape search))))
+	   (cells (org-export-string-to-search-cell search)))
       (or
        ;; Look for reference associated to search cells triggered by
        ;; LINK.  It can match when targeted file has been published

lisp/ox.el

@@ -4195,7 +4195,7 @@ The function ignores links with an implicit type (e.g.,
       (let ((protocol (org-link-get-parameter type :export)))
 	(and (functionp protocol)
 	     (funcall protocol
-		      (org-link-unescape (org-element-property :path link))
+		      (org-element-property :path link)
 		      desc
 		      backend))))))
 
@@ -4379,7 +4379,7 @@ Return value can be an object or an element:
 Assume LINK type is \"fuzzy\".  White spaces are not
 significant."
   (let* ((search-cells (org-export-string-to-search-cell
-			(org-link-unescape (org-element-property :path link))))
+			(org-element-property :path link)))
 	 (link-cache (or (plist-get info :resolve-fuzzy-link-cache)
 			 (let ((table (make-hash-table :test #'eq)))
 			   (plist-put info :resolve-fuzzy-link-cache table)