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).

Macro	Purpose	Example
.Nm	Program name	.Nm grep
.Nd	One-line description	.Nd file pattern searcher
.Fl	Flag	.Fl v renders as -v
.Ar	Argument	.Ar file renders as file
.Op	Optional arg	.Op Fl v renders as [-v]
.Cm	Subcommand	.Cm install
.Pa	Path	.Pa ~/.config/tool
.Ev	Environment variable	.Ev HOME
.Xr	Cross-reference	.Xr grep 1
.Bl / .It / .El	Tagged list	Options list
.Bd / .Ed	Display block	Code examples
.Ex -std	Standard exit status	Exit status section

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)

Section	Content	Example
1	User commands	ls(1), grep(1)
2	System calls	open(2), read(2)
3	Library functions	printf(3)
5	File formats	passwd(5), crontab(5)
7	Overviews, conventions	mdoc(7), regex(7)
8	System administration	mount(8)

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.