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

Question

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

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

虽然我对结果非常满意， 我注意到安装Asciidoc可能需要大量磁盘空间。例如，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进行分发。

如果从“最佳实践”的角度来看这是可以接受的，我该如何实现呢？我试图将它们声明为EXTRA_DIST（EXTRA_DIST = man1_MANS man5_MANS），但我没有太多运气。

任何的想法？

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

Answer 1

即使我怀疑我的具体案例有内置机制。

实际上，有一个这样的机制描述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前缀（由ldav1s指出），foo.conf.5和make dist的生成在dist_期间生成。这两个联机帮助页包含在分发tarball中。
• 通过foo.1.txt中的源foo.conf.5.txt和EXTRA_DIST，我也可以分发这两个文件。这是必需的，因为分发tarball将仅包括已编译的联机帮助页。
• 声明CLEANFILES将导致make clean删除已编译的联机帮助页。

只是为了得到这个想法，通过这种配置，我可以运行make dist并获得具有以下特性的tarball：

1. tarball已经包含已编译的联机帮助页以及asciidoc源。
2. 在解压缩tarball后立即运行./configure && make将无法编译联机帮助页，因为它们已经可用。
3. 解压缩tarball后立即运行./configure && make clean将删除已编译的联机帮助页（即使它们包含在分发tarball中）;

我在安装asciidoc时尝试验证构建系统的行为，以及何时没有安装：我得到了我想要的东西。

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