manpage - 要转换为联机帮助页的有效 Asciidoc（使用 a2x）

Question

我想用 Asciidoc 为我的 CLI 脚本编写手册页并将其转换为

a2x --doctype manpage --format manpage MYMANPAGE.ASCIIDOC

我找不到任何可以使用此命令成功转换为联机帮助页的 Asciidoc 示例。你能给我举个例子或提供一个吗？

Answer 1

找到了一个例子——来自 Asciidoc 源代码本身：

http://code.google.com/p/asciidoc/source/browse/doc/asciidoc.1.txt

（不过，欢迎提供更多 Ascii-doc 格式的联机帮助页示例！）

Answer 2

除了提供了一个非常有用的示例的@ifischer 答案中的链接之外，我还想将读者引导至 asciidoc 文档中的以下页面：http://www.methods.co.nz/asciidoc/chunked/ch24。 .html _

它特别提到：

• 标题需要正确格式化（例如：PROGRAM(1)）

• 文档类型需要是“manpage”（例如：“:doctype: manpage”）

• 第一部分必须是“名称”。此部分的内容也必须正确格式化（例如：“program - ...”）

• 第二部分需要是“概要”。这部分的内容似乎可以是任何内容，尽管标准的联机帮助页做法是列出所有程序调用选项。

• 该文档当然必须是格式正确的 asciidoc 文档。

可以通过文档标题中的“：directives：”为手册页设置可选信息。

运行时a2x，它会根据名称部分和标题的内容自动命名输出的手册页。我相信它总是被命名为“name.x”，其中名称来自名称部分，x 是标题中的数字。