org-latex-preview: Redesign preview creation API

* lisp/org-latex-preview.el (org-latex-preview--check-all-fragments-produced,
org-latex-preview--create, org-latex-preview-fragments,
org-latex-preview-auto--regenerate-overlay,
org-latex-preview-auto--detect-fragments-in-change): Split the
org-element processing and the preview creation components of
`org-latex-preview--create` into two new functions, `
org-latex-preview--place-from-elements' and `org-latex-preview-place'.
The latter of these can serve as a convenient public API for creating
fragments.
(org-latex-preview-place, org-latex-preview-create-image-async): To make
`org-latex-preview-place' this easier to use, we also allow the LaTeX
preamble to be provided as an optional argument, and adjust
`org-latex-preview-create-image-async' to add this as the :latex-header
to the processing-info plist.

lisp/org-latex-preview.el

@@ -654,7 +654,7 @@ This is intended to be placed in `post-command-hook'."
                 (append fragments
                         (org-latex-preview--get-numbered-environments
                          end nil))))
-        (org-latex-preview--create
+        (org-latex-preview--place-from-elements
          org-latex-preview-default-process
          fragments)))))
 
@@ -736,7 +736,7 @@ image.  The preview image is regenerated if necessary."
                         (eq (org-element-type fragment) 'latex-environment)
                         (org-latex-preview--get-numbered-environments
                          (overlay-end ov) nil))))
-      (org-latex-preview--create
+      (org-latex-preview--place-from-elements
        org-latex-preview-default-process
        (append (list fragment) others)))))
 
@@ -999,7 +999,7 @@ protection against placing doubled up overlays."
               'org-latex-overlay)
     (let ((ws (window-start)))
       (if (assq processing-type org-latex-preview-process-alist)
-          (org-latex-preview--create
+          (org-latex-preview--place-from-elements
            processing-type
            (nconc (org-latex-preview-collect-fragments (max ws beg) end)
                   (when (< beg ws)
@@ -1027,29 +1027,52 @@ Some of the options can be changed using the variable
       (org-latex-preview-fragments processing-type beg end)
     (org-latex-preview-replace-fragments prefix processing-type dir msg)))
 
-(defun org-latex-preview--create (processing-type elements)
+(defun org-latex-preview--place-from-elements (processing-type elements)
   "Preview LaTeX math fragments ELEMENTS using PROCESSING-TYPE."
-  (let* ((processing-info
+  (let* ((numbering-table (and org-latex-preview-numbered
-          (cdr (assq processing-type org-latex-preview-process-alist)))
-         (imagetype (or (plist-get processing-info :image-output-type) "png"))
-         (numbering-table (and org-latex-preview-numbered
                                (cl-find 'latex-environment elements
                                         :key #'org-element-type :test #'eq)
                                (org-latex-preview--environment-numbering-table)))
+         (numbering-offsets
+          (and numbering-table
+               (mapcar
+                (lambda (element)
+                  (and numbering-table
+                       (eq (org-element-type element) 'latex-environment)
+                       (gethash element numbering-table)))
+                elements)))
+         (entries
+          (mapcar
+           (lambda (element)
+             (list (org-element-property :begin element)
+                   (- (org-element-property :end element)
+                      (or (org-element-property :post-blank element) 0)
+                      (if (eq (char-before (org-element-property :end element))
+                              ?\n)
+                          1 0))
+                   (org-element-property :value element)))
+           elements)))
+    (org-latex-preview-place processing-type entries numbering-offsets)))
+
+(defun org-latex-preview-place (processing-type entries &optional numbering-offsets latex-preamble)
+  "Preview LaTeX math fragments ENTRIES using PROCESSING-TYPE.
+Each entry of ENTRIES should be a list of 2-3 items, either
+  (BEG END), or
+  (BEG END VALUE)
+Where BEG and END are the positions in the buffer, and the LaTeX previewed
+is either the substring between BEG and END or (when provided) VALUE."
+  (let* ((processing-info
+          (cdr (assq processing-type org-latex-preview-process-alist)))
+         (imagetype (or (plist-get processing-info :image-output-type) "png"))
+         (numbering-offsets (cons nil numbering-offsets))
          fragment-info prev-fg prev-bg)
     (save-excursion
-      (dolist (element elements)
+      (dolist (entry entries)
-        (pcase-let* ((beg (org-element-property :begin element))
+        (pcase-let* ((`(,beg ,end ,provided-value) entry)
-                     (end (- (org-element-property :end element)
+                     (value (or provided-value
-                             (or (org-element-property :post-blank element) 0)
+                                (buffer-substring-no-properties beg end)))
-                             (if (eq (char-before (org-element-property :end element))
-                                     ?\n)
-                                 1 0)))
-                     (value (org-element-property :value element))
                      (`(,fg ,bg) (org-latex-preview--colors-at beg))
-                     (number (and numbering-table
+                     (number (car (setq numbering-offsets (cdr numbering-offsets))))
-                                  (eq (org-element-type element) 'latex-environment)
-                                  (gethash element numbering-table)))
                      (hash (org-latex-preview--hash
                             processing-type value imagetype fg bg number))
                      (options (org-combine-plists
@@ -1071,9 +1094,10 @@ Some of the options can be changed using the variable
                   fragment-info))
           (setq prev-fg fg prev-bg bg))))
     (if fragment-info
-        (org-latex-preview-create-image-async
+        (org-latex-preview--create-image-async
          processing-type
-         (nreverse fragment-info))
+         (nreverse fragment-info)
+         latex-preamble)
       (message "Creating LaTeX previews... done."))))
 
 (defun org-latex-preview--colors-at (pos)
@@ -1206,7 +1230,7 @@ NUMBER is the equation number that should be used, if applicable."
                       (goto-char (org-element-property :begin datum))
                       (org-element-context)))))))))
 
-(defun org-latex-preview-create-image-async (processing-type fragments-info &optional latex-processor)
+(defun org-latex-preview--create-image-async (processing-type fragments-info &optional latex-processor latex-preamble)
   "Preview PREVIEW-STRINGS asynchronously with method PROCESSING-TYPE.
 
 FRAGMENTS-INFO is a list of plists, each of which provides
@@ -1221,7 +1245,9 @@ where
 It is worth noting the FRAGMENTS-INFO plists will be modified
 during processing to hold more information on the fragments.
 
-LATEX-PROCESSOR is a member of `org-latex-compilers' which is guessed if unset."
+LATEX-PROCESSOR is a member of `org-latex-compilers' which is guessed if unset.
+
+When provided, LATEX-PREAMBLE overrides the default LaTeX preamble."
   (let* ((processing-type
           (or processing-type org-latex-preview-default-process))
          (latex-processor
@@ -1232,7 +1258,8 @@ LATEX-PROCESSOR is a member of `org-latex-compilers' which is guessed if unset."
                                 '("LATEX_COMPILER") '("LATEX_COMPILER")))))
               org-latex-compiler))
          (processing-info
-          (nconc (list :latex-processor latex-processor)
+          (nconc (list :latex-processor latex-processor
+                       :latex-header latex-preamble)
                  (alist-get processing-type org-latex-preview-process-alist)))
          (programs (plist-get processing-info :programs))
          (error-message (or (plist-get processing-info :message) "")))
@@ -1584,7 +1611,7 @@ fragments are regenerated."
             (org-latex-preview--display-info
              extended-info bad-fragment))))
         ;; Re-generate the remaining fragments.
-        (org-latex-preview-create-image-async
+        (org-latex-preview--create-image-async
          (plist-get extended-info :processor)
          (cdr fragments))
         (setq fragments nil)))))
@@ -2230,7 +2257,7 @@ a HTML file."
          (post-clean (or (plist-get processing-info :post-clean)
                          '(".dvi" ".xdv" ".pdf" ".tex" ".aux" ".log"
                            ".svg" ".png" ".jpg" ".jpeg" ".out")))
-         (latex-header
+         (latex-preamble
           (or (plist-get processing-info :latex-header)
               (org-latex-make-preamble
                (org-export-get-environment (org-export-get-backend 'latex))
@@ -2270,7 +2297,7 @@ a HTML file."
         (aset string (1- (length string)) ?%)
       (setq string (concat string "%")))
     (with-temp-file texfile
-      (insert latex-header)
+      (insert latex-preamble)
       (insert "\n\\begin{document}\n"
               "\\definecolor{fg}{rgb}{" fg "}%\n"
               (if bg