{"id":47703459,"url":"https://github.com/mwunsch/mansplain","last_synced_at":"2026-04-02T17:46:59.249Z","repository":{"id":347700966,"uuid":"1193833069","full_name":"mwunsch/mansplain","owner":"mwunsch","description":"Generate mdoc(7) man pages from source material","archived":false,"fork":false,"pushed_at":"2026-03-29T03:49:09.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T06:29:00.774Z","etag":null,"topics":["agent-skill","cli","documentation","golang","llm","man-pages","mandoc","manpages","mdoc","ronn"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mwunsch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-27T16:17:04.000Z","updated_at":"2026-03-29T03:54:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mwunsch/mansplain","commit_stats":null,"previous_names":["mwunsch/mansplain"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mwunsch/mansplain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mwunsch%2Fmansplain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mwunsch%2Fmansplain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mwunsch%2Fmansplain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mwunsch%2Fmansplain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mwunsch","download_url":"https://codeload.github.com/mwunsch/mansplain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mwunsch%2Fmansplain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","cli","documentation","golang","llm","man-pages","mandoc","manpages","mdoc","ronn"],"created_at":"2026-04-02T17:46:58.099Z","updated_at":"2026-04-02T17:46:59.243Z","avatar_url":"https://github.com/mwunsch.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mansplain\n\nGenerate mdoc(7) man pages from source material.\n\n```\nmansplain generate --name rg -o rg.1\nmansplain convert man/tool.1.md -o man/tool.1\n```\n\nMost CLI tools ship without man pages. The format is old, the toolchain\nis hostile, and writing mdoc by hand is nobody's idea of a good time.\nmansplain fixes that. Generate man pages with an LLM, or convert\n[ronn-format](https://github.com/rtomayko/ronn) markdown to\n[mdoc(7)](https://man.openbsd.org/mdoc.7) deterministically without one.\n\nIt also ships as an agent skill, so any AI coding agent can generate\nman pages as part of its normal workflow. The goal is to make man pages\na standard part of the CLI project scaffold, like README.md already is.\n\nThe `generate` command targets any OpenAI-compatible API: OpenAI, local\nmodels via LM Studio or Ollama, or any other compatible endpoint.\n\n## Install\n\n```\ncurl -fsSL https://raw.githubusercontent.com/mwunsch/mansplain/main/install.sh | sh\n```\n\nThis downloads the latest release, installs the binary to `~/.local/bin`\nand man pages to `~/.local/share/man/`. Override with `INSTALL_DIR`\nand `MAN_BASE` environment variables.\n\nOr with Go (binary only, no man page):\n\n```\ngo install github.com/mwunsch/mansplain@latest\n```\n\nOr download a tarball directly from\n[GitHub Releases](https://github.com/mwunsch/mansplain/releases).\n\n## Quick start\n\nConfigure your LLM connection:\n\n```\nmansplain configure\n```\n\nThis prompts for a base URL, API key, and model, then saves to\n`~/.config/mansplain/config.toml`. Defaults to OpenAI's API.\n\nFor local models, point it at LM Studio or Ollama:\n\n```toml\n# ~/.config/mansplain/config.toml\nbase_url = \"http://localhost:1234/v1\"\napi_key = \"lm-studio\"\n```\n\nGenerate a man page:\n\n```\n# From a tool name (runs --help automatically)\nmansplain generate --name jq -o jq.1\n\n# From a README\nmansplain generate README.md --name mytool\n\n# From --help output\nmansplain generate --from-help \"rg --help\" -o rg.1\n\n# From stdin\ncurl --help | mansplain generate - --name curl\n\n# Document a config file (section 5)\nmansplain generate config.toml --name myapp.conf --section 5\n\n# Write an overview from architecture docs (section 7)\nmansplain generate ARCHITECTURE.md --name myframework --section 7\n```\n\nPreview and validate:\n\n```\nmansplain generate --name jq | mandoc -Tutf8 | less\nmansplain generate --name jq | mansplain lint -\n```\n\n## Agent skill\n\nThis is the highest-leverage feature. mansplain ships as an\n[Agent Skill](https://agentskills.io) that teaches any compatible coding\nagent how to write proper mdoc(7) man pages. It works across Claude Code,\nCursor, Copilot, Gemini CLI, and\n[30+ others](https://agentskills.io).\n\nThe skill works without the mansplain binary. The agent uses its own model\nand the full project context to generate the man page directly. This\ntypically produces better results than a standalone LLM call because the\nagent has access to the source code, not just the help text.\n\nInstall the skill:\n\n```\nnpx skills add mwunsch/mansplain\n```\n\nOr copy `SKILL.md` from this repo into your project's skills directory.\n\nThe skill teaches the agent to:\n1. Gather context from the project: source code, README, help output, config files\n2. Write a complete mdoc(7) man page following mdoc conventions\n3. Validate with `mandoc -Tlint` (or `mansplain lint` if installed)\n4. Place the file at `man/\u003cname\u003e.\u003csection\u003e` (section 1 for commands, 5 for config files, 7 for overviews)\n\nThe goal: every CLI project built with an AI coding agent should get a\nman page as part of the standard scaffold. If agents know how to write\nREADME.md, they should know how to write a man page too.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `generate` | Generate a man page from source material via LLM |\n| `convert` | Convert ronn-format markdown to mdoc (no LLM required) |\n| `lint` | Validate man page structure and completeness |\n| `install` | Install a man page so man(1) can find it |\n| `configure` | Interactively set up the LLM connection |\n\nUse `generate --dry-run` to see the assembled prompt without calling the API.\n\n## Configuration\n\nmansplain reads configuration from (highest priority first):\n\n1. CLI flags (`--base-url`, `--api-key`, `--model`)\n2. Environment variables (`MANSPLAIN_BASE_URL`, `MANSPLAIN_API_KEY`, `MANSPLAIN_MODEL`)\n3. Config file (`~/.config/mansplain/config.toml`)\n4. `OPENAI_API_KEY` environment variable\n5. Default: `https://api.openai.com/v1`\n\n## Working with man pages\n\nOnce you have a man page, here's how to use the existing toolchain:\n\n```\n# Preview a local man page file\nmandoc -Tutf8 rg.1 | less\n\n# Install it so man(1) can find it\nmansplain install rg.1\n\n# Now it works like any other man page\nman rg\n\n# Search installed man pages by keyword\napropos \"regular expression\"\n\n# One-line description of a tool\nwhatis grep\n\n# See where man looks for pages\nmanpath\n```\n\n`mansplain install` copies man pages to `~/.local/share/man/`, which is\nin the default search path on both macOS and Linux. No sudo required.\n\nIf you need to add a custom directory to the man search path, set `MANPATH`:\n\n```\nexport MANPATH=\"$HOME/myproject/man:$(manpath)\"\n```\n\nNote: `man -l file.1` works on Linux for previewing local files but not\non macOS. Use `mandoc -Tutf8 file.1 | less` instead, which works everywhere.\n\n## Output format\n\nmansplain produces [mdoc(7)](https://man.openbsd.org/mdoc.7) source, the\nsemantic macro set used by OpenBSD's mandoc and widely supported by groff.\nmdoc uses semantic markup (`.Nm` for name, `.Fl` for flag, `.Ar` for argument)\nrather than raw formatting directives, making the output portable and\nmachine-parseable.\n\n## Model quality\n\nOutput quality depends on the model. Larger models (GPT-4o, Claude) produce\nclean, valid mdoc with correct section structure and flag documentation.\nSmaller local models (3-7B parameters) get the general structure right but\nmay have syntax errors or hallucinate flags. The system prompt uses a\nfew-shot example to maximize compatibility with smaller models.\n\n## Convert\n\nThe `convert` command compiles [ronn-format](https://github.com/rtomayko/ronn)\nmarkdown to mdoc. No LLM, no API key, no network. The conversion is\ndeterministic.\n\n```\n# Convert a markdown man page to mdoc\nmansplain convert man/tool.1.md -o man/tool.1\n\n# Pipe through lint to validate\nmansplain convert man/tool.1.md | mansplain lint -\n\n# Read from stdin\ncat doc.md | mansplain convert - -o page.1\n```\n\nRonn-format is markdown with three conventions for man pages: a title\nline (`name(1) -- description`), definition lists for options\n(`* `--flag`:` followed by description), and `\u003cangle brackets\u003e` for\narguments. See `man ronn-format` for the full format reference\n(included with mansplain).\n\nThis is useful for ongoing maintenance. Write the man page source in\nmarkdown, keep it in version control, and compile to mdoc in your\nbuild step. Inspired by [ronn](https://github.com/rtomayko/ronn) by\nRyan Tomayko.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmwunsch%2Fmansplain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmwunsch%2Fmansplain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmwunsch%2Fmansplain/lists"}