Hi Ihor, Picking up the review thread here. First, you can follow the progress at https://github.com/karthink/org-mode on the "olp" branch:
git clone -b olp https://github.com/karthink/org-mode.git or in your existing Org repo: git remote add olp-upstream https://github.com/karthink/org-mode.git ------------------------------------------------------ I have stopped rebasing and am adding commits on top, so it should be easy to see changes based on your feedback. Right now the part near the top of the branch looks like this: The top block contains changes in response to your feedback. I'll be adding more commits on top: 041c98494 org-latex-preview: Update process-alist with runtime dvisvgm flags e07895b7a org-latex-preview: Remove support for matchers 2a77a84fe org-compat: Add autoload for org-latex-preview-preamble 0fe2e99fb ox-odt: Fix inline image path handling ef3d6a3d1 ob-latex: Update png file generation for org-latex-preview 69d5ecc47 org-macs: Improve org-async-call documentation The next block is commits where I revert Timothy's WIP conditional features work. Eventually I'll remove these along with the older conditional features commits. a67efe15d ---END REVERT CONDITIONAL FEATURES DIVIDER--- 075bfd031 Revert "ox: Introduce conditional/generated preamble" a7b6ef20e Revert "oc-*: Make use of conditional preamble for export" a87c0118d Revert "test-ox: Add tests for export feature resolution" c7bb7a191 Revert "org-manual: Document export features" d597c2d3a ---REVERT CONDITIONAL FEATURES DIVIDER--- Next is a block containing some of Timothy's miscellaneous changes to ox-latex. Hopefully you can ignore these for now. 1ef59f0aa ox-latex: EF v0.4 dynamism WIP cdca2be1e ---END PERSONAL NOPUSH DIVIDER--- 5effad859 NOPUSH org: Don't fill displayed equations in text 19204730a NOPUSH org-src: Prettify inline results 500e1c956 NOPUSH org-compat: Add obsolete variable aliases for LaTeX preview b9168aa2e ---NOPUSH PERSONAL DIVIDER--- 99417a642 ox-latex: Fix interning of engraved theme keyword 7bedb201b ox-latex: Introduce \codefont command 983146722 ox-latex: Use more robust engraved theme grouping d13bd8a3c ox-latex: Better handle multiple engraved themes 677eebbd3 ox-latex: Fix engraved-theme propagation f1f6d2475 org: Introduce semantic seperator fontification 9b48659aa ox-html: Fix C++ label CSS 21dc16b00 org-element: Fix table parsing edge-case After that is the 200+ commits that make up the org-latex-preview patchset: a2dd88a6a ---PATCH SET DIVIDER--- ... ... ... fc802c4b7 ---PATCH SET DIVIDER--- Hope that's clear. ------------------------------------------------------ >> Org mode provides two levels of automatic LaTeX preview generation >> with increasing degrees of immediate feedback: > > This sounds abrupt. The paragraph starts right after describing the > basic preview functionality, but it is not immediately obvious that > "automatic LaTeX preview" is referring to an entirely new feature. > Maybe we can add a bit of the context like: "Normally, latex fragments > previews visually replace the underlying latex text. Editing the latex > fragments thus requires disabling the preview first. To make editing > easier, Org also provides optional /automatic/ previews ..." I have reworded this paragraph. >> - Live previews: Continuously preview LaTeX fragments as you type, >> giving you near immediate feedback (especially when using >> =pdflatex=). The preview image will continue to be displayed >> adjacent to the fragment even when editing it. > > It is worth explaining what happens when the fragment has errors or does > not compile. Nothing special happens, so I don't think there is anything to mention here. >> - (~org-latex-preview-reveal-mode~) :: > ^^^^^^ Fixed. >> #+findex: org-latex-preview-mode > >> #+vindex: org-latex-preview-mode-ignored-environments >> You can specify a list of LaTeX environments that should >> not be automatically previewed by ~org-latex-preview-mode~ when >> they are inserted into the buffer. This is controlled by >> ~org-latex-preview-mode-ignored-environments~. > > It is worth mentioning that the default value ignores figure > environments. (BTW, what will happen if somebody removes figure from > that list?) Added note about figure environments. (If you remove figure from that list, dvisvgm will fail to generate a preview for those fragments. dvipng will work but the sizing may be inconsistent.) >> #+vindex: org-latex-preview-debounce >> By default, there is a delay (debounce) of 1 second between editing a >> fragment and generating a live preview. This can be changed by >> setting ~org-latex-preview-debounce~. Note that values of 0.1 or >> lower can cause high CPU utilization. > > `org-latex-preview-mode-update-delay'? Typo, fixed. > Now, I think that we are more or less done with the manual and I will go > ahead with reviewing the code. > > Some initial comments. > >> (defvar org-latex-preview--dvisvgm3-minor-version >> (or (and (executable-find "dvisvgm") >> (with-temp-buffer >> (call-process "dvisvgm" nil t nil "--version") >> (let ((ver (version-to-list >> (string-trim (buffer-string) "dvisvgm ")))) >> (and (= (car ver) 3) (cadr ver))))) >> -1) >> "The minor version of dvisvgm, if dvisvgm 3 is installed. Otherwise -1.") > > I am not sure if I like calling dvisvgm as a side effect of loading the > library. I recommend a different route instead: write a helper > function org-latex-preview--dvisvgm3-minor-version that will either > return the variable value or, if the variable is nil, compute the value > only when it is really needed. Discussed in Org meetup (2026-01-14), concluded it was okay to do this. Precedent set by org-x11idle-exists-p. >> (defcustom org-latex-preview-appearance-options >> '(:foreground auto :background "Transparent" >> :scale 1.0 :zoom 1.0 :page-width 0.6 >> :matchers ("begin" "$1" "$" "$$" "\\(" "\\[")) > > I am wondering if we should take this opportunity to remove :matchers > from this customization into some dedicated option. > >> :matchers A list indicating which matchers should be used to >> find LaTeX fragments. Valid members of this list are: >> \"begin\" find environments >> \"$1\" find single characters surrounded by $.$ >> \"$\" find math expressions surrounded by $...$ >> \"$$\" find math expressions surrounded by $$....$$ >> \"\\(\" find math expressions surrounded by \\(...\\) >> \"\\=\\[\" find math expressions surrounded by \\=\\[...\\]" > > ... because the docstring is not accurate anymore and creates an > impression that :matchers is used for the purposes of preview, not for > underlying latex text fontification. - Removed :matchers from the appearance options - Added new option org-highlight-latex-matchers >> :type 'plist > > Since we are obsoleting :html-* elements of this plist, it will be a > good idea to provide a proper specifier with a closed list of allowed > keywords here, so that people get more hints when they are using > obsolete value. Perhaps in the future? Seems like a low priority item to me. >> (dvisvgm >> :programs ("latex" "dvisvgm") >> :description "dvi > svg" >> :message "you need to install the programs: latex and dvisvgm." >> :image-input-type "dvi" >> :image-output-type "svg" >> :latex-compiler ("%l -interaction nonstopmode -output-directory %o %f") >> :latex-precompiler ("%l -output-directory %o -ini -jobname=%b \"&%L\" >> mylatexformat.ltx %f") >> ;; The --optimise, --clipjoin, and --relative flags cause dvisvgm to >> ;; do some extra work to tidy up the SVG output, but barely add to >> ;; the overall dvisvgm runtime (<1% increace, from testing). >> :image-converter determined-at-runtime) > > The comment seems misplaced. > Also, determined-at-runtime is not documented. I remember now why we did it this way, with (cl-eval-when (load eval) ...) instead of `(dvisvgm :programs ... :image-converter ,(list (concat "dvisvgm --page=1- --optimize --clipjoin --relative --no-fonts" (if (>= org-latex-preview--dvisvgm3-minor-version 2) " -v3 --message='processing page {?pageno}: output written to {?svgpath}'" "") " --bbox=preview -o %B-%%9p.svg %f"))) I think we did not want dvisvgm to run when the file is compiled. But org-latex-preview--dvisvgm3-minor-version is defined in a defvar and it runs at compile time anyway, so it doesn't help. I've switched to the simpler backquote method for now, as discussed in the Org meetup (2026-01-14). If you have a better idea please let me know. >> (cl-defun org-async-call (proc &key success failure filter buffer info >> timeout now process-variables >> (dir default-directory) (coding 'utf-8)) > > I believe that this new functionality should be mentioned in ORG-NEWS. > For the function itself, it would also be nice to have some examples of > usage, so that people not familiar with preview systems were able to > make use of this queuing functionality. - Mentioned org-async-call in ORG-NEWS, feel free to move it around when required. - Added three examples to the org-async-call docstring, but the function is complex enough that more can be added in the future. Additional changes in the newest block of commits: ------------------------------------------------------------------------ Made changes to png path in org-babel-execute:latex to use org-latex-preview-create-images, the new API to get images for LaTeX fragments. Unfortunately, the png path still isn't working because of org-babel-latex-process-alist, which has this value: `((png :programs ("latex" "dvipng") :description "dvi > png" :message "you need to install the programs: latex and dvipng." :image-input-type "dvi" :image-output-type "png" :image-size-adjust (1.0 . 1.0) :latex-compiler ,(if (executable-find "latexmk") '("latexmk -f -pdf -latex -interaction=nonstopmode -output-directory=%o %f") '("latex -interaction nonstopmode -output-directory %o %f" "latex -interaction nonstopmode -output-directory %o %f" "latex -interaction nonstopmode -output-directory %o %f")) :image-converter ("dvipng -D %D -T tight -o %O %f") :transparent-image-converter ("dvipng -D %D -T tight -bg Transparent -o %O %f"))) There are three problems with this variable: - The name of the car needs to be changed to dvipng for consistency with org-latex-preview-process-alist. Can I go ahead and do that? - The latexmk command is wrong for use with org-latex-preview, it needs to generate a dvi, not a pdf. - The bigger problem is that the org-latex-preview API does not support running LaTeX multiple times, so if latexmk is not available this will fail. This is unfortunately not easy to fix. The png path works if I ignore org-babel-latex-process-alist and reuse org-latex-preview-process-alist. ------------------------------------------------------------------------ I'm working on org-latex-preview actively this week, so even incremental feedback will be helpful as I can get started on it. Karthik
