# texplain
[](https://github.com/stano45/texplain/actions/workflows/ci.yml)
[](https://crates.io/crates/texplain)
[](https://docs.rs/texplain)
[](LICENSE)
Strips LaTeX down to the prose inside it, keeping every line where it was. Line N of the output is line N of the `.tex`.
Prose linters do not understand LaTeX. Run Vale over a `.tex` file and `\citep{knuth1984}` comes back as a spelling error, a `tabular` row as a sentence fragment, and the sentence inside `\textbf{…}` is not read at all. Stripping the markup first fixes what the linter sees, but it also moves every line, so the positions it reports no longer match the file you have to edit.
texplain strips without moving anything. Markup lines come back empty, prose lines come back as prose:
| Line | `paper.tex` | stripped output |
|-----:|-------------|-----------------|
| 1 | `\section{Results}` | `Results.` |
| 2 | `Latency fell by 40\%, an effect that` | `Latency fell by 40%, an effect that` |
| 3 | `\emph{prior} work~\cite{knuth1984} missed.` | `prior work missed.` |
| 4 | `\begin{equation}` | |
| 5 | ` L = n/r + \delta` | |
| 6 | `\end{equation}` | |
| 7 | `Table~\ref{tab:runs} confirms it.` | `Table confirms it.` |
An alert on line 3 of the stripped text is an alert on line 3 of the source, so editor jumps and CI annotations land on the sentence that needs fixing.
## Install
```bash
cargo install texplain
```
Or build from source:
```bash
cargo build --release
```
## Usage
```bash
texplain paper.tex > paper.txt
```
Reads a `.tex` file, writes stripped plain text to stdout.
As a library:
```rust
let tex = "Prior work~\\cite{smith2020} shows the \\textbf{naive} approach is slow.\n";
assert_eq!(texplain::strip(tex), "Prior work shows the naive approach is slow.\n");
```
The full surface is four functions:
| Function | Use it for |
|----------|------------|
| `strip(&str) -> String` | A whole document. This is the one you want. |
| `strip_reader(impl Read) -> io::Result<String>` | The same, from a file or socket |
| `strip_line(&str) -> Cow<'_, str>` | One line, LaTeX syntax only |
| `is_remnant(&str) -> bool` | Is this line leftover markup rather than prose? |
`strip` is not `strip_line` in a loop. It also tracks state across lines (blanked environments, multi-line `\author`/`\title`) and blanks debris via `is_remnant`. Its output is newline-terminated, so `strip(src).lines().count() == src.lines().count()`.
## What it does
Given this input:
```latex
\section{Introduction}
\label{sec:intro}
Prior work~\cite{smith2020} shows that the na\"ive approach is slow.
% This comment is dropped before linting.
We revisit it here; the results are surprising.
\begin{equation}
L = \frac{n}{r} + \delta
\end{equation}
Equation~\eqref{eq:latency} gives the closed form.
```
you get this, with the blank lines exactly where the markup was:
```text
Introduction.
Prior work shows that the naïve approach is slow.
We revisit it here; the results are surprising.
Equation gives the closed form.
```
Specifically:
- **Commands are unwrapped or dropped.** `\textbf{bold}` keeps its text, while `\cite{…}`, `\ref{…}`, `\label{…}`, `\url{…}`, `\includegraphics{…}`, `\usepackage{…}` and friends are discarded along with their arguments.
- **Headings become sentences.** `\section{Introduction}` becomes `Introduction.` so sentence-scoped rules see a complete sentence rather than a fragment.
- **Non-prose environments are blanked.** `equation`, `align`, `tabular`, `lstlisting`, `verbatim`, `figure`, `table`, `thebibliography` and others emit empty lines. Their `\caption{…}` text is kept, since captions are prose the linter should check.
- **Multi-line metadata is blanked.** `\author{…}` and `\title{…}` blocks are tracked across lines by brace depth.
- **Comments are removed** from the first unescaped `%` to end of line. `\%` is not a comment.
- **Accents are resolved.** `\"a` becomes `ä`, `\'e` becomes `é`.
- **Debris lines are blanked.** Bare dimensions (`3cm`), label keys (`sec:intro`), package names, file paths, and option fragments left over after stripping.
The output contains no backslashes and no braces.
### Limits
texplain is a line-oriented stripper, not a LaTeX parser. It does not expand macros, resolve `\input`/`\include`, or evaluate conditionals. A brace group that spans lines is only tracked for the constructs listed above. This is a deliberate trade: full parsing would cost the 1:1 line mapping that makes the output useful.
## Linting with Vale
[`examples/vale/`](examples/vale) is a complete, working setup: a `.vale.ini` tuned for IEEE/ACM-style academic prose, a set of custom rules, and a `vale-tex.sh` wrapper that strips and lints in one step.
```bash
cd examples/vale
vale sync
./vale-tex.sh sample.tex
```
See [examples/vale/README.md](examples/vale/README.md) for details.
## Real-world samples
[`examples/samples/`](examples/samples) holds author templates from IEEE, Springer, and Elsevier, 1,304 lines of LaTeX written with no thought for this tool, alongside the text texplain produces from each, checked in so the transformation is reviewable.
[`examples/verify.sh`](examples/verify.sh) runs the full pipeline and checks the result: 60 Vale alerts, every one landing on the span Vale reports, and every one flagging text that appears character for character on the same line of the original `.tex`. See [examples/README.md](examples/README.md).
## Development
```bash
just check
```
Runs a release build, `cargo fmt --check`, `cargo clippy -D warnings`, `cargo deny check`, and the test suite.
The lint configuration is strict on purpose. On top of clippy's `all`, `pedantic`, `nursery`, and `cargo` groups, the restriction lints that forbid panicking are denied: `indexing_slicing`, `string_slice`, `panic`, `unwrap_used`, `expect_used`. A linter that crashes on someone's `.tex` file is worse than one that reports nothing, so the scanner routes every byte access through a checked cursor rather than relying on discipline at ~40 call sites. `Cargo.toml` records which lints are deliberately *not* enabled, and why.
## License
MIT. See [LICENSE](LICENSE).