Mansplain

mansplain

Generate mdoc(7) man pages from source material.

When to use this skill

• User asks to create, update, or add a man page
• A project has a CLI binary but no man page
• A project has a config file that should be documented (section 5)
• A project needs conceptual overview documentation (section 7)
• User wants to add man pages as part of project documentation
• As part of scaffolding a new CLI project, alongside README.md

How to generate a man page

1. Gather context from the project: README, --help output, source code, config file schemas, CLI argument definitions, error messages, tests — anything that helps write an accurate and complete man page. Do not limit yourself to README and --help; use your full knowledge of the project.
2. Determine the appropriate section: 1 for commands, 5 for config files, 7 for overviews.
3. Write an mdoc(7) source file following the format below.
4. Validate with mandoc -Tlint <file> if mandoc is available.
5. If mansplain CLI is installed, use mansplain lint <file> for additional checks.
6. Place the file at man/<name>.<section> in the project.

Alternative: maintain man pages in markdown

If the mansplain CLI is installed, man page source can be maintained in ronn-format(7) markdown and converted deterministically (no LLM required):

1. Write a man/toolname.1.md file in ronn-format markdown
2. Run mansplain convert man/toolname.1.md -o man/toolname.1
3. Validate with mansplain lint man/toolname.1

This is useful for ongoing human maintenance — the markdown source is readable and editable without mdoc knowledge. For initial generation, writing mdoc directly (as this skill teaches) is preferred.

Output a complete mdoc(7) man page. No markdown, no explanation, just the mdoc source.

mdoc(7) format

Every man page starts with this header:

.Dd $Mdocdate$
.Dt TOOLNAME 1
.Os

• .Dd is the document date. Use $Mdocdate$ or Month Day, Year.
• .Dt is the document title in UPPERCASE and the section number.
• .Os takes no argument (the formatter fills it in).

Required sections (in order)

.Sh NAME
.Nm toolname
.Nd one-line description of what the tool does

.Sh SYNOPSIS
.Nm
.Op Fl v
.Op Fl o Ar file
.Ar pattern

.Sh DESCRIPTION
The
.Nm
utility does the thing.

Full example

This is a complete, valid man page. Match this structure exactly.

.Dd $Mdocdate$
.Dt GREP 1
.Os
.Sh NAME
.Nm grep
.Nd file pattern searcher
.Sh SYNOPSIS
.Nm
.Op Fl c
.Op Fl i
.Op Fl n
.Op Fl r
.Op Fl v
.Op Fl A Ar num
.Op Fl B Ar num
.Op Fl e Ar pattern
.Op Ar pattern
.Op Ar
.Sh DESCRIPTION
The
.Nm
utility searches input files for lines matching a pattern.
By default, matching lines are printed to standard output.
.Sh OPTIONS
.Bl -tag -width indent
.It Fl c , Fl -count
Print only a count of matching lines.
.It Fl i , Fl -ignore-case
Case insensitive matching.
.It Fl n , Fl -line-number
Prefix each line with its line number.
.It Fl r , Fl -recursive
Recursively search directories.
.It Fl v , Fl -invert-match
Select non-matching lines.
.It Fl A Ar num
Print
.Ar num
lines after each match.
.It Fl B Ar num
Print
.Ar num
lines before each match.
.It Fl e Ar pattern
Specify a search pattern.
.El
.Sh ENVIRONMENT
.Bl -tag -width indent
.It Ev GREP_OPTIONS
Default options prepended to the argument list.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Search for a pattern in a file:
.Bd -literal -offset indent
grep 'error' /var/log/syslog
.Ed
.Pp
Recursive case-insensitive search:
.Bd -literal -offset indent
grep -ri 'todo' src/
.Ed
.Sh SEE ALSO
.Xr awk 1 ,
.Xr sed 1

Semantic macros

Use these mdoc macros. Never use raw troff (.ft, .sp, .in, .br, .nf, .fi).

Section ordering

NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXIT STATUS, ENVIRONMENT, FILES, EXAMPLES, SEE ALSO, STANDARDS, HISTORY, AUTHORS, BUGS.

Include at least: NAME, SYNOPSIS, DESCRIPTION, OPTIONS (if flags exist), EXAMPLES.

Style rules

• Be terse. Man pages are reference material, not tutorials.
• Every flag from the source material gets an .It entry in OPTIONS.
• EXAMPLES should have 2-3 realistic invocations a user would actually run.
• Use .Bd -literal -offset indent / .Ed for code blocks in examples.
• For tools with subcommands, use .Cm for subcommand names.
• .Dt title must be UPPERCASE.

Section-specific guidance

For section 1 (user commands): follow the structure and example above exactly.

For section 5 (file formats and config files):

• SYNOPSIS shows the file path, not a command: .Sh SYNOPSIS / .Pa /etc/tool.conf
• DESCRIPTION documents the file's purpose, syntax, and fields
• No OPTIONS section. Document fields/directives as a tagged list in DESCRIPTION.
• Include EXAMPLES showing realistic file contents in .Bd -literal blocks.

For section 7 (overviews, conventions, miscellaneous):

• No SYNOPSIS section.
• DESCRIPTION is the main content — longer prose explaining concepts.
• Use .Ss subsection headings to organize topics within DESCRIPTION.
• No OPTIONS section.
• Include at minimum: NAME, DESCRIPTION, SEE ALSO.

Man page sections (not to be confused with mdoc sections above)

Most CLI tools go in section 1. Use section 7 for conceptual overviews of libraries or frameworks. Use section 5 for config file format documentation.

Validation

After generating, validate the output:

# If mandoc is available (macOS, OpenBSD, many Linux):
mandoc -Tlint page.1

# If mansplain is installed:
mansplain lint page.1

# Preview the rendered output:
mandoc -Tutf8 page.1 | less

File placement

Place man pages in the project's man/ directory:

project/
  man/
    toolname.1

The section number is encoded in the file extension (.1 for commands, .5 for file formats, .7 for overviews). Package managers and build tools route files to the correct man<section>/ directory at install time.