doc/man: only require asciidoc-attrs.conf when building the man pages

Situations:

* If you want to and can build the man pages:
  * If it's a tarball tree:
    * Make the man page destinations depend on asciidoc-attrs.conf.
      Since it's a generated file, its date is greater than the
      date of the prebuilt man pages, therefore the man pages are
      built again, which is a good thing because they include the
      default values of this build.
  * If it's a Git tree:
    * Always build the man pages anyway (no prebuilt man pages here).
* If you want to, but cannot build the man pages:
  * If it's a tarball tree:
    * Make the man page destinations NOT depend on asciidoc-attrs.conf,
      because its recent date would ask said destinations to be rebuilt
      and this is not possible because we don't have the tools.

      However, warn the user at configure time that the prebuilt man
      pages will be installed, which means that they will contain the
      project's default values, not this build's default values.
  * If it's a Git tree:
    * Not valid: error at configure time as usual.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/configure.ac b/configure.ac
index 40198a630e72ab75462046db4f81e21b0529b9b1..65f2439c04e112563552279ee6325508bd3361c9 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -595,7 +595,7 @@ AS_IF([test "x$man_pages_opt" = "xyes"], [
                        # thus asciidoc/xmlto are required because we were asked
                        # to build the man pages
                        AC_MSG_ERROR([
-Both asciidoc and xmlto are needed to build the LTTng man pages. Use
+You need asciidoc and xmlto to build the LTTng-tools man pages. Use
 --disable-man-pages to disable building the man pages, in which case
 they will not be installed.
                        ])
@@ -604,11 +604,17 @@ they will not be installed.
                        # pages should already be generated at this point, thus
                        # asciidoc/xmlto are not strictly required
                        AC_MSG_WARN([
-Both asciidoc and xmlto are needed to build the LTTng man pages. Note
-that the man pages are already built in this distribution tarball, so
-asciidoc and xmlto are only needed if you intend to modify their
-sources. Use --disable-man-pages to completely disable building
-and installing the man pages.
+You need asciidoc and xmlto to build the LTTng-tools man pages.
+
+Note that the man pages are already built in this distribution tarball,
+so asciidoc and xmlto are only needed if you intend to modify their
+sources.
+
+Also note that the installed man pages will contain the project's
+default command-line option and environment variable values.
+
+Use --disable-man-pages to completely disable building and installing
+the man pages.
                        ])
                ])
        ], [

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 5ec6f4fafdc0c682cc7f7a6c2f69584b9a939dff..1d838e2ba0961a9458012344fec93f7a551c4e4e 100644 (file)
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -62,7 +62,7 @@ XSL_FILES = \
 XSL_SRC_FILES = $(addprefix $(srcdir)/xsl/,$(XSL_FILES))
 
 # common dependencies
-COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT) $(ASCIIDOC_ATTRS_CONF)
+COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT)
 
 # man pages destinations
 MAN1 = $(addsuffix .1,$(MAN1_NAMES))
@@ -81,6 +81,11 @@ ADOC = $(ASCIIDOC) -f $(ASCIIDOC_CONF) -f $(ASCIIDOC_ATTRS_CONF) -d manpage
 ADOC_DOCBOOK = $(ADOC) -b docbook
 XTO = $(XMLTO) -m $(firstword $(XSL_SRC_FILES)) man
 
+# only add this dependency if we can build the man pages because it's
+# a file generated by the configure script, so it's more recent than
+# the pregenerated man pages in a tarball
+COMMON_DEPS += $(ASCIIDOC_ATTRS_CONF)
+
 # recipes
 %.1.xml: $(srcdir)/%.1.txt $(COMMON_DEPS)
        $(ADOC_DOCBOOK) -o $@ $<