arxiv-package

arXiv 投稿打包工具

用途

将 TeX/LaTeX 项目整理为结构清晰、格式正确的 .tar.gz 或 .zip 归档文件，以便上传至 arXiv。处理文件筛选、排除构建产物、 目录结构、生成 00README 以及验证最终打包文件。

配套技能：

• arxiv-preflight — 打包前进行验证
• arxiv-figures — 打包前优化图片

工作流

1. 清点文件

扫描项目目录。对每个文件进行分类：

纳入 — 必需文件

• 主 .tex 文件
• 所有 \input/\include 目标（递归追踪）
• 所有 \includegraphics 目标
• .bbl 文件（预处理后的参考文献）
• .ind 文件（预处理后的索引）
• .gls/.nls 文件（术语表/符号表）
• TeX Live 中不存在的自定义 .sty、.cls、.bst 文件
• 00README.XXX（如存在）
• anc/ 目录中的内容（附属文件）

排除 — 构建产物

• .aux、.log、.toc、.lot、.lof、.out、.nav、.snm、.vrb
• .dvi、.ps、.pdf（图片 PDF 和附属 PDF 除外）
• .synctex、.synctex.gz、.fls、.fdb_latexmk
• .blg、.ilg、.glg、.nlg（bib/索引/术语表处理生成的日志文件）
• *.bak、*~、*.swp、*.swo（编辑器备份文件）
• .DS_Store、Thumbs.db、desktop.ini（操作系统产物）

排除 — 不应提交

• 期刊模板/样式指南（编译所需的自定义 .sty 除外）
• 审稿意见信、投稿附信
• 构建脚本（Makefile、latexmkrc）— arXiv 不需要
• .git/、.svn/、版本控制目录
• IDE 配置（.vscode/、.idea/、.texpadtmp/）

标记 — 需要决定

• .bib 文件（与 .bbl 一起纳入或省略 — arXiv 会同时处理两者）
• 含有 \documentclass 的多个 .tex 文件（需要使用 toplevelfile 创建 00README.XXX）
• 大型数据文件（作为附属文件或排除）

2. 生成 00README.XXX

在需要时创建或更新 00README.XXX 文件：

# 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

仅在以下情况下生成：

• 多个 .tex 文件包含 \documentclass（声明 toplevelfile）
• 文件需要明确的 ignore 指令
• 用户要求使用 nostamp 或其他指令

3. 验证结构

创建归档文件前：

1. 所有 \input/\include 目标都能在打包文件中找到
2. 所有 \includegraphics 目标都能在打包文件中找到
3. 所有 \bibliography 目标都有对应的 .bbl 文件
4. 所有 TeX 源文件中都没有绝对路径
5. 文件名中没有空格或特殊字符
6. anc/ 目录中没有 .tex 文件
7. 没有隐藏文件（arXiv 公布论文时会删除这些文件）
8. 未压缩的总大小合理（超过 50MB 时标记 — 可能需要申请例外）

4. 创建归档文件

# 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' ...

优先明确指定要纳入的文件，而不是将整个目录纳入后再排除文件。 这样可以避免意外纳入敏感或不必要的文件。

5. 验证归档文件

创建后：

1. 列出归档内容 — 确认没有意外文件
2. 解压到临时目录
3. 尝试在解压后的目录中编译（如果有 TeX 工具链）
4. 报告归档文件大小（压缩后和未压缩）
5. 将文件列表与纳入/排除清单进行比对

6. 报告

# 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

归档格式说明

• 优先使用 .tar.gz 而不是 .zip（学术 TeX 工作流中的标准格式）
• arXiv 接受 .tar（gzip 压缩）和 .zip
• 不要嵌套归档文件（不要在 .zip 内放入 .tar.gz）
• 文件应位于根目录或逻辑子目录中 — 除非项目使用子目录进行组织，否则不要添加外层包装目录

核心原则

• 明确纳入，而非一概排除。 根据所需内容构建文件列表，而不是从所有文件中减去不需要的文件。这样可以发现那些不应提交、但未列入排除清单的文件。
• 打包后进行验证。 提交的是归档文件。应测试归档文件，而不是源目录。
• 保留目录结构。 如果项目使用子目录存放图表或章节，请保留该结构。TeX 路径依赖于此。
• 不要包含敏感文件。 打包前检查 .env、凭据、个人笔记和审稿人通信。