linux中的手册页模板。创建手册页。实例手册页。创建用于自定义脚本的手册页，以检查手册脚本。示例手册页模板。如何在Linux中编写手册页。手册页示例。手册页模板。手册页编辑器。 Linux中的man命令。有关如何编写手册页以及如何使用示例创建手册页的教程。 groff man命令。

在组织中，我们可能已经编写了一个新工具，还需要使用该工具来创建手册页或者使用任何手册页模板编写手册页。

在手册页中，我们可以找到有关相应工具的所有详细信息。 man是系统的手动寻呼机。给man的每个页面参数通常是程序，实用程序或者函数的名称。

如何自己编写Linux手册页？

在哪里查找？

作为最终用户，我们使用man来访问相应工具的手册页，但是我们大多数人都不知道手册页的位置。现在，所有系统工具的手册页的理想位置和默认位置均位于

/usr/share/man/man

我用过的大多数都可以在下面找到

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

但是，如果我们打算创建手册页，则应将文件保留在

/usr/local/man

要获取位置的完整列表，我们可以检查/etc/man_db.conf。以下是一小段代码，有关完整列表，请检查原始的man_db.conf文件。

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

如何创建手册页？

要创建手册页(从头开始假设)，可以从在/usr/local/man/man1下创建一个新文件开始。

为了本文的目的，我将为虚拟工具(test_script)创建手册页。如果我尝试访问test_script的手册页

# man test_script
No manual entry for test_script

由于我们尚未为此工具创建一个，因此会出现此错误。要创建手册页，让我们创建一个空文件。

# touch test_script.1

现在，我们应该可以访问test_script的手册页。由于当前文本文件为空，因此我们看到空白输出。

支持的宏

下面是受支持的宏的列表：

手册页模板和示例

groff(GNU Troff)软件是一个排版程序包，可读取与格式命令混合的纯文本并生成格式输出，例如手册页

我们可以使用任何编辑器来创建手册页，例如vim或者nano。为了演示本文，我将在/usr/local/man/man1下创建手册页。

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

在下面，我创建了手册页模板。其中我尝试使用各种宏，这些宏可以在各种选项之间进行选择，以创建自己的手册页

# 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 theitroad. All rights reserved
https://www.theitroad.com
.SH CREDITS
.PP
This man page is created only for demonstration purpose by hynman Prasad <[email protected]>
.SH
.PP
theitroad test_script(1)

Linux中的Man命令

上面使用模板，我们编写了测试脚本的手册页示例。要访问我们使用手册页模板创建的手册页，可以在终端上使用man scriptname。

# 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 theitroad. All rights reserved https://www.theitroad.com
CREDITS
       This man page is created only for demonstration purpose by hynman Prasad <[email protected]>
       theitroad test_script(1)
                                                                                                             test_script(1)()

如何安装？

要安装手册页，我们可以将文件" test_script.1"保留在"/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

我们也可以将此文件归档为gzip格式

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

接下来，将创建一个带有gzip扩展名的新档案

# 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

如何创建用户特定的手册页？

要创建用户特定的手册页，我们可以选择一个单独的文件夹，该文件夹只能由相应的用户访问。例如，我有一个用户" hynman"，我会将手册页文件放在该用户的主目录下。

所以我将在/home/hynman下创建一个新结构。

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

接下来移动test_script的手册页，将其放在/usr/local/man/man1下。我们正在移动文件，因为我们只希望" hynman"用户访问此手册页。

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

将用户切换到" hynman"

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

接下来，我们必须使用MANPATH为hynman用户定义手册页位置的路径。检查是否存在任何为MANPATH定义的路径。

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

由于没有定义路径，我们将为MANPATH添加新路径。

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

如果用户已经在使用MANPATHvar，则可以使用以下命令添加新路径

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

因此，这会将新的手册页路径添加到MANPATH变量中

接下来验证可变内容

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

因此，这应该可以解决问题，现在我们应该能够访问" test_script"的手册页

[hynman@rhel-7 ~]$man test_script

但是，如果我们尝试使用root用户访问同一文件

# man test_script
No manual entry for test_script

如果我们希望允许root用户访问" test_script"的手册页，则将"/home/hynman/man/man1"路径添加到root用户的shell中，以获取" MANPATH"变量

重要的提示：

此更改仅在当前会话中实现。为了使更改持久化，我们可以使用.bash_profile来定义各个用户的变量。