在 20XX 年编写联机帮助页
Writing manpages in 20XX
我写了一个程序，我想为它写一个联机帮助页。
我开始学Groff了，真的觉得很烂。 man 宏难以理解、难以使用，并且是生产力的真正障碍。 mdoc 宏添加了一个很好的 "semantic" 扩展，但它们仍然受到限制，这使得它变得异常困难。结果"code"可维护性差
当然我知道我可以通过 pandoc 将任何现代标记语言（比如 Markdown）转换成联机帮助页，但我不喜欢这个结果，而且我不太喜欢添加 pandoc 作为无论如何，我的项目的依赖性。
有没有办法从合理的标记语言中获得像样的联机帮助页？
我为我编写的 bash 和 ruby 脚本编写联机帮助页。
我将它们格式化为 markdown，这是一种流行且简单的文本格式。
然后我使用一个名为 ronn 的 ruby gem 将 markdown 处理成带有 man 宏的 groff 格式。 Ronn 还可以从相同的降价源输出 html。
OP在这里。在检查了一些替代方案之后，我决定选择 Asciidoc。
确实有很多选择。例如，勾选 this other question.
我也意识到这个问题没有好的答案，因为可以使用很多工具，最后这只是一个品味问题:)
我将投票结束我自己的问题（如果有的话，它将保留作为参考）。
我写了一个程序，我想为它写一个联机帮助页。
我开始学Groff了，真的觉得很烂。 man 宏难以理解、难以使用，并且是生产力的真正障碍。 mdoc 宏添加了一个很好的 "semantic" 扩展，但它们仍然受到限制，这使得它变得异常困难。结果"code"可维护性差
当然我知道我可以通过 pandoc 将任何现代标记语言（比如 Markdown）转换成联机帮助页，但我不喜欢这个结果，而且我不太喜欢添加 pandoc 作为无论如何，我的项目的依赖性。
有没有办法从合理的标记语言中获得像样的联机帮助页？
我为我编写的 bash 和 ruby 脚本编写联机帮助页。
我将它们格式化为 markdown，这是一种流行且简单的文本格式。
然后我使用一个名为 ronn 的 ruby gem 将 markdown 处理成带有 man 宏的 groff 格式。 Ronn 还可以从相同的降价源输出 html。
OP在这里。在检查了一些替代方案之后，我决定选择 Asciidoc。
确实有很多选择。例如，勾选 this other question.
我也意识到这个问题没有好的答案，因为可以使用很多工具，最后这只是一个品味问题:) 我将投票结束我自己的问题（如果有的话，它将保留作为参考）。