每次查 Linux API ，要么用 man 要么 google 查在线版进去看，其中在线版使用 man7.org 最多，排版护眼排名也最靠前。但如果使用 Zeal 的话一定会更快，且离线版本没有网络的时候也能查。 Zeal 可以认为是开源简化版 Dash ，后者是 Mac 专属付费应用，但两者离线文档格式都是 docset 。所以文档源是有的，目的格式是有的，那么把 man pages 转换格式塞进 Zeal / Dash 应该是可行的，过程中踩坑挺多，所以记录一下。

先看处理结果

生成了 man7.org 版 man pages 的 docset ，并且使用起来比较顺眼， Zeal 中的效果如下：

zeal-linux-man-pages 截图

这里直接附上 docset 下载地址（请注意，对应的 man pages 版本为 5.13 ）：
github.com/Quarkay/BlogFragments

docset 生成方式

这里主要介绍 Linux 平台操作方式， 其他平台的操作对应替换即可。最后结果也只在 Linux Zeal 测试过，但其他平台及 Dash 也应该是可以正常使用的。

环境准备

  • wget
  • Python3
  • 任意文本编辑器

内容下载

首先要把 man7.org 所有 man pages 相关的 html 文件下载下来，使用 wget 就可以做到，从 man pages 首页开始所有链接递归下载即可达到效果。 man7.org 站点还有 man pages 外的其他内容，所以留意加上 --no-parent 。

$ wget --recursive --no-parent https://man7.org/linux/man-pages/index.html

至此，内容准备完毕！

内容转换

从 HTML 到 docset 自然是需要进行格式转换的，但这么多文件不可能一个个手动去转换，所以要用到工具。搜索发现已经有朋友编写了从 man pages 原始文档到 docset 的转换脚本，所以不用自己写，对其略作修改即可。 man pages 原始文档需要使用 Groff 工具集转换成 html ，而这里我们已经准备好了 html ，这就是最大的区别。具体细节和修改内容，感兴趣的朋友可以查看以下链接进行对比，这里不再赘述：

原　版：github.com/Yanpas/mandocset
修改版：gist.github.com/Quarkay/87f840268775ba013ea561b5920ec487

使用修改版文件，执行以下命令：

$ rm man7.org/**/*.license.html
$ python3 mandocset.py -p ./man7.org/linux/man-pages/ -o Linux_Man_Pages -e "ls"

其中第一步删除操作，是因为作为手册用一般不需要看 license ，搜索列表里面出现反而耗费人眼，直接删除该类文件是最简单的操作。其中 man7.org 是 wget 下载生成的目录。 -e "ls" 则是为了覆盖脚本默认处理逻辑，只需要避免报错就行了。

补全和修改样式

此时如果直接丢进 Zeal 预览，会发现没有 CSS 样式，所以对应的把该 style.css 复制过去对应目录即可。

$ cp man7.org/linux/man-pages/style.css ./Linux_Man_Pages.docset/Contents

此时如果直接预览，会发现看起来不太舒服，所以略微修改以下该文件中 body 的样式即可达到本文前面预览图的效果：

body {
    background-color:#f5f5d5;
    font-size: 1.5rem;
    margin-left: 23%;
}

修改 docset 信息

查看 docset 内容目录：

$ ll Linux_Man_Pages.docset/Contents 
总用量 12K
-rw-r--r-- 1 quarkay quarkay  393 11月  9 18:11 Info.plist
drwxr-xr-x 3 quarkay quarkay 4.0K 11月  9 18:10 Resources
-rw-r--r-- 1 quarkay quarkay 2.2K 11月  9 18:13 style.css

其中 Info.plist 文件包含手册基本信息，会在 Zeal 中用到，根据个人喜好做对应修改即可，基本都能猜到作用是啥，不知道的不要改就好了：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleIdentifier</key>
    <string>Linux</string>
    <key>CFBundleName</key>
    <string>Linux Man Pages</string>
    <key>DocSetPlatformFamily</key>
    <string>linux</string>
    <key>isDashDocset</key>
    <true/>
</dict>
</plist>

补充 Icon 信息

同样也是根据个人喜好补充这两个 png 文件即可：

$ ll Linux_Man_Pages.docset/        
总用量 12K
drwxr-xr-x 3 quarkay quarkay 4.0K 11月  9 18:13 Contents
-rw-r--r-- 1 quarkay quarkay 1.8K 11月  9 18:10 icon@2x.png
-rw-r--r-- 1 quarkay quarkay  761 11月  9 18:11 icon.png

icon 图标 - Linux 企鹅

至此 Linux man pages 对应的 docset 已经生成和处理完毕，愉快的使用吧！

踩坑记录

中间踩了挺多坑的，首先是 man2html 工具处理失败，不清楚什么原因，总是原样输出（只补充了基本的 html 骨架内容）。后面开始用 groff 直接处理，结果效果又不满意，不带样式而且中间不能链接跳转。于是开始想着找现成的，结果发现都是为 Dash 准备的，而 Zeal 不支持直接调用 man 预览结果的功能。最后想着要是能把 man7.org 的版本塞进 Zeal 就好了，于是乎有了此文。当然了，回头看踩坑都是因为想节省时间，尽快能用，不想看 docset 文档，更不想自己写脚本。结果到最后，感觉要是一开始就抱着最终目的，老老实实看 docset 文档写脚本，说不定更快！

最后，不清楚版权问题， Linux man pages 的 announce 文件也只是说版权挺复杂的每个模块都不一样，用户你自己去看。其次，这个样式是 man7.org 提供的。