Rename org-latex-preview-width?

[karthink]

Rename org-latex-preview-width -> org-latex-preview-page-width maybe?

Got a report of a user who assumed this variable controlled the preview width, as in its size. To be fair they probably did not read the variable documentation.

[karthink]

Actually, do we even want this to be a separate option?

The plist org-preview-latex-options could contain all the user preferences for generating in-buffer previews.

• :foreground
• :background
• :scale
• :zoom
• :page-width (formerly org-preview-latex-width)

There's also :matchers in there, but I think this is obsolete? We don't respect this any more.

What do you think? Anything else that could live in this plist instead of scattered about the customize menu?

[tecosaur]

:thinking: putting it in the options plist sounds reasonable to me.

[karthink]

How about adding:

• :process, formerly org-latex-preview-default-process? This will break backwards compatibility, but it seems like something that should live inside a variable named org-latex-preview-options
• :preamble, formerly org-latex-preview-preamble?
• :precompile (boolean), formerly org-latex-preview-precompile?

Live preview options:

• :live-display, can be buffer or eldoc, formerly org-latex-preview-live-display-type
• :live-inline, boolean, formerly org-latex-preview-live-preview-inline

I'm not sold on any of this, just bringing it up for consideration. Having them all in one place is nice for configuration, the user just needs to tweak one plist, and the name org-latex-preview-options makes sense too.

But there are two concerns:

• Placing them in org-latex-preview-options makes it harder to change them buffer-locally. The whole plist will have to be made local, and then there's cause for all kinds of confusion re: the other fields of the plist.
• Some of these, like org-latex-preview-live-preview-inline, are looked up constantly, with every live-preview update. Putting them in a plist (with 10 keys, say) adds some lag. As usual, I might be too conservative here, but a bunch of trivial increases like this can eventually add up.

---

It's just a shame that we have both, a variable named org-latex-preview-options that doesn't contain all the relevant options, and a bunch of options spread over the org-latex-preview- namespace.

We could go in the other direction too: deprecate org-latex-preview-options and define org-latex-preview-zoom, org-latex-preview-scale etc. This would also make things more uniform.

[tecosaur]

I'm sold on :page-width but not the rest.

If we do move more options between the plist and variables, we can maintain backward compatibility by using forms like this:

(or (plist-get *-options :thing) *-thing)
(or *-thing (plist-get *-options :thing))

[karthink]

I'm trying to find a division of options that makes some kind of internal sense. Using the short names for brevity:

• :foreground, :background, :scale, :zoom and :page-width all have to do with the appearance/geometry of the image in the buffer
• :process, :precompile and :process-alist are options governing the process (as in OS process) by which previews are generated.
• :preamble is its own thing -- it can change the appearance of the previews but it's more of a LaTeX source thing.
• :live-display and :live-inline and :generate (for org-latex-preview-auto-generate) are about the means of preview display/display updates in the buffer.

So putting the first set in org-latex-preview-options is internally consistent. We could maybe rename it to org-latex-preview-appearance-options to be more accurate, but this will require a make-obsolete-variable and some compat-grumbling-noises from users.

The next two can stay as they are, as individual options.

We could place the last set (auto- and live- behavior) into a single plist, perhaps org-latex-preview-auto-options.

Just musing, so far :page-width is the only change I'm sold on as well.

[tecosaur]

So putting the first set in org-latex-preview-options is internally consistent. We could maybe rename it to org-latex-preview-appearance-options to be more accurate, but this will require a make-obsolete-variable and some compat-grumbling-noises from users.

This is already required due to the prefix change :)

[tecosaur]

Hmm, there's one difference between :page-width and the other parameters that makes implementing the change a little more annoying: everything else can be applied on a per-fragment basis.

[karthink]

Do we ever change any of the other attributes per-fragment?

[tecosaur]

Yes, :foreground and :background.

[tecosaur]

With https://git.tecosaur.net/tec/org-mode/commit/0a4f58e46 I'm happy with how things are.