编写手册页的最佳方式？答案

【问题标题】：Best way to author man pages?编写手册页的最佳方式？
【发布时间】：2010-05-01 03:51:10
【问题描述】：

编写手册页的最佳方式是什么？我应该使用标准的 man 宏来编写，还是现在有一些聪明的包可以使用某种 XML 化的源代码并可以输出手册页、HTML、ASCII 等等？

谢谢

【问题讨论】：

@vy32：你最后用了什么？
我最终是在 nroff 中完成的。

标签： manpage

【解决方案1】：

我以前使用名为 groff 的 GNU 版本的 nroff 来编写手册页。

这里有很好的介绍文章：

http://www.linuxjournal.com/article/1158

【讨论】：

+1 尽管它并不是真正编写它们的工具，而是格式化它们。

【解决方案2】：

Doxygen 是您正在寻找的。请记住，它旨在记录源代码，但您可以轻松地对其进行调整。

它也可以生成html、pdf和latex文档。

【讨论】：

Doxygen 是一个强大的系统，但我不清楚如何让它为命令行选项等发出漂亮的手册页。
是的。可能你需要别的东西。
您可以通过在 doxygen 配置文件中设置 GENERATE_MAN 和可选的 MAN-OUTPUT（设置输出位置）来让 doxygen 输出 man 格式的页面：doxygen.nl/config.html#cfg_man_output 如文档中所述，如果您离开man-output 值为空白，它将默认将手册页放在名为“man”的子目录下

【解决方案3】：

如果您正在考虑编写一次并生成不同的输出格式，例如联机帮助页、HTML、纯 txt 甚至 PDF，那么docbook 应该是最好的选择。

【讨论】：

docbook 不生成手册页。它可以摄取它们，但不能产生它们。
我认为 shadow-utils 成功使用了它，类似于 "xsltproc -nonet docbook.sourceforge.net/release/xsl/current/manpages/… $FILE"

【解决方案4】：

Tcl 社区中常用的一个工具是doctools，它可以生成手册页格式的受限（但有用）子集，适用于使用 groff 或 nroff 进行渲染。它也可以直接生成纯文本和HTML。

【讨论】：

【解决方案5】：

对于我的atinout 程序，我一直在使用ronn，它可以让您以非常易读的markdown 语法编写手册页。我对此非常满意。

atinout(1) -- Send AT commands to modem, capturing the response
===============================================================

## SYNOPSIS

`atinout` <input_file>|`-` <modem_device> <output_file>|`-`<br>
`atinout` `--version`<br>
`atinout` `--usage`<br>
`atinout` `--help`<br>

## DESCRIPTION

**Atinout** reads a list of AT commands. It sends those commands one by one
to the modem, waiting for the final result code for the
currently running command before continuing with the next command in
the list. The output from the commands is saved.
...

see the whole page here.

【讨论】：

不过，如何分发自动运行atinout 的配置脚本？
您的意思是“...自动运行 ronn”？好吧，我没有。两个帽子 atinout 都没有配置脚本，而且我分发了一个预制的 atinout.1，因此 ronn 不是硬构建依赖项（只有当你想修改手册页时才需要它）。
好的。在我基于 autoconf 的项目中，我分发手册页的源代码，并且 nroff 会自动运行..