mathews-tom/arxiv-package

arXiv Submission Packager

Purpose

Assemble a TeX/LaTeX project into a clean, correctly structured .tar.gz or .zip archive ready for arXiv upload. Handles file selection, artifact exclusion, directory structure, 00README generation, and validation of the final package.

Companion skills:

• arxiv-preflight — validate before packaging
• arxiv-figures — optimize figures before packaging

Workflow

1. Inventory

Scan the project directory. Classify every file:

INCLUDE — Required

• Main .tex file(s)
• All \input/\include targets (recursively trace)
• All \includegraphics targets
• .bbl files (pre-processed bibliography)
• .ind files (pre-processed index)
• .gls/.nls files (glossary/nomenclature)
• Custom .sty, .cls, .bst files not in TeX Live
• 00README.XXX (if present)
• anc/ directory contents (ancillary files)

EXCLUDE — Build Artifacts

• .aux, .log, .toc, .lot, .lof, .out, .nav, .snm, .vrb
• .dvi, .ps, .pdf (except figure PDFs and ancillary PDFs)
• .synctex, .synctex.gz, .fls, .fdb_latexmk
• .blg, .ilg, .glg, .nlg (log files from bib/index/glossary processing)
• *.bak, *~, *.swp, *.swo (editor backups)
• .DS_Store, Thumbs.db, desktop.ini (OS artifacts)

EXCLUDE — Should Not Submit

• Journal templates / style guides (unless custom .sty needed for compilation)
• Referee letters, cover letters
• Build scripts (Makefile, latexmkrc) — not needed by arXiv
• .git/, .svn/, version control directories
• IDE configs (.vscode/, .idea/, .texpadtmp/)

FLAG — Needs Decision

• .bib files (include alongside .bbl or omit — arXiv processes both)
• Multiple .tex files with \documentclass (needs 00README.XXX with toplevelfile)
• Large data files (ancillary or exclude)

2. Generate 00README.XXX

Create or update the 00README.XXX file when needed:

# Auto-generated by arxiv-package

# Main TeX file (only if ambiguous — multiple \documentclass files)
main.tex toplevelfile

# Files to exclude from processing
cover-letter.pdf ignore
notes.txt ignore

# Optional directives
# nostamp
# nohypertex

Only generate if:

• Multiple .tex files contain \documentclass (declare toplevelfile)
• Files need explicit ignore directives
• User requests nostamp or other directives

3. Validate Structure

Before creating the archive:

1. All \input/\include targets resolve to files in the package
2. All \includegraphics targets resolve to files in the package
3. All \bibliography targets have corresponding .bbl files
4. No absolute paths in any TeX source
5. No filenames with spaces or special characters
6. anc/ directory contains no .tex files
7. No hidden files (will be deleted by arXiv upon announcement)
8. Total uncompressed size is reasonable (flag >50MB — may need exception request)

4. Create Archive

# From project root, create tar.gz excluding unwanted files
tar czf submission.tar.gz \
  --exclude='*.aux' --exclude='*.log' --exclude='*.toc' \
  --exclude='*.lot' --exclude='*.lof' --exclude='*.out' \
  --exclude='*.nav' --exclude='*.snm' --exclude='*.vrb' \
  --exclude='*.dvi' --exclude='*.synctex*' \
  --exclude='*.fls' --exclude='*.fdb_latexmk' \
  --exclude='*.blg' --exclude='*.ilg' --exclude='*.glg' \
  --exclude='*.bak' --exclude='*~' --exclude='*.swp' \
  --exclude='.git' --exclude='.svn' \
  --exclude='.DS_Store' --exclude='Thumbs.db' \
  --exclude='.vscode' --exclude='.idea' \
  [list of files/directories to include]

# Or create zip
zip -r submission.zip [files] \
  -x '*.aux' -x '*.log' -x '*.toc' ...

Prefer explicit file inclusion over directory-wide inclusion with exclusions. This prevents accidental inclusion of sensitive or unnecessary files.

5. Verify Archive

After creation:

1. List archive contents — verify no unexpected files
2. Extract to temporary directory
3. Attempt compilation in the extracted directory (if TeX toolchain available)
4. Report archive size (compressed and uncompressed)
5. Compare file list against the include/exclude inventory

6. Report

# arXiv Package Report

**Archive:** submission.tar.gz
**Compressed size:** [size]
**Uncompressed size:** [size]
**File count:** [count]

## Contents

| File | Size | Type |
|------|------|------|
| main.tex | 45 KB | Source |
| references.bbl | 12 KB | Bibliography |
| fig1.pdf | 380 KB | Figure |
| anc/data.csv | 1.2 MB | Ancillary |

## Excluded

| File | Reason |
|------|--------|
| main.aux | Build artifact |
| main.log | Build artifact |
| referee-response.pdf | Not for submission |

## 00README.XXX

[Contents if generated]

## Verification

- [ ] Archive extracts cleanly
- [ ] All source references resolve
- [ ] Compilation succeeds (if tested)
- [ ] No sensitive files included

Archive Format Notes

• .tar.gz preferred over .zip (standard in academic TeX workflows)
• arXiv accepts both .tar (gzipped) and .zip
• Do not nest archives (no .tar.gz inside a .zip)
• Files should be at root level or in logical subdirectories — no wrapper directory unless the project uses subdirectories for organization

Core Principles

• Explicit inclusion over blanket exclusion. Build the file list from what's needed, not from everything minus what's not needed. This catches files that shouldn't be submitted but aren't in the exclusion list.
• Verify after packaging. The archive is the submission. Test it, not the source directory.
• Preserve directory structure. If the project uses subdirectories for figures or sections, maintain that structure. TeX paths depend on it.
• No sensitive files. Check for .env, credentials, personal notes, referee correspondence before packaging.