bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al,
> Sounds good. I've attached my updated patch here (updated to on top of
> 16c3da1bcb). I am thinking that your patch implementing the variable
> watching should be a different commit (for appropriate credit and future
> git-blaming).
Sure, can do.
I took another glance. Minor doc comment:
> +
> +@item Customize where previews are shown
> +
> +Set @code{preview-visibility-style} to control when previews appear:
> +
> +@table @code
> +
> +@item off-point
> +Default. Previews replace the source when point is elsewhere. When a
> +preview is opened to show the source, the preview is replaced by an icon.
> +
> +@item at-point
> +Previews never obscure the source. When the cursor enters the source, the
> +preview, if there is one, appears alongside it.
> +
> +@item always
> +Previews are always visible when available. Away from point they replace
> +the source; when opened they remain displayed alongside the source.
> +
> +@end table
> +
I feel that somewhere in the above, the role of preview-auto-reveal
should be noted. For instance, if preview-auto-reveal is set
restrictively, then "cursor enters the source" is not sufficient in the
docs of at-point.
The attribution line in the commit message is appreciated, but I think
the customary way to do this is just to write "(bug#79708)" at the end
of the commit, which points back to the whole conversation.
I suppose we are ready to merge this, then? Anyone object?
Thanks, best,
Paul
___
bug-auctex mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
On 20/01/2026, Paul D. Nelson wrote:
> Yeah, I figured that'd be most convenient, since I feel like most people
> use setq.
Sounds good. I've attached my updated patch here (updated to on top of
16c3da1bcb). I am thinking that your patch implementing the variable
watching should be a different commit (for appropriate credit and future
git-blaming).
> Maybe one scenario to think through is if the user is generating
> previews while switching between buffers. I noticed some issues while
> doing that over the past few weeks, but haven't yet taken the time to
> track down or think about whether they might be due to your patch. Of
> course this can be addressed after your patch lands.
I do have that scenario in mind and the code is supposed to handle it.
That being said, while I didn't see any issue during my testing, it's
not far fetched to think that I missed a use-case or two and would be
happy to address them if given enough details.
Best regards,
-- Al
>From 39e930e8ece0224c5d2b700380dcff03cc0471f3 Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Wed, 26 Nov 2025 12:26:40 +0100
Subject: [PATCH] New feature: preview at point
* doc/preview-latex.texi: Add docs for new customizations.
* preview.el: (preview-visibility-style, preview-keep-stale-images,
preview-at-point-placement): New customizations.
(preview--update-buframe, preview-overlay-updated): New functions.
(preview-leave-open-previews-visible, preview-protect-point): Mark as
obsolete.
(preview--string): New macro.
(preview-log-error): Fix typo in doc.
(preview-replace-active-icon): Call preview-overlay-updated.
(preview-place-preview): Clear-out before toggling.
(preview-mark-point, preview--open-for-replace): Add condition on
`preview-visibility-style'.
(preview-toggle): Update to handle values of preview-visibility-style
and preview-at-point-placement call preview-overlay-updated. Handle ARG
being equal to `maybe-open'.
(preview-move-point): Handle `preview-visibility-style' and call
`preview--update-buframe'.
(preview-active-string, preview-disabled-string): Refactor into a
generic preview--string and mark as obsolete.
(preview-disable): Always call preview-toggle and condition deleting
files on `preview-keep-stale-images' and `preview-visibility-style' not
being nil.
(preview-parse-messages): Restore point before placing preview.
(preview-region): Update documentation to return started process.
(preview-dvi*-command): Fix case in docstring.
(preview-gs-flag-error): Fix bug and conditionally open previews.
(preview-gs-place): Use `preview-keep-stale-images' instead of
`preview-leave-open-previews-visible'.
(preview-check-changes): Use `preview-visibility-style' instead of
`preview-leave-open-previews-visible'.
(preview-temporary-opened): Change location of definition to avoid
compilation errors.
(preview-generate-preview): Changed return doc to imperative.
Developed in collaboration with Paul D. Nelson (ultrono (at) gmail).
---
doc/preview-latex.texi | 58 +++--
preview.el | 477 +
2 files changed, 389 insertions(+), 146 deletions(-)
diff --git a/doc/preview-latex.texi b/doc/preview-latex.texi
index 19210a3506..bca41d12f5 100644
--- a/doc/preview-latex.texi
+++ b/doc/preview-latex.texi
@@ -480,6 +480,47 @@ math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
@previewlatex{}'s, you can turn off inline math previews. In the
@samp{Preview Latex} group, remove @code{textmath} from
@code{preview-default-option-list} by customizing this variable.
+
+@item Customize where previews are shown
+
+Set @code{preview-visibility-style} to control when previews appear:
+
+@table @code
+
+@item off-point
+Default. Previews replace the source when point is elsewhere. When a
+preview is opened to show the source, the preview is replaced by an icon.
+
+@item at-point
+Previews never obscure the source. When the cursor enters the source, the
+preview, if there is one, appears alongside it.
+
+@item always
+Previews are always visible when available. Away from point they replace
+the source; when opened they remain displayed alongside the source.
+
+@end table
+
+The placement of previews when shown with their source is controlled with
+@code{preview-at-point-placement}, which can take these values:
+
+@table @code
+
+@item before-string
+Show the preview before the source (default).
+
+@item after-string
+Show the preview after the source.
+
+@item buframe
+Show the preview in a side frame adjacent to point. Requires the
+@code{buframe} package (available on ELPA). Only one frame is used,
+showing the preview whose source is at point. If
+@code{preview-visibility-style} is set to @code{off-point} or
+@code{always}, a preview opened away from point is shown only when point
+is on its source.
+
+@end table
@end itemize
@node Known problems, For advanced users, Simple customization, top
@@ -671,18 +712,11 @@ when this is needed is in
accordingly @code{split} is one entry in
@co
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, >> Regarding the issue of custom setters for the obsoleted variable >> preview-leave-open-previews-visible, here's a diff (on top of your >> latest patch) indicating how this might be done: > Since you seem to be wanting the setting of `preview-keep-stale-images` > to change the variables only when set to non-nil, then perhaps a custom > setter is sufficient after all? Or are you wanting to handle setq as well? Yeah, I figured that'd be most convenient, since I feel like most people use setq. > It would be difficult for me to test all possible async paths. But the > purpose of this statement is to select the truly selected buffer in the > window, rather than a temporarily selected one since > `preview-overlay-updated` itself is/might be called inside a different > `with-current-buffer`. > > I can't use (overlay-buffer ov) since the point is for > `preview--update-buframe` to display the buframe if the currently > selected buffer in the window is equal to the overlay buffer. Maybe one scenario to think through is if the user is generating previews while switching between buffers. I noticed some issues while doing that over the past few weeks, but haven't yet taken the time to track down or think about whether they might be due to your patch. Of course this can be addressed after your patch lands. > I copied this verbatim from `preview-generate-preview` (the last form in > the function). Should I change both? Might as well, at least from my POV. Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Paul, Thanks for this! I'll address your comments in the next patch, but some questions/clarifications below. On 05/01/2026, Paul D. Nelson wrote: > Regarding the issue of custom setters for the obsoleted variable > preview-leave-open-previews-visible, here's a diff (on top of your > latest patch) indicating how this might be done: Since you seem to be wanting the setting of `preview-keep-stale-images` to change the variables only when set to non-nil, then perhaps a custom setter is sufficient after all? Or are you wanting to handle setq as well? > I remember some discussion about the use of cl-* functions (not macros), > see https://lists.gnu.org/archive/html/bug-auctex/2024-04/msg00117.html > and follow-ups. Others will know better than I do whether we would need > to add cl-lib to Packages-Requires, etc. OK, I'll just use delq > Is it clear why this should be a macro? Wouldn't a defun be easier to > debug? I also think a function is better, but since it is a thin wrapper around the macro `preview-make-clickable` I thought a macro is more appropriate. Happy to change it. > This returns a single string, so the pluralization seems unclear. Also, > this function doesn't seem to be used anymore. Sorry, that was a typo, it should `preview-disabled-string`. This is an old obsolete function. > This last sentence (starting "ARG ...") seems a bit garbled to me. Indeed, it should be ARG can also be `maybe-open' to display the underlying text only when the cursor of the overlay's buffer is inside the overlay (in this case, OV is added to `preview-temporary-opened'). >> +(defun preview-overlay-updated (ov) >> + "Mark preview OV as updated." >> + (with-current-buffer (window-buffer) > > What if a preview is updated via some async path while you're working in > another buffer/window/frame? Are there some assumptions about how this > function is called? Would it be more robust to use (overlay-buffer ov) > instead of (window-buffer)? It would be difficult for me to test all possible async paths. But the purpose of this statement is to select the truly selected buffer in the window, rather than a temporarily selected one since `preview-overlay-updated` itself is/might be called inside a different `with-current-buffer`. I can't use (overlay-buffer ov) since the point is for `preview--update-buframe` to display the buframe if the currently selected buffer in the window is equal to the overlay buffer. > I believe the convention is to prefer the imperative: "Return the > started process." > I copied this verbatim from `preview-generate-preview` (the last form in the function). Should I change both? > Also, just checking: are there any failure paths along which it doesn't > start the process, or return it? I don't see any, short of an error or if `preview-generate-preview` itself does not return the process, in which case the documentation of that function is itself wrong. > I guess it'd be cleaner if this were "buframe-find", but OK. Indeed. I now rename this function in buframe and will push a version bump soon. I also fixed the issue of the frame placement with the multi-monitor, if you can pull the change and test it on your setup. Thanks, -- Al ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, Thanks. I've been testing the past week, looks good to me. Regarding the issue of custom setters for the obsoleted variable preview-leave-open-previews-visible, here's a diff (on top of your latest patch) indicating how this might be done: --8<---cut here---start->8--- diff --git a/preview.el b/preview.el index 07a22d8e..490bf879 100644 --- a/preview.el +++ b/preview.el @@ -480,13 +480,6 @@ sync with the preview." (const :tag "Only away from point, hiding source" off-point) (const :tag "Both" always))) -(define-obsolete-variable-alias - 'preview-leave-open-previews-visible - 'preview-keep-stale-images - "14.2.0" - "Use `preview-keep-stale-images' \ - and `preview-visibility-style' instead.") - (defcustom preview-keep-stale-images nil "Keep the last preview image visible even when the source changes. If non-nil, a preview that was just edited retains its previous image @@ -498,6 +491,43 @@ The value of this variable is ignored when `preview-visibility-style' is :group 'preview-appearance :type 'boolean) +(defun preview--obsolete-leave-open-previews-visible-apply (value) + "Apply obsolete `preview-leave-open-previews-visible' VALUE. +When VALUE is non-nil, configure `preview-visibility-style' and +`preview-keep-stale-images' to match the old behavior." + (when value +(set-default 'preview-visibility-style 'always) +(set-default 'preview-keep-stale-images t))) + +(defun preview--obsolete-leave-open-previews-visible-watcher +(_symbol newval operation where) + (when (and (eq operation 'set) + ;; Ignore buffer-local bindings. + (null where)) +(preview--obsolete-leave-open-previews-visible-apply newval))) + +(defcustom preview-leave-open-previews-visible nil + "Obsolete option; whether to leave previews visible when they are opened. +This option is obsolete. When set to non-nil, it configures +`preview-visibility-style' to \\='always and `preview-keep-stale-images' +to t. When set to nil, it does not change those variables." + :group 'preview-appearance + :type 'boolean) + +(make-obsolete-variable + 'preview-leave-open-previews-visible + "Use `preview-visibility-style' and `preview-keep-stale-images' instead." + "14.2.0") + +(add-variable-watcher + 'preview-leave-open-previews-visible + #'preview--obsolete-leave-open-previews-visible-watcher) + +;; Handle `setq' from before preview.el is loaded. +(when (default-value 'preview-leave-open-previews-visible) + (preview--obsolete-leave-open-previews-visible-apply + (default-value 'preview-leave-open-previews-visible))) + (defcustom preview-at-point-placement 'before-string "Placement of the at-point preview or icon relative to its source. --8<---cut here---end--->8--- Some further comments on your latest patch: >>From 9fa0fab280dc4b5cf24fe9a0ff4dd5a1607f7396 Mon Sep 17 00:00:00 2001 > From: Al Haji-Ali > Date: Wed, 26 Nov 2025 12:26:40 +0100 > Subject: [PATCH] New feature: preview at point > > * doc/preview-latex.texi: Add docs for new customizations. > > * preview.el: (preview-visibility-style, preview-keep-stale-images, > preview-at-point-placement): New customizations. > (preview--update-buframe, preview-overlay-updated): New functions. > (preview-leave-open-previews-visible, preview-protect-point): Mark as > obsolete. > (preview--string): New macro. > (preview-replace-active-icon): Call preview-overlay-updated. > (preview-place-preview): Clear-out before toggling. > (preview-mark-point, preview--open-for-replace): Add condition on > `preview-visibility-style'. > (preview-toggle): Update to handle values of preview-visibility-style > and preview-at-point-placement call preview-overlay-updated. Handle ARG > being equal to `maybe-open'. > (preview-move-point): Handle `preview-visibility-style' and call > `preview--update-buframe'. > (preview-active-string, preview-disabled-string): Refactor into a > generic preview--string and mark as obsolete. > (preview-disable): Always call preview-toggle and condition deleting > files on `preview-keep-stale-images' and `preview-visibility-style' not > being nil. > (preview-parse-messages): Restore point before placing preview. > (preview-region): Update documentation to return started process. > (preview-dvi*-command): Fix case in docstring. > (preview-gs-flag-error): Fix bug and conditionally open previews. > (preview-gs-place): Use `preview-keep-stale-images' instead of > `preview-leave-open-previews-visible'. > (preview-check-changes): Use `preview-visibility-style' instead of > `preview-leave-open-previews-visible'. > (preview-temporary-opened): Change location of definition to avoid > compilation errors. > > Developed in collaboration with Paul D. Nelson (ultrono (at) gmail). > --- > doc/preview-latex.texi | 58 - > preview.el | 496 + > 2 files changed, 394 insertions(+), 160 deletion
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Paul,
On 29/12/2025, Paul D. Nelson wrote:
> I'm likewise happy to leave it like it was in the previous patch
> until someone who uses that combination of settings complains.
Great. Attached is an updated patch (I also removed the docs on the old
customization variables). Let me know if I missed anything.
-- Al
>From 9fa0fab280dc4b5cf24fe9a0ff4dd5a1607f7396 Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Wed, 26 Nov 2025 12:26:40 +0100
Subject: [PATCH] New feature: preview at point
* doc/preview-latex.texi: Add docs for new customizations.
* preview.el: (preview-visibility-style, preview-keep-stale-images,
preview-at-point-placement): New customizations.
(preview--update-buframe, preview-overlay-updated): New functions.
(preview-leave-open-previews-visible, preview-protect-point): Mark as
obsolete.
(preview--string): New macro.
(preview-replace-active-icon): Call preview-overlay-updated.
(preview-place-preview): Clear-out before toggling.
(preview-mark-point, preview--open-for-replace): Add condition on
`preview-visibility-style'.
(preview-toggle): Update to handle values of preview-visibility-style
and preview-at-point-placement call preview-overlay-updated. Handle ARG
being equal to `maybe-open'.
(preview-move-point): Handle `preview-visibility-style' and call
`preview--update-buframe'.
(preview-active-string, preview-disabled-string): Refactor into a
generic preview--string and mark as obsolete.
(preview-disable): Always call preview-toggle and condition deleting
files on `preview-keep-stale-images' and `preview-visibility-style' not
being nil.
(preview-parse-messages): Restore point before placing preview.
(preview-region): Update documentation to return started process.
(preview-dvi*-command): Fix case in docstring.
(preview-gs-flag-error): Fix bug and conditionally open previews.
(preview-gs-place): Use `preview-keep-stale-images' instead of
`preview-leave-open-previews-visible'.
(preview-check-changes): Use `preview-visibility-style' instead of
`preview-leave-open-previews-visible'.
(preview-temporary-opened): Change location of definition to avoid
compilation errors.
Developed in collaboration with Paul D. Nelson (ultrono (at) gmail).
---
doc/preview-latex.texi | 58 -
preview.el | 496 +
2 files changed, 394 insertions(+), 160 deletions(-)
diff --git a/doc/preview-latex.texi b/doc/preview-latex.texi
index 19210a3506..bca41d12f5 100644
--- a/doc/preview-latex.texi
+++ b/doc/preview-latex.texi
@@ -480,6 +480,47 @@ math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
@previewlatex{}'s, you can turn off inline math previews. In the
@samp{Preview Latex} group, remove @code{textmath} from
@code{preview-default-option-list} by customizing this variable.
+
+@item Customize where previews are shown
+
+Set @code{preview-visibility-style} to control when previews appear:
+
+@table @code
+
+@item off-point
+Default. Previews replace the source when point is elsewhere. When a
+preview is opened to show the source, the preview is replaced by an icon.
+
+@item at-point
+Previews never obscure the source. When the cursor enters the source, the
+preview, if there is one, appears alongside it.
+
+@item always
+Previews are always visible when available. Away from point they replace
+the source; when opened they remain displayed alongside the source.
+
+@end table
+
+The placement of previews when shown with their source is controlled with
+@code{preview-at-point-placement}, which can take these values:
+
+@table @code
+
+@item before-string
+Show the preview before the source (default).
+
+@item after-string
+Show the preview after the source.
+
+@item buframe
+Show the preview in a side frame adjacent to point. Requires the
+@code{buframe} package (available on ELPA). Only one frame is used,
+showing the preview whose source is at point. If
+@code{preview-visibility-style} is set to @code{off-point} or
+@code{always}, a preview opened away from point is shown only when point
+is on its source.
+
+@end table
@end itemize
@node Known problems, For advanced users, Simple customization, top
@@ -671,18 +712,11 @@ when this is needed is in
accordingly @code{split} is one entry in
@code{preview-inner-environments}.
-@item preview-protect-point
-This boolean variable determines whether previews generated on top of the
-current point should be temporarily opened. Default value is @code{nil}.
-
-@item preview-leave-open-previews-visible
-This boolean variable determines whether to leave preview images visible
-when they are opened.
-
-There is a side effect in enabling this option. The preview image doesn't
-turn into construction sign temporarily when you edit the underlying
-@LaTeX{} code and regenerate the preview; it is just replaced by updated
-image when ready. This behavior suppresses flicker in the appearance.
+@item preview-keep-stale-images
+This boolean variable determines whether to retain preview images whose
+s
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al,
>> The motivation for that behavior (preview-leave-open-previews-visible)
>> was to eliminate flickering with automatic and/or live previewing
>> enabled. Seeing as most users of automatic previewing will probably
>> take visibility-style to be either 'always or 'at-point, there's perhaps
>> less benefit in the 'off-point case under discussion, so if you feel
>> strongly and/or if it would complicate the implementation, then I'm
>> happy to leave it as is until someone else complains. So maybe all
>> that's left on this point is to sync the docs with the behavior.
> My 'off-point special treatment does not simplify the implementation,
> but I simply don't know what's the best thing to do (given that we
> agreed to keep the previews open when the source is modified).
>
> For reference and your testing, I attach a patch which removes the
> off-point special treatment (in `preview-disable`). I am happy to leave
> it like this and document that `'off-point` works best with
> `preview-keep-stale-images` being nil as I do in this patch in
> `preview-visibility-style`.
>
> However, you will see that the behaviour with
> `preview-keep-stale-images` being non-nil is highly non-intuitive:
> - Editing the source replaces the icon with a stale image (when using
> 'always, the stale image is simply kept).
> - Moving away from source does not collapse the preview (as we discussed
> since the preview does not match the source).
>
> I don't see a good way to design this, which is why I was suggesting
> ignoring when `preview-keep-stale-images` is non-nil. As you mentioned,
> this might be an unnecessary discussion since this combination of
> settings is likely to be rare and we can leave it as is until someone
> complains with a better suggestion.
I agree that this new version behaves counterintuitively, and that
editing the source should not replace the icon with a stale image.
My feeling is that with 'off-point, the option preview-keep-stale-images
should control whether the construction icon is replaced by the stale
preview during regeneration, and nothing else. That way, previews are
open after source is modified (until regeneration begins), and
preview-keep-stale-images has some effect.
I believe we discussed this approach already and there were some pros
and cons (e.g., it might be unclear when the preview fails to generate),
so I'm likewise happy to leave it like it was in the previous patch
until someone who uses that combination of settings complains.
>> Do you mean keeping the old image visible (no flicker), or keeping TeX
>> source visible? For my workflow ('always with automatic previewing),
>> keeping the TeX source visible during regeneration would feel jarring.
>> The contract is that the TeX code is visible only while I'm editing it.
>> Otherwise, I just see previews everywhere, which update as soon as they
>> can (a fraction of a second).
> [cont]
>>
>> I might be misremembering on this point -- I tried testing just now,
>> and it wasn't so jarring with the TeX source visible. Moreover, it
>> seems like the TeX source stays visible during the brief regeneration
>> even after loading an earlier preview.el.
> OK, I am not sure anymore. I believe the old and current versions close
> the preview (hide the source) while it's being generated. My idea of the
> "contract" is that the preview should only replace the source when it is
> an accurate reflection of it, and when the user is not editing the
> source. That is why I was suggesting keeping the preview open while
> generating. However, I tested this and it is indeed quite jarring, so I
> suggest we leave it as it as.
Sounds good.
> BTW, I restored `preview-inactive-string` and `preview-disabled-string`
> and marked them obsolete. I also tried adding a value setter for
> `preview-leave-open-previews-visible` as you suggested, however I ran
> into an issue where setting the value of `preview-keep-stale-images` and
> `preview-visibility-style` before loading preview, then loading preview
> results in resetting those variables (because
> 'preview-leave-open-previews-visible' is set to nil when defined), so I
> don't think it's a good solution. I am open to suggestions.
OK, I see. I can try thinking a bit more about this later.
Thanks, best,
Paul
___
bug-auctex mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul,
On 22/12/2025, Paul D. Nelson wrote:
> The motivation for that behavior (preview-leave-open-previews-visible)
> was to eliminate flickering with automatic and/or live previewing
> enabled. Seeing as most users of automatic previewing will probably
> take visibility-style to be either 'always or 'at-point, there's perhaps
> less benefit in the 'off-point case under discussion, so if you feel
> strongly and/or if it would complicate the implementation, then I'm
> happy to leave it as is until someone else complains. So maybe all
> that's left on this point is to sync the docs with the behavior.
My 'off-point special treatment does not simplify the implementation,
but I simply don't know what's the best thing to do (given that we
agreed to keep the previews open when the source is modified).
For reference and your testing, I attach a patch which removes the
off-point special treatment (in `preview-disable`). I am happy to leave
it like this and document that `'off-point` works best with
`preview-keep-stale-images` being nil as I do in this patch in
`preview-visibility-style`.
However, you will see that the behaviour with
`preview-keep-stale-images` being non-nil is highly non-intuitive:
- Editing the source replaces the icon with a stale image (when using
'always, the stale image is simply kept).
- Moving away from source does not collapse the preview (as we discussed
since the preview does not match the source).
I don't see a good way to design this, which is why I was suggesting
ignoring when `preview-keep-stale-images` is non-nil. As you mentioned,
this might be an unnecessary discussion since this combination of
settings is likely to be rare and we can leave it as is until someone
complains with a better suggestion.
> Do you mean keeping the old image visible (no flicker), or keeping TeX
> source visible? For my workflow ('always with automatic previewing),
> keeping the TeX source visible during regeneration would feel jarring.
> The contract is that the TeX code is visible only while I'm editing it.
> Otherwise, I just see previews everywhere, which update as soon as they
> can (a fraction of a second).
[cont]
>
> I might be misremembering on this point -- I tried testing just now,
> and it wasn't so jarring with the TeX source visible. Moreover, it
> seems like the TeX source stays visible during the brief regeneration
> even after loading an earlier preview.el.
OK, I am not sure anymore. I believe the old and current versions close
the preview (hide the source) while it's being generated. My idea of the
"contract" is that the preview should only replace the source when it is
an accurate reflection of it, and when the user is not editing the
source. That is why I was suggesting keeping the preview open while
generating. However, I tested this and it is indeed quite jarring, so I
suggest we leave it as it as.
> I'm on macOS. You can probably see my detailed specs in the debug
> attachments from a couple messages ago.
>
> Here are the stats for the main, secondary and tertiary monitors in my
> current setup.
OK, this will require a bit more investigation on my part. It certainly
is a "bug" in buframe, not in the preview code, and I think I know the
reason for it but I need to check.
BTW, I restored `preview-inactive-string` and `preview-disabled-string`
and marked them obsolete. I also tried adding a value setter for
`preview-leave-open-previews-visible` as you suggested, however I ran
into an issue where setting the value of `preview-keep-stale-images` and
`preview-visibility-style` before loading preview, then loading preview
results in resetting those variables (because
'preview-leave-open-previews-visible' is set to nil when defined), so I
don't think it's a good solution. I am open to suggestions.
Best regards,
-- Al
>From 4c9b4d5fae73a64d61306aa9380441fecddca742 Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Wed, 26 Nov 2025 12:26:40 +0100
Subject: [PATCH] New feature: preview at point
* doc/preview-latex.texi: Add docs for new customizations.
* preview.el: (preview-visibility-style, preview-keep-stale-images,
preview-at-point-placement): New customizations.
(preview--update-buframe, preview-overlay-updated): New functions.
(preview-leave-open-previews-visible, preview-protect-point): Mark as
obsolete.
(preview--string): New macro.
(preview-replace-active-icon): Call preview-overlay-updated.
(preview-place-preview): Clear-out before toggling.
(preview-mark-point, preview--open-for-replace): Add condition on
`preview-visibility-style`.
(preview-toggle): Update to handle values of preview-visibility-style
and preview-at-point-placement call preview-overlay-updated. Handle ARG
being equal to `maybe-open'.
(preview-move-point): Handle `preview-visibility-style` and call
`preview--update-buframe`.
(preview-active-string, preview-disabled-string): Refactor into a
generic preview--string and mark as obsolete.
(preview-disable): Always call preview-toggle and condition de
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul,
On 22/12/2025, Paul D. Nelson wrote:
> The motivation for that behavior (preview-leave-open-previews-visible)
> was to eliminate flickering with automatic and/or live previewing
> enabled. Seeing as most users of automatic previewing will probably
> take visibility-style to be either 'always or 'at-point, there's perhaps
> less benefit in the 'off-point case under discussion, so if you feel
> strongly and/or if it would complicate the implementation, then I'm
> happy to leave it as is until someone else complains. So maybe all
> that's left on this point is to sync the docs with the behavior.
I don't particularly mind either way, in fact what I was doing did not
particularly simplify the implementations. In the attached patch I
removed the special consideration for 'off-point so that 'off-point and
'always behave "similarly" away from point. If you test 'off-point with
preview-keep-stale-images=t, you will see the issues that I highlighted
in a normal operation with this straightforward implementation. I am
happy to leave it as is, or make any changes you suggest as long as the
preview remains open when modified which as I argued is a fundamental
feature.
The issues of 'off-point' can be avoided by setting
`preview-keep-stale-images` to nil. I added this in the documentation of
`preview-visibility-style` and we can have a value-setting function to
do this automatically.
> Do you mean keeping the old image visible (no flicker), or keeping TeX
> source visible? For my workflow ('always with automatic previewing),
> keeping the TeX source visible during regeneration would feel jarring.
> The contract is that the TeX code is visible only while I'm editing it.
> Otherwise, I just see previews everywhere, which update as soon as they
> can (a fraction of a second).
I think there is a broader discussion on what is the best behaviour for
the few seconds while the preview is being generated and an icon or an
old preview is being shown: to hide or show the source?
The "contract", as I see it, is that the preview should only replace the
source when it is a reflection of it (and unless the user wants to
modify the source).
With the being said, leaving the preview open during generation is a
much bigger departure from the current and old implementation, so I
suggest we leave it as is for now.
> Here are the stats for the main, secondary and tertiary monitors in my
> current setup.
> [...]
> Hope that helps!
This is gonna require more time on my part as I don't see an issue with
the output.
> I might be misremembering on this point -- I tried testing just now, and
> it wasn't so jarring with the TeX source visible. Moreover, it seems
> like the TeX source stays visible during the brief regeneration even
> after loading an earlier preview.el.
I am not sure of this anymore. I think the old preview.el would close
the preview (hide the source) while generating it when
preview-leave-open-previews-visible is nil or t.
BTW, I've tried adding the custom setting code for
preview-leave-open-previews-visible, but I ran into an issue if I set
the custom variables `preview-keep-stale-images` and
`preview-visibility-style` before loading preview then their value is
overwritten once preview is loaded and
preview-leave-open-previews-visible is defined. So I don't think this is
a good option.
Best regards,
-- Al
>From e9d4ef65826ad164091d0a8efccdbac0f896e485 Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Wed, 26 Nov 2025 12:26:40 +0100
Subject: [PATCH] New feature: preview at point
* doc/preview-latex.texi: Add docs for new customizations.
* preview.el: (preview-visibility-style, preview-keep-stale-images,
preview-at-point-placement): New customizations.
(preview--update-buframe, preview-overlay-updated): New functions.
(preview-leave-open-previews-visible, preview-protect-point): Mark as
obsolete.
(preview--string): New macro.
(preview-replace-active-icon): Call preview-overlay-updated.
(preview-place-preview): Clear-out before toggling.
(preview-mark-point, preview--open-for-replace): Add condition on
`preview-visibility-style`.
(preview-toggle): Update to handle values of preview-visibility-style
and preview-at-point-placement call preview-overlay-updated. Handle ARG
being equal to `maybe-open'.
(preview-move-point): Handle `preview-visibility-style` and call
`preview--update-buframe`.
(preview-active-string, preview-disabled-string): Refactor into a
generic preview--string and mark as obsolete.
(preview-disable): Always call preview-toggle and condition deleting
files on `preview-leave-open-previews-visible`.
(preview-parse-messages): Restore point before placing preview.
(preview-region): Update documentation to return started process.
(preview-dvi*-command): Fix case in docstring.
(preview-gs-flag-error): Fix spacing, fix bug and conditionally open
previews.
(preview-gs-place): Use `preview-keep-stale-images` instead of
`preview-leave-open-previews-visible`.
(preview-check-changes): Use `preview-vis
bug#79708: 14.1.0; [PATCH] New feature: preview-point
>> This behaviour would be even stranger once the preview correctly remains
>> open during regeneration (which I haven't fixed yet).
>
> Do you mean keeping the old image visible (no flicker), or keeping TeX
> source visible? For my workflow ('always with automatic previewing),
> keeping the TeX source visible during regeneration would feel jarring.
> The contract is that the TeX code is visible only while I'm editing it.
> Otherwise, I just see previews everywhere, which update as soon as they
> can (a fraction of a second).
I might be misremembering on this point -- I tried testing just now, and
it wasn't so jarring with the TeX source visible. Moreover, it seems
like the TeX source stays visible during the brief regeneration even
after loading an earlier preview.el.
___
bug-auctex mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al,
>> Another related point: when preview-keep-still-images is t and
>> preview-visibility-style is 'off-point, as the preview starts
>> regenerating, the construction icon flashes. I feel like setting
>> preview-keep-still-images to t should universally suppress the
>> construction icon. It does when preview-visibility-style is 'always, so
>> why not also when it is 'off-point? (If it did, then
>> preview-keep-still-images would retain some relevance in the 'off-point
>> case.)
>
> Yes. As noted, when `preview-visibility-style` is `off-point`,
> `preview-keep-still-images` is ignored; so what you describe is intended
> behaviour.
>
> I take your point about suppressing the construction icon. That said,
> the behaviour follows from the earlier discussion about keeping the
> preview open when modified.
The earlier discussion (as I understood it) was about how the preview
looked immediately after editing, not while it regenerates. I don't see
any reason the two behaviors should be the same. For instance, they
currently differ when preview-visibility-style is 'always (in a good
way, in my opinion, as discussed below).
> Showing an icon immediately before generation, then briefly flashing
> the old preview on regeneration, risks suggesting the preview failed
> to update, before it is replaced by the correct one.
OK, I see what you mean here -- I don't experience preview failures
often enough to have a sense for how useful this is, but can imagine.
> On the other hand, I am not sure what the benefit of such behaviour
> would be.
The motivation for that behavior (preview-leave-open-previews-visible)
was to eliminate flickering with automatic and/or live previewing
enabled. Seeing as most users of automatic previewing will probably
take visibility-style to be either 'always or 'at-point, there's perhaps
less benefit in the 'off-point case under discussion, so if you feel
strongly and/or if it would complicate the implementation, then I'm
happy to leave it as is until someone else complains. So maybe all
that's left on this point is to sync the docs with the behavior.
> This behaviour would be even stranger once the preview correctly remains
> open during regeneration (which I haven't fixed yet).
Do you mean keeping the old image visible (no flicker), or keeping TeX
source visible? For my workflow ('always with automatic previewing),
keeping the TeX source visible during regeneration would feel jarring.
The contract is that the TeX code is visible only while I'm editing it.
Otherwise, I just see previews everywhere, which update as soon as they
can (a fraction of a second).
>> If I recall correctly, I did get the chance to test the latest buframe
>> code on a multi-monitor setup earlier this week and that it continued to
>> misbehave, but I didn't get the chance to look closely at this.
> OK. I just had a chance to test on a multi-monitor setup (on macOS
> FWIW). The new "fix" is indeed wrong. However, after undoing the fix
> (i.e., using the old way of getting window coordinates), the previews
> with buframes work flawlessly on my setup with either monitor. So we're
> gonna have to dig deeper into this issue on your system.
>
> One way to proceed is if you can tell me what your OS/windowing-system
> are and what does `window-inside-pixel-edges` and `frame-position`
> return when called on a new frame in different monitors (the first
> return value should be the same while the latter should be different).
I'm on macOS. You can probably see my detailed specs in the debug
attachments from a couple messages ago.
Here are the stats for the main, secondary and tertiary monitors in my
current setup.
With fullscreen frames:
window-inside-pixel-edges:
(10 18 1711 1030)
(10 18 1270 1390)
(10 18 955 1030)
frame-position:
(1 . -1432)
(0 . -2512)
(3 . 45)
With a non-fullscreen window, dragged to the upper-left corner of each
monitor:
window-inside-pixel-edges:
(10 18 388 544)
(10 18 388 544)
(10 18 388 544)
frame-position:
(1 . 38)
(2 . -1415)
(0 . -2495)
Hope that helps!
Thanks, best,
Paul
___
bug-auctex mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul, On 20/12/2025, Paul D. Nelson wrote: > OK, makes sense. I'm happy to leave this aspect as it is for now. > > Another related point: when preview-keep-still-images is t and > preview-visibility-style is 'off-point, as the preview starts > regenerating, the construction icon flashes. I feel like setting > preview-keep-still-images to t should universally suppress the > construction icon. It does when preview-visibility-style is 'always, so > why not also when it is 'off-point? (If it did, then > preview-keep-still-images would retain some relevance in the 'off-point > case.) Yes. As noted, when `preview-visibility-style` is `off-point`, `preview-keep-still-images` is ignored; so what you describe is intended behaviour. I take your point about suppressing the construction icon. That said, the behaviour follows from the earlier discussion about keeping the preview open when modified. Showing an icon immediately before generation, then briefly flashing the old preview on regeneration, risks suggesting the preview failed to update, before it is replaced by the correct one. On the other hand, I am not sure what the benefit of such behaviour would be. This behaviour would be even stranger once the preview correctly remains open during regeneration (which I haven't fixed yet). > If I recall correctly, I did get the chance to test the latest buframe > code on a multi-monitor setup earlier this week and that it continued to > misbehave, but I didn't get the chance to look closely at this. OK. I just had a chance to test on a multi-monitor setup (on macOS FWIW). The new "fix" is indeed wrong. However, after undoing the fix (i.e., using the old way of getting window coordinates), the previews with buframes work flawlessly on my setup with either monitor. So we're gonna have to dig deeper into this issue on your system. One way to proceed is if you can tell me what your OS/windowing-system are and what does `window-inside-pixel-edges` and `frame-position` return when called on a new frame in different monitors (the first return value should be the same while the latter should be different). > One thought about deprecation: I think the now-obsolete variable > preview-leave-open-previews-visible should have a custom setter that > sets preview-visibility-style to 'always and preview-keep-still-images > to t, since that would give the most faithful reproduction of previous > behavior. (Happy to elaborate or provide code if that'd help.) Agreed. I'll add that code to the next version of the patch. Best regards, -- Al ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, > On 10/12/2025, Paul D. Nelson wrote: >> Question: in the above scenario, should the old preview appear (covering >> the TeX source, like it did before we modified) as soon as point moves >> away, rather than just for a brief moment while the preview generates? > > This behaviour is inherited from the current way of viewing previews. In > particular, when text is modified the preview is opened, and remains > open until it is re-generated. > > I believe this is a reasonable behaviour. If I am editing text which > corresponds to a preview, then I likely want to go back to it to edit it > again and hiding it every time the cursor leaves the region creates > unnecessary friction while editing source. Also, I believe a reasonable > expectation is that the text should be replaced with a preview only if > the preview accurately reflects the source, otherwise the source should > always be visible. OK, thanks for discussing. I agree that it's reasonable. > If you are referring to the fact that the preview should not be "closed" > in the brief time while it is being regenerated (i.e. the source should > be visible), then I can look into modifying this behaviour (though I > suspect it will be annoying to fix due to the mechanism of replacing > images that is currently employed). OK, probably not worth it for now. >> A related point: the docs suggest that that 'always and 'off-point >> should yield the same behavior for previews away from point, but this is >> not the case after modifying a preview and moving point away. > > I think it is the case that they are the same from the perspective of > showing/hiding overlays and frames which show symbols or previews (they > should be exactly the same when `preview-keep-stale-images` is nil). I > guess you are referring to what is being shown (icons vs previews). If > so, this is related to the other point I raised with the inconsistency > of `preview-keep-stale-images=t` and `preview-visibility-style = > 'off-point`. So I discuss it below. > >> I would have thought that "reusing the image" here would refer to what >> happens when point moves away from the modified TeX source, like in my >> response above. >> >> In fact, with >> >> preview-visibility-style = 'off-point, >> >> does preview-keep-stale-images make any difference at all? > > I may be misunderstanding you, but this is exactly my point. > > With preview-visibility-style = 'off-point, when the cursor enters the > preview, the source is shown and an icon appears. When the cursor moves > away, the source is hidden and the preview reappears. This is the basic > use case: show the source at point; otherwise show the preview hiding > the source. > > Now consider editing under the same setting. The cursor enters the > source, the icon appears, and the source is modified. As argued above, > the source should then remain visible when the cursor leaves to avoid > unnecessary editing friction. Given that, and with > preview-keep-stale-images set to t, what should happen when the cursor > leaves the source? > > Currently, preview-keep-stale-images is effectively ignored and the icon > remains. This matches buframe behaviour: a stale preview is never shown > away from point. I also think this is consistent with 'off-point: when > the source is visible, the user does not want to see the preview. Yes, seems consistent to me so far. > The alternative is to replace the icon with the stale preview when the > cursor leaves. I tried this initially and found it jarring. The preview > appears with the source while the cursor is away, then is replaced with > an icon when the cursor re-enters the visible source. It felt like a > pointless visual gimmick with no clear benefit. OK, makes sense. I'm happy to leave this aspect as it is for now. Another related point: when preview-keep-still-images is t and preview-visibility-style is 'off-point, as the preview starts regenerating, the construction icon flashes. I feel like setting preview-keep-still-images to t should universally suppress the construction icon. It does when preview-visibility-style is 'always, so why not also when it is 'off-point? (If it did, then preview-keep-still-images would retain some relevance in the 'off-point case.) Some other notes: If I recall correctly, I did get the chance to test the latest buframe code on a multi-monitor setup earlier this week and that it continued to misbehave, but I didn't get the chance to look closely at this. One thought about deprecation: I think the now-obsolete variable preview-leave-open-previews-visible should have a custom setter that sets preview-visibility-style to 'always and preview-keep-still-images to t, since that would give the most faithful reproduction of previous behavior. (Happy to elaborate or provide code if that'd help.) Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul, On 10/12/2025, Paul D. Nelson wrote: > Question: in the above scenario, should the old preview appear (covering > the TeX source, like it did before we modified) as soon as point moves > away, rather than just for a brief moment while the preview generates? This behaviour is inherited from the current way of viewing previews. In particular, when text is modified the preview is opened, and remains open until it is re-generated. I believe this is a reasonable behaviour. If I am editing text which corresponds to a preview, then I likely want to go back to it to edit it again and hiding it every time the cursor leaves the region creates unnecessary friction while editing source. Also, I believe a reasonable expectation is that the text should be replaced with a preview only if the preview accurately reflects the source, otherwise the source should always be visible. If you are referring to the fact that the preview should not be "closed" in the brief time while it is being regenerated (i.e. the source should be visible), then I can look into modifying this behaviour (though I suspect it will be annoying to fix due to the mechanism of replacing images that is currently employed). > A related point: the docs suggest that that 'always and 'off-point > should yield the same behavior for previews away from point, but this is > not the case after modifying a preview and moving point away. I think it is the case that they are the same from the perspective of showing/hiding overlays and frames which show symbols or previews (they should be exactly the same when `preview-keep-stale-images` is nil). I guess you are referring to what is being shown (icons vs previews). If so, this is related to the other point I raised with the inconsistency of `preview-keep-stale-images=t` and `preview-visibility-style = 'off-point`. So I discuss it below. > I would have thought that "reusing the image" here would refer to what > happens when point moves away from the modified TeX source, like in my > response above. > > In fact, with > > preview-visibility-style = 'off-point, > > does preview-keep-stale-images make any difference at all? I may be misunderstanding you, but this is exactly my point. With preview-visibility-style = 'off-point, when the cursor enters the preview, the source is shown and an icon appears. When the cursor moves away, the source is hidden and the preview reappears. This is the basic use case: show the source at point; otherwise show the preview hiding the source. Now consider editing under the same setting. The cursor enters the source, the icon appears, and the source is modified. As argued above, the source should then remain visible when the cursor leaves to avoid unnecessary editing friction. Given that, and with preview-keep-stale-images set to t, what should happen when the cursor leaves the source? Currently, preview-keep-stale-images is effectively ignored and the icon remains. This matches buframe behaviour: a stale preview is never shown away from point. I also think this is consistent with 'off-point: when the source is visible, the user does not want to see the preview. The alternative is to replace the icon with the stale preview when the cursor leaves. I tried this initially and found it jarring. The preview appears with the source while the cursor is away, then is replaced with an icon when the cursor re-enters the visible source. It felt like a pointless visual gimmick with no clear benefit. > I'm not at all sure about this, but would it make sense to fold > preview-keep-stale-images into preview-visibility-style, effectively > taking the value nil precisely when preview-visibility-style='off-point? > I might have guessed that most people who learn about these settings > will want to use either 'always or 'at-point as well as automatic > previewing, which work best with preview-keep-stale-images = t. One > downside is that it would further complicate the docstring for > preview-visibility-style. I think keeping or removing stale images is an important customization for 'always and 'at-point. I don't think the inconsistency between 'off-point and keeping stale images is enough of a reason to have such restrictions. I prefer coming up with better names for the customizations or documentation to resolve it. Let's keep discussing the other points that I raised above and we can revisit this suggestion. > I did a quick search through my package repos for these functions, and > they turned up only in https://github.com/ultronozm/czm-preview.el. > That package has been deprecated for a bit over a year (it's superceded > by patches to AUCTeX + preview-auto), but I suspect a couple colleagues > are still using it, so maybe marking as obsolete would be the gentler > approach. Will do. Best regards, -- Al ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, Thanks for your continued work on this. I've been using for a few days now and it's looking good. > - When a preview fails or is modified (and thus disabled), it remains > open, showing the source, and its visibility follows > `preview-visibility-style` as expected. The exception is when > `preview-visibility-style` is `always` or `off-point` and > `preview-at-point-placement` is `buframe`. In this setup, the preview > is not shown away from point, because only one buframe can be visible > at a time, and it always displays the preview under point. This seems > inherent to the design; it likely just needs to be documented, though > I'm not sure my current wording is adequate. I understand the constraint about not having multiple buframes visible at the same time, but consider the following experiment. Take preview-visibility-style = 'always, preview-keep-stale-images = t preview-at-point-placement = 'buframe Render a preview, modify the underlying tex source, move point away, and render it again. There's a brief moment, before it shows the new preview, where it shows the old preview instead of the TeX source. Question: in the above scenario, should the old preview appear (covering the TeX source, like it did before we modified) as soon as point moves away, rather than just for a brief moment while the preview generates? Besides that such behavior makes sense to me intuitively, it also seems consistent with how preview-keep-stale-images is documented, and does not violate the "multiple buframe" constraint. A related point: the docs suggest that that 'always and 'off-point should yield the same behavior for previews away from point, but this is not the case after modifying a preview and moving point away. I think it would be the case if, after modifying the TeX source of a preview and moving point away, - preview-keep-stale-images=t meant that the old preview covers the modified source, and - preview-keep-stale-images=nil meant that the TeX icon appears to the left of the modified source, like it does by default in AUCTex. > - Another point is that, while I like splitting > `preview-leave-open-previews-visible` into `preview-keep-stale-images` > and `preview-visibility-style = 'off-point` (in particular, it allows > always showing non-stale images), there's one issue. If > `preview-keep-stale-images` is t, while `preview-visibility-style` is > 'off-point, then modifying the source disables the preview, but > reusing the image is nonsensical since the preview is replaced by an > icon when opened. Currently stale images are not kept in either of > those case. I feel this is OK, but I am open to suggestions. I would have thought that "reusing the image" here would refer to what happens when point moves away from the modified TeX source, like in my response above. In fact, with preview-visibility-style = 'off-point, does preview-keep-stale-images make any difference at all? I'm not at all sure about this, but would it make sense to fold preview-keep-stale-images into preview-visibility-style, effectively taking the value nil precisely when preview-visibility-style='off-point? I might have guessed that most people who learn about these settings will want to use either 'always or 'at-point as well as automatic previewing, which work best with preview-keep-stale-images = t. One downside is that it would further complicate the docstring for preview-visibility-style. > As part of a small refactor I removed two old functions: > preview-disabled-string and preview-inactive-string, and used the new > macro preview--string directly instead. I think these are internal > functions, but let me know if I should retain them or mark them as > obsolete. I did a quick search through my package repos for these functions, and they turned up only in https://github.com/ultronozm/czm-preview.el. That package has been deprecated for a bit over a year (it's superceded by patches to AUCTeX + preview-auto), but I suspect a couple colleagues are still using it, so maybe marking as obsolete would be the gentler approach. Thanks again and best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul,
My apologies, this was indeed a silly bug in the previous patch. Please
find attached an updated one (also fixing the compilation errors).
Best regards,
-- Al
>From cb2a2530d8eb7a75ccbcbdcf1e21e556af7f70e2 Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Wed, 26 Nov 2025 12:26:40 +0100
Subject: [PATCH] New feature: preview at point
* doc/preview-latex.texi: Add docs for new customizations.
* preview.el: (preview-visibility-style, preview-keep-stale-images,
preview-at-point-placement): New customizations.
(preview--update-buframe, preview-overlay-updated): New functions.
(preview-leave-open-previews-visible, preview-protect-point): Mark as
obsolete.
(preview--string): New macro.
(preview-replace-active-icon): Call preview-overlay-updated.
(preview-place-preview): Clear-out before toggling.
(preview-mark-point, preview--open-for-replace): Add condition on
`preview-visibility-style`.
(preview-toggle): Update to handle values of preview-visibility-style
and preview-at-point-placement call preview-overlay-updated. Handle ARG
being equal to `maybe-open'.
(preview-move-point): Handle `preview-visibility-style` and call
`preview--update-buframe`.
(preview-active-string, preview-disabled-string): Remove and refactor
into a generic preview--string.
(preview-disable): Always call preview-toggle and condition deleting
files on `preview-leave-open-previews-visible`.
(preview-parse-messages): Restore point before placing preview.
(preview-region): Update documentation to return started process.
(preview-dvi*-command): Fix case in docstring.
(preview-gs-flag-error): Fix spacing, fix bug and conditionally open
previews.
(preview-gs-place): Use `preview-keep-stale-images` instead of
`preview-leave-open-previews-visible`.
(preview-check-changes): Use `preview-visibility-style` instead of
`preview-leave-open-previews-visible`.
(preview-temporary-opened): Change location of defining to avoid
compilation errors.
Developed in collaboration with Paul D. Nelson (ultrono (at) gmail).
---
doc/preview-latex.texi | 41
preview.el | 491 -
2 files changed, 374 insertions(+), 158 deletions(-)
diff --git a/doc/preview-latex.texi b/doc/preview-latex.texi
index 19210a35..9daab4ee 100644
--- a/doc/preview-latex.texi
+++ b/doc/preview-latex.texi
@@ -480,6 +480,47 @@ math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
@previewlatex{}'s, you can turn off inline math previews. In the
@samp{Preview Latex} group, remove @code{textmath} from
@code{preview-default-option-list} by customizing this variable.
+
+@item Customize where previews are shown
+
+Set @code{preview-visibility-style} to control when previews appear:
+
+@table @code
+
+@item off-point
+Default. Previews replace the source when point is elsewhere. When a
+preview is opened to show the source, the preview is replaced by an icon.
+
+@item at-point
+Previews never obscure the source. When the cursor enters the source, the
+preview, if there is one, appears alongside it.
+
+@item always
+Previews are always visible when available. Away from point they replace
+the source; when opened they remain displayed alongside the source.
+
+@end table
+
+The placement of previews when shown with their source is controlled with
+@code{preview-at-point-placement}, which can take these values:
+
+@table @code
+
+@item before-string
+Show the preview before the source (default).
+
+@item after-string
+Show the preview after the source.
+
+@item buframe
+Show the preview in a side frame adjacent to point. Requires the
+@code{buframe} package (available on ELPA). Only one frame is used,
+showing the preview whose source is at point. If
+@code{preview-visibility-style} is set to @code{off-point} or
+@code{always}, a preview opened away from point is shown only when point
+is on its source.
+
+@end table
@end itemize
@node Known problems, For advanced users, Simple customization, top
diff --git a/preview.el b/preview.el
index 94812886..a2744e09 100644
--- a/preview.el
+++ b/preview.el
@@ -453,9 +453,77 @@ show as response of Ghostscript."
"Set this for single-file PostScript conversion.
This will have no effect when `preview-image-type' is
set to `postscript'."
- :group 'preview-latex
+ :group 'preview-appearance
+ :type 'boolean)
+
+(defcustom preview-visibility-style 'off-point
+ "Controls when previews are shown.
+
+Values:
+
+ \\='always Show previews both at point (alongside the source) and
+ away from point (replacing the source).
+
+ \\='at-point Show previews only when point is on their source; never hide
+ the source.
+
+ \\='off-point Show previews only away from point, replacing the source;
+ at point, show a small icon instead (alongside the
+ source). Regenerated previews appear immediately,
+ hiding the source."
+ :group 'preview-appearance
+ :type '(choice
+ (const :tag "Only a
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al,
> Can you try to send a reproduction recipe?
>
> I am not seeing this behaviour when I test on my setup or on "emacs -Q"
> with various settings and I don't quite understand how you could arrive
> to the strings that you listed, so I am missing something.
Sure. I start Emacs like this:
--8<---cut here---start->8---
emacs -Q \
-L ~/.emacs.d/elpaca/repos/auctex \
--eval "(require 'tex-site)" \
--eval "(setopt preview-visibility-style 'always preview-keep-stale-images t)"
--8<---cut here---end--->8---
I then navigate to a tex file, like this:
--8<---cut here---start->8---
\documentclass{article}
\begin{document}
$x - y$
\end{document}
--8<---cut here---end--->8---
I do C-c C-p C-b, navigate inside the tex source, and modify it in any
way; this produces an 'x' like in my previous email.
The bug doesn't show up in any of your previous patches and goes away if
I evaluate preview.el from the main branch, for instance.
I've attached my "report bug" dumps for Emacs, AUCTeX and preview, in
case those are of any help.
Thanks, best,
Paul
In GNU Emacs 31.0.50 (build 1, aarch64-apple-darwin24.6.0, NS
appkit-2575.70 Version 15.6.1 (Build 24G90)) of 2025-11-15 built on
d51735
Repository revision: 1af8af35681aaf91d8875ff6cc6261dba4f7871d
Repository branch: rmail-view-button
Windowing system distributor 'Apple', version 10.3.2575
System Description: macOS 15.7.2
Configured features:
ACL DBUS GLIB GNUTLS LCMS2 LIBXML2 MODULES NOTIFY KQUEUE NS PDUMPER PNG
RSVG SQLITE3 THREADS TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XIM ZLIB
Important settings:
value of $LC_CTYPE: UTF-8
value of $LANG: en_US.UTF-8
locale-coding-system: utf-8-unix
Major mode: LaTeX/P
Minor modes in effect:
TeX-PDF-mode: t
tooltip-mode: t
global-eldoc-mode: t
eldoc-mode: t
show-paren-mode: t
electric-indent-mode: t
mouse-wheel-mode: t
tool-bar-mode: t
menu-bar-mode: t
file-name-shadow-mode: t
global-font-lock-mode: t
font-lock-mode: t
blink-cursor-mode: t
minibuffer-nonselected-mode: t
minibuffer-regexp-mode: t
line-number-mode: t
transient-mark-mode: t
auto-composition-mode: t
auto-encryption-mode: t
auto-compression-mode: t
Load-path shadows:
None found.
Features:
(shadow sort mail-extr emacsbug lisp-mnt message mailcap yank-media puny
dired dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg
rfc6068 epg-config gnus-util mm-decode mm-bodies mm-encode mailabbrev
gmm-utils mailheader sendmail mail-parse rfc2231 rfc2047 rfc2045
ietf-drums mm-util mail-prsvr mail-utils vc-git diff-mode track-changes
files-x vc-dispatcher preview tex-bar toolbar-x noutline outline
tex-mode shell pcomplete font-latex latex easy-mmode edmacro kmacro
latex-flymake flymake project byte-opt gv bytecomp byte-compile compile
text-property-search comint ansi-osc ansi-color ring warnings thingatpt
tex-ispell tex-style tex crm texmathp auctex latexenc time-date subr-x
cus-edit pp cus-start cus-load icons wid-edit cl-loaddefs cl-lib
auctex-autoloads tex-site rmc iso-transl tooltip cconv eldoc paren
electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode mwheel
term/ns-win ns-win ucs-normalize mule-util term/common-win tool-bar dnd
fontset image regexp-opt fringe tabulated-list replace newcomment
text-mode lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow
isearch easymenu timer select scroll-bar mouse jit-lock font-lock syntax
font-core term/tty-colors frame minibuffer nadvice seq simple cl-generic
indonesian philippine cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek
romanian slovak czech european ethiopic indian cyrillic chinese
composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help abbrev obarray oclosure cl-preloaded button loaddefs
theme-loaddefs faces cus-face macroexp files window text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget keymap
hashtable-print-readable backquote threads dbusbind kqueue cocoa ns
lcms2 multi-tty make-network-process tty-child-frames emacs)
Memory information:
((conses 16 185963 11822) (symbols 48 25944 0) (strings 32 66252 2227)
(string-bytes 1 1235735) (vectors 16 22165)
(vector-slots 8 212046 8362) (floats 8 86 58) (intervals 56 314 0)
(buffers 1064 16))
Emacs : GNU Emacs 31.0.50 (build 1, aarch64-apple-darwin24.6.0, NS
appkit-2575.70 Version 15.6.1 (Build 24G90))
of 2025-11-15
Package: 14.1.0
current state:
==
(setq
window-system 'ns
LaTeX-version "2e"
TeX-style-path '("~/.emacs.d/auctex/"
"/Users/au710211/.emacs.d/elpaca/repos/auctex/style"
"/Users/au710211/.emacs.d/auctex/auto"
"/Users/au710211/.emacs.d/auctex/style" "auto" "style")
TeX-auto-save nil
TeX-parse-self nil
TeX-master t
TeX-command-list '(("T
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul, On 07/12/2025, Paul D. Nelson wrote: > Thanks. I'll take a look at your specific comments later, but wanted to > mention an issue that came up immediately. With > 'preview-visibility-style' set to 'always or 'at-point, if I modify the > preview, then the graphic is replaced by the character "x". In case > it's helpful for debugging, the relevant overlay property looks like so: Can you try to send a reproduction recipe? I am not seeing this behaviour when I test on my setup or on "emacs -Q" with various settings and I don't quite understand how you could arrive to the strings that you listed, so I am missing something. -- Al ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al,
Thanks. I'll take a look at your specific comments later, but wanted to
mention an issue that came up immediately. With
'preview-visibility-style' set to 'always or 'at-point, if I modify the
preview, then the graphic is replaced by the character "x". In case
it's helpful for debugging, the relevant overlay property looks like so:
strings
(#("x" 0 1
(display
(image :file
"~/scratch/tex/build/_region_.prv/tmpggqjfo/prev001.png"
:type png :ascent 85)
mouse-face highlight help-echo
" opens text\n more options"
keymap
(keymap
(mouse-3
. #[257 "\301\300\"\207"
[#
preview-context-menu]
4
("~/.emacs.d/elpaca/builds/auctex/preview.elc"
. 89759)
"e"])
(mouse-2
. #[0 "\301\300!\207"
[#
preview-regenerate]
2 nil nil]
. #("x\n" 0 1
(keymap
(keymap
(mouse-3
. #[257 "\301\300\"\207"
[#
preview-context-menu]
4
("~/.emacs.d/elpaca/builds/auctex/preview.elc"
. 89759)
"e"])
(mouse-2
. #[0 "\301\300!\207"
[#
preview-regenerate]
2 nil nil]))
help-echo
" regenerates preview\n more options"
mouse-face highlight display nil)))
I tried tweaking the various settings (keep-stale-images, etc.) and this
behavior didn't seem to change. Happy to attempt to give a more
detailed reproduction if that would help, but maybe the above is enough
to see what's going on.
P.S. there are some minor compiler warnings (preview--string and
preview-temporary-opened are used before their definition).
Thanks, best,
Paul
___
bug-auctex mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul,
Attached is an updated patch. I quite like this new model of
customization and feel it is more intuitive than before. Thank you for
the feedback and the suggestions. In this patch, three new
customizations are added, and two are made obsolete, so the overall
customization complexity is not dramatically increased.
There's a couple of discrepancies that I noticed in my tests:
- When a preview fails or is modified (and thus disabled), it remains
open, showing the source, and its visibility follows
`preview-visibility-style` as expected. The exception is when
`preview-visibility-style` is `always` or `off-point` and
`preview-at-point-placement` is `buframe`. In this setup, the preview
is not shown away from point, because only one buframe can be visible
at a time, and it always displays the preview under point. This seems
inherent to the design; it likely just needs to be documented, though
I'm not sure my current wording is adequate.
- Another point is that, while I like splitting
`preview-leave-open-previews-visible` into `preview-keep-stale-images`
and `preview-visibility-style = 'off-point` (in particular, it allows
always showing non-stale images), there's one issue. If
`preview-keep-stale-images` is t, while `preview-visibility-style` is
'off-point, then modifying the source disables the preview, but
reusing the image is nonsensical since the preview is replaced by an
icon when opened. Currently stale images are not kept in either of
those case. I feel this is OK, but I am open to suggestions.
As part of a small refactor I removed two old functions:
preview-disabled-string and preview-inactive-string, and used the new
macro preview--string directly instead. I think these are internal
functions, but let me know if I should retain them or mark them as
obsolete.
Best regards,
-- Al
On 04/12/2025, Paul D. Nelson wrote:
> Hi Al,
>
> I see your points, and am likewise happy with what you ultimately
> suggest:
>
>> my preference is still to simply have a single customization variable
>> which we can use directly in the code.
>
> Thanks, best,
>
> Paul
>From 0e88784655234c855a19000414eccce6f06ac681 Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Wed, 26 Nov 2025 12:26:40 +0100
Subject: [PATCH] New feature: preview at point
* doc/preview-latex.texi: Add docs for new customizations.
* preview.el: (preview-visibility-style, preview-keep-stale-images,
preview-at-point-placement): New customizations.
(preview--update-buframe, preview-overlay-updated): New functions.
(preview-leave-open-previews-visible, preview-protect-point): Mark as
obsolete.
(preview--string): New macro.
(preview-replace-active-icon): Call preview-overlay-updated.
(preview-place-preview): Clear-out before toggling.
(preview-mark-point, preview--open-for-replace): Add condition on
`preview-visibility-style`.
(preview-toggle): Update to handle values of preview-visibility-style
and preview-at-point-placement call preview-overlay-updated. Handle ARG
being equal to `maybe-open'.
(preview-move-point): Handle `preview-visibility-style` and call
`preview--update-buframe`.
(preview-active-string, preview-disabled-string): Remove and refactor
into a generic preview--string.
(preview-disable): Always call preview-toggle and condition deleting
files on `preview-leave-open-previews-visible`.
(preview-parse-messages): Restore point before placing preview.
(preview-region): Update documentation to return started process.
(preview-dvi*-command): Fix case in docstring.
(preview-gs-flag-error): Fix spacing, fix bug and conditionally open
previews.
(preview-gs-place): Use `preview-keep-stale-images` instead of
`preview-leave-open-previews-visible`.
(preview-check-changes): Use `preview-visibility-style` instead of
`preview-leave-open-previews-visible`.
Developed in collaboration with Paul D. Nelson (ultrono (at) gmail).
---
doc/preview-latex.texi | 41
preview.el | 479 -
2 files changed, 368 insertions(+), 152 deletions(-)
diff --git a/doc/preview-latex.texi b/doc/preview-latex.texi
index 19210a35..9daab4ee 100644
--- a/doc/preview-latex.texi
+++ b/doc/preview-latex.texi
@@ -480,6 +480,47 @@ math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
@previewlatex{}'s, you can turn off inline math previews. In the
@samp{Preview Latex} group, remove @code{textmath} from
@code{preview-default-option-list} by customizing this variable.
+
+@item Customize where previews are shown
+
+Set @code{preview-visibility-style} to control when previews appear:
+
+@table @code
+
+@item off-point
+Default. Previews replace the source when point is elsewhere. When a
+preview is opened to show the source, the preview is replaced by an icon.
+
+@item at-point
+Previews never obscure the source. When the cursor enters the source, the
+preview, if there is one, appears alongside it.
+
+@item always
+Previews are always visible when available. Away from point
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, I see your points, and am likewise happy with what you ultimately suggest: > my preference is still to simply have a single customization variable > which we can use directly in the code. Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul, On 02/12/2025, Paul D. Nelson wrote: > One worry is that I have found it tricky to reason about code when one > setting controls many logically unrelated features. I take your point. However, I think from a user-perspective `preview-visibility-style` is logical enough by simply controlling visibility of the preview on and off-point, especially if we drop `off-point-deferred`. > One compromise would be to keep the individual knobs S/D/P and layer > 'preview-visibility-style' as a preset that simply sets S/D/P to the > combinations you listed. That saves users from juggling three booleans, > but allows the code to read in terms of simple predicates and retains > flexibility for users who might want some "nonstandard" combination. > (There's some precedent for such presets in cc-mode, org, ...) I think this is a good compromise in theory, but my worry is that by having /custom variables/ as you suggest, it indicated that all value combinations are valid and supported (if not otherwise documented). This means that we and future contributors to preview will have to make sure that any changes are compatible with all possible values of the custom variables even if only a smaller subset is in active use by most users -- I got tripped up by this multiple times forgetting to test a particular combination or another. This is why I prefer having fewer points of user customizations that give concrete and limited use-cases which are easily configurable and testable. So my thinking is that if you want to keep these individual knobs for maximum hackability as you suggest they should be defvar's instead of defcustom's (possibly documenting that they are internal), though my preference is still to simply have a single customization variable which we can use directly in the code. Best regards, -- Al ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, I like these suggestions. In the language of my previous email, you're pointing out that for S=preview-show-away-from-point, D=preview-at-point-display, P=preview-protect-point, not all 2^3=8 combinations make sense in practice, and it's nicer to tweak one variable than three. Maybe we call the combined option 'preview-visibility-style' to avoid having a non-mode end in '-mode'? One worry is that I have found it tricky to reason about code when one setting controls many logically unrelated features. For instance, 'preview-leave-open-previews-visible' (which I'm to blame for) affects two different sorts of behavior. Every time I revisited code that referenced it, I had to reread its docstring and try to recall which side effect was in play. Splitting into 'preview-keep-stale-images' and 'preview-at-point-display' should fix that. I worry that 'preview-visibility-style' might be similarly complicated (we'd at least need a crisp docstring). One compromise would be to keep the individual knobs S/D/P and layer 'preview-visibility-style' as a preset that simply sets S/D/P to the combinations you listed. That saves users from juggling three booleans, but allows the code to read in terms of simple predicates and retains flexibility for users who might want some "nonstandard" combination. (There's some precedent for such presets in cc-mode, org, ...) Regarding the preset list, I'd be fine dropping 'off-point-deferred. 'preview-protect-point' was added only ~1.5 years ago with the purpose of supporting auto/live previewing via what we're now calling the 'always preset. Whenever I've advertised it, it was in tandem with 'preview-leave-open-previews-visible', so I doubt many people are using it on its own. In any event, no flexibility would ultimately be lost via the "preset" route. Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul, On 30/11/2025, Paul D. Nelson wrote: > A couple minor comments: > > - The buframe jumps around a bit while live editing (regardless of other > settings). Could this be reduced somehow? (Not a big issue, and can > be postponed to later patches if it's at all tricky.) This one is tricky because I am not sure what a better solution would be. Currently, I use `buframe-position-right-of-overlay` to determine the position of the buframe which places it to the right, centred vertically. As the overlay dimension change (when the TeX source is modified), the buframe placement changes. This was intentional as I wanted the frame to move out of the way of the text (so it always gets pushed right). I can disable vertical re-centring, but the frame would still be moving around. > - The comment ';;; preview-point customizations and variables' now seems > obsolete (and many things in the section that it demarcates are > unrelated to the new functionality). Noted. > Rename 'preview-always-show' to 'preview-show-away-from-point', rename > 'preview-point-where' to 'preview-at-point-placement', and split > 'preview-leave-open-previews-visible' into 'preview-at-point-display' > and 'preview-keep-image-during-regeneration', with behavior as follows: IMO the name `preview-keep-image-during-regeneration` is not accurate because the images are kept when the preview is disabled or "stale" (after change) even before generation. Perhaps `preview-keep-stale-images` is better? Regarding the other options, the inconsistency for me is that `preview-at-point-display` is only relevant when `preview-show-away-from-point` is non-nil. A similar inconsistency is with `preview-protect-point`, which is relevant only when `preview-show-away-from-point` is non-nil (in fact it only makes sense if icons are displayed on point -- if the preview is always displayed then there's no reason not to "protect point"). If we are open to completely changing the customization interface, how about we add a new single customization `preview-show-mode` taking one of four values (to map it to your proposal, let S=preview-show-away-from-point, D=preview-at-point-display, P=preview-protect-point): - 'always: Show preview both at point with the source and away from it replacing the source (S=t, D=preview, P=t). - 'at-point: Show preview only at point with the source (S=nil, D and P irrelevant). - 'off-point: Show preview only away from point replacing the source. At point, show the source with an icon. Update preview immediately when regenerated, hiding source (S=t, D=icon, P=nil). - 'off-point-deferred: Show preview only away from point replacing the source. At point, show the source with an icon. Defer updating the preview when regenerated until cursor moves out of source (S=t, D=icon, P=t). This drops support for (S=t, D=preview, P=nil), but IMO this is a useless mode since the visible preview will be updated when it is generated and there's no need to hide the source on regeneration. This proposal would be in addition to `preview-keep-stale-images` and `preview-at-point-placement` above and would make the two variables `preview-protect-point` and `preview-leave-open-previews-visible` obsolete. Best regards, -- Al ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
> I am not sure what the issue is, but here's another patch rebased to > 4308da8159 Fix infinite loop with `TeX-previous-error'. Thanks, that one works! (The earlier one had a spurious "g" at the left of line 413, but even deleting that didn't fix it for me.) Most issues have been resolved. I'll test on multiple monitors soon. A couple minor comments: - The buframe jumps around a bit while live editing (regardless of other settings). Could this be reduced somehow? (Not a big issue, and can be postponed to later patches if it's at all tricky.) - The comment ';;; preview-point customizations and variables' now seems obsolete (and many things in the section that it demarcates are unrelated to the new functionality). The remaining conceptual issue from my POV is that it is now quite difficult to describe what 'preview-leave-open-previews-visible' does. It was already complicated enough, and the docstring needs to be updated further to incorporate the effect of 'preview-always-show'. The best solution I've come up with is to split it into a couple settings (which was already on the table when the option was added, see https://lists.gnu.org/archive/html/bug-auctex/2024-04/msg00128.html, but was less pressing then). What do you think about the following? Rename 'preview-always-show' to 'preview-show-away-from-point', rename 'preview-point-where' to 'preview-at-point-placement', and split 'preview-leave-open-previews-visible' into 'preview-at-point-display' and 'preview-keep-image-during-regeneration', with behavior as follows: --8<---cut here---start->8--- (defcustom preview-show-away-from-point t "Show previews while point is outside their source. When non-nil, overlays away from point display as rendered previews. When nil, overlays away from point show the TeX source until point enters their source; then, the options `preview-at-point-display' and `preview-at-point-placement' apply." :group 'preview-appearance :type 'boolean) (defcustom preview-at-point-display 'icon "Display style while point is inside a preview overlay. Set this to `icon' to reveal the TeX placeholder glyph, or to `preview' to display the rendered image while point is present. The placement is determined by `preview-at-point-placement'." :group 'preview-appearance :type '(choice (const :tag "TeX icon" icon) (const :tag "Rendered preview" preview))) (defcustom preview-at-point-placement 'before-string "Where to place the at-point preview or icon relative to its source. [Remainder of docstring same as before]." :group 'preview-appearance :type ;; ...same as before... ) (defcustom preview-keep-image-during-regeneration t "Keep the last preview image visible during regeneration. If non-nil, a preview that was just edited retains its previous image while it sits in the disabled state instead of showing the construction icon. When nil, the icon appears until the refreshed image arrives." :group 'preview-appearance :type 'boolean) (defcustom preview-leave-open-previews-visible nil "Obsolete alias for the at-point display and flicker knobs. Setting this also sets `preview-keep-image-during-regeneration' to the same value, and sets `preview-at-point-display' to `preview' when non-nil." :group 'preview-appearance :type 'boolean :set (lambda (sym value) (set-default sym value) (set-default 'preview-keep-image-during-regeneration value) (set-default 'preview-at-point-display (if value 'preview 'icon (make-obsolete-variable 'preview-leave-open-previews-visible "Use `preview-keep-image-during-regeneration' \ and `preview-at-point-display' instead." "14.2.0") --8<---cut here---end--->8--- Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul,
I am not sure what the issue is, but here's another patch rebased to
4308da8159 Fix infinite loop with `TeX-previous-error'.
Best regards,
-- Al
>From 50b3a2361e74565687a2c04666501340a46b1dcf Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Wed, 26 Nov 2025 12:26:40 +0100
Subject: [PATCH] New feature: preview at point
* doc/preview-latex.texi: Add docs for previewing at point.
* preview.el (preview-always-show, preview-point-where): New
customizations.
(preview--update-buframe, preview-overlay-updated): New functions.
(preview--string): New macro.
(preview-replace-active-icon): Call preview-overlay-updated.
(preview-place-preview): Clear-out before toggling.
(preview-mark-point, preview--open-for-replace): Add condition on
`preview-always-show`.
(preview-toggle): Update to handle values of preview-always-show and
preview-point-where and call preview-overlay-updated. Handle ARG being
equal to `maybe-open'.
(preview-move-point): Handle `preview-always-show` and call
`preview--update-buframe`.
(preview-active-string, preview-disabled-string): Refactor into
preview--string.
(preview-disable): Always call preview-toggle and condition deleting
files on `preview-leave-open-previews-visible`.
(preview-parse-messages): Restore point before placing preview.
(preview-region): Update documentation to return started process.
(preview-dvi*-command): Fix case in docstring.
(preview-gs-flag-error): Fix spacing, fix bug and conditionally open
previews.
---
doc/preview-latex.texi | 26 +++
preview.el | 381 -
2 files changed, 292 insertions(+), 115 deletions(-)
diff --git a/doc/preview-latex.texi b/doc/preview-latex.texi
index 19210a3506..c41211156c 100644
--- a/doc/preview-latex.texi
+++ b/doc/preview-latex.texi
@@ -480,6 +480,32 @@ math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
@previewlatex{}'s, you can turn off inline math previews. In the
@samp{Preview Latex} group, remove @code{textmath} from
@code{preview-default-option-list} by customizing this variable.
+
+@item Show previews always or at point.
+
+By default, previews are always shown when available, but this can be
+disabled by setting @code{preview-always-show} to @code{nil}. In this
+case, the preview is only shown when the cursor enters the corresponding
+TeX source.
+
+@item Control placement of previews.
+
+You can set @code{preview-point-where} to determine where previews are
+placed relative to the TeX source when both are being shown. This variable
+can take the following values:
+
+@table @code
+
+@item before-string
+Show the preview before the TeX source (default).
+
+@item after-string
+Show the preview after the TeX source.
+
+@item buframe
+Show the preview in a separate frame next to the cursor. Requires the
+@code{buframe} package to be installed (available on ELPA).
+@end table
@end itemize
@node Known problems, For advanced users, Simple customization, top
diff --git a/preview.el b/preview.el
index 9481288675..46ce9618ac 100644
--- a/preview.el
+++ b/preview.el
@@ -456,6 +456,37 @@ set to `postscript'."
:group 'preview-latex
:type 'boolean)
+;;; preview-point customizations and variables.
+(defcustom preview-always-show t
+ "If non-nil, always show previews.
+
+When nil, previews are only shown when a cursor enters their source.
+See `preview-point-where' to control where they are shown."
+ :type 'boolean)
+
+(defcustom preview-point-where 'before-string
+ "Specifies where to show the preview relative to TeX source.
+
+Can be `before-string', `after-string' to show the preview at before or
+after the TeX code or `buframe' to show it in a separate frame (the
+`buframe' package must be installed). Can also be \\='(buframe FN-POS
+FRAME-PARAMETERS BUF-PARAMETERS) where FN-POS is a position
+function (default is `buframe-position-right-of-overlay') and
+FRAME-PARAMETERS is an alist of additional frame parameters, default is
+nil and BUF-PARAMETERS is an alist of buffer local variables and their
+values."
+ :type '(choice
+ (const :tag "Before string (default)" before-string)
+ (const :tag "After string" after-string)
+ (const :tag "On frame" buframe)
+ (list :tag "On frame with explicit parameters"
+(const buframe)
+(choice
+ (const :tag "Default" nil)
+ (function :tag "Position function"))
+(alist :tag "Frame parameters")
+(alist :tag "Buffer parameters"
+
(defun preview-string-expand (arg &optional separator)
"Expand ARG as a string.
It can already be a string. Or it can be a list, then it is
@@ -567,7 +598,7 @@ CMD can be used to override the command line which is used as a basis.
You may set the variable `preview-dvi*-command' to
`preview-dvisvgm-command' and set `preview-dvi*-image-type' to
-`svg' to produce svg images instead of png ones."
+\\='svg to produce SVG images instead of PNG o
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, The patch seems to be corrupted - could you please check on it? Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul,
On 28/11/2025, Paul D. Nelson wrote:
> ...the previews are shown by default, together with the tex code, which
> is not the intended effect.
Indeed, this was an issue with the previous implementation (one too many
simplifications). I've now addressed it in the attached patch. I've
tried to test all combinations of: preview-point-where,
preview-always-show, preview-protect-point,
preview-leave-open-previews-visible (I realize now that
preview-protect-point is meaningless when preview-always-show is nil).
With this more through testing, I've noticed several issues which the
attached patch fixes as well. One is an issue with the old preview code
(even without my patches) when previewing a statement like
$\ifPreview\special{ps: junk}\fi f \geq 2$
with the cursor being inside the equation (moving away from the preview closes
it which is not intended).
I also refactored the code for `preview-disabled-string` and
`preview-inactive-string` and added appropriate new-lines to the strings
depending on the value of `preview-point-where` (I didn't notice this issue
before).
Best regards,
-- Al
>From 2ae17738172f8fbd740fdb6d34ea65e43d503f77 Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Wed, 26 Nov 2025 12:26:40 +0100
Subject: [PATCH] New feature: preview at point
* doc/preview-latex.texi: Add docs for previewing at point.
* preview.el (preview-always-show, preview-point-where): New
customizations.
(preview--update-buframe, preview-overlay-updated): New functions.
(preview--string): New macro.
(preview-replace-active-icon): Call preview-overlay-updated.
(preview-place-preview): Clear-out before toggling.
(preview-mark-point, preview--open-for-replace): Add condition on
`preview-always-show`.
(preview-toggle): Update to handle values of preview-always-show and
preview-point-where and call preview-overlay-updated. Handle ARG being
equal to `maybe-open'.
(preview-move-point): Handle `preview-always-show` and call
`preview--update-buframe`.
(preview-active-string, preview-disabled-string): Refactor into
preview--string.
(preview-disable): Always call preview-toggle and condition deleting
files on `preview-leave-open-previews-visible`.
(preview-parse-messages): Restore point before placing preview.
(preview-region): Update documentation to return started process.
(preview-dvi*-command): Fix case in docstring.
(preview-gs-flag-error): Fix spacing, fix bug and conditionally open
previews.
---
doc/preview-latex.texi | 26 +++
preview.el | 383 -
2 files changed, 294 insertions(+), 115 deletions(-)
diff --git a/doc/preview-latex.texi b/doc/preview-latex.texi
index 19210a3506..c41211156c 100644
--- a/doc/preview-latex.texi
+++ b/doc/preview-latex.texi
@@ -480,6 +480,32 @@ math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
@previewlatex{}'s, you can turn off inline math previews. In the
@samp{Preview Latex} group, remove @code{textmath} from
@code{preview-default-option-list} by customizing this variable.
+
+@item Show previews always or at point.
+
+By default, previews are always shown when available, but this can be
+disabled by setting @code{preview-always-show} to @code{nil}. In this
+case, the preview is only shown when the cursor enters the corresponding
+TeX source.
+
+@item Control placement of previews.
+
+You can set @code{preview-point-where} to determine where previews are
+placed relative to the TeX source when both are being shown. This variable
+can take the following values:
+
+@table @code
+
+@item before-string
+Show the preview before the TeX source (default).
+
+@item after-string
+Show the preview after the TeX source.
+
+@item buframe
+Show the preview in a separate frame next to the cursor. Requires the
+@code{buframe} package to be installed (available on ELPA).
+@end table
@end itemize
@node Known problems, For advanced users, Simple customization, top
diff --git a/preview.el b/preview.el
index 9481288675..4ecf8f 100644
--- a/preview.el
+++ b/preview.el
@@ -456,6 +456,37 @@ set to `postscript'."
:group 'preview-latex
:type 'boolean)
+;;; preview-point customizations and variables.
+(defcustom preview-always-show t
+ "If non-nil, always show previews.
+
+When nil, previews are only shown when a cursor enters their source.
+See `preview-point-where' to control where they are shown."
+ :type 'boolean)
+
+(defcustom preview-point-where 'before-string
+ "Specifies where to show the preview relative to TeX source.
+
+Can be `before-string', `after-string' to show the preview at before or
+after the TeX code or `buframe' to show it in a separate frame (the
+`buframe' package must be installed). Can also be \\='(buframe FN-POS
+FRAME-PARAMETERS BUF-PARAMETERS) where FN-POS is a position
+function (default is `buframe-position-right-of-overlay') and
+FRAME-PARAMETERS is an alist of additional frame parameters, default is
+nil and BUF-PARAMETERS is an alist of buffer local variables and their
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, Thanks, I've been testing the latest patch. It indeed seems that (A) is fixed. I haven't yet had the chance to test (C) (the monitor-related issue). One thing I've noticed now is that with the settings (setopt preview-leave-open-previews-visible t) (setopt preview-always-show nil) (setopt preview-point-where 'before-string) ...the previews are shown by default, together with the tex code, which is not the intended effect. Please let me know if more details would help. Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul,
On 27/11/2025, Paul D. Nelson wrote:
>> I've seen this issue once, but I thought I already addressed it and I no
>> longer see it. I also don't recognize the behaviour you describe since
>> with these settings, calling `preview-at-point` updates the preview,
>> yeets the cursor out of the source and the preview is shown inline until
>> one enters it again whereupon it is shown in a buframe. Can you confirm
>> and/or provide more details?
>
> I use (setq preview-protect-point t), which I suspect accounts for the
> difference you observe (but let me know if otherwise).
Ah, I forgot about this mode. I fixed the issue in the attached patch
along with some other changes that you suggested (let me know if I
missed any) and other simplifications.
I've also pushed a fix to buframe that might handle the (C) issue (I
don't have multiple monitors so it's difficult for me to truly test it),
can you confirm?
> I haven't been able to reproduce this just now -- not sure what changed.
> I'll try some more over the coming days.
Let me know, but please use the attached patch if possible. I've made
some further simplifications that should also make things easier to
debug issues.
I've also removed the custom face for disabled previews (I will probably
suggest it as another patch). This is because it requires a bit more
work to make it work well with "under-construction" previews while
avoiding flickering.
Best regards,
-- Al
>From 98308a893127cc5649737dec4a5032608321659e Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Wed, 26 Nov 2025 12:26:40 +0100
Subject: [PATCH] New feature: preview at point
* doc/preview-latex.texi: Add docs for previewing at point.
* preview.el (preview-always-show, preview-point-where): New customizations.
(preview--frame): New variable.
(preview-replace-active-icon): Call preview-overlay-updated.
(preview-place-preview): Clear-out before toggling.
(preview-gs-flag-error, preview-mark-point, preview--open-for-replace):
Add condition on `preview-always-show`.
(preview-toggle): Update to handle values of preview-always-show and
preview-point-where and call preview-overlay-updated.
(preview-move-point): Handle `preview-always-show` and call
`preview--update-buframe`.
(preview-disabled-string): Handle `preview-leave-open-previews-visible`.
(preview-disable): Always call preview-toggle and condition deleting
files on `preview-leave-open-previews-visible`.
(preview-parse-messages): Restore point before placing preview.
(preview-region): Update documentation to return started process.
(preview--update-buframe, preview-overlay-updated): New functions.
(preview-dvi*-command): Fix case in docs.
---
doc/preview-latex.texi | 26
preview.el | 275 ++---
2 files changed, 232 insertions(+), 69 deletions(-)
diff --git a/doc/preview-latex.texi b/doc/preview-latex.texi
index 19210a35..c4121115 100644
--- a/doc/preview-latex.texi
+++ b/doc/preview-latex.texi
@@ -480,6 +480,32 @@ math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
@previewlatex{}'s, you can turn off inline math previews. In the
@samp{Preview Latex} group, remove @code{textmath} from
@code{preview-default-option-list} by customizing this variable.
+
+@item Show previews always or at point.
+
+By default, previews are always shown when available, but this can be
+disabled by setting @code{preview-always-show} to @code{nil}. In this
+case, the preview is only shown when the cursor enters the corresponding
+TeX source.
+
+@item Control placement of previews.
+
+You can set @code{preview-point-where} to determine where previews are
+placed relative to the TeX source when both are being shown. This variable
+can take the following values:
+
+@table @code
+
+@item before-string
+Show the preview before the TeX source (default).
+
+@item after-string
+Show the preview after the TeX source.
+
+@item buframe
+Show the preview in a separate frame next to the cursor. Requires the
+@code{buframe} package to be installed (available on ELPA).
+@end table
@end itemize
@node Known problems, For advanced users, Simple customization, top
diff --git a/preview.el b/preview.el
index 94812886..257baf91 100644
--- a/preview.el
+++ b/preview.el
@@ -456,6 +456,41 @@ set to `postscript'."
:group 'preview-latex
:type 'boolean)
+;;; preview-point customizations and variables.
+(defcustom preview-always-show t
+ "If non-nil, always show previews.
+
+When nil, previews are only shown when a cursor enters their source.
+See `preview-point-where' to control where they are shown."
+ :type 'boolean)
+
+(defcustom preview-point-where 'before-string
+ "Specifies where to show the preview relative to TeX source.
+
+Can be `before-string', `after-string' to show the preview at before or
+after the TeX code or `buframe' to show it in a separate frame (the
+`buframe' package must be installed). Can also be \\='(buframe FN-POS
+FRAME-PARAMETERS BUF-PARAMETERS) where FN-POS is a pos
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, > However, one use case for `preview-leave-open-previews-visible` (V) is > controlling if an icon is displayed in certain cases, e.g., when the > preview is disabled after editing or when it is being re-generated, > instead of the (outdated) preview. This use case is always relevant for > all values of `preview-point-where` and `preview-always-show`. Agreed so far (and indeed, the intent of "V" was simply to reduce flicker with automatic previewing, which is likewise relevant for all such values). > The other point is that, currently, the placement of the icon itself is > also determined by the value of `preview-point-where`. If we use a nil > value to denote icons, then we would fix the placement of the icon which > seems unnecessarily inconsistent with the new increased customization. I see your point about increased customization, although I wonder about the value of allowing flexible placement of the icon -- would any user care to move it away from its default location, and why? I still see your point and will think about it more. > >> I noticed the following issues (A), (B), (C): > What emacs version you are using and what value of `preview-auto-reveal` > (I mainly have my tests with it being set to `t`)? I'm on a fairly recent Emacs master (28f0658d8f5 from Nov 15), using the default value of preview-auto-reveal, with preview-auto-reveal-commands customized to: (czm-tex-edit-return tex-parens-backward-down-list tex-parens-down-list czm-tex-jump-back-with-breadcrumb consult-register-load ace-window other-window flymake-goto-prev-error flymake-goto-next-error (key-binding [left]) (key-binding [right]) backward-char forward-char pop-to-mark-command undo) I have not tested with 'preview-auto-reveal' set to t. >> (A) With >> >> (setq preview-always-show t) >> (setq preview-point-where 'buframe) >> > I've seen this issue once, but I thought I already addressed it and I no > longer see it. I also don't recognize the behaviour you describe since > with these settings, calling `preview-at-point` updates the preview, > yeets the cursor out of the source and the preview is shown inline until > one enters it again whereupon it is shown in a buframe. Can you confirm > and/or provide more details? I use (setq preview-protect-point t), which I suspect accounts for the difference you observe (but let me know if otherwise). > >> (B) With >> >> (setq preview-leave-open-previews-visible t) >> (setq preview-always-show nil) >> (setq preview-point-where 'buframe) >> >> Enter a generated preview, edit it, regenerate it in place (e.g., with >> 'preview-at-point'), and then exit it. Both the tex source and the >> preview remain visible (until the preview is regenerated, so let's >> suppose automatic previewing is disabled). >> > > I don't see this behaviour either, definitely not with buframe. Can you > confirm again and provide more details (source)? The post-command-hook > `preview-move-point` calls `preview--update-buframe` which should hide > the buframe when the overlay at point does not have the buframe > property, so exiting the source should hide the buframe unless there's a > case I am not considering. I haven't been able to reproduce this just now -- not sure what changed. I'll try some more over the coming days. Everything else you said sounds great (and I don't object to the whitespace change, especially given, as you point out, that you're modifying the same function). Thanks also for your clarifications in the other message. Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi again, A couple of replies to points I missed: On 22/11/2025, Paul D. Nelson wrote: >> + ;; Restore point to current one before >> + ;; placing preview >> + (goto-char point-current) > Is there a new reason for adding this goto-char? Absolutely. `preview-place-preview` calls the 'place' function. This sets the preview properties and could show the buframe if the cursor is on top of the overlay. Before, this wasn't possible because the point was always set to be on top of the overlay when the preview is placed and there's no way for preview-toggle to know the real cursor position. >> +(eq (overlay-buffer ov) (window-buffer)) > Consider: (current-buffer) I use window-buffer because this function is sometimes called from within a `with-current-buffer` so (current-buffer) is bogus for purposes of determining if the currently displayed buffer is the same as the overlay-buffer. Although, I am realizing this could be unnecessary, so I'll check it. -- Al ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul, On 22/11/2025, Paul D. Nelson wrote: > I wonder whether the default should instead be a new setting "nil", > meaning that previews at point are not be displayed at all (the current > default behavior in AUCTeX). I agree that the current situation is not ideal, in the sense that the combination/naming of customization variables are not 100% coherent. However, one use case for `preview-leave-open-previews-visible` (V) is controlling if an icon is displayed in certain cases, e.g., when the preview is disabled after editing or when it is being re-generated, instead of the (outdated) preview. This use case is always relevant for all values of `preview-point-where` and `preview-always-show`. The other point is that, currently, the placement of the icon itself is also determined by the value of `preview-point-where`. If we use a nil value to denote icons, then we would fix the placement of the icon which seems unnecessarily inconsistent with the new increased customization. > I noticed the following issues (A), (B), (C): What emacs version you are using and what value of `preview-auto-reveal` (I mainly have my tests with it being set to `t`)? > > (A) With > > (setq preview-always-show t) > (setq preview-point-where 'buframe) > I've seen this issue once, but I thought I already addressed it and I no longer see it. I also don't recognize the behaviour you describe since with these settings, calling `preview-at-point` updates the preview, yeets the cursor out of the source and the preview is shown inline until one enters it again whereupon it is shown in a buframe. Can you confirm and/or provide more details? > (B) With > > (setq preview-leave-open-previews-visible t) > (setq preview-always-show nil) > (setq preview-point-where 'buframe) > > Enter a generated preview, edit it, regenerate it in place (e.g., with > 'preview-at-point'), and then exit it. Both the tex source and the > preview remain visible (until the preview is regenerated, so let's > suppose automatic previewing is disabled). > I don't see this behaviour either, definitely not with buframe. Can you confirm again and provide more details (source)? The post-command-hook `preview-move-point` calls `preview--update-buframe` which should hide the buframe when the overlay at point does not have the buframe property, so exiting the source should hide the buframe unless there's a case I am not considering. > (C) With > > (setq preview-point-where 'buframe) > > The buframe feature doesn't work correctly with a multi-monitor setup. > On my main monitor, it works fine, but on my other two monitors, it > either doesn't display at all or displays very far from the original > preview graphic. I haven't dug in to debug this. This is possible and is probably a bug in buframe. I will do some tests to confirm and fix it there. > The defcustom signature for the final option does not match the > documentation (and if we adopt the final option via the customize > interface, then it won't work correctly). Either put 'buframe in the > first entry of the list, or test for the final option via 'listp'. Apologies, I noticed this mistake after sending the patch. I had already corrected it to the following, which I will send in an updated patch: ``` (choice (const :tag "Before string" before-string) (const :tag "After string (default)" after-string) (const :tag "On frame" buframe) (list :tag "On frame with explicit parameters" (const buframe) (choice (const :tag "Default" nil) (function :tag "Position function")) (alist :tag "Frame parameters") (alist :tag "Buffer parameters"))) ``` >> +(defface preview-disabled-face >> + '((t (:inherit shadow))) >> + "Face used when preview is disabled." >> + :group 'preview) > > It's not clear to me what the purpose of this new face is. I see that > it affects the text stored in the before/after-string and strings > properties of the overlay, but not the actual TeX code. This face is for the preview itself rather than the source. I believe the face's background colour will affect all previews, while the size/foreground colour only has an effect if the preview is an svg image. I could add this explanation to the docstring. >> + >> +(defvar preview--frame nil >> + "The last active preview popup frame.") > > (Maybe consider something like 'preview--buframe' or 'preview--last-buframe' > to hint at the domain scope of this variable.) I prefer frame since that's the type of value, but I will update the docstring to mention buframe. > (This looks to be just a whitespace change; my understanding was that we > usually avoid pure whitespace changes unless we're touching the code > anyway, but others may know better.) Indeed, I thought the spacing is wrong and could be fixed in this patch since the function is being modified, but I can remove this change. Best regards,
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al,
Thanks, I've been testing this the past few days and it's looking
very good! Response and comments below.
> - `preview-point-where`: default 'before-string, can be set to
> 'after-string and 'buframe as well.
I wonder whether the default should instead be a new setting "nil",
meaning that previews at point are not be displayed at all (the current
default behavior in AUCTeX). To explain more fully, there are three
relevant options:
- 'preview-leave-open-previews-visible' (call it "V")
- 'preview-point-where' (call it "W")
- 'preview-always-show' (call it "S")
The current behavior is as follows (independent of W):
| S | V | shown at point |
|-+-+|
| t | nil | TeX icon |
| nil | nil | preview|
| t | t | preview|
| nil | t | preview|
First, the difference between the first two lines seems odd. Why should
S, which ostensibly controls preview visibility *away* from point, also
affect whether it is the TeX icon or the preview graphic that is shown
*at* point?
Next, the option V currently has two unrelated effects:
(1) causing the preview graphic (rather than TeX icon) to be shown at
point, and
(2) keeping the preview graphic visible when in the "disabled" state
(post-edit, pre-regeneration).
What do you think about refactoring so that (1) is controlled entirely
by W (rather than by some odd combination of S and V, as above)?
Specifically, the proposal is that if W is nil, then the TeX icon is
shown; otherwise, the preview graphic is shown, and the (non-nil) value
of W controls the precise location. This would also address what I
found odd about the above table.
With this change, the only effect of V would be (2).
> Also, I wasn't sure if I should respect `preview-auto-reveal` when
> `preview-always-show` is nil, so I've done that for now. This means that
> to truly get the same behaviour as preview-point, set
> `preview-auto-reveal` to t. Otherwise, the default value of that
> variable only shows the preview on specific key strokes.
This also seems right to me, FWIW, because it maximizes flexibility.
I noticed the following issues (A), (B), (C):
(A) With
(setq preview-always-show t)
(setq preview-point-where 'buframe)
Create an equation environment with some math, and do 'preview-point'.
Alternatively, add some math at the end of an existing equation, and do
'preview-point'. When the buframe preview updates, it does not initially
have the correct bounds -- it's typically too small to accommodate the
previewed graphic. The bounds become correct after exiting and
re-entering the preview.
(B) With
(setq preview-leave-open-previews-visible t)
(setq preview-always-show nil)
(setq preview-point-where 'buframe)
Enter a generated preview, edit it, regenerate it in place (e.g., with
'preview-at-point'), and then exit it. Both the tex source and the
preview remain visible (until the preview is regenerated, so let's
suppose automatic previewing is disabled).
If we instead use
(setq preview-leave-open-previews-visible nil)
then the TeX icon remains visible post-edit, pre-regeneration.
In either case, it seems odd that 'preview-always-show' is nil, yet the
preview and/or TeX icon stick around after point leaves the preview.
(C) With
(setq preview-point-where 'buframe)
The buframe feature doesn't work correctly with a multi-monitor setup.
On my main monitor, it works fine, but on my other two monitors, it
either doesn't display at all or displays very far from the original
preview graphic. I haven't dug in to debug this.
--
OK, now some comments on the patch (some of which are stylistic, please
feel free to ignore):
> +By default, previews are always shown when available, but this can be
> +disabled by setting @code{preview-always-show} to @code{nil}. In this
> +case, the preview is only shown when the cursor enters the corresponding
> +TeX source.
Maybe mention 'preview-point-where' here.
> +;;; preview-point customizations and variables.
> +(defcustom preview-always-show t
> + "If non-nil, always show previews.
> +
> +When nil, previews are only shown when a cursor enters their source. See
> +`preview-point-where' to control where they are shown."
> + :type 'boolean)
Check the fill on this docstring (M-q); with standard settings, I get:
When nil, previews are only shown when a cursor enters their source.
See `preview-point-where' to control where they are shown."
> +
> +(defcustom preview-point-where 'before-string
> + "Specifies where to show the preview relative to TeX source.
> +
> +Can be `before-string', `after-string' to show the preview at before or
> +after the TeX code or `buframe' to show it in a separate frame (the
> +`buframe' package must be installed). Can also be \\='(buframe FN-POS
> +FRAME-PARAMETERS BUF-PARAMETERS) where FN-POS is a position
> +function (default is `buframe-position-right-of-overlay') and
> +FRAME-PARAMETERS is an alist of additional frame parameters, def
bug#79708: 14.1.0; [PATCH] New feature: preview-point
As discussed, I've now made the changes to introduce two customizations
(I am open to changing the names):
- `preview-always-show`: default t, when set to nil it essentially has
the preview-point behaviour (See below).
- `preview-point-where`: default 'before-string, can be set to
'after-string and 'buframe as well.
As an added bonus, this splitting of customizations forced me to rethink
the implementation and now it is greatly simplified with smaller changes
to the existing code.
Also, I wasn't sure if I should respect `preview-auto-reveal` when
`preview-always-show` is nil, so I've done that for now. This means that
to truly get the same behaviour as preview-point, set
`preview-auto-reveal` to t. Otherwise, the default value of that
variable only shows the preview on specific key strokes.
I've also decided to remove the automatic previewing code for now. Since
the two features are orthogonal, I will send that code as a separate patch
to not confuse things.
Feedback is welcome,
-- Al
>From 52f070df6561aabd32e1ededb97f13befd2f87ef Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Wed, 19 Nov 2025 22:52:37 +0100
Subject: [PATCH] New feature: preview at point
* doc/preview-latex.texi: Add docs for previewing at point.
* preview.el (preview-always-show, preview-point-where): New customizations.
(preview-disabled-face): New face for disabled previews.
(preview--frame): New variable.
(preview-gs-sentinel, preview-gs-transact, preview-dvi*-place-all,
preview-place-preview): Call `preview-overlay-updated'.
(preview-gs-flag-error, preview-mark-point, preview--open-for-replace):
Add condition on `preview-always-show`.
(preview-ascent-from-bb): Return 'center when 'preview-point-where' is
'buframe.
(preview-toggle): Update to handle values of preview-always-show and
preview-point-where.
(preview-move-point): Handle `preview-always-show` and call
`preview--update-buframe`.
(preview-disabled-string): Handle `preview-leave-open-previews-visible`
and add `preview-disabled-face`.
(preview-disable): Always call preview-toggle and condition deleting
files on `preview-leave-open-previews-visible`.
(preview-parse-messages): Restore point before placing preview.
(preview-region): Update documentation to return started process.
(preview--update-buframe, preview-overlay-updated): New functions.
---
doc/preview-latex.texi | 26 +++
preview.el | 365 ++---
2 files changed, 293 insertions(+), 98 deletions(-)
diff --git a/doc/preview-latex.texi b/doc/preview-latex.texi
index 19210a3506..c41211156c 100644
--- a/doc/preview-latex.texi
+++ b/doc/preview-latex.texi
@@ -480,6 +480,32 @@ math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
@previewlatex{}'s, you can turn off inline math previews. In the
@samp{Preview Latex} group, remove @code{textmath} from
@code{preview-default-option-list} by customizing this variable.
+
+@item Show previews always or at point.
+
+By default, previews are always shown when available, but this can be
+disabled by setting @code{preview-always-show} to @code{nil}. In this
+case, the preview is only shown when the cursor enters the corresponding
+TeX source.
+
+@item Control placement of previews.
+
+You can set @code{preview-point-where} to determine where previews are
+placed relative to the TeX source when both are being shown. This variable
+can take the following values:
+
+@table @code
+
+@item before-string
+Show the preview before the TeX source (default).
+
+@item after-string
+Show the preview after the TeX source.
+
+@item buframe
+Show the preview in a separate frame next to the cursor. Requires the
+@code{buframe} package to be installed (available on ELPA).
+@end table
@end itemize
@node Known problems, For advanced users, Simple customization, top
diff --git a/preview.el b/preview.el
index 9481288675..ebb4f43860 100644
--- a/preview.el
+++ b/preview.el
@@ -456,6 +456,42 @@ set to `postscript'."
:group 'preview-latex
:type 'boolean)
+;;; preview-point customizations and variables.
+(defcustom preview-always-show t
+ "If non-nil, always show previews.
+
+When nil, previews are only shown when a cursor enters their source. See
+`preview-point-where' to control where they are shown."
+ :type 'boolean)
+
+(defcustom preview-point-where 'before-string
+ "Specifies where to show the preview relative to TeX source.
+
+Can be `before-string', `after-string' to show the preview at before or
+after the TeX code or `buframe' to show it in a separate frame (the
+`buframe' package must be installed). Can also be \\='(buframe FN-POS
+FRAME-PARAMETERS BUF-PARAMETERS) where FN-POS is a position
+function (default is `buframe-position-right-of-overlay') and
+FRAME-PARAMETERS is an alist of additional frame parameters, default is
+nil and BUF-PARAMETERS is an alist of buffer local variables and their
+values."
+ :type '(choice
+ (const :tag "Before string" before-string)
+ (const :tag "After st
bug#79708: 14.1.0; [PATCH] New feature: preview-point
> I largely agree with you, and I am happy for finer control over the > behaviour to be added. Glad to hear we're on the same page now. > The new mode of operation I was referring to is when > `preview-display-style` is set to 'preview (so that previews away from > point are displayed) and `preview-reveal-display` is `buframe`. > > Presumably the previews away from the cursor are being shown using the > 'display' property of the overlay (as is currently done). When the > cursor opens the preview, I think you are proposing that the> TeX > source is displayed in the buffer (by setting 'display to nil) while > the preview *moves* to a buframe. This last sentence indeed captures the intended user-facing behavior, which seems like the amalgam of two features that already exist: - In traditional preview, when point enters a preview, the preview becomes invisible (or the TeX symbol takes its place). - In preview-point, when point enters a preview, the preview is displayed in a buframe. I might be overlooking some nuance, but I had hoped these two apparently orthogonal features could be combined fairly easily. > When the cursor moves out of the source, the preview moves back into > the buffer as a 'display property, correct? If so, don't you think > previews moving between buframe and main buffer would be jarring? This is a valid concern, and it might take some experimentation to see how it feels. I was hoping it'd be no more jarring than what happens in traditional preview, where the preview becomes invisible and then visible again. > I am also still unclear what happens in this case when the TeX source > is modified. Does the preview return back to the buffer as a 'display > property or does the TeX source remain visible (I'd guess the latter > is more reasonable)? I was thinking we could follow the current "traditional preview" behavior: when the TeX source is modified, the preview is disabled and never shown again, except when preview-leave-open-previews-visible is non-nil, in which case the preview remains visible via the 'display property (assuming, of course, that preview-display-style is 'preview). Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
On 03/11/2025, Paul D. Nelson wrote: > I may have added to the confusion by writing "construction symbol" (what > shows up when a preview is regenerating) in a few places where I should > have written "TeX symbol" (what shows up when the TeX source is made > visible after point enters a preview). Ah this is finally becoming clear to me. Sorry it took a while and I thank you for your patience. > I don't think I'm proposing to introduce more modes of operation. I'm > just observing that preview-point bundles two orthogonal features: (a) > disabling preview display by default, and (b) richer customization of > how to display the preview at point. Feature (b) would be useful even > without feature (a), so it seems worth decoupling the two and allowing > them to be configured separately. Does that clarify what I had in mind? I largely agree with you, and I am happy for finer control over the behaviour to be added. The new mode of operation I was referring to is when `preview-display-style` is set to 'preview (so that previews away from point are displayed) and `preview-reveal-display` is `buframe`. Presumably the previews away from the cursor are being shown using the 'display' property of the overlay (as is currently done). When the cursor opens the preview, I think you are proposing that the TeX source is displayed in the buffer (by setting 'display to nil) while the preview *moves* to a buframe. When the cursor moves out of the source, the preview moves back into the buffer as a 'display property, correct? If so, don't you think previews moving between buframe and main buffer would be jarring? I am also still unclear what happens in this case when the TeX source is modified. Does the preview return back to the buffer as a 'display property or does the TeX source remain visible (I'd guess the latter is more reasonable)? In any case, if my understanding is correct, this would require new, careful implementation of moving the preview back and forth. Best regards, -- Al ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
> Hmmm... I am not sure what I am missing. On my setup, the construction
> symbol only appears when the source is modified. If I open the preview
> by having the cursor "go into" the preview image, then navigate away
> from the source, the preview is collapsed again if I don't modify the
> source.
>
> The documentation is also unclear, because the first part of
> `preview-leave-open-previews-visible` leans toward what you say:
>
> --8<---cut here---start->8---
> Whether to leave previews visible when they are opened.
>
> If nil, then the TeX preview icon is used when the preview is opened.
> If non-nil, then the preview image remains visible. In either case, the
> TeX code appears either below or to the right of the displayed graphic.
> --8<---cut here---end--->8---
>
> but then the next part is what I am seeing:
>
> --8<---cut here---start->8---
> If you enable this option, the preview image doesn't turn into
> construction sign temporarily when you edit the underlying LaTeX code
> and regenerate the preview; it is just replaced by updated image when
> ready. This behavior suppresses flicker in the appearance.
> --8<---cut here---end--->8---
I may have added to the confusion by writing "construction symbol" (what
shows up when a preview is regenerating) in a few places where I should
have written "TeX symbol" (what shows up when the TeX source is made
visible after point enters a preview).
You're right that the docstring covers two behaviors: (i) what happens
when a preview is revealed, and (ii) what happens when it's regenerated.
I was talking about (i) before. Since you write that the discussion
below clarified things somewhat, I'll focus my response there.
>
>> Let me restate the proposal using your terminology and proposed setting
>> 'preview-display-style' (for which the 'both option is not what I had in
>> mind, but could also be considered). Two independent knobs:
>>
>> - preview-display-style ('preview, 'src): controls what's shown for
>> previews away from point, that the cursor is *not* inside.
>>
>> - preview-reveal-display ('none, 'after, 'before, 'buframe). What to
>> show when point enters a previewed region (i.e., the overlay or the
>> underlying tex source):
>>
>> - 'none means just show the tex source and the construction sign
>>
>> - 'before means show the preview before the tex source while editing
>>
>> - 'after means show the preview after the tex source while editing
>>
>> - 'buframe means to show the preview in a buframe while editing
>>
>
> OK, this makes it clearer somewhat. Though see above regarding how
> modification of the TeX source changes behaviour (at least in my
> setup). You also mention "while editing", so what happens when not
> editing?
When I say "while editing", I mean "when the point enters the TeX
source, so that the user could in principle edit it". Consider how
'preview-point' behaves right now: either the point is inside some TeX
region (that's what I mean by "while editing"), or away from it.
Behavior "when not editing" is controlled by 'preview-display-style'.
>> Let's translate current behaviors to the above setup:
>>
>> Traditional preview with preview-leave-open-previews-visible nil:
>>
>> (setopt preview-display-style 'preview)
>> (setopt preview-reveal-display 'none)
>
> I am gonna assume you mean that while editing or during the generation
> of the preview the construction sign appears (before or after?). What
> happens when the preview is ready?
When the point later exits the TeX source (and, if modification occurs,
after the preview regenerates), the display reverts to what is specified
by 'preview-display-style'.
>> One benefit of separating these concerns is that we could keep
>> traditional preview behavior away from point while using a buframe for
>> live editing of tex source:
>>
>> (setopt preview-display-style 'preview)
>> (setopt preview-reveal-display 'buframe)
> This is what I was trying to say. I think using a buframe for source
> editing is not really tenable and would be too difficult to get
> right.
I think we have a misunderstanding. By "using a buframe for source
editing", I mean:
- The point is in the TeX source, editing the TeX code there.
- The previewed math is (only) displayed in a separate buframe (updating
live as the user edits, if automatic previewing is enabled).
This is what exactly 'preview-point' already does in its current
implementation. (It sounds to me like you thought I was proposing to
have the TeX source in the buframe, which was not my intention; I can
see how you would view that proposal as untenable.)
> Overall, I am of the opinion that (modulo some forward-thinking
> introduction of the options) we do not over-complicate the current
> implementation at this point by introducing more modes of operation.
I don't think I'm proposing to in
bug#79708: 14.1.0; [PATCH] New feature: preview-point
On 02/11/2025, Paul D. Nelson wrote:
> The main effect of preview-leave-open-previews-visible isn't tied to
> whether the tex source has been modified, but is rather that when point
> enters a preview overlay, the preview remains visible instead of
> collapsing to the construction symbol.
Hmmm... I am not sure what I am missing. On my setup, the construction
symbol only appears when the source is modified. If I open the preview
by having the cursor "go into" the preview image, then navigate away
from the source, the preview is collapsed again if I don't modify the
source.
The documentation is also unclear, because the first part of
`preview-leave-open-previews-visible` leans toward what you say:
--8<---cut here---start->8---
Whether to leave previews visible when they are opened.
If nil, then the TeX preview icon is used when the preview is opened.
If non-nil, then the preview image remains visible. In either case, the
TeX code appears either below or to the right of the displayed graphic.
--8<---cut here---end--->8---
but then the next part is what I am seeing:
--8<---cut here---start->8---
If you enable this option, the preview image doesn't turn into
construction sign temporarily when you edit the underlying LaTeX code
and regenerate the preview; it is just replaced by updated image when
ready. This behavior suppresses flicker in the appearance.
--8<---cut here---end--->8---
> Let me restate the proposal using your terminology and proposed setting
> 'preview-display-style' (for which the 'both option is not what I had in
> mind, but could also be considered). Two independent knobs:
>
> - preview-display-style ('preview, 'src): controls what's shown for
> previews away from point, that the cursor is *not* inside.
>
> - preview-reveal-display ('none, 'after, 'before, 'buframe). What to
> show when point enters a previewed region (i.e., the overlay or the
> underlying tex source):
>
> - 'none means just show the tex source and the construction sign
>
> - 'before means show the preview before the tex source while editing
>
> - 'after means show the preview after the tex source while editing
>
> - 'buframe means to show the preview in a buframe while editing
>
OK, this makes it clearer somewhat. Though see above regarding how
modification of the TeX source changes behaviour (at least in my
setup). You also mention "while editing", so what happens when not
editing?
Also, the placement of the construction sign can be before or after the
source, just like the preview (in fact that's what preview-point does as
well when preview-leave-open-previews-visible is nil).
> Let's translate current behaviors to the above setup:
>
> Traditional preview with preview-leave-open-previews-visible nil:
>
> (setopt preview-display-style 'preview)
> (setopt preview-reveal-display 'none)
I am gonna assume you mean that while editing or during the generation
of the preview the construction sign appears (before or after?). What
happens when the preview is ready?
> One benefit of separating these concerns is that we could keep
> traditional preview behavior away from point while using a buframe for
> live editing of tex source:
>
> (setopt preview-display-style 'preview)
> (setopt preview-reveal-display 'buframe)
This is what I was trying to say. I think using a buframe for source
editing is not really tenable and would be too difficult to get
right.
Overall, I am of the opinion that (modulo some forward-thinking
introduction of the options) we do not over-complicate the current
implementation at this point by introducing more modes of operation.
Best regards,
-- Al
___
bug-auctex mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al,
>> - the preview before the tex code (current behavior of
>> preview-leave-open-previews-visible t)
>> - the preview after the tex code
> My understanding of the `preview-leave-open-previews-visible` option is
> that the previews remain open only when the tex code is changed rather than
> being replaced with a sign. If the tex source is not changed, the
> previews are not kept open. In particular, this shouldn't affect the
> position of the image AFAIK.
The main effect of preview-leave-open-previews-visible isn't tied to
whether the tex source has been modified, but is rather that when point
enters a preview overlay, the preview remains visible instead of
collapsing to the construction symbol.
Let me restate the proposal using your terminology and proposed setting
'preview-display-style' (for which the 'both option is not what I had in
mind, but could also be considered). Two independent knobs:
- preview-display-style ('preview, 'src): controls what's shown for
previews away from point, that the cursor is *not* inside.
- preview-reveal-display ('none, 'after, 'before, 'buframe). What to
show when point enters a previewed region (i.e., the overlay or the
underlying tex source):
- 'none means just show the tex source and the construction sign
- 'before means show the preview before the tex source while editing
- 'after means show the preview after the tex source while editing
- 'buframe means to show the preview in a buframe while editing
Let's translate current behaviors to the above setup:
Traditional preview with preview-leave-open-previews-visible nil:
(setopt preview-display-style 'preview)
(setopt preview-reveal-display 'none)
Traditional preview with preview-leave-open-previews-visible t:
(setopt preview-display-style 'preview)
(setopt preview-reveal-display 'before)
(In particular, if this proposal makes sense, then I think
preview-reveal-display could supersede
preview-leave-open-previews-visible.)
preview-point with buframe:
(setopt preview-display-style 'src)
(setopt preview-reveal-display 'buframe)
One benefit of separating these concerns is that we could keep
traditional preview behavior away from point while using a buframe for
live editing of tex source:
(setopt preview-display-style 'preview)
(setopt preview-reveal-display 'buframe)
We could similarly position the preview after the tex source, if
desired.
Does that sound consistent with what you had in mind?
Thanks, best,
Paul
___
bug-auctex mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello Paul,
Apologies, there's something I don't fully understand. Below is an
attempt at explaining what I currently understand.
On 02/11/2025, Paul D. Nelson wrote:
>
> - just the construction symbol and the tex code (default behavior in
> AUCTeX)
>
> - the preview before the tex code (current behavior of
> preview-leave-open-previews-visible t)
> - the preview after the tex code
My understanding of the `preview-leave-open-previews-visible` option is
that the previews remain open only when the tex code is changed rather than
being replaced with a sign. If the tex source is not changed, the
previews are not kept open. In particular, this shouldn't affect the
position of the image AFAIK.
So, I assume then that you don't mean changing the traditional preview
style after all? But rather have a mode which always show the preview
before or after the tex source with the point movement not affecting
previews.
> - a buframe showing the preview
This has to be point-specific, otherwise it would require showing too
many frames and I don't think it would look good to always show and move
them around.
In summary, here are the behaviours we can have:
- classical preview, before-string (open on cursor going inside image).
- classical preview, after-string (open on cursor going inside image) -- New,
needed?
- preview-point with {after,before}-string or buframe.
- a new mode where previews are not affected by cursor movement, and
previews are always shown as {before,after}-string.
If my understanding is correct of your proposal, then indeed one can have two
options, let's say:
- preview-display: 'preview, 'src, 'both
- preview-display-style: 'after-string, 'before-string, 'buframe
with 'buframe being only supported when `preview-display` is `'src`.
Here:
- preview-display='src is the preview-point style.
- preview-display='preview: is the current preview style.
- preview-display='both: is the new style you want where both source and
preview are always shown and point movement does not affect them.
If my understanding is correct, it shouldn't be too difficult to implement
these, I think.
Best regards,
-- Al
___
bug-auctex mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al,
Responding just to the structural question for now. I think I
miscommunicated:
> We could frame the feature as what's being displayed by default, with
> display-styles for either mode being after-string, before-string or
> buframe's.
I wasn't proposing to change what's displayed *by default* for all
previews, but rather what's shown *after entering an existing preview*.
The options would include:
- just the construction symbol and the tex code (default behavior in
AUCTeX)
- the preview before the tex code (current behavior of
preview-leave-open-previews-visible t)
- the preview after the tex code
- a buframe showing the preview
Does that clarify? Could either shoehorn this option into
preview-leave-open-previews-visible, or absorb that into a new defcustom
('preview-reveal-display'?) taking the values 'none, 'after, 'before,
'buframe. The issue is orthogonal to preview-point vs. normal -- it's
just about "reveal behavior on entry". Note that we're not trying to
edit inside the preview image - we're just choosing how the preview is
displayed when the tex source is made visible after you enter the
overlay.
Does that clarify? I think this would be useful (e.g., I would try it
out with traditional previews).
Paul
___
bug-auctex mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi all, (Paul, I answer below to your point). Attached is an updated patch. Following Paul's suggestions, I added two minor modes: - preview-point-mode: is a global minor mode to enable point preview. Display style is controlled through preview-point-display. - preview-point-auto-mode: is a local minor mode to enable auto updating of existing previews and generation of new ones. Generation is controlled via `preview-point-auto-function`. If the function returns a region, that is used instead of relying on `preview-next-border`. As Paul suggested, auto-previewing can probably can become preview-point agnostic once it is thoroughly tested with classical previews. A couple of points: - Currently, I update all previews in the current buffer when toggling `preview-point-mode` so that the mode can be toggled back and forth. This is problematic because other opened buffers will still have the "wrong" previews with the "wrong" local hooks. The main issue is preview-point-mode is not local while the hooks and the previews are. We can either leave it as is, or loop through all open buffers to do the necessary cleanup. I found making preview-point-mode local a bit cumbersome to implement (I never understood what the best practice is to deal with local variables when a master and included files are involved -- I might take another crack at it later). - One thing I wanted to check: Can we rely on the `preview-region' returning the preview process. It calls `preview-generate-preview' which has this documented behaviour, but `preview-region' does not. Perhaps I can add that to the documentation to make it official? On 01/11/2025, Paul D. Nelson wrote: > (a) Previews away from point are no longer displayed at all. > (b) We gain further flexibility in how we can display the preview at > point -- before the TeX source, after the TeX source, or in a buframe. > [...] > WDYT? Does it reasonable to you to separate these features? I think fundamentally, preview-point and the classical preview are different in what they show by default. preview-point shows the source by default, and then shows the preview when the cursor is inside the source. Classical preview shows the preview by default, but then displays the source when the cursor is "inside" the image. Both do not display the hidden content away from point. We could frame the feature as what's being displayed by default, with display-styles for either mode being after-string, before-string or buframe's. However, I suspect this or having (b) as a feature on its own will be of limited value since buframe only really works with preview-point. Displaying the preview in a buframe means that point cannot get "inside" it to show the source in classical preview mode (plus we would have to track the many displayed buframes). We can't of course show the source in a buframe, since that would prevent editing it. So the only flexibility one gets is being able to show the preview in an `after-string`, as well as the current `before-string`, but I am not sure how desired such a feature is. Best regards, -- Al >From e2a5062c3d5e1c266533965ee9acb6ce659036df Mon Sep 17 00:00:00 2001 From: Al Haji-Ali Date: Tue, 9 Sep 2025 21:19:43 +0100 Subject: [PATCH] preview: New feature, preview-point * doc/preview-latex.texi: Add docs for preview-point-mode * preview.el (preview-silent-errors): New local variable. (preview-point-mode): New globalized minor mode. (preview-point-display): New custom variables (preview-point-disabled-face, preview-point-processing-face): New faces. (preview-point--frame, preview-point--current-overlay): New variables. (preview-dvipng-image-type): Update doc. (preview-log-error,preview-reraise-error): Implement silent mode based on `preview-silent-errors'. (preview-gs-sentinel, preview-gs-transact): Call `preview-point-refresh'. (preview-ascent-from-bb): Return 'center when 'preview-point-mode' is non-nil. (preview-toggle): Call preview-point activation function. (preview-disable): Control behaviour based on preview-point-mode. (preview-map): Add key-binding for `preview-point-mode'. (preview-mode-setup): Control preview setup based on `preview-point-mode'. (preview-parse-messages): Restore point before calling place functions. (preview-point--buframe, preview-point-inside-overlay-p, preview-point-activate-maybe, preview-point-move-point, preview-point-updated, preview-point-mode, preview-point-toggle-auto-refresh, preview-point@around@write-region, preview-point--preview-at-point, preview-point-has-preview-p, preview-point-buf-change): New functions. (preview-point-auto-mode): New local minor mode. (preview-point-auto-delay,preview-point-auto-function): New custom variable. (preview-point-auto): New functions. Automatic previewing code derived from preview-auto.el (Copyright 2024 FSF, by Paul D. Nelson), adapted and integrated here. --- NEWS.org | 2 + doc/preview-latex.texi | 12 + preview.el
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, I had another thought about how preview-point could be structured. It currently combines two somewhat orthogonal features: (a) Previews away from point are no longer displayed at all. (b) We gain further flexibility in how we can display the preview at point -- before the TeX source, after the TeX source, or in a buframe. I think (b) makes sense and would be useful, independent of (a). Conceptually, we could view this as a more flexible form of preview-leave-open-previews-visible, which currently only allows the preview to be displayed before the TeX source. One way to decouple (a) and (b) would be to: - Control (a) via a new defcustom, preview-hide-away-from-point. - Control (b) by allowing preview-leave-open-previews-visible to take new values (e.g., 'after, 'buframe). That setting would then play the role currently played by preview-point. To display previews at point with buframe, one would do (setopt preview-leave-open-previews-visible 'buframe) To recover the current preview-point behavior, one would additionally do (setopt preview-hide-away-from-point t) WDYT? Does it reasonable to you to separate these features? Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, Al Haji-Ali writes: > What's the best practice here about updating patches? Should I send an > updated full patch or a new one on top of the current one? I'd prefer an updated full patch for each iteration. > This setting should be for both. Updating existing previews when the > text is changed and for generating new ones whenever > `preview-point-auto-p` returns non-nil on (point). For example, one can > set it to `texmathp` to automatically generate previews for math > expressions. I will see how I can update the documentation to better > reflect this. Can we please find another name for `preview-point-auto-p'? This is a custom variable, right? The '-?p' thing is more for predicate functions. I suggest we follow Emacs conventions here[1] and name it `preview-point-auto-function' or similar. Best, Arash Footnotes: [1] https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips-for-Defining.html ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, > What's the best practice here about updating patches? Should I send an > updated full patch or a new one on top of the current one? I think sending a full patch is the custom. >> It would be much more ergonomic if we could enable preview-point after >> visiting a buffer. Is this a hard limitation? > No, I can make this change. It would simply require modifying a couple > of hooks. Should the logic be in a custom-setter code, or in a > function/mode? Note that the setting has to be global (at least in the > current implementation -- though I might be able to make it buffer-local > if there's a real need for it). I guess we could go with either of the following: (A) A defcustom with custom setters that both determines whether the feature is enabled and how the feature is displayed. (B) A minor-mode (ideally buffer-local), say preview-point-mode [1], that determines whether the feature is enabled at all, together with a defcustom preview-point [2] that determines how the feature displays. Based on what you wrote elsewhere regarding the intent of the defcustom: > Just to say, the purpose of this command is to provide an easy way to > hide/show previews, for example if they are getting in the way of > editing text. I wasn't thinking about it as a way to enable > preview-point. I am open to suggestions of improvement to this > interface. I think (B) makes more sense. [1] or maybe preview-at-point-mode? [2] or maybe preview-point-display, preview-point-display-type, preview-point-type, preview-at-point-type, etc? > I had actually wanted to ask you if the introduction of > `preview-point-auto-p` could be a clean way to incorporate the logic of > `preview-auto`, since I think one can have the clever code in > preview-auto which detects if a preview should be generated as a > customization of this variable. > > My thinking is to have automatic previewing split into two logical > parts: The mechanism of updating previews which should be general > enough, and the detection of when to do it which will be > user-controlled. That sounds good to me. I'll take a careful look once you've sent the revised patch. Thanks, best, Paul ___ bug-auctex mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Paul,
On 30/10/2025, Paul D. Nelson wrote:
> I've started taking a look and have several comments.
Thank you for taking the time, really appreciate it as well as your
earlier work on preview-auto.
What's the best practice here about updating patches? Should I send an
updated full patch or a new one on top of the current one?
> I have several unrelated comments:
Thanks for those, I agree with all of them and will make those changes.
> It would be much more ergonomic if we could enable preview-point after
> visiting a buffer. Is this a hard limitation?
No, I can make this change. It would simply require modifying a couple
of hooks. Should the logic be in a custom-setter code, or in a
function/mode? Note that the setting has to be global (at least in the
current implementation -- though I might be able to make it buffer-local
if there's a real need for it).
> The documentation does not indicate any intended value. Also, from what
> I understand, this setting controls when new previews are generated, but
> does not affect whether existing previews are automatically regenerated;
> the docs don't seem to emphasize this distinction.
This setting should be for both. Updating existing previews when the
text is changed and for generating new ones whenever
`preview-point-auto-p` returns non-nil on (point). For example, one can
set it to `texmathp` to automatically generate previews for math
expressions. I will see how I can update the documentation to better
reflect this.
> The command ends in "-mode" but does not come from a major/minor mode.
> Perhaps instead something like "preview-point-toggle-display"?
>
> It might be cleaner to move the body of this command to a custom setter
> for preview-point and then either delete the command altogether, or
> rewrite it as a light wrapper around customize-set-variable. That way,
> users can tweak preview-point via either the new C-c C-p C-t bind or
> customize-set-variable.
I'll see how that would look. Just to say, the purpose of this command
is to provide an easy way to hide/show previews, for example if they are
getting in the way of editing text. I wasn't thinking about it as a way
to enable preview-point. I am open to suggestions of improvement
to this interface.
>> +(defun preview-point-toggle-auto-update (enable &optional silent)
>
> This reads like a minor mode. I would suggest introducing a small,
> display-agnostic "preview-automatic-mode", bound to C-c C-p C-a, that,
> when enabled, automatically regenerates existing previews, for both
> preview-point and "traditional" preview. This aligns with an earlier
> suggestion [1] to upstream automatic previewing. (It's simpler than
> preview-auto, which also *finds* new regions to preview, but that
> feature could be added later via a strategy variable or hook.) I'd be
> happy to draft that refactor on top of your patch if the idea sounds
> reasonable.
>
> [1] https://lists.gnu.org/archive/html/auctex-devel/2024-06/msg00031.html
I agree a minor mode is better here and a patch would be appreciated
(once I send the updated one with your suggested changes).
I had actually wanted to ask you if the introduction of
`preview-point-auto-p` could be a clean way to incorporate the logic of
`preview-auto`, since I think one can have the clever code in
preview-auto which detects if a preview should be generated as a
customization of this variable.
My thinking is to have automatic previewing split into two logical
parts: The mechanism of updating previews which should be general
enough, and the detection of when to do it which will be
user-controlled.
In any case, I think it would be good to have the infrastructure of
automatic previewing which is being added here as suitable for the
integration of preview-auto as possible (we might need to modify
`preview-point-auto-p` so that it can return a region).
>> +
>> +;;; preview-point -- Auto-preview
>
> If we refactor as suggested above, then most of the functions below
> should be given agnostic names ("preview-automatic-*"?), reflecting that
> they are not specific to the preview-point feature.
Agreed, though I haven't tested automatic previewing without
preview-point.
> --8<---cut here---start->8---
> Automatic previewing code derived from preview-auto.el (Copyright 2024
> FSF, by Paul D. Nelson), adapted and integrated by Al-Haji Ali.
> --8<---cut here---end--->8---
Will add this comment to the commit message.
Best regards,
-- Al
___
bug-auctex mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-auctex
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hi Al, I've started taking a look and have several comments. Thanks, best, Paul > +(defvar-local preview-silent-errors nil > + "When non-nil, do not signal preview errors nor display output buffer. > +This variable should be set in the process buffer.") (Very good.) > +;;; preview-point customizations and variables. > +(defcustom preview-point nil > + "Specifies where to show the preview. > +If non-nil, show the preview at point. Can be `before-string', > +`after-string' to show at before or after the TeX code or `buframe' to > +show in a separate frame (the `buframe' package must be installed). Can > +also be \\='(buframe FN-POS FRAME-PARAMETERS BUF-PARAMETERS) where > +FN-POS is a position function (default is > +`buframe-position-right-of-overlay') and FRAME-PARAMETERS is an alist of > +additional frame parameters, default is nil and BUF-PARAMETERS is an > +alist of buffer local variables and their values. > + > +This variable must be set before opening a TeX file. Charging its value > +while a file is open will lead to previews not being displayed > +correctly. See `preview-point-toggle-mode'." > + :type '(choice > + (const :tag "Before string" before-string) > + (const :tag "After string (default)" after-string) > + (const :tag "On frame" buframe) > + (list :tag "On frame with explicit parameters" > +(function :tag "Position function") > +(alist :tag "Frame parameters") > +(alist :tag "Buffer parameters" I have several unrelated comments: Documentation: preview-point seems to work fine in non-file buffers, so perhaps replace "TeX file" with "TeX buffer". Typo: "Charging its value" -> "Changing its value" The default is nil, but ':type' doesn't accept nil. Consider adding (const :tag "Disabled" nil). It would be much more ergonomic if we could enable preview-point after visiting a buffer. Is this a hard limitation? > +(defcustom preview-point-auto-p nil > + "Set this to enable previewing automatically. > +When non-nil, it is assumed to be a function that is is called with no > +arguments at (point) when there is not a preview already. If the > +function return a non-nil value, a `preview-at-point' will be initiated." > + :type 'symbol) The documentation does not indicate any intended value. Also, from what I understand, this setting controls when new previews are generated, but does not affect whether existing previews are automatically regenerated; the docs don't seem to emphasize this distinction. > +(defun preview-point-toggle-mode (mode) > + "Set `preview-point' to MODE. > +If called interactively `preview-point' is toggled and the user is asked > +for the MODE when it is switch on. > + > +This function has an effect only if `preview-point' is non-nil, which > +should be set before opening a TeX file." > + (interactive > + (list (if preview-point > + (if (not (eq preview-point 'hidden)) > + 'hidden > + (intern > +(cadr (read-multiple-choice > + "Mode :" > + '((?b "before-string") > + (?a "after-string") > + (?f "buframe")) > + (error "Preview-point is not enabled. \ > +Set preview-point before opening the TeX file" > + > + (unless preview-point > +(error "Preview-point needs to be enabled first (before opening the tex > file).")) > + ;; Hide current overlay if it is visible. > + (when preview-point--current-overlay > +(preview-toggle preview-point--current-overlay nil)) > + (setq preview-point mode) > + ;; Show the preview if it at point. > + (preview-point-move-point)) The command ends in "-mode" but does not come from a major/minor mode. Perhaps instead something like "preview-point-toggle-display"? It might be cleaner to move the body of this command to a custom setter for preview-point and then either delete the command altogether, or rewrite it as a light wrapper around customize-set-variable. That way, users can tweak preview-point via either the new C-c C-p C-t bind or customize-set-variable. > +(defun preview-point-toggle-auto-update (enable &optional silent) > + "Enable auto refresh of previews. > +When ENABLE is nil, disable auto-update instead. If called > +interactively, auto-updating is toggled." > + (interactive (list 'toggle)) > + (when (eq enable 'toggle) > +(setq enable (not (memq > + #'preview-point-buf-change > + after-change-functions > + (if enable > + (progn > +(add-hook 'after-change-functions #'preview-point-buf-change nil t) > +(add-hook 'post-command-hook #'preview-point-auto nil t) > +(preview-point-buf-change) > +(unless silent > + (message "Auto-updating previews enabled"))) > +(remove-hook 'after-change-functions #'preview-point-buf-change t) > +(remove-hook 'p
bug#79708: 14.1.0; [PATCH] New feature: preview-point
Hello,
This is the last follow-up bug-report/patch from:
https://lists.gnu.org/archive/html/auctex-devel/2025-08/msg00026.html
which includes the main preview-point feature. It can be enabled by setting
`preview-point` to `'after-string` for example.
To use `buframe`, the package needs to be installed as well (available on
ELPA).
Any comments/questions are welcome. I realized it's a a lot of code to review.
Best regards,
-- Al
>From 33807f005de8403499cd0dd5eb2ba2990847197c Mon Sep 17 00:00:00 2001
From: Al Haji-Ali
Date: Tue, 9 Sep 2025 21:19:43 +0100
Subject: [PATCH] New feature, preview-point
* doc/preview-latex.texi: Add docs for preview-point
* preview.el (preview-silent-errors): New local variable.
(preview-point,preview-point-auto-p): New custom variables
(preview-point-disabled-face, preview-point-processing-face): New faces.
(preview-point--frame, preview-point--current-overlay): New variables.
(preview-dvipng-image-type): Update doc.
(preview-log-error,preview-reraise-error): Implement silent mode based
on `preview-silent-errors'.
(preview-gs-sentinel, preview-gs-transact): Call `preview-point-refresh'.
(preview-ascent-from-bb): Return 'center when 'preview-point' is
non-nil.
(preview-toggle): Call preview-point activation function.
(preview-disable): Control behaviour based on preview-point.
(preview-map): Add key-binding for `preview-point-toggle-mode'.
(preview-mode-setup): Control setup based on `preview-point'.
(preview-parse-messages): Restore point before calling place functions.
(preview-point-auto-delay): New custom variable.
(preview-point--buframe, preview-point-inside-overlay-p,
preview-point-activate-maybe, preview-point-move-point,
preview-point-auto, preview-point-updated, preview-point-toggle-mode,
preview-point-toggle-auto-refresh, preview-point@around@write-region,
preview-point--preview-at-point, preview-point-has-preview-p,
preview-point-buf-change): New functions.
---
doc/preview-latex.texi | 20 ++
preview.el | 507 +++--
2 files changed, 463 insertions(+), 64 deletions(-)
diff --git a/doc/preview-latex.texi b/doc/preview-latex.texi
index e9e03fd5..299a161c 100644
--- a/doc/preview-latex.texi
+++ b/doc/preview-latex.texi
@@ -480,6 +480,26 @@ math (@code{$@dots{}$}), or if your usage of @code{$} conflicts with
@previewlatex{}'s, you can turn off inline math previews. In the
@samp{Preview Latex} group, remove @code{textmath} from
@code{preview-default-option-list} by customizing this variable.
+
+@item Enable preview at point.
+
+To enable a mode where previews are shown only when the cursor is inside
+the preview area, set @code{preview-point}. Valid values are:
+
+@table @code
+@item after-string
+Show the preview after the TeX source.
+
+@item before-string
+Show the preview before the TeX source.
+
+@item buframe
+Show the preview in a separate frame next to the cursor. Requires the
+@code{buframe} package to be installed (available on ELPA).
+@end table
+
+See also @code{preview-point-auto-p} to enable automatic updating or
+generation of previews.
@end itemize
@node Known problems, For advanced users, Simple customization, top
diff --git a/preview.el b/preview.el
index e9339307..205d6d93 100644
--- a/preview.el
+++ b/preview.el
@@ -370,6 +370,10 @@ See also `preview-gs-command'."
"List of overlays to convert using gs.
Buffer-local to the appropriate TeX process buffer.")
+(defvar-local preview-silent-errors nil
+ "When non-nil, do not signal preview errors nor display output buffer.
+This variable should be set in the process buffer.")
+
(defvar-local preview-gs-outstanding nil
"Overlays currently processed.")
@@ -454,6 +458,53 @@ set to `postscript'."
:group 'preview-latex
:type 'boolean)
+;;; preview-point customizations and variables.
+(defcustom preview-point nil
+ "Specifies where to show the preview.
+If non-nil, show the preview at point. Can be `before-string',
+`after-string' to show at before or after the TeX code or `buframe' to
+show in a separate frame (the `buframe' package must be installed). Can
+also be \\='(buframe FN-POS FRAME-PARAMETERS BUF-PARAMETERS) where
+FN-POS is a position function (default is
+`buframe-position-right-of-overlay') and FRAME-PARAMETERS is an alist of
+additional frame parameters, default is nil and BUF-PARAMETERS is an
+alist of buffer local variables and their values.
+
+This variable must be set before opening a TeX file. Charging its value
+while a file is open will lead to previews not being displayed
+correctly. See `preview-point-toggle-mode'."
+ :type '(choice
+ (const :tag "Before string" before-string)
+ (const :tag "After string (default)" after-string)
+ (const :tag "On frame" buframe)
+ (list :tag "On frame with explicit parameters"
+(function :tag "Position function")
+(alist :tag "Frame parameters")
+(alist :tag "Buffer parameters"
+
+(defcus
