libmandoc-rs

libmandoc-rs is a safe Rust ownership boundary around a pinned copy of libmandoc. It parses man(7), mdoc(7), roff, tbl(7), and eqn(7) input into an owned syntax tree, so callers never need to depend on libmandoc's private C structures or parser lifetime.

What this crate provides

• A fully owned AST with source locations, macro roles, display/list metadata, table cells, equations, and validated same-document tags.
• A Parser API whose caller-controlled .so policy defaults to denial.
• Structured non-fatal diagnostics and typed source/decompression failures.
• Top-level uncompressed, gzip, and zstd manual sources.
• Serialized calls to the upstream parser, whose relevant state is global.

The crate is a parser layer only. It intentionally does not render terminal output or HTML, locate system manual pages, interpret application-specific section models, or run a pager.

Basic use

use libmandoc_rs::{IncludePolicy, ParseOptions, Parser};

let parser = Parser::new(ParseOptions {
    includes: IncludePolicy::SourceTree,
    ..ParseOptions::default()
});
let report = parser.parse_file("/usr/share/man/man1/ls.1.gz")?;

println!("{:?}", report.document.macro_set);
for diagnostic in report.diagnostics {
    eprintln!("{:?}: {}", diagnostic.level, diagnostic.message);
}
# Ok::<(), Box<dyn std::error::Error>>(())

Use Parser::parse_bytes if the caller owns the source transport. Its auto mode recognizes plain input and zstd frames; callers must decompress gzip byte streams first or pass the file to parse_file. Unix can retain libmandoc's native gzip file transport; Windows decodes gzip files in Rust before entering the memory parser.

IncludePolicy::Deny is the default. SourceTree preserves ordinary manual tree lookup. Root(path) resolves .so requests against a directory the caller explicitly chooses, rejects absolute and lexical parent paths, and does not fall back to the process working directory. Native C file inclusion is currently Unix-only; Windows callers resolve sources first and use the default memory-only policy.

Enable the optional serde feature to derive Serialize and Deserialize for the public AST, parser configuration, reports, diagnostics, and errors.

Compression contract

For parse_file, Compression::Auto recognizes plain, gzip, and zstd manual files. Windows decodes gzip and zstd in Rust; Unix retains libmandoc's native gzip reader and uses Rust for zstd. For parse_bytes, auto mode recognizes plain input and zstd, not gzip. Compression::Plain bypasses top-level compression detection, and Compression::Zstd requires a zstd frame. Other compression formats are not part of this crate's supported contract.

Vendor layering

The vendored C source at vendor/mandoc-1.14.6/ is derived from the official 1.14.6 snapshot with optional local patches applied. End-user cargo build compiles this tree directly; no network access or external patch tool is required.

Maintainers use scripts/sync-vendor to regenerate the vendor tree:

./scripts/sync-vendor           # download, patch, replace vendor/
./scripts/sync-vendor --verify  # CI: check vendor/ matches upstream + patches

The script reads upstream/SOURCE for tarball URL and SHA-256, and patches/series for the ordered patch list. --verify reconstructs the tree from those inputs and compares it with vendor/. Semantic parser changes need a Rust test with the smallest useful roff input; portability patches are covered by the relevant target CI jobs.

Build requirements and supported targets

The source package vendors libmandoc 1.14.6 and compiles it with the cc crate, so a working C compiler is required. Checked configurations are supplied for Linux/glibc, macOS, and Windows/MSVC. Unix native-file parsing also requires zlib development headers; Windows builds the memory-only parser and does not link system zlib. Linux/musl remains rejected until it has a checked configuration.

Licensing

The Rust wrapper and C shim are licensed under Apache-2.0. The vendored libmandoc source is primarily ISC licensed and includes selected compatibility files under BSD-2-Clause and BSD-3-Clause terms. The complete license texts and upstream attribution are shipped under LICENSES/ and vendor/mandoc-1.14.6/LICENSE.

This crate is not affiliated with the upstream mandoc project.