NAME

mansplain — generate mdoc(7) man pages from source material

DESCRIPTION

mansplain generates mdoc(7) man pages from source material. It provides two paths to man page authorship:

generate: Uses an LLM to produce man pages from --help output, README files, config files, or any text. Targets any OpenAI-compatible API.
convert: Compiles ronn-format(7) markdown to mdoc deterministically. No LLM, no network, no API key.

mansplain also ships as an agent skill that teaches coding agents (Claude Code, Cursor, Copilot, Gemini CLI, and others) how to write man pages using their own model and project context.

For the command reference, see mansplain(1).

INSTALL

curl | sh

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

Installs the binary to ~/.local/bin and man pages to ~/.local/share/man. Override with INSTALL_DIR and MAN_BASE environment variables.

Go

go install github.com/mwunsch/mansplain@latest

Binary only. Run ‘mansplain install man/mansplain.1’ afterward to get the man page.

GitHub Releases

Download prebuilt binaries from GitHub Releases. Each archive includes the binary, man pages, and agent skill.

GETTING STARTED

Configure the LLM connection:

mansplain configure

This prompts for a base URL, API key, and model, then saves to ~/.config/mansplain/config.toml. Defaults to the OpenAI API. For local models, point it at LM Studio or Ollama:

base_url = "http://localhost:1234/v1"
api_key = "lm-studio"

Generate a man page:

mansplain generate --name jq -o jq.1
mansplain generate README.md --name mytool
curl --help | mansplain generate - --name curl

Generate man pages for config files (section 5) or overviews (section 7):

mansplain generate config.toml --name myapp.conf --section 5
mansplain generate ARCHITECTURE.md --name myframework --section 7

Preview and validate:

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

CONVERT

The convert command compiles ronn-format(7) markdown to mdoc. No LLM required.

mansplain convert man/tool.1.md -o man/tool.1
mansplain convert man/tool.1.md | mansplain lint -

Ronn-format is markdown with conventions for man pages: a title line (‘name(1) -- description’), definition lists for options, and angle brackets for arguments.

This is useful for ongoing maintenance. Write the source in markdown, keep it in version control, and compile to mdoc in your build step.

AGENT SKILL

Install the skill into any project:

npx skills add mwunsch/mansplain

The skill works without the mansplain binary. The agent uses its own model and full project context to write the man page directly, producing better results than a standalone LLM call with limited context.

The skill teaches the agent to:

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

WORKING WITH MAN PAGES

Once you have a man page, the standard toolchain takes over:

mansplain install file: Copy a man page to ~/.local/share/man so man(1) can find it. No sudo required.
mandoc(1) -Tutf8 file | less(1): Preview a man page in the terminal.
apropos(1) keyword: Search installed man pages by keyword. This is what makes installed man pages discoverable.
whatis(1) command: Show the one-line description of a command.
manpath(1): Show where man(1) looks for pages.

Note: ‘man -l file.1’ works on Linux but not macOS. Use ‘mandoc -Tutf8 file.1 | less’ instead.