如何为deb包创建手动输入

Question

创建deb包时，我在哪里编写手册？ 是否有任何格式规则/最佳实践要尊重？

我对deb包的创建很新。 在一些教程之后，我刚刚创建了一个可以很好地安装/执行的包，所以现在我想编写一些文档，以便man myFancyPackage返回一些内容，而不是myFancyPackage的手动输入 。

不幸的是，我找到的所有教程都没有谈到手动创建。

Answer 1

有很多方法可以构建Debian软件包，但目前的“最佳实践”是使用Debhelper提供的工具。 对于手册页，有一个名为dh_installman的工具（读取其手册页 ），由dh自动调用。 如果您使用dh_make或类似的方法为您的包创建模板，那么dh调用将在您的debian/rules文件中。

dh_installman通过读取文件debian/manpages或debian/nameofyourpackage.manpages 。 此文件包含指向程序包手册页的路径列表。 路径相对于包的根目录。 这里有一个真实包的例子 。 然后，此程序将正确安装您的手册页在正确的目录中。

因此，总而言之，您只需要创建debian/package.manpages并将其填充到手册页的路径中。 这些路径必须相对于包的根目录。 如果打包器正在编写手册页，那么它们必须放在Debian/目录中。

Answer 2

手册页是由传统的排版语言叫做roff使用宏包叫做an （所以在命令行是roff -man ，原文如此），但很少有人写原始roff了。

有各种SGML和XML文档格式可以生成man页源，但在这个时代， Markdown可能正在成为新文档的事实标准。 谷歌的热门话题是https://github.com/remarkjs/remark-man虽然我肯定也建议你看看pandoc 。

# NAME

Markdown - popular text markup language

# SYNOPSIS

man markdown

# DESCRIPTION

This is a popular lightweight syntax
to generate styled text from an
editor-friendly text source.
It is used on [Stack Overflow][1],
[Github][2], and increasingly on
blogging and authoring platforms.

  [1]: https://stackoverflow.com/
  [2]: https://github.com/

我还要提到POD格式 ，它在Perl社区中有很长的历史，并且有许多与流行的，更新的轻量级格式相同的功能。 除非你有其他理由喜欢它，否则我不会选择它用于新的文档，但它曾经在Perl世界之外的中等受欢迎，因为它是具有简单的人类可读源格式的唯一选项之一，显而易见语义学，以及一个多功能，维护良好的工具链和支持生态系统。 有些人可能会说它仍然存在。

=head1 NAME

Pod::Example - Example POD document

=head1 SYNOPSIS

pod2man thisdoc.pod >thisdoc.1

=head1 DESCRIPTION

Lightweight syntax for subheads,
hyperlinks, indented lists,
and not much else.
Natively supported in Perl source files
to facilitate a crude form of
literate programming.