Merge branch 'master' into next

doc/org-manual.org

@@ -3050,14 +3050,17 @@ or alternatively
 
 : [[LINK]]
 
-Once a link in the buffer is complete (all brackets present), Org
+Once a link in the buffer is complete---all brackets present---, Org
 changes the display so that =DESCRIPTION= is displayed instead of
-=[[LINK][DESCRIPTION]]= and =LINK= is displayed instead of =[[LINK]]=.  Links are be
-highlighted in the face ~org-link~, which by default is an underlined
-face.  You can directly edit the visible part of a link.  Note that
-this can be either the LINK part, if there is no description, or the
-{{{var(DESCRIPTION)}}} part.  To edit also the invisible
-{{{var(LINK)}}} part, use {{{kbd(C-c C-l)}}} with point on the link.
+=[[LINK][DESCRIPTION]]= and =LINK= is displayed instead of =[[LINK]]=.
+Links are highlighted in the ~org-link~ face, which, by default, is an
+underlined face.
+
+You can directly edit the visible part of a link.  This can be either
+the {{{var(LINK)}}} part, if there is no description, or the
+{{{var(DESCRIPTION)}}} part otherwise.  To also edit the invisible
+{{{var(LINK)}}} part, use {{{kbd(C-c C-l)}}} with point on the link
+(see [[*Handling Links]]).
 
 If you place point at the beginning or just behind the end of the
 displayed text and press {{{kbd(BS)}}}, you remove
@@ -11119,7 +11122,7 @@ Org only loads back-ends for the following formats by default: ASCII,
 HTML, iCalendar, LaTeX, and ODT.  Additional back-ends can be loaded
 in either of two ways: by configuring the ~org-export-backends~
 variable, or by requiring libraries in the Emacs init file.  For
-example, to load the markdown back-end, add this to your Emacs config:
+example, to load the Markdown back-end, add this to your Emacs config:
 
 #+begin_src emacs-lisp
 (require 'ox-md)

lisp/org-macs.el

@@ -827,8 +827,9 @@ end of string are ignored."
 		    (cons (substring string i) results)))))))
 
 (defun org--string-from-props (s property)
-  "Return visible string according to text properties in string S.
-PROPERTY is either `invisible' or `display'."
+  "Return the visible part of string S.
+Visible part is determined according to text PROPERTY, which is
+either `invisible' or `display'."
   (let ((len (length s))
 	(new nil)
 	(i 0)
@@ -836,22 +837,30 @@ PROPERTY is either `invisible' or `display'."
     (while (setq i (text-property-not-all i len property nil s))
       (let* ((end (next-single-property-change i property s len))
 	     (props (text-properties-at i s))
+	     (spec (plist-get props property))
 	     (value
-	      (if (eq property 'invisible)
-		  ;; If `invisible' property in PROPS means text is to
-		  ;; be invisible, return the empty string.  Otherwise
-		  ;; return nil so that the part is skipped.
-		  (and (or (eq t buffer-invisibility-spec)
-			   (assoc-string (plist-get props 'invisible)
-					 buffer-invisibility-spec))
-		       "")
-		(let ((display (plist-get props 'display)))
-		  (pcase (if (stringp display) display
-			   (cl-some #'stringp display))
-		    (`nil nil)
+	      (pcase property
+		(`invisible
+		 ;; If `invisible' property in PROPS means text is to
+		 ;; be invisible, return the empty string.  Otherwise
+		 ;; return nil so that the part is skipped.
+		 (and (or (eq t buffer-invisibility-spec)
+			  (assoc-string spec buffer-invisibility-spec))
+		      ""))
+		(`display
+		 (pcase spec
+		   (`nil nil)
+		   (`(image . ,_)
+		    ;; Since we are returning a string, create
+		    ;; a place-holder with the same width as the
+		    ;; image.
+		    (make-string (ceiling (car (image-size spec))) ?\s))
+		   ((pred stringp)
 		    ;; Displayed string could contain invisible parts,
 		    ;; but no nested display.
-		    (s (org--string-from-props s 'invisible)))))))
+		    (org--string-from-props spec 'invisible))
+		   (_ (error "Un-handled `display' value: %S" spec))))
+		(_ (error "Unknown property: %S" property)))))
 	(when value
 	  (setq new (concat new (substring s cursor i) value))
 	  (setq cursor end))
@@ -863,7 +872,9 @@ PROPERTY is either `invisible' or `display'."
 (defun org-string-width (string)
   "Return width of STRING when displayed in the current buffer.
 Unlike `string-width', this function takes into consideration
-`invisible' and `display' text properties."
+`invisible' and `display' text properties.  It supports the
+latter in a limited way; it raises an error if it cannot handle
+a given `display' combination."
   (string-width
    (org--string-from-props (org--string-from-props string 'display)
 			   'invisible)))