如何在 mac os x 上安装自定义手册（手册）页面

Posted 2023-02-24

【中文标题】如何在 mac os x 上安装自定义手册（手册）页面

【英文标题】：How to install custom man (manual) pages on mac os x

【发布时间】：2015-07-28 06:51:05

【问题描述】：

我正在尝试在 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 [e-mail] 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 ([e-mail])

---

【问题讨论】：

据我所知，没有任何名为“emacs 控制台”的东西，因此措辞不明确，但我想象您指的是M-x shell -只提供一个哑终端，因此“警告：终端功能不全”对于任何想要更多东西的东西（例如，如果man 调用像less 这样的寻呼机）。您可以使用M-x term 在 Emacs 中获得一个功能齐全的终端仿真器，但对于手册页，最好使用M-x man 或M-x woman 而不是运行shell 命令。跨度>

【参考方案1】：

首先，您可能需要检查您尝试安装的手册页是否格式正确，是否可以通过man 命令打开。为此，将 man 文件的路径传递给 man 命令。它必须包含斜杠才能被识别为路径，例如：

man /usr/local/man/man1/custom_command.1

然后你应该确保你安装手册页的路径在man 命令的搜索列表中。为了找到手册页，它的路径必须是：

用-M 选项指定man 命令 设置在环境变量MANPATH 列在其配置文件（OS X 上的/private/etc/man.conf）下MANPATH 语句或MANPATH_MAP 语句下（仅适用于PATH 环境变量中的位置） 位于相对于二进制安装位置的位置，即：如果二进制安装在path/bin 中，则在path/man、path/cat 和path/bin/man、path/bin/cat 中搜索手册页 在/private/etc/manpaths.d/ 目录中添加的文件中列出

手册页文件的名称必须与带有可选节号的命令名称相同。它可能被压缩了。

查看 man 将在哪里搜索您的 custom_command 手册页运行

man -d custom_command

【参考方案2】：

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

【参考方案3】：

我已经通过 brew 安装了软件包，但是 man 命令显示为空白，因为我已将 brew 安装到不同的目录。 为了解决这个问题，仍然链接包（将内容链接到几个目录），然后我可以在我的 .bash_profile 中添加到 MANPATH，就像这样......

MANPATH="/Users/me/Developer/share/man:$MANPATH"

【讨论】：

如果你想为特定的包添加手册页，这是要走的路——在我的例子中是 OpenSSL MANPATH=/usr/local/Cellar/openssl/1.0.2o_1/share/man:$MANPATH

登录时，$MANPATH 环境变量通常不会在 macOS 中设置，并且已经有一段时间没有设置了。如果你使用Brew，它通常应该为它用来安装包的每个 Homebrew 公式定义和更新$MANPATH，IIRC。

【参考方案4】：

MacOS X 中的手册页

MacOS X 中的 man 命令使用一种复杂的方法来查找手册页文件，该方法基于调用选项和环境变量、/private/etc/man.conf 配置文件以及一些内置的约定和启发式方法。

在 MacOS X 中你有一个命令：

/usr/bin/manpath 

这列出了您当前用于搜索手册页的所有位置。 只需键入即可调用它

manpath

在终端中。

它不会将它添加到您的 $MANPATH shell 变量中。

但是您仍然可以使用 man 命令访问手册页。 manpath 中包含的 get 在

中定义

/private/etc/man.conf

不建议在不添加以下输出的情况下导出名为 MANPATH 的环境变量：

`manpath` 

到列表中。

因此，如果您想将 $MANPATH 导出到您的 shell 环境，请执行以下操作：

export MANPATH="`manpath`:/path/to/man/pages/to/include"

这样您将获得操作系统定义的手册页的完整列表以及您自己添加的任何路径。

如需更多信息，请打开终端并查看：

man manpath

和 man.conf 文件：

more /private/etc/man.conf

通常，在特殊位置包含手册页的更好选择是创建一个符号链接，指向包含 /​​usr/local/share/man 中的手册页的目录，该目录默认由“man 生态系统”索引。

【参考方案5】：

虽然现有答案确实提供了一些有助于解决 OP 问题的提示/选项，但它们实际上并没有回答标题中的问题。

确实，为了让man 程序打开手册页，它应该知道去哪里寻找它。这是一个明显的声明，但它没有多大帮助。问题是您是否应该使用一些“标准”位置（如果是，那些“标准”查找路径是什么，它们在哪里定义），或者您应该将手册页与您的程序一起放置，并以某种方式指向 @ 987654322@ 程序到您的自定义位置？

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 默认配置并简单地将自定义程序/脚本的手册页复制到这些目录之一是正确的做法。

原因是默认的manpath是根据man.conf配置的只有如果$MANPATH环境变量没有设置或者为空。如果$MANPATH 环境变量设置/非空，则/etc/man.conf 中的路径不用于查找手册页。

默认情况下，$MANPATH 未设置。但是如果您的程序/脚本+手册页将分发给其他用户，您无法确定它是否设置在那里。

那么，什么是可靠的解决方案？在我看来，将手册页与脚本一起提供，并使用path_helper（man path_helper 获取更多信息）将man 指向自定义 manpath 是第三方程序的最佳方式。

程序/脚本作者唯一需要做的就是将包含程序手册页路径的文件放入/etc/manpaths.d 目录。 path_helper 应该做剩下的事情。

似乎path_helper 是专门为这种用例设计的，并且它被第三方程序使用（我在安装 Wireshark 并尝试使其手册页可发现时了解到它），但有一个警告：

path_helper 不会让 man 知道您的自定义 manpath，如果之前未设置 $MANPATH 环境变量（正如我们所知，默认情况下未设置）。来自path_helper 手册页：

（MANPATH环境变量不会被修改，除非它已经在环境中设置。）

这就是您实际上想要设置$MANPATH 以允许path_helper 之后使用自定义人路径对其进行扩充的原因。

就我而言，我将export MANPATH（只是为了设置它，没有任何值）添加到/etc/zshenv（我使用的是macOS Big Sur，zsh是默认shell），path_helper成功添加了所有来自/etc/manpaths.d 文件的自定义人路径。

【参考方案6】：

除了baf's answer 中指出的所有条目之外，还有/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 用于正则表达式中的字边界，因此您可能希望在 ~/.bashrc 中设置 MANPAGER（或你喜欢的地方）：

export MANPAGER=/usr/local/bin/less

【讨论】：

关于 macOS 中 less 的相关讨论：***.com/a/22742371/537554