mansplain

Generate mdoc(7) man pages from source material.

mansplain generate --name rg -o rg.1
mansplain convert man/tool.1.md -o man/tool.1

Most CLI tools ship without man pages. The format is old, the toolchain is hostile, and writing mdoc by hand is nobody's idea of a good time. mansplain fixes that. Generate man pages with an LLM, or convert ronn-format markdown to mdoc(7) deterministically without one.

It also ships as an agent skill, so any AI coding agent can generate man pages as part of its normal workflow. The goal is to make man pages a standard part of the CLI project scaffold, like README.md already is.

The generate command targets any OpenAI-compatible API: OpenAI, local models via LM Studio or Ollama, or any other compatible endpoint.

Install

curl -fsSL https://raw.githubusercontent.com/mwunsch/mansplain/main/install.sh | sh

This downloads the latest release, installs the binary to ~/.local/bin and man pages to ~/.local/share/man/. Override with INSTALL_DIR and MAN_BASE environment variables.

Or with Go (binary only, no man page):

go install github.com/mwunsch/mansplain@latest

Or download a tarball directly from GitHub Releases.

Quick start

Configure your LLM connection:

mansplain configure

This prompts for a base URL, API key, and model, then saves to ~/.config/mansplain/config.toml. Defaults to OpenAI's API.

For local models, point it at LM Studio or Ollama:

# ~/.config/mansplain/config.toml
base_url = "http://localhost:1234/v1"
api_key = "lm-studio"

Generate a man page:

# From a tool name (runs --help automatically)
mansplain generate --name jq -o jq.1

# From a README
mansplain generate README.md --name mytool

# From --help output
mansplain generate --from-help "rg --help" -o rg.1

# From stdin
curl --help | mansplain generate - --name curl

# Document a config file (section 5)
mansplain generate config.toml --name myapp.conf --section 5

# Write an overview from architecture docs (section 7)
mansplain generate ARCHITECTURE.md --name myframework --section 7

Preview and validate:

mansplain generate --name jq | mandoc -Tutf8 | less
mansplain generate --name jq | mansplain lint -

Agent skill

This is the highest-leverage feature. mansplain ships as an Agent Skill that teaches any compatible coding agent how to write proper mdoc(7) man pages. It works across Claude Code, Cursor, Copilot, Gemini CLI, and 30+ others.

The skill works without the mansplain binary. The agent uses its own model and the full project context to generate the man page directly. This typically produces better results than a standalone LLM call because the agent has access to the source code, not just the help text.

Install the skill:

npx skills add mwunsch/mansplain

Or copy SKILL.md from this repo into your project's skills directory.

The skill teaches the agent to:

1. Gather context from the project: source code, README, help output, config files
2. Write a complete mdoc(7) man page following mdoc conventions
3. Validate with mandoc -Tlint (or mansplain lint if installed)
4. Place the file at man/<name>.<section> (section 1 for commands, 5 for config files, 7 for overviews)

The goal: every CLI project built with an AI coding agent should get a man page as part of the standard scaffold. If agents know how to write README.md, they should know how to write a man page too.

Commands

Command	Description
generate	Generate a man page from source material via LLM
convert	Convert ronn-format markdown to mdoc (no LLM required)
lint	Validate man page structure and completeness
install	Install a man page so man(1) can find it
configure	Interactively set up the LLM connection

Use generate --dry-run to see the assembled prompt without calling the API.

Configuration

mansplain reads configuration from (highest priority first):

1. CLI flags (--base-url, --api-key, --model)
2. Environment variables (MANSPLAIN_BASE_URL, MANSPLAIN_API_KEY, MANSPLAIN_MODEL)
3. Config file (~/.config/mansplain/config.toml)
4. OPENAI_API_KEY environment variable
5. Default: https://api.openai.com/v1

Working with man pages

Once you have a man page, here's how to use the existing toolchain:

# Preview a local man page file
mandoc -Tutf8 rg.1 | less

# Install it so man(1) can find it
mansplain install rg.1

# Now it works like any other man page
man rg

# Search installed man pages by keyword
apropos "regular expression"

# One-line description of a tool
whatis grep

# See where man looks for pages
manpath

mansplain install copies man pages to ~/.local/share/man/, which is in the default search path on both macOS and Linux. No sudo required.

If you need to add a custom directory to the man search path, set MANPATH:

export MANPATH="$HOME/myproject/man:$(manpath)"

Note: man -l file.1 works on Linux for previewing local files but not on macOS. Use mandoc -Tutf8 file.1 | less instead, which works everywhere.

Output format

mansplain produces mdoc(7) source, the semantic macro set used by OpenBSD's mandoc and widely supported by groff. mdoc uses semantic markup (.Nm for name, .Fl for flag, .Ar for argument) rather than raw formatting directives, making the output portable and machine-parseable.

Model quality

Output quality depends on the model. Larger models (GPT-4o, Claude) produce clean, valid mdoc with correct section structure and flag documentation. Smaller local models (3-7B parameters) get the general structure right but may have syntax errors or hallucinate flags. The system prompt uses a few-shot example to maximize compatibility with smaller models.

Convert

The convert command compiles ronn-format markdown to mdoc. No LLM, no API key, no network. The conversion is deterministic.

# Convert a markdown man page to mdoc
mansplain convert man/tool.1.md -o man/tool.1

# Pipe through lint to validate
mansplain convert man/tool.1.md | mansplain lint -

# Read from stdin
cat doc.md | mansplain convert - -o page.1

Ronn-format is markdown with three conventions for man pages: a title line (name(1) -- description), definition lists for options (* --flag: followed by description), and <angle brackets> for arguments. See man ronn-format for the full format reference (included with mansplain).

This is useful for ongoing maintenance. Write the man page source in markdown, keep it in version control, and compile to mdoc in your build step. Inspired by ronn by Ryan Tomayko.

License

MIT