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.
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:
| Macro | Meaning |
|---|---|
| .B | Bold |
| .BI | Bold, italic alternating |
| .BR | Bold, roman alternating |
| .EE | Example end |
| .EX | Example end |
| .I | Italic |
| .IB | Italic, bold alternating |
| .IP | Indented paragraph |
| .IR | Italic, roman alternating |
| .LP | (Left) paragraph |
| .ME | Mail-to end |
| .MT | Mail-to start |
| .OP | (Command-line) option |
| .P | Paragraph |
| .PP | Paragraph |
| .RB | Roman, bold alternating |
| .RE | Relative-indent end |
| .RI | Roman, italic alternating |
| .RS | Relative-indent start |
| .SB | Small bold |
| .SH | Section heading |
| .SM | Small |
| .SS | Subsection heading |
| .SY | Synopsis start |
| .TH | Title heading |
| .TP | Tagged paragraph |
| .TQ | Tagged paragraph continuation |
| .UE | URL end |
| .UR | URL start |
| .YS | Synopsis 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
.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.
