org-latex-preview: Support symbol entrypoint args

* lisp/org-latex-preview.el (org-latex-preview): Refactor to support a
symbol-value "mode" argument as well as prefix arguments.  This stops
forcing programmatic invocations from having to use uninformative
values, and actually makes the implementation slightly nicer to read I
think.

* lisp/org.el: Change the argument in the preview startup invocation to 'buffer.

lisp/org-latex-preview.el

@@ -858,60 +858,78 @@ BEG and END are buffer positions."
    beg end))
 
 ;;;###autoload
-(defun org-latex-preview (&optional arg)
+(defun org-latex-preview (&optional mode)
-  "Toggle preview of the LaTeX fragment at point.
+  "Generate or hide LaTeX fragment previews.
 
-If the cursor is on a LaTeX fragment, create the image and
+The particular behaviour depends on MODE (which recognises a
-overlay it over the source code, if there is none.  Remove it
+number of symbols and prefix arguments), or when MODE is nil the
-otherwise.  If there is no fragment at point, display images for
+context of the current buffer when called.
-all fragments in the current section.  With an active region,
-display images for all fragments in the region.
 
-With a `\\[universal-argument]' prefix argument ARG, clear images \
+- point: Toggle preview of the LaTeX fragment at point
-for all fragments
+- region: Display previews of all fragments in the selected region
-in the current section.
+- section: Display previews of all fragments in the current section
+- buffer: Display previews of all fragments in the buffer
+- clear-region: Clear all previews in the current region
+- clear-section: Clear all previews in the current section
+- clear-buffer: Clear all previews in the buffer
 
-With a `\\[universal-argument] \\[universal-argument]' prefix \
+When MODE is nil and the cursor is on a LaTeX fragment, toggle
-argument ARG, display image for all
+previewing of the LaTeX fragment at point.  If the there is no
-fragments in the buffer.
+preview, generate a preview and overlay it on the text.  Remove
+the preview image otherwise.  If there is no fragment at point,
+display previews for all fragments in the current section, or
+active region should it exist.
 
-With a `\\[universal-argument] \\[universal-argument] \
+Prefix arguments are handled as follows:
-\\[universal-argument]' prefix argument ARG, clear image for all
+- `\\[universal-argument]' is equivalent to setting MODE to clear-region (if a region
-fragments in the buffer."
+   is currently active) or clear-section
+- `\\[universal-argument] \\[universal-argument]' is equivalent to setting MODE to buffer
+- `\\[universal-argument] \\[universal-argument] \\[universal-argument]' is equivalent to setting MODE to clear-buffer
+
+MODE can also be a org-element LaTeX environment or fragment, which
+will be treated as \"point\"."
   (interactive "P")
-  (cond
+  (when (display-graphic-p)
-   ((not (display-graphic-p)) nil)
+    (when (integerp (car-safe mode)) ; Prefix argument
-   ;; Clear whole buffer.
+      (setq mode
-   ((equal arg '(64))
+            (pcase (car mode)
-    (org-latex-preview-clear-overlays (point-min) (point-max))
+              (64 'clear-buffer)
-    (message "LaTeX previews removed from buffer"))
+              (16 'buffer)
-   ;; Preview whole buffer.
+              (4 (if (use-region-p) 'clear-region 'clear-section))
-   ((equal arg '(16))
+              (_ (and (use-region-p) 'region)))))
-    (org-latex-preview--preview-region (point-min) (point-max)))
+    (unless mode ; Auto, i.e. element at point or section
-   ;; Clear current section.
+      (setq mode (if-let ((datum (org-element-context))
-   ((equal arg '(4))
+                          ((memq (org-element-type datum) '(latex-environment latex-fragment))))
-    (org-latex-preview-clear-overlays
+                     datum 'section)))
-     (if (use-region-p)
+    (pcase mode
-         (region-beginning)
+      ('buffer
-       (if (org-before-first-heading-p) (point-min)
+       (org-latex-preview--preview-region (point-min) (point-max)))
-         (save-excursion
+      ('clear-buffer
-           (org-with-limited-levels (org-back-to-heading t) (point)))))
+       (org-latex-preview-clear-overlays (point-min) (point-max))
-     (if (use-region-p)
+       (message "LaTeX previews removed from buffer"))
-         (region-end)
+      ('section
-       (org-with-limited-levels (org-entry-end-position)))))
+       (let ((beg (if (org-before-first-heading-p) (point-min)
-   ((use-region-p)
+                    (save-excursion
-    (org-latex-preview--preview-region (region-beginning) (region-end)))
+                      (org-with-limited-levels (org-back-to-heading t) (point)))))
-   ;; Toggle preview on LaTeX code at point.
+             (end (org-with-limited-levels (org-entry-end-position))))
-   ((let ((datum (org-element-context)))
+         (org-latex-preview--preview-region beg end)))
-      (and (memq (org-element-type datum) '(latex-environment latex-fragment))
+      ('clear-section
-           (org-latex-preview--auto-aware-toggle datum))))
+       (org-latex-preview-clear-overlays
-   ;; Preview current section.
+        (if (org-before-first-heading-p) (point-min)
-   (t
+          (save-excursion
-    (let ((beg (if (org-before-first-heading-p) (point-min)
+            (org-with-limited-levels (org-back-to-heading t) (point))))
-                 (save-excursion
+        (org-with-limited-levels (org-entry-end-position))))
-                   (org-with-limited-levels (org-back-to-heading t) (point)))))
+      ('region
-          (end (org-with-limited-levels (org-entry-end-position))))
+       (org-latex-preview--preview-region (region-beginning) (region-end)))
-      (org-latex-preview--preview-region beg end)))))
+      ('clear-region
+       (org-latex-preview-clear-overlays (region-beginning) (region-end)))
+      ('point
+       (when-let ((datum (org-element-context))
+                  ((memq (org-element-type datum) '(latex-environment latex-fragment))))
+         (org-latex-preview--auto-aware-toggle datum)))
+      ((guard (memq (org-element-type mode) '(latex-environment latex-fragment)))
+       (org-latex-preview--auto-aware-toggle mode))
+      (bad-value (error "Invalid `org-latex-preview' mode argument: %S" bad-value)))))
 
 (defun org-latex-preview--auto-aware-toggle (datum)
   "Toggle the preview of the LaTeX fragment/environment DATUM.

lisp/org.el

@@ -4802,7 +4802,7 @@ The following commands are available:
     (org-unmodified
      (when org-startup-with-beamer-mode (org-beamer-mode))
      (when org-startup-with-inline-images (org-display-inline-images))
-     (when org-startup-with-latex-preview (org-latex-preview '(16)))
+     (when org-startup-with-latex-preview (org-latex-preview 'buffer))
      (unless org-inhibit-startup-visibility-stuff (org-cycle-set-startup-visibility))
      (when org-startup-truncated (setq truncate-lines t))
      (when org-startup-numerated (require 'org-num) (org-num-mode 1))