From a931da50cfc7bcbbeb328b5c08d8101085ae4021 Mon Sep 17 00:00:00 2001
From: TEC <git@tecosaur.net>
Date: Sat, 7 Jan 2023 21:38:47 +0800
Subject: [PATCH] org-latex-preview: Document async image logic

* lisp/org-latex-preview.el (org-latex-preview-create-image-async):
Explain the async call structure/logic with a large code comment.
---
 lisp/org-latex-preview.el | 54 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/lisp/org-latex-preview.el b/lisp/org-latex-preview.el
index f892a30af..b552f552e 100644
--- a/lisp/org-latex-preview.el
+++ b/lisp/org-latex-preview.el
@@ -1116,6 +1116,60 @@ during processing to hold more information on the fragments."
     (dolist (fragment fragments-info)
       (overlay-put (plist-get fragment :overlay)
                    'face 'org-latex-preview-processing-face))
+    ;; At this point we will basically construct a tree of async calls:
+    ;;
+    ;; dvisvgm case:
+    ;; └─ Compile tex file ⟶ stdout to `org-latex-preview--latex-preview-filter'
+    ;;    └─ (success or failure)
+    ;;       └─Extact images ⟶ stdout to `org-latex-preview--dvisvgm-filter'
+    ;;         ├─ (success)
+    ;;         │  ├─ Call `org-latex-preview--check-all-fragments-produced',
+    ;;         │  │  which can rerun the async tree if needed.
+    ;;         │  ├─ Delete tempfiles (`org-latex-preview--cleanup-callback').
+    ;;         │  └─ Message "creating latex previews... done.".
+    ;;         └─ (failure)
+    ;;            ├─ Run `org-latex-preview--failure-callback' (remove overlays).
+    ;;            └─ Message "creating latex previews... failed. please see %s for details".
+    ;;
+    ;; dvipng case:
+    ;; ├─ Compile tex file ⟶ stdout to `org-latex-preview--latex-preview-filter'
+    ;; └─ Extract images ("--follow" tex ouput) ⟶ stdout to `org-latex-preview--dvipng-filter'
+    ;;    ├─ (success)
+    ;;    │  ├─ Call `org-latex-preview--check-all-fragments-produced',
+    ;;    │  │  which can rerun the async tree if needed.
+    ;;    │  ├─ Delete tempfiles (`org-latex-preview--cleanup-callback')
+    ;;    │  └─ message "creating latex previews... done."
+    ;;    └─ (failure)
+    ;;       ├─ Run `org-latex-preview--failure-callback' (remove overlays).
+    ;;       └─ Message "creating latex previews... failed. please see %s for details".
+    ;;
+    ;; generic case:
+    ;; └─ Compile tex file ⟶ stdout to `org-latex-preview--latex-preview-filter'
+    ;;    └─ (success or failure)
+    ;;       └─Extact images
+    ;;         ├─ (success)
+    ;;         │  └─ Call `org-latex-preview--generic-callback'.
+    ;;         └─ (failure)
+    ;;            ├─ Run `org-latex-preview--failure-callback' (remove overlays).
+    ;;            └─ Message "creating latex previews... failed. please see %s for details".
+    ;;
+    ;; With continuous, synchronous processing:
+    ;;
+    ;; ⟶ stdout to `org-latex-preview--latex-preview-filter'
+    ;;   ├─ read preview fontsize
+    ;;   └─ capture compilation errors
+    ;;
+    ;; ⟶ stdout to `org-latex-preview--dvisvgm-filter'
+    ;;   ├─ read preview image metadata
+    ;;   ├─ edit svgs and adjust colors
+    ;;   ├─ cache svgs with org-persist or in /tmp
+    ;;   └─ update overlays in buffer with svg images and metadata
+    ;;
+    ;; ⟶ stdout to `org-latex-preview--dvipng-filter'
+    ;;   ├─ read preview image metadata
+    ;;   ├─ cache pngs with org-persist or in /tmp
+    ;;   └─ update overlays in buffer with png images and metadata
+    ;;
     (let* ((extended-info
             (append processing-info
                     (list :processor processing-type