04/04: build: Rewrite comments for man pages.

[Mathieu Lirzin]

mthl pushed a commit to branch master
in repository guix.

commit 39118b5eed53725dcd3feb61dc6cde5f98929579
Author: Mathieu Lirzin <address@hidden>
Date:   Sat Mar 19 15:27:54 2016 +0100

    build: Rewrite comments for man pages.
    
    * doc.am <Man pages>: Rewrite comments to describe the build process and
    the meaning of the noticeable idiosyncrasies in a more general way.
---
 doc.am |   19 ++++++++++---------
 1 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/doc.am b/doc.am
index 956ac1f..8356ffa 100644
--- a/doc.am
+++ b/doc.am
@@ -98,6 +98,12 @@ dvi-local: ps-local
 ##  Man pages. ##
 ## ----------- ##
 
+# The man pages are generated using GNU Help2man.  In makefiles rules they
+# depend not on the binary, but on the source files.  This usage allows a
+# manual page to be generated by the maintainer and included in the
+# distribution without requiring the end-user to have 'help2man' installed.
+# They are built in $(srcdir) like info manuals.
+
 sub_commands_mans =                            \
   $(srcdir)/doc/guix-archive.1                 \
   $(srcdir)/doc/guix-build.1                   \
@@ -120,22 +126,19 @@ dist_man1_MANS =                          \
   $(srcdir)/doc/guix.1                         \
   $(sub_commands_mans)
 
-# Man pages are generated using GNU help2man.
 gen_man =                                              \
   LANGUAGE= $(top_builddir)/pre-inst-env $(HELP2MAN)   \
   $(HELP2MANFLAGS)
 
 HELP2MANFLAGS = --source=GNU --info-page=$(PACKAGE_TARNAME)
 
-# Note: Do not depend on 'scripts/guix' since that would trigger a rebuild
-# even for people building from a tarball.
 $(srcdir)/doc/guix.1: scripts/guix.in $(sub_commands_mans)
        -$(AM_V_HELP2MAN)$(gen_man) --output="$@" `basename "$@" .1`
 
-# Note: The dependency on $(GOBJECTS) is meant to force these docs to be made
-# only after all Guile modules have been compiled.  The 'case' ensures the man
-# pages are only generated if the corresponding script source has been
-# changed.
+# The 'case' ensures the man pages are only generated if the corresponding
+# source script (the first prerequisite) has been changed.  The $(GOBJECTS)
+# prerequisite is solely meant to force these docs to be made only after all
+# Guile modules have been compiled.
 $(srcdir)/doc/guix-%.1: guix/scripts/%.scm $(GOBJECTS)
        address@hidden '$?' in \
          *$<*) $(AM_V_P) && set -x || echo "  HELP2MAN $@"; \
@@ -147,8 +150,6 @@ if BUILD_DAEMON
 
 dist_man1_MANS += $(srcdir)/doc/guix-daemon.1
 
-# Note: Do not depend on 'guix-daemon' since that would trigger a rebuild even
-# for people building from a tarball.
 $(srcdir)/doc/guix-daemon.1: nix/nix-daemon/guix-daemon.cc
        -$(AM_V_HELP2MAN)$(gen_man) --output="$@" `basename "$@" .1`