当前的 man-pages 维护者是 (自 2004 年起) Michael Kerrisk ([email protected]; 博客); 自 2020 年起，Alejandro Colomar ([email protected]) 加入成为共同维护者。
此页面提供了一些关于如何维护 Linux man-pages 项目的技巧 (对于任何想帮助 man-pages 工作的人也很有用)。
至少阅读以下内容
所有这些页面都与维护 man-pages 相关。其中一些页面是 man-pages 以外的软件包的一部分。
历史很重要。man-pages 项目不仅记录了 Linux 内核和 glibc API 的当前状态，还记录了它们随时间的变化。
曾经，man-pages 也用于记录 Linux libc 的详细信息 (libc4, libc5)，但 Linux libc 在 1990 年代后期开始消失 (有关详细信息，请参见此处和此处)，现在不再需要记录其特殊性。
您可以在 https://linuxkernel.org.cn/ 找到几乎所有曾经发布的内核版本。
您可以使用以下命令获取 Linus 的 Git 树的副本 (即当前的开发树)
$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git之后，只需使用 git pull 更新副本。
对于浏览内核源代码，Elixir Cross Referencer 可能很有用。(可以在 http://fxr.watson.org/ 找到各种免费内核的在线可浏览版本。)
可以在 https://ftp.gnu.org/gnu/glibc/ 找到许多 glibc tarball。可以在 https://www.win.tue.nl/~aeb/ftpdocs/linux-local/libc.archive/ 找到许多较旧的 tarball。可以通过 git 获取最新的 glibc 开发树的副本
git clone git://sourceware.org/git/glibc.git
有时，grep 随机源代码以查看某个 API 的用途以及方式可能会很有用。例如，可以解压缩发行版的所有源代码，然后 grep 该代码。源代码的下载位置：Fedora； OpenSUSE。
最大的挑战之一是与内核和 glibc 的更改保持同步。有几种方法可以做到这一点。本节列出了一些最有用的方法。
这些网站很有用，因为它们部分包括其他人试图总结 Linux 内核的更改。
linux-api 邮件列表 ([email protected]) 讨论了影响 Linux 编程接口 (API 或 ABI) 的更改。理论上，所有更改接口的补丁都应抄送至此列表。要订阅，请向 [email protected] 发送包含以下正文的消息
subscribe linux-api
可以在 lore.kernel.org 上找到此列表的存档。
以下是一些尝试发现内核和 glibc 中更改的其他方法。这里有太多的信息要跟踪 (尤其是，几乎不可能跟踪所有邮件列表)，但是下面的列表可以提醒您一些可能找到有用信息的地方。
linux-next 树是旨在用于下一个内核合并窗口的补丁的保留区域。跟踪那里的情况可以帮助您了解即将对内核进行的更改。(关于使用 linux-next 的一些注释。)
如果您正在寻找特定的内核提交，或包含特定字符串的提交日志消息，那么搜索 Linus 的 Git 树可能会很有用。
Linux 内核 (LKML)
此列表 ([email protected]) 包含有关内核的补丁、错误报告和一般讨论。要订阅，请向 [email protected] 发送包含以下正文的消息
subscribe linux-kernel
此列表的问题在于信息量非常大，因此要密切跟踪所有信息将需要大量时间。
vger.kernel.org/ 提供了此邮件列表的一些可搜索存档的位置，当然在 lore.kernel.org 上也有一个存档。
Linux 内核公告
此低容量列表 ([email protected]) 会发布各种内核分支的新版本，包括主线内核的候选版本和新的 -mm 内核。要订阅，请向 [email protected] 发送包含以下正文的消息
subscribe linux-kernel-announce
netdev
netdev 列表 ([email protected]) 是 Linux 网络子系统的开发人员使用的列表。
要订阅，请向 [email protected] 发送包含以下正文的消息
subscribe netdev
Linux 测试项目 (LTP)
LTP 为 Linux 内核生成测试套件。在此处订阅讨论列表 here。此处有列表存档 here。
内核新手
此列表 ([email protected]) 对于询问有关您不理解的内核源代码方面的问题很有用。
要订阅，请向 [email protected] 发送包含以下正文的消息
subscribe kernelnewbies
可以在 lore 和 marc 上找到此列表的存档。有关更多信息，请参见 kernelnewbies 网站。
libc-announce
此列表 ([email protected]) 会发布每个 glibc 版本。通过向 [email protected] 发送电子邮件或访问 此页面 进行订阅。此处有一个列表存档 here。
libc-alpha
此列表 ([email protected]) 是 glibc 的开发列表。通过向 [email protected] 发送电子邮件或访问 此页面 进行订阅。此处有一个列表存档 here。
libc-help
此列表 ([email protected]) 用于提出一般问题并获得有关 glibc 的帮助。通过向 [email protected] 发送电子邮件或访问 此页面 进行订阅。此处有一个列表存档 here。
以下内容对于大致了解各种 glibc 版本中哪些符号是新的或已更改很有用 -- 在 glibc 树的根目录执行它
cat $(find . -name 'Versions' |
egrep -v '/(s390|alpha|sparc|hurd|sh4|bsd|ia64|powerpc|x86_64)') |
sed -n '/GLIBC/,/}/p' | sed 's/#.*//'| tr ';' '\012' |
sed 's/^ *//' | sed 's/ *$//' | sed '/^$/d' |
grep -v '^_' |
awk '{ if ($1 ~ "^GLIBC_2.*") {
tag = $1
} else if ($1 ~ "^[a-z].*") {
printf "%-32s %s\n", $1, tag
}
}' |
sort -u
kernel.org bugzilla 可用于报告 man-pages 错误。可以在此处查看 bugzilla 中未解决的错误列表。
同样有用：如何使用 bugzilla.kernel.org。
Debian 使上游维护人员可以轻松订阅手册页的错误报告。为此，请访问 https://packages.qa.debian.org/ 并查找 Debian 源代码软件包 manpages。
可以在 此处 查看当前 man-pages 的 Debian 错误报告列表。Debian manpages 补丁跟踪器是 此处。
Debian 甚至提供了一个电子邮件界面，允许上游维护人员操作 Debian 错误报告 (使用“tags”命令；请参见 https://www.debian.org/Bugs/server-control)。
可以在 此处 查看 Debian 开发人员/以上游为中心的 manpages 视图。
有时可能值得查看应用于 man-pages 的 Debian 下游差异补丁，以查看是否有任何他们应该已推送到上游但未推送的内容。请查看通过遵循 https://packages.debian.org/manpages 和 https://packages.debian.org/manpages-dev 上的“unstable”版本链接，并下载 Debian tarball 获取的差异补丁。或者查看 Web 补丁跟踪器。
以下邮件地址可联系到 Debian 中对手册页感兴趣的人员：[email protected]。
Ubuntu 使用 Launchpad 进行 manpages (bugs, package) 和 manpages-posix (bugs, package)。“bugs”页面上有允许订阅错误报告的链接。
Red Hat 提供了一个 man-pages bugzilla 组件。
Fedora 软件包的 URL：https://koji.fedoraproject.org/koji/packageinfo?packageID=401。从那里，您可以访问 RPM 文件，并解压缩它们以查看与上游的差异，使用
rpm2cpio foo.rpm | cpio -idmv --no-absolute-filenames
Red Hat 补丁的下游 Git 存储库
git clone https://src.fedoraproject.org/rpms/man-pages.git
可以订阅 Fedora man-pages 错误报告，如下所示
编写测试程序（使用 C 语言）是编写 man 页面的重要组成部分。它验证了作者对文档内容的理解，并能发现内核和 glibc 中的 bug。在某些情况下，示例程序也适合包含在 man 页面本身中。
为了紧跟开发曲线，请尝试构建和测试发布候选版（“rc”）内核；发布候选版在Git 仓库中被标记。在构建和安装内核之后，编写程序来测试新特性。由于新的系统调用的声明可能还不在您的 (g)libc 中，可能需要使用 syscall(2)；请参阅 syscall(2) man 页面。
有关构建和测试 glibc 发布版本的信息，请参阅 glibc 手册中的附录 C 安装 GNU C 库，glibc wiki 上的关于 GNU C 库的常见问题，特别是 Carlos O'Donell 在 glibc wiki 上的 测试 glibc 构建 页面。
仅仅记录 Linux 的行为是不够的。编写可移植应用程序的程序员需要了解 Linux 与其他 UNIX 实现不同的地方，以及它不符合标准的地方。
如果对可移植性有疑问，编写一个测试程序并在其他几个系统上运行它。作为起点，在 Solaris、FreeBSD 和 HP-UX 上进行测试可能会揭示其他实现中出现的大部分差异。在其他 BSD 系统、AIX 等系统上进行测试会有额外加分。
加入 Austin group。（会员资格是免费的。）
获取当前和过去的 UNIX 标准的电子副本，特别是 POSIX.1-2008/SUSv4 标准，该标准以 PDF 格式提供给 Austin group 的成员，并且可以在线浏览。另请注意，man 页面的第 3p 节包含 POSIX.1 中所有函数的规范页面（例如，尝试 man 3p stat）。
其他需要注意的标准是 SUSv1、SUSv2 和 SVID（System V 接口定义），所有这些都以电子形式提供。
并获取C 编程语言标准。
并查看 LSB。
检查其他 UNIX 系统的手册页面，看看与 Linux 有什么不同，这可能会很有用。FreeBSD 项目网站显示了一系列 UNIX 实现的手册页面；请点击这里查看。
有时，在特定函数的 info(1) 文档中可以找到有用的信息（如果存在 info 文档 ...）。总是值得检查的。
拥有一组来自其他各种实现的 /usr/include 树可能会很方便。 Grep 所有这些树可以提供有关其他 UNIX 实现中存在/不存在的接口的一些线索。
一些其他 UNIX 实现的源代码是可用的，并且为了确定这些系统上未记录的行为细节，研究它们很有用。
FreeBSD 源代码可以通过 Git 镜像在 https://github.com/freebsd/freebsd 获取。
请点击这里查看。
发布 tarball 在 https://linuxkernel.org.cn/pub/linux/docs/man-pages/ 上可用。文件使用 kup 上传。 请点击这里查看。
man-pages 网站位于 https://linuxkernel.org.cn/doc/man-pages/。
该网站的 Git 存储库位于 https://git.kernel.org/pub/scm/docs/man-pages/website.git/。通过发布带注释的标签并推送到仓库来发布新版本的网站。
在编写 man 页面时测试内核和 glibc 特性将不可避免地发现 bug，理想情况下应该报告这些 bug。
对于内核，报告 bug（例如，在新系统调用中）最有效的方法通常是向 API 开发人员发送电子邮件，并抄送给 LKML ([email protected]) 或其他相关列表。或者，您可以尝试在 内核 bugzilla 中创建 bug 报告。
有关报告 glibc bug（包括 glibc info(1) 文档中的错误）的信息，请参阅 https://sourceware.org/glibc/wiki/FilingBugs。
man-pages 项目由 Rik Faith 于 1993 年启动，他创建了 1.0 到 1.5 版本（1995 年 2 月）。
Rik Faith 的继任者是 Andries Brouwer (aeb)，他在这个角色上工作了九年多，创建了 1.6 版本（1995 年 6 月）到 1.70 版本（2004 年 10 月）。
现任维护者 Michael Kerrisk (mtk) 于 2004 年 11 月接任，从 2.00 版本开始。