Karthik Chikmagalur <[email protected]> writes:
> Hope that's clear.
Yup.
>>> - 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.
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.
Also, "preview LaTeX in the Org buffer when editing it in a dedicated
LaTeX-mode buffer with ~org-edit-special~" sounds heavy.
>>> #+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.)
Maybe add a footnote about this caveat?
>> 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
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.
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.
>>> :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.
> - 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?
> Relevant options and commands can be found via =M-x customize-group=,
> and in the Org manual.
Which group?
> 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.
> - 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.
Also,
> (list 'org-async-task ; dvi to svg conversion process
> '(\"dvisvgm\" \"--page=1-\" \"-o out-%p.svg\" \"texfile.dvi\")
What is %p?
> 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.
Also, `org-async-timeout' is not documented at all in the docstirng.
> (defvar org-async--counter 0)
Please add docstring.
org-async-wait-for should probably be documented in org-async-call 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.
> 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?
You can, but you need to leave png as an alias. Or we are going to break
user's setups.
> - 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?
> - 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?
> 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.
--
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>
