NAME

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

SYNOPSIS

DESCRIPTION

mansplain generates mdoc(7) man pages from source material. The generate command uses an OpenAI-compatible LLM to produce man pages from --help output, README files, config files, or any text passed as input. The convert command deterministically compiles ronn-format(7) markdown to mdoc without an LLM.

mansplain also ships as an agent skill compatible with Claude Code, Cursor, Copilot, Gemini CLI, and other coding agents. The skill teaches agents to write man pages directly using their own model and project context, without requiring the mansplain binary. Install the skill with:

COMMANDS

generate [file | -]

Generate a man page from source material via LLM. Source material can be a file given as a positional argument, ‘-’ for standard input, --from-help to run a command and capture its output, or --name to automatically run name --help. Multiple sources can be combined. Use --section to generate man pages for config file formats (section 5) or conceptual overviews (section 7).

lint file | -

Validate an mdoc(7) file for structural problems. Runs mandoc(1) -Tlint if available, checks for required sections (NAME, SYNOPSIS, DESCRIPTION), and warns about missing recommended sections (OPTIONS, EXAMPLES, EXIT STATUS, SEE ALSO).

convert file | -

Convert a ronn-format(7) markdown file to mdoc(7) source. No LLM required. The conversion is deterministic. See ronn-format(7) for the input format.

install file

Copy a man page to ~/.local/share/man/ so that man(1) can find it. The section number is inferred from the file extension.

configure

Interactively set up the LLM connection. Prompts for base URL, API key, and model. Saves to ~/.config/mansplain/config.toml.

OPTIONS

Global options:

--base-url url

OpenAI-compatible API base URL.

--api-key key

API key for authentication.

--model name

LLM model to use.

-v, --version

Print version and exit.

Options for generate:

--from-help command

Run command and capture its output as source material.

--name name

Tool name for the man page. If no source material is provided, runs name --help automatically. Inferred from source content if not given.

--section num

Man page section number. Section 1 for commands (default), 5 for config file formats, 7 for conceptual overviews. Affects the structure the LLM is prompted to produce.

-o, --output file

Write output to file instead of standard output.

--dry-run

Print the assembled LLM prompt instead of calling the API. Does not require an API key.

ENVIRONMENT

MANSPLAIN_API_KEY

API key for authentication. Overrides the config file.

MANSPLAIN_BASE_URL

API base URL. Overrides the config file.

MANSPLAIN_MODEL

Model name. Overrides the config file.

OPENAI_API_KEY

Fallback API key if MANSPLAIN_API_KEY is not set.

XDG_CONFIG_HOME

Override the base configuration directory. Defaults to ~/.config.

FILES

~/.config/mansplain/config.toml

Configuration file. Contains base_url, api_key, and model fields in TOML format.

~/.local/share/man/

Local man page installation directory used by install. In the default manpath(1) on macOS and Linux.

EXIT STATUS

The mansplain utility exits 0 on success, and >0 if an error occurs.

The lint command exits 0 if the file passes all checks, or 1 if errors are found.

EXAMPLES

Generate a man page for ripgrep:

mansplain generate --name rg -o rg.1

Generate from a README and preview:

mansplain generate README.md --name mytool | mandoc -Tutf8 | less

Pipe help output from another tool:

curl --help | mansplain generate - --name curl -o curl.1

Document a config file (section 5):

mansplain generate config.toml --name myapp.conf --section 5

Write a conceptual overview from architecture docs (section 7):

mansplain generate ARCHITECTURE.md --name myframework --section 7

Convert a ronn-format markdown file to mdoc:

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

Generate and validate in one pipeline:

mansplain generate --name jq | mansplain lint -

See the prompt that would be sent to the LLM:

mansplain generate --dry-run --name rg

Install a man page locally:

mansplain install rg.1
man rg

SEE ALSO

apropos(1), groff(1), man(1), mandoc(1), manpath(1), whatis(1), mdoc(7), ronn-format(7)