People don’t write manpages anymore. This is partially because of Google being a more common first line for help, but it’s also because people are scared to write them.
Most of the tools for generating manpages are complex, or generate weird output. They’re actually easy to write by hand. This is a crash course in (badly) writing simple manpages by hand.
Manpages have a “section” number. Command-line tools are section 1, file formats are section 5. You’ll probably only write section 1 and 5 manpages.
Manpages are written in a language called
groff or something similar.
It’s a little like Markdown, in that text can be wrapped however you want, but a blank line makes a new paragraph. Unlike Markdown:
You can write comments using
roff has “macros”. These are lines that start with a
. and then a couple of letters. The only ones you need to
worry about are
.THstarts a manpage (Top/Title Header probably).
.SHstarts a section (Section Header).
.BRis just HTML’s
The basic structure is:
(For section 5 manpages, only 1 and 2 apply. These are more free-form.)
The first line is just
.TH, your tool name in all-caps,
and the manpage section. For example:
.TH SECRET\-SENDER 1 \" or .TH EJSON 5
.SH NAME, then another line: your tool name
and a very brief description. It should fit on one line:
.SH NAME \-sender \- send passwords over slacksecret
Look at other manpages for reference on how the general use of bold
and underline goes, and use
If you have multiple different invocation forms, you can separate them
with a line containing
\fBfind\fR \fIpath\fR [\fIexpression\fR] .BR \fBfind\fR [\fB\-H\fR] \fIpath\fR
This renders looking like:
find path [expression]
find [-H] path
Just write text here. You often use this space to document all the
different command line flags you support, which you can do a lot like in
None of what’s described here is a very good way to write
manpages, but it gets the job done. If you want to do something fancier,
there’s a lot of reference material at
.TH SECRET\-SENDER 1 .SH NAME \-sender \- send passwords and tokens manually over insecure channels secret.SH SYNOPSIS \fBsecret\-sender\fR send .BR \fBsecret\-sender\fR receive .SH DESCRIPTION \fBsecret\-sender\fR requires two users to run the program at the same time in cooperation, and paste messages at each other as a communication medium. These messages are not secret, so can be pasted on (e.g.) Slack. \fBsecret\-sender\fR uses NaCl Box cryptograpy, or Under the hood, curve25519xsalsa20poly1305. The receiver generates an ephemeral keypair and sends the public portion to the sender, who encrypts the secret to that key, before sending the ciphertext to the receiver. The receiver then recovers the plaintext and terminates, discarding the private key. Neither subcommand takes any arguments, but both ask for user input. Scripting\fBejson\fR directly. this is discouraged: Use .SH SEND \fBsecret\-sender Invoked when a user wants to send a secret to another user, \fR first asks for the public key generated by the user running send\fBreceive\fR, then prints the encrypted secret to send to the receiver. .SH RECEIVE \fBsecret\-sender Invoked when a user wants to receive a secret from a sender, \fR prints a public key to send to the sender, then waits for the receive returned ciphertext from the sender, which it decrypts immediately beforeexiting.