6 steps to create linux man page
Normally we always use linux man page for any help or to get all the details with all options. why don’t we create our customized linux man page. To create linux man page we can use nroff utility. Normally man files are created using troff. troff is a bit difficult to use. So that’s Here we will learn to create linux MAN page for our custom binaries/programs using the command line tool nroff which is very easy to learn.
Follow below steps to create linux man page:
Step 1: Write a manual page in using vi. Use Man format only. for example I have written sample man page using vi for sample command “mycommand”.
[root@rhel1 ~]# cat mycommand MYCOMMAND(1) User Commands NAME mycommand - this is test command for man page creation SYNOPSIS mycommand [OPTION]. [FILE]. DESCRIPTION List information about the FILEs (the current directory by default). Sort entries alphabetically if none of -cftuvSUX nor --sort. Mandatory arguments to long options are mandatory for short options too. -a, --all do not ignore entries starting with . -A, --almost-all do not list implied . and .. --author with -l, print the author of each file [root@rhel1 ~]#
Step 2: use below command to create linux man page.
[root@rhel1 ~]# nroff -e -man mycommand|more -s MYCOMMAND(1) User Commands NAME mycommand - this is test command for man page creation SYNOPSIS mycommand [OPTION]. [FILE]. DESCRIPTION List information about the FILEs (the current directory by default). Sort entries alphabetically if none of -cftuvSUX nor --sort. Mandatory arguments to long options are mandatory for short options too. -a, --all do not ignore entries starting with . -A, --almost-all do not list implied . and .. --author with -l, print the author of each file --More--
Following are options details:
-e --> Produce equally-spaced words in adjusted lines, using full terminal resolution. -man --> Macro name
Step 3: Rename it and give extension 1 to 8, any no. & then compress it with gzip.
[root@rhel1 ~]# mv mycommand mycommand.3 [root@rhel1 ~]# gzip mycommand.3 [root@rhel1 ~]# ll -rw-r--r--. 1 root root 367 Dec 31 17:00 mycommand.3.gz drwxr-xr-x. 2 root root 4096 Dec 31 16:36 p [root@rhel1 ~]#
Step 4: Create man/man3 directory under your home directory.
Note: Here I renamed the file with the extension. 3, that’s why I created the man3 directory.
Step 5: Move gzip file in $HOME/man/man3 and use updatedb.
[root@rhel1 ~]# mv mycommand.3.gz $HOME/man/man3 [root@rhel1 ~]# updatedb
Please note that , The system stores its man pages at /usr/share/man/ directory , however to give example with all the details I have used non default location.
Step 6: Then use below command to open the created MAN page.
[root@rhel1 ~]# man -M $HOME/man mycommand MYCOMMAND(1) User Commands NAME mycommand - this is test command for man page creation SYNOPSIS mycommand [OPTION]. [FILE]. DESCRIPTION List information about the FILEs (the current directory by default). Sort entries alphabetically if none of -cftuvSUX nor --sort. Mandatory arguments to long options are mandatory for short options too. -a, --all do not ignore entries starting with . -A, --almost-all do not list implied . and .. --author with -l, print the author of each file (END)
Here -M is used to give path of man files. If you don’t want to use -M option every time you can add below “MANPATH” entry in “/etc/man.config” file as below, since /etc/man.config stores the details about linux man page.
[root@rhel1 ~]# cat /etc/man.config |grep MANPATH # when MANPATH contains an empty substring), to find out where the cat # MANPATH manpath_element [corresponding_catdir] # MANPATH_MAP path_element manpath_element # Every automatically generated MANPATH includes these fields MANPATH /usr/man MANPATH /usr/share/man MANPATH /usr/local/man MANPATH /usr/local/share/man MANPATH /usr/X11R6/man MANPATH /root/man
In above section we have added /root/man or $HOME/man MANPATH entry. Now you can use man command without any option as below.
[root@rhel1 ~]# man mycommand MYCOMMAND(1) User Commands NAME mycommand - this is test command for man page creation SYNOPSIS mycommand [OPTION]. [FILE]. DESCRIPTION List information about the FILEs (the current directory by default). Sort entries alphabetically if none of -cftuvSUX nor --sort. Mandatory arguments to long options are mandatory for short options too. -a, --all do not ignore entries starting with . -A, --almost-all do not list implied . and .. --author with -l, print the author of each file (END)
How to make a man page for my shell script?
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?
Yes, but is says that I need a specially formatted file and it doesn’t tell me how to format it :/ . Also I don’t understand how to install it.
5 Answers 5
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.
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
C1sc0 there is an error in your answer.
to make your own man page, follow the steps below:
$ 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 :
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:
6- make a copy with the good suffix:
$ cp your_function 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 !