如何在不使用 groff 的情况下将 Linux 手册页转换为 HTML？

Question

我想在不使用 groff 的情况下将一些 Linux 手册页转换为 HTML。我对 groff 的偏见是由于它给我带来的一些 PNG 渲染问题似乎已本地化到 Sabayon（因为这些问题似乎不会发生在我的其他发行版的 VirtualBox VM 上）。我意识到这是一个错误，但解决方案似乎不会在不久的将来出现，所以我想问一下是否有其他方法可以将 Linux 手册页转换为 HTML。使用http://linux.die.net/man 上的 HTML 页面是不可接受的解决方案，因为我感兴趣的一些手册页不存在（例如，emerge(1)不存在）。

Answer 1

有很多替代方案，例如rofit、troff、man2html。还有基于 perl 的在线联机帮助页浏览器，例如manServer。

我最喜欢的是pandoc，但遗憾的是它似乎默认不支持 ROFF 输入（尽管如果您需要将多个转换过滤器链接在一起，您可能可以使用它。

man2html 示例：

zcat /usr/share/man/man1/dd.1.gz \ 
    | man2html \
    | sudo tee /var/www/html/dd.html

示例：

git clone git://github.com/bagder/roffit.git
cd roffit
zcat /usr/share/man/man1/dd.1.gz \
    | perl roffit \
    | sudo tee /var/www/html/dd-roffit.html

其他工具：

• troffcvt做同样的事情。
• '真实' troff- 要尝试http://heirloom.sourceforge.net/doctools.html。我怀疑 schily 有 OpenSolaris 和朋友的想法:-)。

Answer 2

第一点是来自官方网站的无耻翻录：

mandoc是一套编译工具mdoc，是roffBSD 手册页的首选宏语言man，也是 UNIX 手册的主要历史语言。它体积小、ISO C、ISC 许可，而且速度相当快。该工具集的主要组件是mandoc基于libmandoc验证编译器的实用程序，用于格式化 UNIX 终端（支持宽字符语言环境）、XHTML、HTML、PostScript 和 PDF 的输出。

mandoc主要是在 OpenBSD 上开发的，既是 OpenBSD 又是 BSD.lv 项目。我们努力支持所有感兴趣的免费操作系统，特别是 FreeBSD、NetBSD、DragonFly、illumos、Minix 3 和 GNU/Linux，以及所有运行pkgsrc可移植包构建系统的系统。为了支持mandoc开发，请考虑向 OpenBSD 基金会捐款。

pacman通知我我本地安装的mdocml包大小是 3.28mb，它包含以下/usr/bin定位的二进制文件：

/usr/bin/demandoc
/usr/bin/makewhatis
/usr/bin/mandoc
/usr/bin/mapropos
/usr/bin/mman
/usr/bin/mwhatis

有了它，我可以做到：

/usr/bin/demandoc
/usr/bin/makewhatis
/usr/bin/mandoc
/usr/bin/mapropos
/usr/bin/mman
/usr/bin/mwhatis

您可以根据需要应用自己的样式表。所有文档也都在线。我认为，所有这些也是编译的mandoc。

Answer 3

首先，应该注意的是，有不止一个程序叫做man2html.

一种称为man2htmlC 程序的实用程序最初由埃因霍温科技大学的 Richard Verhoeven 于 1990 年代后期编写。该程序具有相当古怪的内部结构。但是，它的优势在于它可以使用原始手册页源，而不是troff或nroff输出。该程序已添加到 Frederico Lucifredi 的男士套件中。

程序理解man和mandoc宏的语义，并输出合理的 HTML 结构。例如，当您使用缩进段落时，如下所示：

.IP字
的定义
单词。
.RS

程序会放出一个 HTML 定义列表。

我维护了一个非常大的手册页（大部分是 1 兆字节的源代码，将近400 800 页长，当通过 转换为信纸大小的 PDF 时groff）：

$ ls -l txr.1
 -rw-rw-r-- 1 kaz kaz 980549 Jan 3 11:38 txr.1 
-rw-rw-r-- 1 kaz kaz 2016633 Apr 7 16:00 txr.1

大约五年前，当我需要将其转换为 HTML 时，我发现唯一能做合理工作的是man2htmlC 程序，加上对其输出的后处理以“按季节品尝”。

最终，我想要一个质量更好的 HTML 文档，所以我开始编写troff宏。C 程序的局限性变得非常明显，所以我对它进行了分叉。在我的 git 站点上，您可以找到一个包含 30 个补丁的git repo 到 man2html。这些补丁修复了许多错误，并通过大大改进的解释 troff 宏、条件、循环和其他结构的能力来增强程序。我还添加了一个M2寄存器，您可以通过它编写代码来检测它正在运行，man2html并且可以有条件地做一些不同的事情（例如向下滚动）。同样，我添加了一个.M2SS命令，可让您发出自定义 HTML 标题部分。

我的大型联机帮助页托管在此处。这是用 生成的man2html，由我的genman.txr程序进行后处理，它重新排列了各个部分，并在整个文档中添加了超链接。它还将目录中的内部链接重写为稳定的 URL（基于散列而不是任意枚举），并通过一些 Javascript 使目录可折叠。

my 使用的确切命令Makefile：

man2html txr.1 | ./txr genman.txr - > txr-manpage.html
tbl txr.1 | pdfroff -man --no-toc -> txr-manpage.pdf

有关输出如何在 HTML 之间有条件地不同的示例，nroff我们可以查看man输出的一部分：

       9.19.4 宏解构

       句法：

                (defstruct {<name> | (<name> <arg>*)} <super>
                   <插槽说明符>*)

              defstruct 宏定义了一个新的结构类型和寄存器
              它在 <name> 下，它必须是一个可绑定的符号，根据
              可绑定函数。同样，每个 <slot> 的名称必须
              也是一个可绑定的符号。

上面，请注意参数在<angle> <brackets>. 在 HTML 版本中，它们以斜体显示。

源代码中的语法部分如下所示：

.coNP 宏@defstruct
.synb
.mets (defstruct >> { name | >> ( name << arg *)} < super
.mets \ \ << 插槽说明符 *)
.syne

这是在同一文档中定义的所有自定义宏。在 下.mets，< bmeansb是一个元句法变量。>> a bmeansa是一个具体的句法，接下来是b没有任何中间空间的元句法，<> a b cmeansb是一个在a和c文字之间加紧的元句法。

我的改进版本man2html理解实现这些标记约定的相当复杂的宏。

另外，请注意手册如何自动为部分编号：这都是由 troff 代码完成的，它可以man2html理解。