man帮助页

man命令

sections

man页, 查看系统的各项数据的手册, man可以指定不同的section来浏览不同的手册, 例如man 1 ls. 对于大部分的命令, 查看man帮助文档不需要额外指定sections, 但是对于有歧义的关键字比如macOS上的open, 其本身有open命令帮助页和open函数帮助页, 此时就需要手动指定sections. section可选项字段含义如下:

1, commands 普通命令
2, system calls 系统调用,例如open,write函数
3, library calls 库函数,例如fprintf函数
4, special file 特殊文件,例如/dev下的各种设备文件
5, file formats and convertions 文件的格式,例如passwd就会指定该文件中各项含义
6, games 游戏预留
7, macro packages and convertions 附件中的某些变量
8, system management commands 系统管理用的命令

优先级

对于单一的命令或者其他标识符,直接输入man cmd即可得到想要的手册,但是对于某些标识符,其可能存在多个sections中,这时的输出就是按照上面的优先级来输出的,当然,你也可以指定section, 例如:

1 2	man open # 输出open命令 man 2 open # 输出open函数的手册

格式

命令格式: man [-a..] [section] [-M path] title, 其中options格式:

-h             显示帮助信息
-f             类似whatis,在数据库中查找以关键字开头的帮助信息
-k             模糊查找 whatis数据库
-w             查看命令文档所在path,默认搜索到第一个文件就退出

man手册

布局

标准化布局: 跨手册页标的标准化布局,所有命令都拥有的布局

NAME: 命令的名称和用途,简单精炼的阐述最初的命令用途
SYNOPSIS: 命令语法,概要和摘要,更加详细的命令用法需要见2.2中各个字段说明
DESCRIPTION: 命令或者函数功能的文本描述,主要介绍该命令的功能和用途
EXAMPLES: 常用例子
SEE ALSO: 相关命令以及函数列表

非标准化布局, 不同的命令可能不同

EXPRESSION: 命令的表达式
OPTIONS: 命令行参数
PRIMARIES: 基元,最初的

其他冗余布局

EXIT STATUS: 返回状态含义
FILES: 叙述对象相关的文件链接
BUGS: 已知的该命令 BUGS 信息
HISTORY: 历史
COPYRIGHT: 版权

SYNOPSIS and OPTIONS

OPTIONS是SYNOPSIS 的组成部分,在很多简单命令中, OPTIONS 常常合并到 DESCRIPTION 中. OPTIONS是除EXPRESSION 之外的命令说明语法,一般在 EXPRESSION 表达式之前.

OPTIONS格式-类别如下:

长选项: –help
短选项: -h, 多个短选项可以组合,长选项则不能组合使用

OPTIONS格式-特殊符号

方括号:                 可选值
黑体或者粗体:           命令名/标志, 必须原样输入
斜体字或者下划线:       使用适当值代替
省略号:                 参数可以多次重复
选项和参数组合:         两者必须都存在
|:                      多选一

SYNOPSIS and EXPRESSION

EXPRESSION是 SYNOPSIS 的组成部分,一般命令的最后,在大部分命令中都是没有的. EXPRESSION 常常用于查找或者提取命令(例如 find 命令),EXPRESSION 充当最后的要实现的操作集合.

TESTS或PRIMARIES: 判断提取的对象,并返回 true/false 值,例如 find 中的-empty用于判断文件是否为空.
Actions: 命令操作并产生side effects,返回 true/false 值,注意只有返回真的items才会被提取过滤并打印出来,所以所有命令中的 EXPRESSION 说明中的 TRUE/FALSE 非常重要.
Operators: 拼接多个expression

中文

平常开发工作中需要经常使用到man help帮助页, 但是一般系统中帮助页都是英文, 虽然使用原有英文帮助文档更加直接, 但是为了工作效率考虑, 简易将帮忙文档更改为中文翻译man页.
毕竟, 程序员学习英文的地方多的去了, 至少平常开发的时候不用逐句的去看命令使用说明, 中文输出下一目三四行快速浏览不好吗. 那么, 应该怎么安装中文帮助页呢? linux发行版安装manpages-zh非常简单:

# ubuntu
sudo apt update
sudo apt install manpages-zh

# 2. red hat/centos
yum update
yum install man-pages-zh-CN

对于ubuntu和centos只要安装中文帮助页成功就可以使用中文帮助文档, 感谢相关翻译人员. 但是对于mac, 则需要从源码进行编译安装, 其步骤如下:

安装依赖环境并配置中文支持

# 1. 依赖
brew install automake
brew install opencc

# 2. 下载manpages源码(简易使用github加速插件下载)
git clone https://github.com/man-pages-zh/manpages-zh.git
cd manpages-zh

# 3. 编译安装
autoreconf --install --force
./configure
make
make install

解决中文乱码

1	brew install groff

更改配置:

# 增加MANPATH 配置
MANPATH /usr/local/share/man/zh_CN

# 更改NROFF或者增加新的一行
NROFF       preconv -e UTF8 | /usr/local/bin/nroff -Tutf8 -mandoc -c