texplain 0.1.0

Strip LaTeX to plain text with 1:1 line mapping, so prose linters report the source line.
Documentation
  • Coverage
  • 100%
    5 out of 5 items documented1 out of 2 items with examples
  • Size
  • Source code size: 84.1 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 200.0 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 6s Average build duration of successful builds.
  • all releases: 6s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • stano45/texplain
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • stano45

texplain

CI crates.io docs.rs License: MIT

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

cargo install texplain

Or build from source:

cargo build --release

Usage

texplain paper.tex > paper.txt

Reads a .tex file, writes stripped plain text to stdout.

As a library:

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:

\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:

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/ 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.

cd examples/vale
vale sync
./vale-tex.sh sample.tex

See examples/vale/README.md for details.

Real-world 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 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.

Development

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.