Writing Man Pages

The built-in help message system is useful for quick reference, but is too terse for thoroughly documenting command line applications. For this, I recommend that you write a man page and ship it alongside every application that you create.

I recommend that you watch the presentation "Man, ‘splained: 40 Plus Years of Man Page History", by Breanne Boland. It goes into the reasons and best-practices of writing man pages. You can also read the manual page's manual page (run man man) if you like.

Template

Instead of writing a manual page by hand in troff, you can use the following markdown template and run it through pandoc.

---
title: MY-APP
section: 1
header: User Manual
footer: App 1.0.0
date: June 2022
---

# NAME

my-app \- do something

# SYNOPSIS

**`my-app [--option1 <name>] [--option2 <name>] <arg>`**

# DESCRIPTION

An application which does something useful with `<arg>`.

The description can go into details of what the application does, and can span
multiple paragraphs.

## A subsection

You can use subsections in the description to go into finer details.

# OPTIONS

**`--option1=<string>`**
: An arbitrary string which sets some specific configuration value. Defaults to
some sane value.

**`--option2=<string>`**
: Another arbitrary string which sets some specific configuration value.
Defaults to some sane value.

# EXIT STATUS

Return 0 on success, 1 on error.

# ENVIRONMENT

`MY_APP_VARIABLE`
: Environment variable used by this application.

# FILES

`/etc/my-app.conf`
: This is an important file. Configuration values are read from this file if
they are not specified on the command-line

# EXAMPLES

**An example tells a thousand words.**

```
you can use markdown code sections
```

**Please include at least one example!**

# SEE ALSO

[A reference](https://pandoc.org/)

To preview the page after editing, run:

pandoc -s -f markdown-smart manpage.md -t man | man -l -

(the -smart is necessary here, to avoid converting '--' into an em-dash)

And, once ready, save it as a man page:

pandoc -s -f markdown-smart manpage.md -t man > manpage.1

then finally ship it alongside your application.

Since it's written in markdown, you can also convert to html and make it available online.