From 293b1f83ae0967890f1f99671ccad47e7608111e Mon Sep 17 00:00:00 2001 From: Jim Porter Date: Sat, 31 May 2025 12:11:01 -0700 Subject: [PATCH] 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) --- doc/lispref/display.texi | 50 +++++++++++++++++++-------------------- lisp/emacs-lisp/subr-x.el | 21 ++++++++-------- src/xdisp.c | 24 ++++++++++--------- 3 files changed, 48 insertions(+), 47 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b5fd0b63d18..5ed981557e7 100644 --- 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 df4565658b5..cfd0927fe66 100644 --- 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 519194f984a..30818191e42 100644 --- a/src/xdisp.c +++ b/src/xdisp.c @@ -5570,7 +5570,7 @@ setup_for_ellipsis (struct it *it, int len) 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); } -- 2.39.5