Metadata-Version: 2.4
Name: scoop-latex-packer
Version: 0.1.0
Summary: Package a top-level .tex file and its dependencies into a .zip for submission to publishers or arXiv.
Author-email: Roland Herzog <roland.herzog123@gmail.com>
License: MIT License
        
        Copyright (c) 2023 Scoop Group
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://gitlab.com/scoopgroup-public/scoop-latex-packer
Project-URL: Source, https://gitlab.com/scoopgroup-public/scoop-latex-packer
Project-URL: Issues, https://gitlab.com/scoopgroup-public/scoop-latex-packer/-/issues
Project-URL: Changelog, https://gitlab.com/scoopgroup-public/scoop-latex-packer/-/blob/main/CHANGELOG.md
Keywords: latex,arxiv,packaging,submission
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# scoop-latex-packer

`scoop-latex-packer` takes a top-level `.tex` file, resolves its dependencies, and packs them into a `.zip` suitable for submission to a publisher or to [arXiv](https://arxiv.org/).
It also validates the resulting archive by re-compiling it in a sterile environment, so you find out *before* submission whether anything is missing.

## Installation

```bash
pip install scoop-latex-packer
```

This installs the `slp` command (with `scoop-latex-packer` available as a longer-form alias). The examples below use `slp`.

## Requirements

* Python 3.11 or newer.
* `latexmk` and `kpsewhich` on `PATH`. Both ship with every standard TeX distribution (TeX Live, MiKTeX, MacTeX).

## Usage

The CLI has three subcommands: `pack` builds a submission archive, `analyze` prints what `pack` would include without writing the archive, and `validate` verifies that an archive compiles in isolation.
Run `slp` with no arguments to see the top-level help.

The top-level `.tex` file argument to `pack` is optional: if you omit it, `slp` looks for a unique `.tex` file containing `\documentclass` in the current directory and uses that.
If the argument carries a directory component (e.g. `papers/preprint.tex` or `/abs/path/preprint.tex`), `slp` changes into that directory before packing, so all output files — including the resulting `.zip` — land beside the source.

```bash
# Pack the only top-level .tex file in the current directory.
slp pack

# Pack a specific top-level .tex file.
slp pack preprint.tex

# Pack a paper that lives in another directory — slp changes
# into that directory first, so the resulting .zip lands beside the source.
slp pack papers/preprint.tex
slp pack ~/Work/papers/preprint.tex

# Pack for arXiv submission (freezes the minted cache; ships .bib sources).
slp pack --arxiv preprint.tex

# Include extra data files that the recorder doesn't detect (repeat for multiple).
slp pack --extra-file data/run1.csv --extra-file data/run2.csv preprint.tex

# Show what pack would include in the archive without actually writing it.
# Accepts the same flags as `pack` (e.g. --arxiv to preview the prepends).
slp analyze preprint.tex
slp analyze --arxiv preprint.tex

# Verify that the resulting archive compiles with no help from your local
# TEXINPUTS/BIBINPUTS/BSTINPUTS environment.
slp validate preprint.zip

# Keep the extraction directory around for poking at after a failure.
slp validate --keep-tmpdir preprint.zip
```

`slp <subcommand> --help` (or `scoop-latex-packer <subcommand> --help`) lists every option for that subcommand.

## Project-local config

A `slp.toml` file next to the top-level `.tex` is auto-loaded; CLI flags always win over config values, which in turn win over the built-in defaults.
`pack` and `analyze` share the `[pack]` section; `validate` reads `[validate]`.

```toml
[pack]
arxiv = true
extra-files = ["data/run1.csv", "data/run2.csv"]

[validate]
no-open = true
```

You can keep several configs side-by-side in the same directory (`arxiv.toml`, `journal-x.toml`, …) and pick one with `-c` / `--config`:

```bash
slp pack -c arxiv.toml preprint.tex
slp pack -c journal-x.toml preprint.tex
```

Config keys mirror the CLI flag names with hyphens (e.g. `freeze-minted = true`); the lone exception is `include-bibfiles = false`, the positive form of `--exclude-bibfiles`.
Unknown keys produce a warning so typos surface immediately.

A reference [`examples/slp.toml`](examples/slp.toml) ships in the development repository (not in the PyPI wheel) with every supported key set to its default value — copy it as a starting point.

## Features

* Works with `bibtex` and `biber`/`biblatex` bibliographies.
* Auto-detects the top-level `.tex` file from the presence of `\documentclass`.
* Finds dependent files on `TEXINPUTS`, `BIBINPUTS`, and `BSTINPUTS`.
* Ships bibliography **sources** (`.bib`/`.bst`) and never the generated `.bbl` (nor `.toc`/`.lof`/`.lot`); the recipient regenerates them. This avoids the arXiv TeX Live 2025 `.bbl` version-mismatch error, and matches arXiv's current recommendation to upload `.bib` files.
* `--arxiv` switch for one-step arXiv preparation. Under arXiv's Submission 1.5 system (2025) this just freezes the `minted` cache — arXiv now selects the engine interactively and recompiles the bibliography itself, so no `\pdfoutput=1` is injected.
* `--freeze-minted` freezes the `minted` package's cache so the archive compiles without `--shell-escape` (which arXiv disables).
* `validate` re-compiles the archive in an isolated temp directory with the `TEXINPUTS`/`BIBINPUTS`/`BSTINPUTS` variables stripped, catching missing dependencies before you submit.

## Limitations

* Files included via relative paths outside the current directory (e.g. `\includegraphics{../somedir/result.pdf}`) cannot be packed: the archive layout assumes everything lives at or below the project root. `pack` (and `analyze`) detect these and abort with a non-zero exit and a message naming every offending file, rather than silently producing a broken archive. Move such files under the project directory (and update the reference in your `.tex`) before packing.
* A bibliography resource named with a subdirectory (e.g. `\addbibresource{shared/refs.bib}`) that lives *outside* the project — found through an absolute `BIBINPUTS`/`BSTINPUTS` search path — is packed under its bare filename at the archive root, so the `shared/` part of the reference no longer resolves. Keep such resources under the project directory. `validate` catches this case by failing the sterile recompile.

## Development

The development repository lives at <https://gitlab.com/scoopgroup-public/scoop-latex-packer> and contains a `tests/` directory with sample `.tex` and `.bib` fixtures.
The `tests/` directory is excluded from the PyPI wheel and sdist, so end users never see it.

```bash
git clone https://gitlab.com/scoopgroup-public/scoop-latex-packer
cd scoop-latex-packer
python -m venv .venv && source .venv/bin/activate
pip install -e .
# Now run pack/validate against the fixtures in tests/.
```

## License

MIT — see `LICENSE`.
