I've added more commits to the branch addressing these comments:
> Ok. Looking at that part of the manual again, I notice
>
> #+vindex: org-latex-preview-live
> Additionally, if the option ~org-latex-preview-mode-display-live~ is
> non-nil, previews for modified or new LaTeX fragments will be
> displayed adjacent to the fragment, and updated in real-time as you
> type.
>
> ~org-latex-preview-mode-display-live~ can be configured to apply
> separately to
> LaTeX fragments and LaTeX environments. Additionally, it can also be
> set to preview LaTeX in the Org buffer when editing it in a dedicated
> LaTeX-mode buffer with ~org-edit-special~.
>
> Note how the last paragraph is dedented, falling out of the "-
> (~org-latex-preview-mode~) ::"
> list.
Fixed vindex and dedent.
> Also, "preview LaTeX in the Org buffer when editing it in a dedicated
> LaTeX-mode buffer with ~org-edit-special~" sounds heavy.
Reworded comment.
>> 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.)
>
> Maybe add a footnote about this caveat?
Added footnote.
>> - Removed :matchers from the appearance options
>> - Added new option org-highlight-latex-matchers
>
> What you did is breaking for users who customized the obsolete
> `org-format-latex-options'.
> You should still consult :matchers from user-customized value of
> `org-format-latex-options', if it is present.
> The obsolete alias should be updated accordingly, pointing that it is
> not merely a rename, but users need to use a completely different new
> variable for :matchers.
- org-latex-and-related-regexp now consults
org-highlight-latex-matchers. If that is nil, it falls back to
(plist-get org-latex-preview-appearance-options :matchers)
- The docstring for org-format-latex-options now mentions :machers (as
before), but also that support for :machers is obsolete and that
org-highlight-latex-matchers should be used instead.
> Also, we need to refer to this new variable from "A number of LaTeX
> preview options and functions have been obsoleted or changed" in ORG-NEWS.
- There was already a new entry for org-highlight-latex-matchers in "New
and changed options". Additionally,
- The "A number of LaTeX preview options and functions" heading now also
mentions the new variable.
>>>> :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.
>
> Maybe. But we should indicate which new variable should be used instead
> in the obsoletion warning. Similar to what I said about :matchers.
The docstring for org-format-latex-options now mentions that :machers
support is obsolete, as mentioned above.
>> - Mentioned org-async-call in ORG-NEWS, feel free to move it around when
>> required.
>
> Looking there again...
>
>>- Inline previews are aligned and scaled to match the font baseline
>> and size.
>
> This also applied to exports, right?
Reworded the section "The LaTeX preview system has been overhauled" to
mention HTML/ODT export additions.
>> Relevant options and commands can be found via =M-x customize-group=,
>> and in the Org manual.
>
> Which group?
org-latex-preview, now mentioned there.
>> Additionally, if the option ~org-latex-preview-mode-track-inserts~ is
>> non-nil (which see), previews for new LaTeX fragments will be
>> auto-generated as they are inserted.
>
> Maybe inserted->yanked. Inserted sounds strange.
You must be looking at an older commit, because the wording was changed
to be less awkward in a recent commit.
----------------------------------------------------
org-async feedback:
>> - Added three examples to the org-async-call docstring, but the function
>> is complex enough that more can be added in the future.
>
> There are some checkdoc warnings in the docstring.
Fixed.
> Also,
>> (list 'org-async-task ; dvi to svg conversion process
>> '(\"dvisvgm\" \"--page=1-\" \"-o out-%p.svg\" \"texfile.dvi\")
>
> What is %p?
It's a format spec used by dvisvgm. This is irrelevant in the
documentation of org-async-call, so I've removed the -%p bit. This
example is for illustration only, and cannot be run anyway.
>> When NOW is non-nil, the PROC is started immediately, regardless
>> of `org-async-process-limit'.
>
> `org-async-process-limit' should probably be documented upfront when
> describing what org-async-call does.
Added doc mentioning the process limit to org-async-call.
> Also, `org-async-timeout' is not documented at all in the docstirng.
Oops. Added.
>> (defvar org-async--counter 0)
>
> Please add docstring.
Added a docstring for now, but this variable might be removed based on
your comments/suggestions from your other/future emails.
> org-async-wait-for should probably be documented in org-async-call docstring.
I've added a mention of org-async-wait-for to the docstring.
> I'd also like to see some kind of section comment describing why we need
> to roll out custom implementation of async calls different from Emacs's
> built-ins.
Added a section comment.
----------------------------------------------------
ob-latex feedback: I'm not making any changes yet.
>> 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:
>>
>> [...]
>>
>> 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?
>
> You can, but you need to leave png as an alias. Or we are going to break
> user's setups.
Noted.
>> - The latexmk command is wrong for use with org-latex-preview, it needs
>> to generate a dvi, not a pdf.
>
> How does it work now then?
I am not sure.
>> - 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.
>
> Does it mean that
>
> :latex-compiler list of LaTeX commands, as strings or a function.
> Each of them is given to the shell.
> Place-holders \"%t\", \"%b\" and \"%o\" are
> replaced with values defined below.
> When a function, that function should accept the
> file name as its single argument.
>
> in the docstring of `org-latex-preview-process-alist' is not accurate?
> Is function also not supported?
Yes, both lists of commands and functions are unsupported.
The docstring needs to be changed, or support for these things needs to
be added to org-latex-preview--tex-compile-async. In this function you
can see what we are doing right now inside a let-binding:
(tex-compile-command-fmt
(pcase (plist-get extended-info :latex-compiler)
((and (pred stringp) cmd) cmd)
((and (pred consp) cmds)
(when (> (length cmds) 1)
(warn "Preview :latex-compiler must now be a single command. %S will be
ignored."
(cdr cmds)))
(car cmds))))
I think we meant to do something about this later and lost track of it.
My understanding of this issue today is the following:
- the default :latex-compiler and :image-converter commands in
org-latex-preview-process-alist are very finely tuned for
performance/speed to support live previews.
- If you customize :latex-compiler, you will also have to customize
:image-converter carefully to be compatible. I think the functions
--tex-compile-async and --image-extract-async make some assumptions
that make it difficult to customize :latex-compiler and
:image-converter at all -- the process is inherently more complex than
the previous method of calling org-compile-file synchronously.
- I have tested that using latexmk in the :latex-compiler does indeed
work (with no changes to :image-converter), but I remember that I had
to be careful to choose a very specific set of CLI arguments.
I don't know what the way forward should be. I haven't changed the
docstring of org-latex-preview-process-alist yet.
>> The png path works if I ignore org-babel-latex-process-alist and reuse
>> org-latex-preview-process-alist.
>
> It is important that we use latexmk/triple latex there as it will allow
> resolving references. Let's discuss what can be done.
Based on the above, latexmk will work, but only with a specific set of
CLI arguments. If they want to customize org-babel-latex-process-alist,
it's going to be beyond the ability of most users to figure out what
these arguments should be.
The triple LaTeX there may not require changes to org-async-call, and it
might be enough to change org-latex-preview--tex-compile-async to
support it. But I am not sure yet.
Karthik
