Thanks Ihor. I've updated the manual but it's not on Teco's fork yet.
I'll send you an update when it is. But in the meantime, please read
the below for my thoughts and questions.
>> - (~org-latex-preview-auto-mode~) ::
>> #+findex: org-latex-preview-auto-mode
>>
> When reading this section, I feel confused about the difference between
> "automatic" and "live" previews. The words "automatic" and "live" feel
> too similar: "Generate previews of LaTeX fragments as they are entered
> in the buffer" can be interpreted both as "automatic" and "live".
This is true, these are degrees of automation, with
"live" > "automatic".
Any suggestion for a better name?
> The above description is also not fully consistent with the minor mode
> docstring:
>
>> [...]
>
> IMHO, `org-latex-preview-auto-mode' is kind of doing double job: (1)
> implementing something akin org-appear; (2) providing live preview for
> newly inserted and edited fragments.
All of these behaviors are separately configurable, except for ones that
I don't think make sense.
There is only one minor-mode, `org-latex-preview-auto-mode', for any
kind of automatic preview behavior, with its other behaviors controlled
by user options. Here is the new entry for auto-mode:
- (~org-latex-preview-auto-mode~) ::
#+findex: org-latex-preview-auto-mode
Hide or show LaTeX preview images when the cursor moves into or out
of a previewed fragment, respectively. Previews are updated when
the cursor moves out of the fragment.
The level of automation may be tuned based on the following two user
options.
If ~org-latex-preview-auto-track-inserts~ is non-nil, generate
previews of LaTeX fragments as they are entered in the buffer.
Previews will be generated (or removed) when after any change to
the buffer that includes the insertion (or deletion) of a LaTeX
environment or fragment.
#+vindex: org-latex-preview-live
If ~org-latex-preview-live~ is set, preview LaTeX fragments as
you type, displaying a preview image adjacent to the fragment while
it is edited.
Is this clearer?
> May these two jobs be separated?
> 0. I feel like the minimal job that is done by
> `org-latex-preview-auto-mode' is closer to org-appear, and it would
> better be called `org-latex-preview-appear-mode'. Then, a reasonable
> design for customization will be:
> 1. Configure whether the previews are completely hidden or just
> displayed aside/below when the cursor enters latex formula. This may
> be a single customization.
> 2. Configure whether new previews are also automatically created when
> the new fragments are inserted/edited.
>
> Maybe (2) can even be a mode of its own.
These behaviors are available. Let's call them 0, 1 and 2. Then we
have, depending on the user options org-latex-preview-auto-track-inserts
and org-latex-preview-live:
| | -track-inserts:t | -track-inserts:nil |
|------------+------------------+--------------------|
| -live: t | 2a | 1 |
| -live: nil | 2b | 0 |
2a and 2b are finer-grained variants of behavior 2.
I think this makes more sense than having several minor modes. There is
only one mode for automatic previews, and its degree of automation is
customizable via these two user options.
>> You can customize ~org-latex-preview-preamble~ to specify the default
>> LaTeX preamble used for processing LaTeX fragments. This can include
>> the placeholder strings =[DEFAULT-PACKAGES]= and =[PACKAGES]= to
>> include packages specified in ~org-latex-default-packages-alist~ and
>> ~org-latex-packages-alist~ respectively. When previewing, this
>> preamble will be combined with keywords specified in the document via
>
> We may refer to `org-latex-classes' for more detailed description of the
> placeholders.
I added:
See ~org-latex-classes~ for a detailed description of the placeholders.
But I don't know how to link to that variable in the manual.
>> - Page width: The ~:page-width~ property determines the width of the
>> preview image (including whitespace padding) of display-math
>> environments.
>
> What is "display-math"?
Changed to LaTeX environments (as opposed to LaTeX fragments). However
I'm not sure that the user will know the distinction made by Org's
syntax between the two. I think LaTeX users are more familiar with
inline math (as in \(...\) or $...$) and display math (as in \[...\],
$$...$$ or \begin{}...\end{}).
>> **** New options
>>
>> ***** New option ~org-latex-preview-cache~ to enable preview image caching
>
> I think that you do not need to list every single new option in the
> news. It should be enough to (1) Say that we have a new library
> org-latex-preview.el. (2) That the relevant options can be found via M-x
> cusomize-group ... and in the manual.
>
> Obsolete and changed existing options should still be listed, but
> probably moved to "New and changed options"/"Removed or renamed functions and
> variables".
> Also, the renamed options can be grouped under a single heading.
This is confusing so I've pinged you asking to meet with screenshare to
sort it out.
--------- ACKNOWLEDGEMENT OF OTHER FIXES ---------
>> I've left it in.
>
> But not in all the places where you replaced #+vindex. Let's leave it
> everywhere and only remove the obsolete vindex entry from the manual
> when we actually remove that variable.
Okay, I've added back two more vindex entries, so there are three in
total now that refer to obsolete variables:
#+vindex: org-preview-latex-default-process
#+vindex: org-format-latex-header
#+vindex: org-format-latex-options
>> - Live previews: In addition to the above, 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.
>
> I think you can remove "In addition to the above" as it is already a list.
Done.
>> Generate previews of LaTeX fragments as they are entered in the
>> buffer. Previews will be generated (removed) when there is any
>> change to the buffer that includes the insertion (deletion) of a
>> LaTeX environment or fragment.
>
> generated (removed) and insertion (deletion) read slightly confusing.
> Maybe generated (or removed) and insertion (or deletion)?
Fixed.
>> You can control where LaTeX previews are cached by customizing
>> ~org-latex-preview-cache~. By default, Org stores them in the
>> org-persist cache with an expiry determined by
>
> Maybe we can instead refer to `org-persist-directory', as we do not talk
> about org-persist in the manual (for now).
Fixed.
>> If the results are not to your liking, you can customize the
>> appearance of LaTeX previews by modifying
>> ~org-latex-preview-appearance-options~. This plist can be used to
>> specify the following aspects of the apperance of LaTeX previews:
>
> *appearance
Fixed.
>> +If you still want to use python-mode with ob-python, you might
>> +consider
>> [[https://gitlab.com/jackkamm/ob-python-mode-mode][ob-python-mode-mode]],
>> where the code to support python-mode
>> +has been ported to.
>
> This is a stray change (or problem with rebasing).
Removed.
Karthik
