Improve documentation for display property functions

Specifically, use the term "display specification" more consistently to
distinguish from "display property", which is the full value of the
'display' text property.

* src/xdisp.c (find_display_property): Rename PROP to SPEC.
(Fget_display_property): Rename PROP to SPEC and improve docstring.

* lisp/emacs-lisp/subr-x.el (add-display-text-property): Rename PROP to
SPEC and improve docstring.

* doc/lispref/display.texi (Display Property): Reword documentation to
more-consistently refer to display specifications.

(cherry picked from commit 24e6cd42330c341f3525e3fdc384e4a646dec733)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index b5fd0b63d18dd3d4d19238734650b4211476d62c..5ed981557e7509366012e4a4d18f7860423f9be1 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -5284,29 +5284,29 @@ Properties}.
 specification, or a list or vector containing several display
 specifications.
 
-@defun get-display-property position prop &optional object properties
-This convenience function can be used to get a specific display
-property, no matter whether the @code{display} property is a vector, a
-list or a simple property.  This is like @code{get-text-property}
-(@pxref{Examining Properties}), but works on the @code{display} property
-only.  For properties with a single value (e.g.@: @code{height}, this
-returns the value itself; for properties with a list of values (e.g.@:
-@code{slice}), this returns the list of values.
+@defun get-display-property position spec &optional object properties
+This convenience function can be used to get the value of a specific
+display specification, no matter whether the @code{display} property is
+a vector, a list or a single display specification.  This is like
+@code{get-text-property} (@pxref{Examining Properties}), but works on
+the @code{display} property only.  For specifications with a single
+value (e.g.@: @code{height}), this returns the value itself; for
+properties with a list of values (e.g.@: @code{slice}), this returns the
+list of values.
 
 @var{position} is the position in the buffer or string to examine, and
-@var{prop} is the @code{display} property to return.  The optional
-@var{object} argument should be either a string or a buffer, and
-defaults to the current buffer.  If the optional @var{properties}
-argument is non-@code{nil}, it should be a @code{display} property,
-and in that case, @var{position} and @var{object} are ignored.  (This
-can be useful if you've already gotten the @code{display} property
-with @code{get-char-property}, for instance (@pxref{Examining
-Properties}).
+@var{spec} is the @sc{car} of the display specification to return.  The
+optional @var{object} argument should be either a string or a buffer,
+and defaults to the current buffer.  If the optional @var{properties}
+argument is non-@code{nil}, it should be a @code{display} property, and
+in that case, @var{position} and @var{object} are ignored.  (This can be
+useful if you've already gotten the @code{display} property with
+@code{get-char-property}, for instance (@pxref{Examining Properties}).
 @end defun
 
-@defun add-display-text-property start end prop value &optional object
-Add @code{display} property @var{prop} of @var{value} to the text from
-@var{start} to @var{end}.
+@defun add-display-text-property start end spec value &optional object
+Add the display specification @code{(@var{prop} @var{value})} to the
+text from @var{start} to @var{end}.
 
 If any text in the region has a non-@code{nil} @code{display}
 property, those properties are retained.  For instance:
@@ -5317,13 +5317,13 @@ property, those properties are retained.  For instance:
 @end lisp
 
 After doing this, the region from 2 to 4 will have the @code{raise}
-@code{display} property, the region from 4 to 8 will have both the
-@code{raise} and @code{height} @code{display} properties, and finally
-the region from 8 to 12 will only have the @code{raise} @code{display}
-property.
+display specification, the region from 4 to 8 will have both the
+@code{raise} and @code{height} display specifications, and finally the
+region from 8 to 12 will only have the @code{raise} display
+specification.
 
-If @var{object} is non-@code{nil}, it should be a string or a buffer.
-If @code{nil}, this defaults to the current buffer.
+@var{object} is either a string or a buffer to add the specification to.
+If omitted, @var{object} defaults to the current buffer.
 @end defun
 
 @cindex display property, unsafe evaluation

diff --git a/lisp/emacs-lisp/subr-x.el b/lisp/emacs-lisp/subr-x.el
index df4565658b5add0e26d937935c221f40d545cea3..cfd0927fe66cba5c1f3a939f6e0123c854c57bf9 100644 (file)
--- a/lisp/emacs-lisp/subr-x.el
+++ b/lisp/emacs-lisp/subr-x.el
@@ -411,14 +411,13 @@ indivisible unit."
     (nreverse result)))
 
 ;;;###autoload
-(defun add-display-text-property (start end prop value
-                                        &optional object)
-  "Add display property PROP with VALUE to the text from START to END.
-If any text in the region has a non-nil `display' property, those
-properties are retained.
-
-If OBJECT is non-nil, it should be a string or a buffer.  If nil,
-this defaults to the current buffer."
+(defun add-display-text-property (start end spec value &optional object)
+  "Add the display specification (SPEC VALUE) to the text from START to END.
+If any text in the region has a non-nil `display' property, the existing
+display specifications are retained.
+
+OBJECT is either a string or a buffer to add the specification to.
+If omitted, OBJECT defaults to the current buffer."
   (let ((sub-start start)
         (sub-end 0)
         disp)
@@ -429,7 +428,7 @@ this defaults to the current buffer."
                                                    (min end (point-max)))))
       (if (not (setq disp (get-text-property sub-start 'display object)))
           ;; No old properties in this range.
-          (put-text-property sub-start sub-end 'display (list prop value)
+          (put-text-property sub-start sub-end 'display (list spec value)
                              object)
         ;; We have old properties.
         (let (type)
@@ -449,14 +448,14 @@ this defaults to the current buffer."
                   (setq type 'list)
                   disp)))
           ;; Remove any old instances.
-          (when-let* ((old (assoc prop disp)))
+          (when-let* ((old (assoc spec disp)))
             ;; If the property value was a list, don't modify the
             ;; original value in place; it could be used by other
             ;; regions of text.
             (setq disp (if (eq type 'list)
                            (remove old disp)
                          (delete old disp))))
-          (setq disp (cons (list prop value) disp))
+          (setq disp (cons (list spec value) disp))
           (when (eq type 'vector)
             (setq disp (seq-into disp 'vector)))
           ;; Finally update the range.

diff --git a/src/xdisp.c b/src/xdisp.c
index 519194f984af8a2f9323a95b554a040fab08122b..30818191e42f29d3529505b4c793f36102606cc4 100644 (file)
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -5570,7 +5570,7 @@ setup_for_ellipsis (struct it *it, int len)
 
 \f
 static Lisp_Object
-find_display_property (Lisp_Object disp, Lisp_Object prop)
+find_display_property (Lisp_Object disp, Lisp_Object spec)
 {
   Lisp_Object elem;
   if (NILP (disp))
@@ -5583,7 +5583,7 @@ find_display_property (Lisp_Object disp, Lisp_Object prop)
          elem = AREF (disp, i);
          if (CONSP (elem)
              && CONSP (XCDR (elem))
-             && EQ (XCAR (elem), prop))
+             && EQ (XCAR (elem), spec))
            goto found;
        }
       return Qnil;
@@ -5597,7 +5597,7 @@ find_display_property (Lisp_Object disp, Lisp_Object prop)
          elem = XCAR (disp);
          if (CONSP (elem)
              && CONSP (XCDR (elem))
-             && EQ (XCAR (elem), prop))
+             && EQ (XCAR (elem), spec))
            goto found;
 
          /* Check that we have a proper list before going to the next
@@ -5612,7 +5612,7 @@ find_display_property (Lisp_Object disp, Lisp_Object prop)
   /* A simple display spec.  */
   else if (CONSP (disp)
           && CONSP (XCDR (disp))
-          && EQ (XCAR (disp), prop))
+          && EQ (XCAR (disp), spec))
     {
       elem = disp;
       goto found;
@@ -5753,13 +5753,15 @@ display_min_width (struct it *it, ptrdiff_t charpos,
 
 DEFUN ("get-display-property", Fget_display_property,
        Sget_display_property, 2, 4, 0,
-       doc: /* Get the value of the `display' property PROP at POSITION.
-If OBJECT, this should be a buffer or string where the property is
-fetched from.  If omitted, OBJECT defaults to the current buffer.
+       doc: /* Get the value of the display specification SPEC at POSITION.
+SPEC is the car of the display specification to fetch, e.g. `height'.
 
-If PROPERTIES, look for value of PROP in PROPERTIES instead of the
-properties at POSITION.  */)
-  (Lisp_Object position, Lisp_Object prop, Lisp_Object object,
+OBJECT is either a string or a buffer to fetch the specification from.
+If omitted, OBJECT defaults to the current buffer.
+
+If PROPERTIES is non-nil, look for value of SPEC in PROPERTIES instead
+of the properties at POSITION.  */)
+  (Lisp_Object position, Lisp_Object spec, Lisp_Object object,
    Lisp_Object properties)
 {
   if (NILP (properties))
@@ -5767,7 +5769,7 @@ properties at POSITION.  */)
   else
     CHECK_LIST (properties);
 
-  return find_display_property (properties, prop);
+  return find_display_property (properties, spec);
 }