Hi Ihor,
Please pull from tecosaur's fork to see the updated version of the
manual.
ORG-NEWS is updated too, but I've placed all changes under:
* Version 9.8 (not released yet)
** Important announcements and breaking changes
*** The LaTeX preview system has been overhauled
**** New features
**** New options
**** Removed or renamed functions and variables
So that everything is in one place for review. I can move these
sections out to the other headings afterwards.
> 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.
I've left it in.
> 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.
It should be org-latex-preview-preamble everywhere. ob-latex.el is not
yet fixed, please ignore this file for now.
>> + **** 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.
> I'd rather quickly introduce live previews in the opening section. IMHO,
> it is far more useful information for the users.
I've shuffled the sections around and mentioned auto and live-previews in
the opening section.
> 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.
Added the following concepts:
#+cindex: @LaTeX{} fragments, live preview
#+cindex: @LaTeX{} fragments, precompilation
#+cindex: @LaTeX{} preview preamble
>> #+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.
Done.
>> #+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.
Done.
>> - (~org-latex-preview-clear-cache~) ::
>> #+findex: org-latex-preview-clear-cache
>
> 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 moved this to the section with details on customizing the preview
process. There are occasionally issues with caching, so it might be
worth keeping the command in the manual.
>> 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?
Done.
Yes, clearing the cache has proven to be a necessary escape valve for
when things go wrong. In the past users could just delete the
org-format-latex-directory (or whatever it was called) and the preview
would automatically recompile next time. With org-persist based caching
it is not possible to do this manually.
>> #+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.
Expanded on this briefly in the manual.
> Also, should you describe `latex-preview-compiler-command-map' in the manual?
I don't think so, there is almost no reason to change this. Should this
be made a defvar instead?
I will address the :matchers issue in a separate email.
Karthik
