如何在 mac os x 上安装自定义手册页
How to install custom man (manual) pages on mac os x
我正在尝试在 Mac OS X 10.9.5 上安装 bash 脚本的手册页。我尝试遵循的过程总结如下：man page tutorial。我还在下面总结了我尝试过的步骤：
cp custom_command.1 /usr/local/man/man1/custom_command.1
gzip /usr/local/man/man1/custom_command.1
尝试 man custom_command 时，我收到输出 No manual entry for custom_command。我也尝试了man page tutorial中提到的其他安装方法。
有趣的是，上面的步骤适用于 emacs 控制台，即当我输入 man custom_command 时，我确实得到了正确的手册。但是，该命令无法被自动完成识别，并且在我能够阅读手册之前收到以下警告：WARNING: terminal is not fully functional.
任何关于如何解决上述问题（即系统终端和 emacs 控制台）的建议都将不胜感激。
备注1
作为参考，我尝试安装的 man 脚本取自 tutorial，并在下面重述以供参考：
.\" Manpage for nuseradd.
.\" Contact vivek@nixcraft.net.in to correct errors or typos.
.TH man 8 "06 May 2010" "1.0" "nuseradd man page"
.SH NAME
nuseradd \- create a new LDAP user
.SH SYNOPSIS
nuseradd [USERNAME]
.SH DESCRIPTION
nuseradd is high level shell program for adding users to LDAP server. On Debian, administrators should usually use nuseradd.debian(8) instead.
.SH OPTIONS
The nuseradd does not take any options. However, you can supply username.
.SH SEE ALSO
useradd(8), passwd(5), nuseradd.debian(8)
.SH BUGS
No known bugs.
.SH AUTHOR
Vivek Gite (vivek@nixcraft.net.in)
OS X 用户命令手册页通常创建于：
/usr/local/share/man/man1
如果您更喜欢在不同的目录中创建手册页，请编辑：
/private/etc/man.conf
然后将新路径添加到MANPATH_MAP，例如：
MANPATH_MAP /usr/local/bin /usr/local/man
让 man 搜索具有默认回退的非默认路径 (/usr/local/share/man):
MANPATH /usr/local/man
MANPATH /usr/local/share/man
MANPATH_MAP /usr/local/bin /usr/local/share/man
首先，您可能需要检查您尝试安装的手册页是否格式正确，是否可以通过 man 命令打开。为此，将 man 文件的路径传递给 man 命令。它必须包含斜杠才能被识别为路径，例如：
man /usr/local/man/man1/custom_command.1
然后你应该确保你安装手册页的路径在man命令的搜索列表中。为了找到手册页，它的路径必须是：
- 使用
man 命令的 -M 选项指定
- 在环境变量中设置
MANPATH
- 在其配置文件中列出（
/private/etc/man.conf on OS X）在 MANPATH 语句下或 MANPATH_MAP 语句下（仅适用于 [=21 中的位置） =] 环境变量)
- 位于相对于二进制文件安装位置的位置，即：如果二进制文件安装在
path/bin 中，则在 path/man、path/cat 和 [=25] 中搜索手册页=], path/bin/cat
- 在
/private/etc/manpaths.d/ 目录中添加的文件中列出
手册页文件的名称必须与带有可选节号的命令名称相同。它可能被 gzip 压缩。
查看人们将在哪里搜索您的 custom_command 手册页 运行
man -d custom_command
我已经通过 brew 安装了软件包，但是 man 命令显示空白，因为我已经将 brew 安装到另一个目录。
为了解决这个问题，仍然链接包（将内容链接到几个目录），然后我可以添加到我的 .bash_profile 中的 MANPATH，就像这样...
MANPATH="/Users/me/Developer/share/man:$MANPATH"
Mac 中的手册页OS X
Mac 中的 man 命令OS X 使用复杂的方法查找手册页文件，基于调用选项和环境变量、/private/etc/man.conf 配置文件和一些内置的惯例和启发式。
在 Mac 中OS X 你有一个命令：
/usr/bin/manpath
列出了您当前用于搜索手册页的所有位置。
只需键入
即可调用它
manpath
在终端中。
但是它不会将此添加到您的 $MANPATH shell 变量中。
但是您仍然可以使用 man 命令访问联机帮助页。
manpath 中包含的内容在
中定义
/private/etc/man.conf
不建议在不添加以下输出的情况下导出名为 MANPATH 的环境变量：
`manpath`
加入列表。
因此，如果您想将 $MANPATH 导出到您的 shell 环境，请按以下方式操作：
export MANPATH="`manpath`:/path/to/man/pages/to/include"
这样您将获得由 OS 定义的联机帮助页的完整列表以及您自己添加的任何路径。
有关详细信息，请打开终端并检查：
man manpath
和 man.conf 文件：
more /private/etc/man.conf
通常，在特殊位置包含手册页的更好选择是创建一个指向包含 /usr/local/share/man 中手册页的目录的符号链接，该目录默认由 "man ecosystem" 索引。
除了 中指出的所有条目外，还有 /etc/manpaths，用于包含通过 Homebrew 安装的手册页非常方便。
例如下面是我的/etc/manpaths的内容：
/usr/local/opt/coreutils/libexec/gnuman
/usr/local/opt/findutils/libexec/gnuman
/usr/local/opt/gawk/libexec/gnuman
/usr/local/opt/gnu-sed/share/man
/usr/local/opt/readline/share/man
/usr/local/share/man
/usr/share/man
同时确保在 /etc/profile 中，MANPATH 在加载 path_helper 之前定义：
export MANPATH= # hack: path_helper doesn't setup MANPATH without this
eval `/usr/libexec/path_helper -s`
顺便说一句，在 macOS 中，默认的分页器 /usr/bin/less 有点旧，甚至不支持正则表达式中的单词边界 \b，因此您可能需要设置 MANPAGER 在 ~/.bashrc（或您喜欢的地方）：
export MANPAGER=/usr/local/bin/less
虽然现有答案确实提供了一些 hints/options 可以帮助解决 OP 的问题，但它们实际上并没有回答标题中的问题。
的确，为了让 man 程序打开手册页，它应该知道在哪里寻找它。这是一个显而易见的声明，但没有多大帮助。问题是你是否应该使用一些“标准”位置（如果是这样，那些“标准”查找路径是什么，它们在哪里定义），或者你应该将手册页与你的程序一起放置，并以某种方式指向 man 程序到您的自定义位置？
OP 似乎已尝试将手册页放在他认为是“标准”位置的地方 (/usr/local/man)，但 man 并没有意识到这一点。
如果使用 /usr/local/share/man/man1/custom_command.1 而不是 /usr/local/man/man1/custom_command.1，它应该会起作用。你怎么会知道这个？答案在/etc/man.conf:
#
# Every automatically generated MANPATH includes these fields
#
MANPATH /usr/share/man
MANPATH /usr/local/share/man
MANPATH /usr/X11/man
MANPATH /Library/Apple/usr/share/man
/etc/man.conf 用于配置默认的 manpath（提供的示例来自 macOS Big Sur 中的默认 man.conf）。话虽如此，我认为依赖 man.conf 默认配置并简单地将自定义 program/script 的手册页复制到这些目录之一是正确的做法。
原因是默认的manpath是根据man.conf配置的 只有如果$MANPATH环境变量没有设置或者是空的。如果 $MANPATH 环境变量 set/not 为空，则 /etc/man.conf 中的路径不用于查找手册页。
默认情况下，未设置$MANPATH。但是，如果您的 program/script + 手册页将分发给其他用户，您无法确定它是否设置在那里。
那么，什么是可靠的解决方案？在我看来，将手册页与脚本一起发送，并使用 path_helper（man path_helper 获取更多信息）将 man 指向自定义手册路径是获得 third-party 程序。
来自 program/script 作者，唯一需要做的就是将包含程序手册页路径的文件放入 /etc/manpaths.d 目录中。 path_helper 应该做剩下的事情。
似乎 path_helper 是专门为这种用例设计的，并且它被 third-party 程序使用（我是在安装 Wireshark 并试图使其手册页可被发现时了解到它的） , 但有一个警告：
path_helper 不会让 man 知道你的自定义 manpath，如果之前没有设置 $MANPATH 环境变量（而且我们知道，它不是默认设置的） .来自 path_helper 手册页：
(The MANPATH environment variable will not be modified unless it is already set in the environment.)
这就是为什么您实际上想要设置 $MANPATH 以允许 path_helper 之后使用自定义 manpath 来扩充它的原因。
在我的例子中，我将 export MANPATH（只是为了设置它，没有任何值）添加到 /etc/zshenv（我使用的是 macOS Big Sur，zsh 是默认值 shell)，并且 path_helper 成功添加了来自 /etc/manpaths.d 个文件的所有自定义 manpath。
我正在尝试在 Mac OS X 10.9.5 上安装 bash 脚本的手册页。我尝试遵循的过程总结如下：man page tutorial。我还在下面总结了我尝试过的步骤：
cp custom_command.1 /usr/local/man/man1/custom_command.1
gzip /usr/local/man/man1/custom_command.1
尝试 man custom_command 时，我收到输出 No manual entry for custom_command。我也尝试了man page tutorial中提到的其他安装方法。
有趣的是，上面的步骤适用于 emacs 控制台，即当我输入 man custom_command 时，我确实得到了正确的手册。但是，该命令无法被自动完成识别，并且在我能够阅读手册之前收到以下警告：WARNING: terminal is not fully functional.
任何关于如何解决上述问题（即系统终端和 emacs 控制台）的建议都将不胜感激。
备注1
作为参考，我尝试安装的 man 脚本取自 tutorial，并在下面重述以供参考：
.\" Manpage for nuseradd.
.\" Contact vivek@nixcraft.net.in to correct errors or typos.
.TH man 8 "06 May 2010" "1.0" "nuseradd man page"
.SH NAME
nuseradd \- create a new LDAP user
.SH SYNOPSIS
nuseradd [USERNAME]
.SH DESCRIPTION
nuseradd is high level shell program for adding users to LDAP server. On Debian, administrators should usually use nuseradd.debian(8) instead.
.SH OPTIONS
The nuseradd does not take any options. However, you can supply username.
.SH SEE ALSO
useradd(8), passwd(5), nuseradd.debian(8)
.SH BUGS
No known bugs.
.SH AUTHOR
Vivek Gite (vivek@nixcraft.net.in)
OS X 用户命令手册页通常创建于：
/usr/local/share/man/man1
如果您更喜欢在不同的目录中创建手册页，请编辑：
/private/etc/man.conf
然后将新路径添加到MANPATH_MAP，例如：
MANPATH_MAP /usr/local/bin /usr/local/man
让 man 搜索具有默认回退的非默认路径 (/usr/local/share/man):
MANPATH /usr/local/man
MANPATH /usr/local/share/man
MANPATH_MAP /usr/local/bin /usr/local/share/man
首先，您可能需要检查您尝试安装的手册页是否格式正确，是否可以通过 man 命令打开。为此，将 man 文件的路径传递给 man 命令。它必须包含斜杠才能被识别为路径，例如：
man /usr/local/man/man1/custom_command.1
然后你应该确保你安装手册页的路径在man命令的搜索列表中。为了找到手册页，它的路径必须是：
- 使用
man命令的-M选项指定 - 在环境变量中设置
MANPATH - 在其配置文件中列出（
/private/etc/man.confon OS X）在MANPATH语句下或MANPATH_MAP语句下（仅适用于 [=21 中的位置） =] 环境变量) - 位于相对于二进制文件安装位置的位置，即：如果二进制文件安装在
path/bin中，则在path/man、path/cat和 [=25] 中搜索手册页=],path/bin/cat - 在
/private/etc/manpaths.d/目录中添加的文件中列出
手册页文件的名称必须与带有可选节号的命令名称相同。它可能被 gzip 压缩。
查看人们将在哪里搜索您的 custom_command 手册页 运行
man -d custom_command
我已经通过 brew 安装了软件包，但是 man 命令显示空白，因为我已经将 brew 安装到另一个目录。 为了解决这个问题，仍然链接包（将内容链接到几个目录），然后我可以添加到我的 .bash_profile 中的 MANPATH，就像这样...
MANPATH="/Users/me/Developer/share/man:$MANPATH"
Mac 中的手册页OS X
Mac 中的 man 命令OS X 使用复杂的方法查找手册页文件，基于调用选项和环境变量、/private/etc/man.conf 配置文件和一些内置的惯例和启发式。
在 Mac 中OS X 你有一个命令：
/usr/bin/manpath
列出了您当前用于搜索手册页的所有位置。 只需键入
即可调用它manpath
在终端中。
但是它不会将此添加到您的 $MANPATH shell 变量中。
但是您仍然可以使用 man 命令访问联机帮助页。 manpath 中包含的内容在
中定义/private/etc/man.conf
不建议在不添加以下输出的情况下导出名为 MANPATH 的环境变量：
`manpath`
加入列表。
因此，如果您想将 $MANPATH 导出到您的 shell 环境，请按以下方式操作：
export MANPATH="`manpath`:/path/to/man/pages/to/include"
这样您将获得由 OS 定义的联机帮助页的完整列表以及您自己添加的任何路径。
有关详细信息，请打开终端并检查：
man manpath
和 man.conf 文件：
more /private/etc/man.conf
通常，在特殊位置包含手册页的更好选择是创建一个指向包含 /usr/local/share/man 中手册页的目录的符号链接，该目录默认由 "man ecosystem" 索引。
除了 /etc/manpaths，用于包含通过 Homebrew 安装的手册页非常方便。
例如下面是我的/etc/manpaths的内容：
/usr/local/opt/coreutils/libexec/gnuman
/usr/local/opt/findutils/libexec/gnuman
/usr/local/opt/gawk/libexec/gnuman
/usr/local/opt/gnu-sed/share/man
/usr/local/opt/readline/share/man
/usr/local/share/man
/usr/share/man
同时确保在 /etc/profile 中，MANPATH 在加载 path_helper 之前定义：
export MANPATH= # hack: path_helper doesn't setup MANPATH without this
eval `/usr/libexec/path_helper -s`
顺便说一句，在 macOS 中，默认的分页器 /usr/bin/less 有点旧，甚至不支持正则表达式中的单词边界 \b，因此您可能需要设置 MANPAGER 在 ~/.bashrc（或您喜欢的地方）：
export MANPAGER=/usr/local/bin/less
虽然现有答案确实提供了一些 hints/options 可以帮助解决 OP 的问题，但它们实际上并没有回答标题中的问题。
的确，为了让 man 程序打开手册页，它应该知道在哪里寻找它。这是一个显而易见的声明，但没有多大帮助。问题是你是否应该使用一些“标准”位置（如果是这样，那些“标准”查找路径是什么，它们在哪里定义），或者你应该将手册页与你的程序一起放置，并以某种方式指向 man 程序到您的自定义位置？
OP 似乎已尝试将手册页放在他认为是“标准”位置的地方 (/usr/local/man)，但 man 并没有意识到这一点。
如果使用 /usr/local/share/man/man1/custom_command.1 而不是 /usr/local/man/man1/custom_command.1，它应该会起作用。你怎么会知道这个？答案在/etc/man.conf:
#
# Every automatically generated MANPATH includes these fields
#
MANPATH /usr/share/man
MANPATH /usr/local/share/man
MANPATH /usr/X11/man
MANPATH /Library/Apple/usr/share/man
/etc/man.conf 用于配置默认的 manpath（提供的示例来自 macOS Big Sur 中的默认 man.conf）。话虽如此，我认为依赖 man.conf 默认配置并简单地将自定义 program/script 的手册页复制到这些目录之一是正确的做法。
原因是默认的manpath是根据man.conf配置的 只有如果$MANPATH环境变量没有设置或者是空的。如果 $MANPATH 环境变量 set/not 为空，则 /etc/man.conf 中的路径不用于查找手册页。
默认情况下，未设置$MANPATH。但是，如果您的 program/script + 手册页将分发给其他用户，您无法确定它是否设置在那里。
那么，什么是可靠的解决方案？在我看来，将手册页与脚本一起发送，并使用 path_helper（man path_helper 获取更多信息）将 man 指向自定义手册路径是获得 third-party 程序。
来自 program/script 作者，唯一需要做的就是将包含程序手册页路径的文件放入 /etc/manpaths.d 目录中。 path_helper 应该做剩下的事情。
似乎 path_helper 是专门为这种用例设计的，并且它被 third-party 程序使用（我是在安装 Wireshark 并试图使其手册页可被发现时了解到它的） , 但有一个警告：
path_helper 不会让 man 知道你的自定义 manpath，如果之前没有设置 $MANPATH 环境变量（而且我们知道，它不是默认设置的） .来自 path_helper 手册页：
(The MANPATH environment variable will not be modified unless it is already set in the environment.)
这就是为什么您实际上想要设置 $MANPATH 以允许 path_helper 之后使用自定义 manpath 来扩充它的原因。
在我的例子中，我将 export MANPATH（只是为了设置它，没有任何值）添加到 /etc/zshenv（我使用的是 macOS Big Sur，zsh 是默认值 shell)，并且 path_helper 成功添加了来自 /etc/manpaths.d 个文件的所有自定义 manpath。