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 f6dc031309fd8d7e797f1af208fbf2175e3086fb..885edb915326c04a63fe87df58dfbf4cd8a2a678 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -616,7 +616,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.
                        ])
@@ -625,11 +625,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 9c7f125d00e08ff3a195186b275cddb370fab3c4..845e475dd4e82c0c73fccc2927a76da7bd7ec756 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 $@ $<