linux生成man手册方法

安装转换工具

yum install pandoc -y

man手册组成部分

• Name： 命令的名称和功能描述
• Synopsis：程序的使用方法的概要，一般包含展示可接收的命令行参数
• Description：命令或功能的描述
• Options：命令行参数可选项，及其作用
• Examples：一些常用的例子
• Exit Values: 可能的返回值，和对应的含义
• Bugs： 已知的bug列表和规避方法。一般提供对问题跟踪的链接
• Author：作者
• Copyright：版权信息

linux手册组成部分

1. Executable programs：或者shell命令
2. System calls：内核提供的功能
3. Library calls：程序包中的功能
4. Special files。
5. File formats and conventions：如"/etc/passwd"
6. Games
7. Miscellaneous:宏包和约定。如groff
8. System administration commands:为root用户保留
9. Kernel routines: 非一般默认安装的

编写man手册对应的markdown内容组成部分

Front Matter

% MS(1) ms 1.0.3

% kwing

% 2022.1.10

第一行：包含命令的名称

第二行：作者

第三行：日期

Name

# NAME ms - look up manufacturer from mac address

Synopsis

# SYNOPSIS
**ms** [*OPTION*]\
**ms** *PATTERN*

Description

# DESCRIPTION
**ms** identifilest the hardware manufacturer from a Media Access Control address(MAC address).

Options

# OPTIONS
**-h**, **--help**
: Displays a friendly help message
**-v**, **--version**
: Displays the software version

Examples

# EXAMPLES
**ms** 
: Displays usage and version information, then exists. 
**ms 3C:BB:FE** 
: Displays the manufacturer for MAC address 3C:BB:FE

Exit Values

# EXIT VALUES
**0** 
: Success 
**1** 
: Invalid option

Bugs

# BUGS
I should think so.

Copyright

# COPYRIGHT
Copyright © 2022 Kwing. License GPLv3+:GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

全部内容

% MS(1) ms 1.0.3
% kwing
% 2022.1.10

# NAME
ms - look up manufacturer from mac address

# SYNOPSIS
**ms** [*OPTION*]\
**ms** *PATTERN*

# DESCRIPTION
**ms** identifilest the hardware manufacturer from a Media Access Control address(MAC address).

# OPTIONS
**-h**, **--help**
: Displays a friendly help message
**-v**, **--version**
: Displays the software version

# EXAMPLES
**ms**
: Displays usage and version information, then exists.
**ms 3C:BB:FE**
: Displays the manufacturer for MAC address 3C:BB:FE

# BUGS
I should think so.

# COPYRIGHT
Copyright © 2022 Kwing. License GPLv3+:GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.

等效的工作方式

touch ms.1.md

vim ms.1.md，将上面的内容粘贴到ms.1.md中，保存并退出

预览效果：

pandoc ms.1.md -s -t man | /usr/bin/man -l -

创建自己的man手册

生成ms.1手册

pandoc ms.1.md -s -t man -o ms.1

查看man搜索的路径

manpath

输出结果包含

• /usr/share/man：手册的标准库位置
• /usr/local/share/man：“/usr/share/man”的软连接
• /usr/local/*/man：本地的man手册位置，我们也将部署的手册存放在该路径下

生成手册

mkdir -p /usr/local/man/man1
# 将本地制作好的man手册放到指定目录
cp ms.1 /usr/local/man/man1
# man调用时希望手册被压缩过
gzip /usr/local/man/man1/ms.1
# 重新生成man数据库数据（会重新识别新添加的手册路径）
mandb

 参考文档

How to Create a man Page on Linux (howtogeek.com)