Support build variables in math preview so absolute paths can be included

[bordaigorl]

Typical scenario: main.tex defines a bunch of custom math macros in a file mymath.tex. The preview can only be customised to include globally available packages. This is because the preview tex file is compiled in a temporary folder and the plugin wants to avoid copying the full project there just in case the user includes files from it.

A workaround is to use "preview_math_template_packages": [..., "\input{/absolute/path/to/mymath.tex}"], but this needs to be setup per project, and changed if the project is moved.

A cheap but sound solution would be to allow reference to build variables such as $project_path so that the above can be rewritten as "preview_math_template_packages": [..., "\input{$project_path/mymath.tex}"]. This can be easily achieved by using sublime.expand_variables in conjuction with window.extract_variables.

All that is needed is proper use of the above API functions in here: https://github.com/SublimeText/LaTeXTools/blob/f2da1d97bd63c4e789c49f42e05a74997fb6d43c/st_preview/preview_math.py#L841

[r-stein]

For technical reasons you should not use \input or similiar commands, which change the output content without changing the base document, in that string. The rendering result are cached based on the document content. Changes in the included file are not propagated to the document and therefore the rendered image will not be updated (even after a ST restart), but you can slightly (e.g. adding a space or swaping two lines) changing the preamble/packages to refresh all rendered images.

Because there were already issue about this I added the preview_math_template_file setting, which only accepts absolute paths, but can be set per project. Thus changing this per project is possible, but you still need an extra file which does not use the \input command and is written as specified in the comment above the setting.

An alternative idea would be to create some kind of "preprocessor macros", e.g. you would write "preview_math_template_packages": [..., "<<read($tex_root/mymath.tex)>>"] and it would read the content of the file and put it into the document, which is compiled for the preview.

[bordaigorl]

In my opinion there are two better options.

The First option is to add a separate preview_math_template_include setting which is just a list of filenames (supporting variables) which will be read and copied verbatim in the template. A variation of this idea that supports complete control over the order between package imports and inputed files is: make preview_math_template_packages accept items of the form {"file": path}. If you see just a string instead, use the old behaviour.

The Second option is to provide a command palette item "LaTeXTools: Clean Math Preview Cache" which the user needs to trigger manually after changing an "inputed" file. Typically the macro files will not be changed frequently. This would probably speed up the preview since the file read is handled by tex directly. This option would greatly benefit from support for variables in the preview_math_template_packages items.

[r-stein]

If I understand it correct your first option is essentially the same idea and usage as my suggested "preprocessor macros". You can write "preview_math_template_packages": [..., "<<read($tex_root/mymath.tex)>>", ...] or "preview_math_template_packages": [..., {"file": "$tex_root/mymath.tex"}, ...].

The second option already exists: the thumbnail cache is cleared when you call LaTeXTools: Clear Cache.

[bordaigorl]

Yes, sorry my message was not very clear. The first option is in the same direction as your preprocessor macros; I would still avoid doing some custom parsing with ad-hoc syntax and exploit JSON.

Regarding the second option: thanks for pointing out the Clear Cache command, I missed it when I looked. Since the command is already there, supporting the build variables in preview_math_template_packages makes even more sense no? All one has to do is mention the problem in the docs and suggest to issue a Clear Cache when the included files are changed.

[r-stein]

Since its from a user perspective just a different syntax I don't think its worth to discuss much about it. However from a developer perspective the JSON dictionary has to be resolved before creating the template document and the macro can be evaluated afterwards. Technically we already have similiar substitutions to replace e.g. <<set_color>> to create a foreground color which fits the current color scheme. We would just have to add a little more complicated regex substitution:

def read_file(match):
    try:
        file_path = match.group(1)
    except (AttributeError, IndexError):
        return ""
    # read/cache file_content
    file_content = ...
    return file_content
latex_template = re.sub(r'<<read\(([^\)]*)\)>>', read_file, latex_template)

For the other option: I really like workarounds (e.g. using the math preview to preview tables), but I don't want to include a feature, which does not work without unexpected manual steps. In addition adding a template substitution might have unexpected side effects if someone uses $ for other reasons in the preamble.

[bordaigorl]

I thought of a third option. LaTeX supports local modifications of the search path for inputed files, using the \input@path macro. So for example, by injecting

\makeatletter
\def\input@path{{PATH_OF_MAIN_FILE}}
\makeatother

one can effectively write \input{file} in preview_math_template_packages and have LaTeX search in the main file's path for file.tex in case it's not found in the current path. The \input@path system supports multiple paths with syntax \input@path{{PATH1}{PATH2}...{PATHN}}.

One way to make this work, without supporting variables in preview_math_template_packages but without setting ad hoc per-project paths, would be to introduce an option preview_math_paths: [listofpaths] where each item of the list can use build variables. Then when constructing the preview latex file you just inject the appropriate \input@path definition.

This would still have the problem of requiring manual cache flushes if editing the inputed files, but maybe since the option is separate, one can make sure the user is aware of this when setting it to a non-trivial list of paths.