How to make a man page for my shell script?

Question

How do I create a man page for my shell script?
I couldn't find a beginner approach on how to make man pages on Google.

What is the easiest way to make my own Man page, based of a template, and install it with my script?

Answer 1

I'd recommend you to use Grapse, an online man page editor, since you can see the results in real-time. I believe it's really useful for beginners.

Answer 2

What about using pandoc. You can write document in markdown (or even html, latex) and can covert to html, pdf, word,man pages, epub, .... This way you can write documentation in one format and convert/distribute in any format you like

Answer 3

C1sc0 there is an error in your answer.

to make your own man page, follow the steps below:

1- become superuser:

$ sudo -i 

2- go to this directory:

$ cd /usr/bin
$ nano your_function

3- copy paste this template of man (maual) page and then personalize it depending on your project:

./" Manpage for your_fonction
.TH man 1 "10 September 2017" "1.0" "your_fonction man page"
.SH NAME
your_fonction - do.... 
.SH SYNOPSIS
your_fonction [optionnal argument] [optionnal argument]
.SH DESCRIPTION
your_fonction is a function which .....
.SH OPTIONS
your_fonction does not take any options
.SH BUGS
No known bugs.
.SH AUTHOR
written by your_name (your_website or your_github or whatever)
.SH REPORTING BUGS
you_github_repository/isssues for example

4- you have to choose in which directory man your file has to be, look at :

$ cd/usr/share/man/ && ls

you see man1, man2,.... These are the categories:

(man1) 1 - Commands available to users
(man2) 2 - Unix and C system calls
(man3) 3 - C library routines for C programs
(man4) 4 - Special file names
(man5) 5 - File formats and conventions for files used by Unix
(man6) 6 - Games
(man7) 7 - Word processing packages
(man8) 8 - System administration commands and procedures

here for the example the destination will be man1, so:

5- back to usr/bin

$ cd /usr/bin

6- make a copy with the good suffix:

$ cp your_function your_function.1

7- gzip your_function.1

$ gzip your_function.1

8- send it to the good directory, here for the example man1:

$ cp your_function.1.gz /usr/share/man/man1/

that's done, you can test your beautiful man page !

 $ man your_function

Answer 4

Sample man page, from the link:

.\" Manpage for nuseradd.
.\" Contact vivek@nixcraft.net.in to correct errors or typos.
.TH man 8 "06 May 2010" "1.0" "nuseradd man page"
.SH NAME
nuseradd \- create a new LDAP user
.SH SYNOPSIS
nuseradd [USERNAME]
.SH DESCRIPTION
nuseradd is high level shell program for adding users to LDAP server.  On Debian, administrators should usually use nuseradd.debian(8) instead.
.SH OPTIONS
The nuseradd does not take any options. However, you can supply username.
.SH SEE ALSO
useradd(8), passwd(5), nuseradd.debian(8)
.SH BUGS
No known bugs.
.SH AUTHOR
Vivek Gite (vivek@nixcraft.net.in)

Installing with your script:

install -g 0 -o 0 -m 0644 nuseradd.1 /usr/local/man/man8/
gzip /usr/local/man/man8/nuseradd.1

Installing it manually:

cp nuseradd /usr/local/man/man8/nuseradd.1
gzip /usr/local/man/man8/nuseradd.1

Answer 5

help2man uses the output of your script when given the --help flag to generate a decent manpage.

This requires very little effort and provides a reasonable output. As it relies on the output of your script when passed --help and --version it also forces you to write a decent --help :-)