Create man page in Linux with examples (sample man page template)

man page template in linux. create man page. man page with examples. create man page for custom script to check man script. sample man page template. how to write man page in Linux. Man page example. Man page template. Man Page editor. man command in linux. tutorial on how to write man page and how to create man page with examples. groff man command.

How to create man page in Linux with examples (Sample man page template)

 

It is possible that in your organisation you have written a new tool for which you also need to create man page or write man page using any man page template. As man page are the single place where you can find all the details regarding the respective tool. man is the system's manual pager. Each page argument given to man is normally the name of a program, utility or function.

So in this article I will share the steps to create man page with example in Linux with a sample man page template.

 

Where to find?

As an end user we use man to access the man page of the respective tool but most of us are unaware of the location of the man page. Now the ideal and default location of man pages of all the system tools are available under

/usr/share/man/man

Most which I have used were available under

/usr/share/man/man2
/usr/share/man/man8

But if you plan to create man page, you should keep the file under

/usr/local/man

To get the complete list of locations you can check /etc/man_db.conf. Below is a small snippet, for complete list please check the original man_db.conf file.

MANDATORY_MANPATH           /usr/man
MANDATORY_MANPATH           /usr/share/man
MANDATORY_MANPATH           /usr/local/share/man

 

How to create man page?

To create man page (assuming from scratch), you can start by creating a new file under /usr/local/man/man1.

For the sake of this article I will create man page for a dummy tool (test_script). If I try to access the man page of test_script

# man test_script
No manual entry for test_script

As we have not created one for this tool, we get this error. To create man page let us create an empty file.

# touch test_script.1

Now you should be able to access the man page for test_script. Since currently the text file is empty, we see blank output.

 

Supported Macros

Below are the list of supported Macros:

MacroMeaning
.BBold
.BIBold, italic alternating
.BRBold, roman alternating
.EEExample end
.EXExample end
.IItalic
.IBItalic, bold alternating
.IPIndented paragraph
.IRItalic, roman alternating
.LP(Left) paragraph
.MEMail-to end
.MTMail-to start
.OP(Command-line) option
.PParagraph
.PPParagraph
.RBRoman, bold alternating
.RERelative-indent end
.RIRoman, italic alternating
.RSRelative-indent start
.SBSmall bold
.SHSection heading
.SMSmall
.SSSubsection heading
.SYSynopsis start
.THTitle heading
.TPTagged paragraph
.TQTagged paragraph continuation
.UEURL end
.URURL start
.YSSynopsis end

 

Man Page Template and Example

The groff (GNU Troff) software is a typesetting package which reads plain text mixed with formatting commands and produces formatted output such as man page

You can use any editor to create man page such as vim or nano. To demonstrate this article I will create man page under /usr/local/man/man1.

# touch /usr/local/man/man1/test_script.1

Below I have created a man page template. Here I have tried to use various macros which can help you choose between various options to help you create man page of your own

# cat /usr/local/man/man1/test_script.1
." Process this file with
." groff -man -Tascii test_script.1
."
.TH test_script(1)

.Sh NAME
.B test_script
- user interface to perform some task

.SH SYNOPSIS
.B test_script
.RB {| OBJECT |}
.RB [| OPTIONS |]

.SH DESCRIPTION
.B test_script
Write detailed description of the tool here. This script can perform all these tasks and must be executed as root user. More information on the tasks performed is explained below:

.RS
.nf
- Performs task 1
- Performs task 2
- Performs task 3
- Performs task 4
.RE

This is a test script for man page template. Place brief description here.

.SH OBJECT
.TP
.B -^-a1|-arg1 <arg1_value>
Provide arg1_value. Must be fIintegerfR. Provide more hint for the user related to arg1_value

.TP
.B -^-a2|-arg2 <arg2_value>
Provide arg2_value. Must be fIintegerfR. Provide more hint for the user related to arg2_value

.TP
.B -^-a3|-arg3 "value1,value2,value3,.."

.TP
Different man page examples formats

.PP
.B
Display in normal format with regular TAB using .RS and TAB value of 1.2i

.RS 1.2i
.PP
.I TEAM1
.B -
team1_value1, team1_value2
.PP
.I TEAM2
.B -
team2_value1, team2_value2
.RE

.TP
.B
Display content in Table Format. Floating in Left
.

.RS 1.2i

.TS
tab(@), left, box;
c | c
rB | r.
TEAM@Value
_
TEAM1@team1_value1, team1_value2
TEAM2@team2_value1, team2_value2
TEAM3@team3_value1, team3_value2
TEAM4@team4_value1, team4_value2
.TE
.RE

.TP
.B
Display content in a Tabular format

.RS 1.2i

.TS
tab (@);
l c c.
TEAM@Value@Comment
_
T{
TEAM1
T}@team1_value1, team1_value2@Value for team1@
T{
TEAM2
T}@team2_value1, team2_value2@Value for team2
T{
TEAM3
T}@team3_value1, team3_value2@Value for team3
T{
TEAM4
T}@team4_value1, team4_value2@Value for team4
.TE


.TP
.RE
.PP
Multiple values can be added within inverted commas separated by comma for different teams


.SH OPTIONS
.IP "fB--arg4fP <arg4_value>"
Put description for argument 4 value. The is optional argument.

.IP "fB-h|--helpfP"
Prints help

.SH FILES
.TP
.I
/etc/test_script.conf
.TP
.I
/usr/bin/test_script

.SH EXAMPLES
.TP
.BI test_script --arg1  my_arg1  --arg4  'team1_value1,team2_value1'
.TP
.PP
Run test_script with my_arg1 value for team1 value
.TP
.BI test_script --arg2  my_arg2  --arg4  'team2_value1,team2_value2'
.TP
.PP
Run test_script with my_arg2 value for team2 value


.SH DIAGNOSTICS
.PP
The activity performed using this utility is logged in the file fB/var/log/test_scriptfR


.SH EXIT STATUS
.TP
.B
0
Success

.TP
.B
1
Success but reboot required

.TP
.B
2
Success but no reboot required

.SH SEE ALSO
.BR test_script1 (1),
.BR test_script2 (1),
test_script3 (1)

.SH COPYRIGHT
.PP
Copyright 2019 GoLinuxCloud. All rights reserved
https://www.golinuxcloud.com

.SH CREDITS
.PP
This man page is created only for demonstration purpose by Deepak Prasad <admin@golinuxcloud.com>

.SH
.PP
GoLinuxCloud test_script(1)

 

Man command in Linux

Above using the template we wrote our man page example for test script. To access the man page which we created using our man page template you can use man scriptname from the terminal.

# man test_script
test_script(1)()                                                                                             test_script(1)()

test_script - user interface to perform some task

SYNOPSIS
       test_script {OBJECT} [OPTIONS]

DESCRIPTION
       test_script  Write detailed description of the tool here. This script can perform all these tasks and must be executed
       as root user. More information on the tasks performed is explained below:

              - Performs task 1
              - Performs task 2
              - Performs task 3
              - Performs task 4

       This is a test script for man page template. Place brief description here.

OBJECT
       --a1|-arg1 <arg1_value>
              Provide arg1_value. Must be integer. Provide more hint for the user related to arg1_value

       --a2|-arg2  <arg2_value>
              Provide arg2_value. Must be integer. Provide more hint for the user related to arg2_value

       --a3|-arg3 value1,value2,value3,..

       Different man page examples formats

       Display in normal format with regular TAB using .RS and TAB value of 1.2i

                   TEAM1 - team1_value1, team1_value2

                   TEAM2 - team2_value1, team2_value2

       Display content in Table Format. Floating in Left

                   ┌──────┬────────────────────────────┐
                   │TEAM  │           Value            │
                   ├──────┼────────────────────────────┤
                   │TEAM1 │ team1_value1, team1_value2 │
                   │TEAM2 │ team2_value1, team2_value2 │
                   │TEAM3 │ team3_value1, team3_value2 │
                   │TEAM4 │ team4_value1, team4_value2 │
                   └──────┴────────────────────────────┘

       Display content in a Tabular format

                   TEAM              Value                  Comment
                   ─────────────────────────────────────────────────────

                   TEAM1   team1_value1, team1_value2   Value for team1
                   TEAM2   team2_value1, team2_value2   Value for team2
                   TEAM3   team3_value1, team3_value2   Value for team3
                   TEAM4   team4_value1, team4_value2   Value for team4

              Multiple values can be added within inverted commas separated by comma for different teams

OPTIONS
       --arg4 <arg4_value>
              Put description for argument 4 value. The is optional argument.

       -h|--help
              Prints help

FILES
       /etc/test_script.conf

       /usr/bin/test_script

EXAMPLES
       test_script --arg1 my_arg1 --arg4 'team1_value1,team2_value1'

              Run test_script with my_arg1 value for team1 value

       test_script --arg2 my_arg2 --arg4 'team2_value1,team2_value2'

              Run test_script with my_arg2 value for team2 value

DIAGNOSTICS
       The activity performed using this utility is logged in the file /var/log/test_script

EXIT STATUS
       0      Success

       1      Success but reboot required

       2      Success but no reboot required

SEE ALSO
       test_script1(1), test_script2(1), test_script3 (1)

COPYRIGHT
       Copyright 2019 GoLinuxCloud. All rights reserved https://www.golinuxcloud.com

CREDITS
       This man page is created only for demonstration purpose by Deepak Prasad <admin@golinuxcloud.com>

       GoLinuxCloud test_script(1)
                                                                                                             test_script(1)()

 

How to Install?

To install man page you can leave the file test_script.1 under /usr/local/man/man1/

# ls -l /usr/local/man/man1/test_script.1
-rwxr-x--- 1 root root 2891 Sep  9 14:51 /usr/local/man/man1/test_script.1

You can also archive this file into gzip format

# gzip /usr/local/man/man1/test_script.1

Next a new archive will be created with gzip extension

# ls -l /usr/local/man/man1/test_script.1.gz
-rwxr-x--- 1 root root 1263 Sep  9 14:51 /usr/local/man/man1/test_script.1.gz

 

How to create user specific man page?

To create a user specific man page you can choose a separate folder which is accessible only to the respective user. For example I have a user deepak and I will place the man page file under the home directory of this user.

So I will create a new structure under /home/deepak

[deepak@rhel-7 ~]$ mkdir -p /home/deepak/man/man1

Next move the man page of test_script which we placed under /usr/local/man/man1. We are moving the file as we want only deepak user to access this man page.

[deepak@rhel-7 ~]$ mv /usr/local/man/man1/test_script.1.gz /home/deepak/man/man1

Switch user to deepak

rhel-7:/home/deepak/man/man1 # su - deepak
Last login: Mon Sep  9 15:36:34 IST 2019 on pts/0

Next we must define the path of the man page location for deepak user using MANPATH. Check if there are any existing path defined for MANPATH.

[deepak@rhel-7 ~]$ echo $MANPATH

Since there are no paths defined we will add the new path for MANPATH

[deepak@rhel-7 ~]$ export MANPATH=/home/deepak/man

If the user was already using MANPATH var then you can append the new path using below command

# export MANPATH=$MANPATH:/home/deepak/man

So this will append the new man page path to MANPATH variable

Next verify your variable content

[deepak@rhel-7 ~]$ echo $MANPATH
/home/deepak/man

So this should do the trick and now we should be able to access the man page of test_script

[deepak@rhel-7 ~]$ man test_script

But if you try to access the same using root

# man test_script
No manual entry for test_script

If you wish to allow root user to access man page for test_script then add /home/deepak/man/man1 path to root user's shell for MANPATH variable

IMPORTANT NOTE:

This change is implemented for the current session only. To make the change persistent you can use .bash_profile to define the variable of respective user.

 

Lastly I hope the steps from the article to create man page using man page template with examples on Linux was helpful. So, let me know your suggestions and feedback using the comment section.

 

Leave a Comment

Please use shortcodes <pre class=comments>your code</pre> for syntax highlighting when adding code.