Karthik Chikmagalur <karthikchikmaga...@gmail.com> writes: > I've updated the manual sections for org-latex-preview on Teco's branch > -- dev branch at https://code.tecosaur.net/tec/org-mode.git, in commit > 2a18b4014cd1fec5730e7fdf7591b0ad2ceb5691. You can check out the branch > and build it to read the updated manual. > > As discussed, this is probably the best starting point for understanding > what options are available.
Thanks! See my comments below. > -#+vindex: org-format-latex-header > +#+vindex: org-latex-preview-header I think that it is a good idea for the time being to leave old index entries, so that people can still search the manual using the obsolete variable names. Also, what is `org-latex-preview-header'? I see the following in ob-latex.el (defvar org-latex-preview-header) ; From org-latex-preview.el But that variable is not defined there. This variable is also described in ORG-NEWS, but should it be `org-latex-preview-preamble' instead? Something is off. > + **** Customizing the preview LaTeX preamble I think that this section should move to later. In "Customizing the LaTeX preview process" you are describing the overall process and introduce preamble, /after/ talking about preamble. I think that the overall preview flow might be described in a dedicated subsection, before talking about preamble/appearance/etc. Also, you are introducing a number of new concepts and minor modes. It is a good idea to provide new #+cindex entries for these new concepts for easier lookup. > Org mode caches LaTeX fragment preview images so that repeated calls > to ~org-latex-preview~ for the same fragment can reuse them. The > cache can also be manually cleared if required. > > - (~org-latex-preview-clear-cache~) :: > #+findex: org-latex-preview-clear-cache > > Clear the LaTeX preview cache. > > Interactively, act on > - the region if it is active, > - the fragment at point if in a fragment, > - the whole buffer otherwise. > > With a prefix argument, clear the entire LaTeX preview cache and > delete all cached LaTeX preview images. I am wondering if this command belongs to the manual. Is it so frequently needed to clear the cache that we need to let *all* users know about this command? I'd rather quickly introduce live previews in the opening section. IMHO, it is far more useful information for the users. > #+vindex: org-latex-preview-appearance-options > If the results are not to your liking, you can customize the > appearance of LaTeX previews by modifying > ~org-latex-preview-appearance-options~. In particular, its ~:scale~ > and ~:zoom~ properties can be used to adjust the size of the preview > images. If we talk about appearance, maybe it is a good idea to list what customizations are possible. > #+vindex: org-latex-preview-numbered > When generating previews, Org mode can track equation numbers and keep > them consistent by regenerating previews when necessary. This > behavior is controlled by the variable ~org-latex-preview-numbered~. variable -> user option. > 5. When previewing an unmodified LaTeX fragment for a second time, the > image is placed directly from the cache. If you do want to introduce cache clearing command, maybe do it briefly here, without detailing all the prefix arguments. BTW, I am not sure why org-latex-preview-clear-cache is so detailed. Is it really needed to clear just region cache but not the whole cache when there are issues? > #+vindex: org-latex-preview-preamble > You can customize ~org-latex-preview-preamble~ to specify the default > LaTeX preamble used for processing LaTeX fragments. This can refer to > packages in ~org-latex-default-packages-alist~ and > ~org-latex-packages-alist~. When previewing, this preamble will be > combined with keywords specified in the document via It is very confusing what you mean by "refer to" without knowing how `org-format-latex-header' works. Maybe show an example. Also, should you describe `latex-preview-compiler-command-map' in the manual? > org-latex-preview does not support the :matchers field in > org-latex-preview-appearance-options (previously > org-format-latex-options). That is, it is not possible to preview only > certain kinds of LaTeX math delimiters. Adding this is a fair bit of > work, and I'm not sure it's necessary? But you do have `org-latex-preview-auto-ignored-environments', don't you? Could you explain in more details why previewing certain kinds of latex is difficult? Can't you just filter things in `org-latex-preview--construct-entries' as you already do for numbering? > On a related note, auto/live-previews of LaTeX fragments does not > preview $...$ and $$...$$ fragments as you type. This is independent of > the specification in matchers. We track insertions for auto-previews > using after-change-functions, and the logic needs to be very fast -- we > perform a fast, "inner" heuristic check with possible false positives > before we call the "outer", exact org-element-type check. We couldn't > make recognizing $...$ delimiters as you type fast enough to never block > Emacs. Again, this paragraph is about auto/live-previews only, as > activated by org-latex-preview-auto-mode. It is fine as it is a band new feature. If users badly want supporting $...$, they will come with patches. -- Ihor Radchenko // yantar92, Org mode maintainer, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92>
