# tex-fast-recompile
[](https://pypi.python.org/pypi/tex-fast-recompile/)
A Python module to speed up TeX compilation.
This is similar to the [`mylatexformat` TeX package](https://ctan.org/pkg/mylatexformat) that it works by "speed up" some "preamble",
but unlike using "precompiled preamble" i.e. custom TeX format,
this package works with *every* package including package that executes some Lua code, or load OpenType font.
## Installation
It can be installed from PyPI or GitHub:
* https://pypi.org/project/tex-fast-recompile/
* https://github.com/user202729/tex-fast-recompile
You also need to install the helper TeX package `fastrecompile.sty`, which can be found in the `tex/` directory.
Refer to https://tex.stackexchange.com/q/1137/250119 for installation instruction.
(currently the TeX package is not available on CTAN)
### Manual installation from source (GitHub)
In case I fix some bug in the latest version but forget to push to PyPI.
Run from the command-line:
```bash
pip install git+https://github.com/user202729/tex-fast-recompile
```
or alternatively download the code from GitHub by clicking "Code ⯆" green button → "Download ZIP" (at the moment),
then unzip the file and from within the folder,
```bash
pip install -e .
```
The `-e` is an "editable" install, that is if you modify the source code in the folder, you don't need to reinstall the package.
## Usage
### Normal mode
If installed properly, an executable `tex_fast_recompile` should be available on your command-line.
Run `tex_fast_recompile --help` to view the available options.
For example you can use it as follows:
```bash
tex_fast_recompile pdflatex a.tex
```
to compile `a.tex` to `a.pdf` and automatically watch it on changes.
Usually prepending it to your LaTeX compilation command suffices.
### LaTeXmk emulation mode
For compatibility with e.g. `vimtex` plugin, an executable `tex_fast_recompile_latexmk` is provided, which takes arguments similar to that of `latexmk`.
(but it does not invoke bibliography/indexing commands/automatically detect changes to dependent files etc., and the simulation might not be complete)
Run `tex_fast_recompile_latexmk --help` to view the available options. (should be similar to `latexmk`'s accepted options)
For VimTeX usage, putting the following configuration in `.vimrc` usually suffices:
```vim
let g:vimtex_compiler_latexmk = { 'executable' : 'tex_fast_recompile_latexmk' }
```
### Note for Windows users
For yet-unknown reasons, file names containing non-ASCII characters are not supported. For example the following is invalid:
```bash
tex_fast_recompile pdflatex ≡.tex
```
As a workaround, the following appears to work:
```bash
python -m tex_fast_recompile pdflatex ≡.tex
```
### Note for Vim users
If update performance appears slow, try disabling `writebackup`, or set `backupcopy=yes`.
(this issue happened once for me, and I haven't been able to reproduce it so far. Alternatively just try
restarting your computer.)
## Limitations
* If VimTeX is used, the latexmk (emulation) is forcefully killed when compilation stops.
In that case, the temporary directory is not cleaned, and over time it may clutter the temporary directory.
(this has a partial workaround, that is new process spawned will clean up previous process' temporary directories)
* Any file `\input` in the preamble must not be changed. (when the preamble changes, the program will automatically detect that)
* You must not read from the terminal anywhere in the preamble, such as with functions `\read -1 to ...` or `\ior_get_term:nN ...`.
(if you're not sure what this mean, you should be safe)
* The latexmk emulation mode does not necessarily recompile the file sufficiently many times when references changed.
(as such it might be convenient to use `silence` package to suppress the `rerunfilecheck` warnings
such as:
```latex
\WarningFilter{latex}{Reference `}
\WarningFilter{latex}{Citation `}
\WarningFilter{latex}{There were undefined references}
\WarningFilter{latex}{Label(s) may have changed}
\WarningFilter{rerunfilecheck}{}
```
While the first filter may be overly broad, for the purpose of fast preview it isn't too important.)
## Advanced notes
### Explicitly specify preamble ending location
You can put `\fastrecompileendpreamble` on a single line to mark the end of the "fixed preamble" part.
Or equivalently, `\csname fastrecompileendpreamble\endcsname` (note that there must be no space before the `\endcsname`) --
this is the same as above, but will just silently do nothing instead of complaining about `\fastrecompileendpreamble` being not defined
if this program is not used.
Note that:
* `\fastrecompileendpreamble` must appear at most once in the *main* file.
* There must be nothing else on the line that contains `\fastrecompileendpreamble`.
* SyncTeX features of the text part in the "preamble" may not be correct.
Normally, this is assumed to be right before the `\begin{document}` line (or `\AtEndPreamble`),
but if you either
* use the `--copy-output` option (and only read the copied output), or
* there's no package that outputs something at the start of the document (such as `hyperref`),
then you can move the `\fastrecompileendpreamble` to after the `\begin{document}` line.
### Extra note
If you want to read the log file, refer to the help of `--copy-log` option.
It's possible to print out some content in the "preamble" part, but if you do so...
```tex
\documentclass{article}
\usepackage{fastrecompile} % add the package here
% other preamble lines...
\begin{document}
123
\clearpage
\fastrecompileendpreamble
456
\end{document}
```
you must also use the `--copy-output` option if you want to view the resulting PDF.
### Internal note
The module used to create a temporary file instead of `\input` the original file with `begindocument/end` hook,
but with the `--recorder` flag then `\currfileabspath` will be wrong in the preamble,
and `@@input` does not update the file name when the actual file is `\input`-ed.
With the handler moved to `\AtEndPreamble` instead of `\AtBeginDocument` there are some spurious messages... (not critical)
### How does it work?
The principle is very simple. Notice that while the user want fast refresh, the file does not change very frequently.
As such, we start the compiler _before_ the file has changed to process the "preamble", then when the file changed we
continue processing the rest of the file.
A graph for illustration:
**Before:**
(each `*` represents a file change, `|--.--|` represents a compilation where the `.` marks where the preamble processing is done)
```
+----------------------------------------------------> Time
* * * *
|--.--| |--.--| |--.--| |--.--|
```
**After:**
```
+----------------------------------------------------> Time
* * * *
|--.--|--. --|--. --|--. --|
```
It can be easily seen that after the change, it only takes 2 instead of 5 time units
from when the file is saved to when the change is reflected in the PDF.
Raw data
{
"_id": null,
"home_page": "https://github.com/user202729/tex-fast-recompile",
"name": "tex-fast-recompile",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "user202729",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/91/b9/bb96d37c4a8d2be9fb1e6ddc6fe357d22ee6aa5036d5d17333b7038d3116/tex-fast-recompile-0.5.2.tar.gz",
"platform": null,
"description": "# tex-fast-recompile\n\n[](https://pypi.python.org/pypi/tex-fast-recompile/)\n\nA Python module to speed up TeX compilation.\n\nThis is similar to the [`mylatexformat` TeX package](https://ctan.org/pkg/mylatexformat) that it works by \"speed up\" some \"preamble\",\nbut unlike using \"precompiled preamble\" i.e. custom TeX format,\nthis package works with *every* package including package that executes some Lua code, or load OpenType font.\n\n## Installation\n\nIt can be installed from PyPI or GitHub:\n\n* https://pypi.org/project/tex-fast-recompile/\n* https://github.com/user202729/tex-fast-recompile\n\nYou also need to install the helper TeX package `fastrecompile.sty`, which can be found in the `tex/` directory.\nRefer to https://tex.stackexchange.com/q/1137/250119 for installation instruction.\n\n(currently the TeX package is not available on CTAN)\n\n### Manual installation from source (GitHub)\n\nIn case I fix some bug in the latest version but forget to push to PyPI.\n\nRun from the command-line:\n\n```bash\npip install git+https://github.com/user202729/tex-fast-recompile\n```\n\nor alternatively download the code from GitHub by clicking \"Code \u2bc6\" green button \u2192 \"Download ZIP\" (at the moment),\nthen unzip the file and from within the folder,\n\n```bash\npip install -e .\n```\n\nThe `-e` is an \"editable\" install, that is if you modify the source code in the folder, you don't need to reinstall the package.\n\n## Usage\n\n### Normal mode\n\nIf installed properly, an executable `tex_fast_recompile` should be available on your command-line.\n\nRun `tex_fast_recompile --help` to view the available options.\n\nFor example you can use it as follows:\n\n```bash\ntex_fast_recompile pdflatex a.tex\n```\n\nto compile `a.tex` to `a.pdf` and automatically watch it on changes.\n\nUsually prepending it to your LaTeX compilation command suffices.\n\n### LaTeXmk emulation mode\n\nFor compatibility with e.g. `vimtex` plugin, an executable `tex_fast_recompile_latexmk` is provided, which takes arguments similar to that of `latexmk`.\n(but it does not invoke bibliography/indexing commands/automatically detect changes to dependent files etc., and the simulation might not be complete)\n\nRun `tex_fast_recompile_latexmk --help` to view the available options. (should be similar to `latexmk`'s accepted options)\n\nFor VimTeX usage, putting the following configuration in `.vimrc` usually suffices:\n\n```vim\nlet g:vimtex_compiler_latexmk = { 'executable' : 'tex_fast_recompile_latexmk' }\n```\n\n### Note for Windows users\n\nFor yet-unknown reasons, file names containing non-ASCII characters are not supported. For example the following is invalid:\n\n```bash\ntex_fast_recompile pdflatex \u2261.tex\n```\n\nAs a workaround, the following appears to work:\n\n```bash\npython -m tex_fast_recompile pdflatex \u2261.tex\n```\n\n### Note for Vim users\n\nIf update performance appears slow, try disabling `writebackup`, or set `backupcopy=yes`.\n(this issue happened once for me, and I haven't been able to reproduce it so far. Alternatively just try\nrestarting your computer.)\n\n## Limitations\n\n* If VimTeX is used, the latexmk (emulation) is forcefully killed when compilation stops.\nIn that case, the temporary directory is not cleaned, and over time it may clutter the temporary directory.\n\n (this has a partial workaround, that is new process spawned will clean up previous process' temporary directories)\n* Any file `\\input` in the preamble must not be changed. (when the preamble changes, the program will automatically detect that)\n* You must not read from the terminal anywhere in the preamble, such as with functions `\\read -1 to ...` or `\\ior_get_term:nN ...`.\n(if you're not sure what this mean, you should be safe)\n* The latexmk emulation mode does not necessarily recompile the file sufficiently many times when references changed.\n(as such it might be convenient to use `silence` package to suppress the `rerunfilecheck` warnings\nsuch as:\n\n```latex\n\\WarningFilter{latex}{Reference `}\n\\WarningFilter{latex}{Citation `}\n\\WarningFilter{latex}{There were undefined references}\n\\WarningFilter{latex}{Label(s) may have changed}\n\\WarningFilter{rerunfilecheck}{}\n```\n\nWhile the first filter may be overly broad, for the purpose of fast preview it isn't too important.)\n\n## Advanced notes\n\n### Explicitly specify preamble ending location\n\nYou can put `\\fastrecompileendpreamble` on a single line to mark the end of the \"fixed preamble\" part.\n\nOr equivalently, `\\csname fastrecompileendpreamble\\endcsname` (note that there must be no space before the `\\endcsname`) --\nthis is the same as above, but will just silently do nothing instead of complaining about `\\fastrecompileendpreamble` being not defined\nif this program is not used.\n\nNote that:\n\n* `\\fastrecompileendpreamble` must appear at most once in the *main* file.\n* There must be nothing else on the line that contains `\\fastrecompileendpreamble`.\n* SyncTeX features of the text part in the \"preamble\" may not be correct.\n\nNormally, this is assumed to be right before the `\\begin{document}` line (or `\\AtEndPreamble`),\nbut if you either\n* use the `--copy-output` option (and only read the copied output), or\n* there's no package that outputs something at the start of the document (such as `hyperref`),\nthen you can move the `\\fastrecompileendpreamble` to after the `\\begin{document}` line.\n\n### Extra note\n\nIf you want to read the log file, refer to the help of `--copy-log` option.\n\nIt's possible to print out some content in the \"preamble\" part, but if you do so...\n\n```tex\n\\documentclass{article}\n\\usepackage{fastrecompile} % add the package here\n% other preamble lines...\n\\begin{document}\n\n123\n\\clearpage\n\\fastrecompileendpreamble\n456\n\n\\end{document}\n```\n\nyou must also use the `--copy-output` option if you want to view the resulting PDF.\n\n### Internal note\n\nThe module used to create a temporary file instead of `\\input` the original file with `begindocument/end` hook,\nbut with the `--recorder` flag then `\\currfileabspath` will be wrong in the preamble,\nand `@@input` does not update the file name when the actual file is `\\input`-ed.\n\nWith the handler moved to `\\AtEndPreamble` instead of `\\AtBeginDocument` there are some spurious messages... (not critical)\n\n### How does it work?\n\nThe principle is very simple. Notice that while the user want fast refresh, the file does not change very frequently.\n\nAs such, we start the compiler _before_ the file has changed to process the \"preamble\", then when the file changed we\ncontinue processing the rest of the file.\n\nA graph for illustration:\n\n**Before:**\n\n(each `*` represents a file change, `|--.--|` represents a compilation where the `.` marks where the preamble processing is done)\n\n```\n+----------------------------------------------------> Time\n * * * *\n |--.--| |--.--| |--.--| |--.--|\n```\n\n**After:**\n\n```\n+----------------------------------------------------> Time\n * * * *\n |--.--|--. --|--. --|--. --|\n```\n\nIt can be easily seen that after the change, it only takes 2 instead of 5 time units\nfrom when the file is saved to when the change is reflected in the PDF.\n",
"bugtrack_url": null,
"license": "LPPL 1.3c",
"summary": "A Python module to speed up TeX compilation.",
"version": "0.5.2",
"project_urls": {
"Homepage": "https://github.com/user202729/tex-fast-recompile"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5b21a38f339d07241b97a0a88a6f08ecf18e22a58cb710bb3ff505c9dee9d658",
"md5": "182492a7354675c870cac97e01d56ef2",
"sha256": "91d2ce928f14ced218127c735eb3f22ec41d02ba456483ef54b93c49f2d1e35a"
},
"downloads": -1,
"filename": "tex_fast_recompile-0.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "182492a7354675c870cac97e01d56ef2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20370,
"upload_time": "2023-06-06T08:08:01",
"upload_time_iso_8601": "2023-06-06T08:08:01.477375Z",
"url": "https://files.pythonhosted.org/packages/5b/21/a38f339d07241b97a0a88a6f08ecf18e22a58cb710bb3ff505c9dee9d658/tex_fast_recompile-0.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "91b9bb96d37c4a8d2be9fb1e6ddc6fe357d22ee6aa5036d5d17333b7038d3116",
"md5": "04496dc0a6ef68946f4a56eea0b26825",
"sha256": "783bf3e3d54c49f8d0212bf8e899d44923fadc8dea6a7d47043d2ff63314ca80"
},
"downloads": -1,
"filename": "tex-fast-recompile-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "04496dc0a6ef68946f4a56eea0b26825",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26067,
"upload_time": "2023-06-06T08:08:04",
"upload_time_iso_8601": "2023-06-06T08:08:04.567090Z",
"url": "https://files.pythonhosted.org/packages/91/b9/bb96d37c4a8d2be9fb1e6ddc6fe357d22ee6aa5036d5d17333b7038d3116/tex-fast-recompile-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-06 08:08:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "user202729",
"github_project": "tex-fast-recompile",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "tex-fast-recompile"
}
JSON
