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.
This commit is contained in:
Mathieu Lirzin 2016-03-19 15:27:54 +01:00
parent b33d3a5a94
commit 39118b5eed

19
doc.am
View file

@ -98,6 +98,12 @@ dvi-local: ps-local
## Man pages. ## ## 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 = \ sub_commands_mans = \
$(srcdir)/doc/guix-archive.1 \ $(srcdir)/doc/guix-archive.1 \
$(srcdir)/doc/guix-build.1 \ $(srcdir)/doc/guix-build.1 \
@ -120,22 +126,19 @@ dist_man1_MANS = \
$(srcdir)/doc/guix.1 \ $(srcdir)/doc/guix.1 \
$(sub_commands_mans) $(sub_commands_mans)
# Man pages are generated using GNU help2man.
gen_man = \ gen_man = \
LANGUAGE= $(top_builddir)/pre-inst-env $(HELP2MAN) \ LANGUAGE= $(top_builddir)/pre-inst-env $(HELP2MAN) \
$(HELP2MANFLAGS) $(HELP2MANFLAGS)
HELP2MANFLAGS = --source=GNU --info-page=$(PACKAGE_TARNAME) 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) $(srcdir)/doc/guix.1: scripts/guix.in $(sub_commands_mans)
-$(AM_V_HELP2MAN)$(gen_man) --output="$@" `basename "$@" .1` -$(AM_V_HELP2MAN)$(gen_man) --output="$@" `basename "$@" .1`
# Note: The dependency on $(GOBJECTS) is meant to force these docs to be made # The 'case' ensures the man pages are only generated if the corresponding
# only after all Guile modules have been compiled. The 'case' ensures the man # source script (the first prerequisite) has been changed. The $(GOBJECTS)
# pages are only generated if the corresponding script source has been # prerequisite is solely meant to force these docs to be made only after all
# changed. # Guile modules have been compiled.
$(srcdir)/doc/guix-%.1: guix/scripts/%.scm $(GOBJECTS) $(srcdir)/doc/guix-%.1: guix/scripts/%.scm $(GOBJECTS)
-@case '$?' in \ -@case '$?' in \
*$<*) $(AM_V_P) && set -x || echo " HELP2MAN $@"; \ *$<*) $(AM_V_P) && set -x || echo " HELP2MAN $@"; \
@ -147,8 +150,6 @@ if BUILD_DAEMON
dist_man1_MANS += $(srcdir)/doc/guix-daemon.1 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 $(srcdir)/doc/guix-daemon.1: nix/nix-daemon/guix-daemon.cc
-$(AM_V_HELP2MAN)$(gen_man) --output="$@" `basename "$@" .1` -$(AM_V_HELP2MAN)$(gen_man) --output="$@" `basename "$@" .1`