可选手册？还是在分发中预编译？

Question

我正在做一个用 C++ 编写的个人项目，我使用 GNU Autotools 作为构建系统。

我想将我的软件与手册页一起分发，但我不太喜欢 Groff。出于这个原因，我决定在 Asciidoc 中编写所有内容，并在 Groff 中使用 a2x.

进行编译。

虽然我对结果很满意，~~我注意到安装 Asciidoc 可能需要大量磁盘 space。例如，Debian Stretch 中的 asciidoc-base 需要 1928 MB 的依赖项！~~（编辑：甚至不正确。我忘了 disable suggested/recommended，但是使用大小写无论如何都是相关的）。

一种解决方案是将其设为可选。为此，我的 configure.ac 包含以下几行：

AC_CHECK_PROG([asciidoc], [a2x], [a2x], [false])
AM_CONDITIONAL([ASCIIDOC_AVAIL], [test x$asciidoc != xfalse])

…而man/Makefile.am文件定义如下：

if ASCIIDOC_AVAIL

man1_MANS = foo.1
man5_MANS = foo.conf.5

foo.1: foo.1.txt
    $(asciidoc) --doctype manpage --format manpage ./$<

foo.conf.5: foo.conf.5.txt
    $(asciidoc) --doctype manpage --format manpage ./$<

clean:
    rm $(man1_MANS) $(man5_MANS)

endif

尽管这似乎可行，但我对此不是很满意。我不喜欢不提供手册的想法。

预编译手册页作为 make dist 步骤的一部分是否可取？与发行版 foo-x.y.z.tar.gz 包含 configure 脚本（未在 VCS 中检查但由 autoreconf 生成）的方式相同，我可以制作 foo.1 和 foo.conf.5 预编译，并与源 tarball 一起分发。

如果从"best practices"的角度来看是可以接受的，我该如何实现呢？我试图将它们声明为 EXTRA_DIST (EXTRA_DIST = man1_MANS man5_MANS) 但我运气不佳。

有什么想法吗？

编辑：Best way to add generated files to distribution? 问题似乎是相关的，尽管我怀疑我的具体情况是否有内置机制。

Answer 1

even though I doubt there's a built in mechanism for my specific case.

实际上，here 在该页的一半处描述了这样一种机制。 dist_ 前缀就是你要找的：

dist_man1_MANS = foo.1
dist_man5_MANS = foo.conf.5

if ASCIIDOC_AVAIL

foo.1: foo.1.txt
    $(asciidoc) --doctype manpage --format manpage ./$<

foo.conf.5: foo.conf.5.txt
    $(asciidoc) --doctype manpage --format manpage ./$<

CLEANFILES += $(dist_man1_MANS) $(dist_man5_MANS)

endif

Answer 2

OP在这里。

感谢 ldav1s 的回答，我为我的 man/Makefile.am 文件找到了一个很好的定义。我把它放在这里作为答案，但全部归功于 ldav1s。

开始了：

dist_man1_MANS = foo.1
dist_man5_MANS = foo.conf.5

EXTRA_DIST = foo.1.txt foo.conf.5.txt

if ASCIIDOC_AVAIL
foo.1: foo.1.txt
    $(asciidoc) --doctype manpage --format manpage ./$<

foo.conf.5: foo.conf.5.txt
    $(asciidoc) --doctype manpage --format manpage ./$<
endif

CLEANFILES = $(dist_man1_MANS) $(dist_man5_MANS)

关于它的一些有用信息：

联机帮助页 foo.1 和 foo.conf.5 是在 make dist 期间生成的，这要归功于 dist_ 前缀（正如 ldav1s 所指出的）。这两个联机帮助页包含在分发压缩包中。
通过在 EXTRA_DIST 中获取来源 foo.1.txt 和 foo.conf.5.txt，我也可以分发这两个文件。这是必需的，因为分发 tarball 将只包含已编译的联机帮助页。
声明 CLEANFILES 将导致 make clean 删除已编译的联机帮助页。

只是为了理解这个想法，使用这个配置我可以运行 make dist 并获得具有以下属性的 tarball：

tarball 已经包含已编译的联机帮助页和 asciidoc 源代码。
运行 ./configure && make 在解压缩 tarball 后立即不会编译联机帮助页，因为它们已经可用。
运行 ./configure && make clean 在解压缩 tarball 后立即删除编译的联机帮助页（即使它们包含在分发 tarball 中）；

我尝试验证构建系统在安装 asciidoc 和未安装时的行为：我一开始就得到了我想要的。

如果未安装 asciidoc（因此 ./configure 不会检测到它），运行ning ./configure && make clean && make 不会重新编译联机帮助页
如果安装了 asciidoc，运行ning ./configure && make clean && make 将重新编译联机帮助页。

可选手册？还是在分发中预编译？

Optional manuals? Or pre-compiled in distribution?

packaging

autoconf

automake