[PATCH 0/4] Build man pages in $(srcdir).

[PATCH 0/4] Build man pages in $(srcdir).

[Mathieu Lirzin]

This is an alternative to commit 97966e6d65bd3d450f12c7bb41af5f9eafd35a60.

The problem solved by this commit was that doc/guix.1 was still generated by
'help2man' when doing a VPATH build from a tarball.  It is still not clear to
me why this problem was happening.  My guess is that this was related to the
$(sub_commands_mans) variable behind composed of generated files which were
confusing Make in a weird way.

Anyway, inspired by what is done by Automake for info manuals I have tried to
build man pages in $(srcdir), which is fixing the issue too.  The bonus is
that now all the documentation is consistently built in $(srcdir) and that we
avoid adding another "case $? ..." trick.

Mathieu Lirzin (4):
  Revert "build: Do not remake doc/guix.1."
  build: Make 'guix' man page depend on scripts/guix.in.
  build: Build man pages in $(srcdir).
  build: Rewrite comments for man pages.

 doc.am | 67 ++++++++++++++++++++++++++++++++----------------------------------
 1 file changed, 32 insertions(+), 35 deletions(-)

-- 
2.7.0

[PATCH 1/4] Revert "build: Do not remake doc/guix.1."

[Mathieu Lirzin]

This reverts commit 97966e6d65bd3d450f12c7bb41af5f9eafd35a60.
---
 doc.am | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/doc.am b/doc.am
index a1eabad..127029c 100644
--- a/doc.am
+++ b/doc.am
@@ -129,12 +129,8 @@ 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.
-doc/guix.1: scripts/guix.in $(GOBJECTS)
-	-@case '$?' in \
-	  *$<*) $(AM_V_P) && set -x || echo "  HELP2MAN $@"; \
-	        $(gen_man) --output="$@" "guix";; \
-	  *)    : ;; \
-	esac
+doc/guix.1: $(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
-- 
2.7.0

Re: [PATCH 1/4] Revert "build: Do not remake doc/guix.1."

[Ludovic Courtès]

Mathieu Lirzin <mthl@gnu.org> skribis:

> This reverts commit 97966e6d65bd3d450f12c7bb41af5f9eafd35a60.

Fine with me provided everything still works after this patch series.

Ludo’.

[PATCH 2/4] build: Make 'guix' man page depend on scripts/guix.in.

[Mathieu Lirzin]

* doc.am (doc/guix.1): Add scripts/guix.in prerequisite.
---
 doc.am | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc.am b/doc.am
index 127029c..896139f 100644
--- a/doc.am
+++ b/doc.am
@@ -129,7 +129,7 @@ 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.
-doc/guix.1: $(sub_commands_mans)
+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
-- 
2.7.0

Re: [PATCH 2/4] build: Make 'guix' man page depend on scripts/guix.in.

[Ludovic Courtès]

Mathieu Lirzin <mthl@gnu.org> skribis:

> * doc.am (doc/guix.1): Add scripts/guix.in prerequisite.

OK.

Ludo’.

[PATCH 3/4] build: Build man pages in $(srcdir).

[Mathieu Lirzin]

Before that the doc/guix.1 rule was always triggered when doing a VPATH
build from a tarball.

* doc.am (sub_commands_mans, dist_man1_MANS): man pages are now
generated in $(srcdir) like the info manual.
(doc/guix.1, doc/guix-%.1): Prepend $(srcdir) to target name.
[BUILD_DAEMON] (doc/guix-daemon.1): Likewise.
---
 doc.am | 42 +++++++++++++++++++++---------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/doc.am b/doc.am
index 896139f..956ac1f 100644
--- a/doc.am
+++ b/doc.am
@@ -99,25 +99,25 @@ dvi-local: ps-local
 ## ----------- ##
 
 sub_commands_mans =				\
-  doc/guix-archive.1				\
-  doc/guix-build.1				\
-  doc/guix-challenge.1				\
-  doc/guix-download.1				\
-  doc/guix-edit.1				\
-  doc/guix-environment.1			\
-  doc/guix-gc.1					\
-  doc/guix-hash.1				\
-  doc/guix-import.1				\
-  doc/guix-lint.1				\
-  doc/guix-package.1				\
-  doc/guix-publish.1				\
-  doc/guix-pull.1				\
-  doc/guix-refresh.1				\
-  doc/guix-size.1				\
-  doc/guix-system.1
+  $(srcdir)/doc/guix-archive.1			\
+  $(srcdir)/doc/guix-build.1			\
+  $(srcdir)/doc/guix-challenge.1		\
+  $(srcdir)/doc/guix-download.1			\
+  $(srcdir)/doc/guix-edit.1			\
+  $(srcdir)/doc/guix-environment.1		\
+  $(srcdir)/doc/guix-gc.1			\
+  $(srcdir)/doc/guix-hash.1			\
+  $(srcdir)/doc/guix-import.1			\
+  $(srcdir)/doc/guix-lint.1			\
+  $(srcdir)/doc/guix-package.1			\
+  $(srcdir)/doc/guix-publish.1			\
+  $(srcdir)/doc/guix-pull.1			\
+  $(srcdir)/doc/guix-refresh.1			\
+  $(srcdir)/doc/guix-size.1			\
+  $(srcdir)/doc/guix-system.1
 
 dist_man1_MANS =				\
-  doc/guix.1					\
+  $(srcdir)/doc/guix.1				\
   $(sub_commands_mans)
 
 # Man pages are generated using GNU help2man.
@@ -129,14 +129,14 @@ 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.
-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`
 
 # 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.
-doc/guix-%.1: guix/scripts/%.scm $(GOBJECTS)
+$(srcdir)/doc/guix-%.1: guix/scripts/%.scm $(GOBJECTS)
 	-@case '$?' in \
 	  *$<*) $(AM_V_P) && set -x || echo "  HELP2MAN $@"; \
 	        $(gen_man) --output="$@" "guix $*";; \
@@ -145,11 +145,11 @@ doc/guix-%.1: guix/scripts/%.scm $(GOBJECTS)
 
 if BUILD_DAEMON
 
-dist_man1_MANS += 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.
-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`
 
 endif
-- 
2.7.0

Re: [PATCH 3/4] build: Build man pages in $(srcdir).

[Ludovic Courtès]

Mathieu Lirzin <mthl@gnu.org> skribis:

> Before that the doc/guix.1 rule was always triggered when doing a VPATH
> build from a tarball.
>
> * doc.am (sub_commands_mans, dist_man1_MANS): man pages are now
> generated in $(srcdir) like the info manual.
> (doc/guix.1, doc/guix-%.1): Prepend $(srcdir) to target name.
> [BUILD_DAEMON] (doc/guix-daemon.1): Likewise.

OK.

Ludo'.

[PATCH 4/4] build: Rewrite comments for man pages.

[Mathieu Lirzin]

* 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 file 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)
 	-@case '$?' 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`
 
-- 
2.7.0

Re: [PATCH 4/4] build: Rewrite comments for man pages.

[Ludovic Courtès]

Mathieu Lirzin <mthl@gnu.org> skribis:

> * doc.am <Man pages>: Rewrite comments to describe the build process and
> the meaning of the noticeable idiosyncrasies in a more general way.

OK.

Ludo'.

Re: [PATCH 0/4] Build man pages in $(srcdir).

[Ludovic Courtès]

Mathieu Lirzin <mthl@gnu.org> skribis:

> Anyway, inspired by what is done by Automake for info manuals I have tried to
> build man pages in $(srcdir), which is fixing the issue too.  The bonus is
> that now all the documentation is consistently built in $(srcdir) and that we
> avoid adding another "case $? ..." trick.

This sounds reasonable (in fact I wonder why we were not doing it
already given that things are supposed to live in $(srcdir)).

Did you confirm that ‘make distcheck’ passes after that, and that
‘help2man’ is not invoked when building from a tarball?

Thank you!

Ludo’.

Re: [PATCH 0/4] Build man pages in $(srcdir).

[Ludovic Courtès]

Also, do these changes preserve the benefits of
36629097523b0abd89d1b931293150cb9c1f242d (“build: Generate man pages
after compiling Guile objects.”)?

Looks like it, but I just wanna make sure.  :-)

Ludo’.

Re: [PATCH 0/4] Build man pages in $(srcdir).

[Mathieu Lirzin]

ludo@gnu.org (Ludovic Courtès) writes:

> Mathieu Lirzin <mthl@gnu.org> skribis:
>
>> Anyway, inspired by what is done by Automake for info manuals I have tried to
>> build man pages in $(srcdir), which is fixing the issue too.  The bonus is
>> that now all the documentation is consistently built in $(srcdir) and that we
>> avoid adding another "case $? ..." trick.
>
> This sounds reasonable (in fact I wonder why we were not doing it
> already given that things are supposed to live in $(srcdir)).

Why were you expecting such thing?

> Did you confirm that ‘make distcheck’ passes after that, and that
> ‘help2man’ is not invoked when building from a tarball?

I can't confirm for ‘make distcheck’ right now, because of:

--8<---------------cut here---------------start------------->8---
substitute: updating list of substitutes from 'http://hydra.gnu.org'...  33.3%
4 packages are not substitutable:
  /gnu/store/5apc4w376ls7fhydg08plc20agry7pn4-emacs-24.5
  /gnu/store/zfxj52lh6h6q7jmb1w2s34h004zsbaw3-emacs-24.5
  /gnu/store/10qcwd0gxypm977ksbvhjrpa4m1xk334-emacs-24.5
  /gnu/store/r8xphs9ka0lwmwhzxv6mfs9j8nm91843-emacs-24.5

Makefile:4913 : la recette pour la cible « assert-binaries-available » a échouée
--8<---------------cut here---------------end--------------->8---

However I have manually checked that with 'make dist' + (regular build or
VPATH build) 'help2man' is not invoked.

> Also, do these changes preserve the benefits of
> 36629097523b0abd89d1b931293150cb9c1f242d (“build: Generate man pages
> after compiling Guile objects.”)?

Yes it is.  That would be unacceptable if not.  ;)

-- 
Mathieu Lirzin

Re: [PATCH 0/4] Build man pages in $(srcdir).

[Ludovic Courtès]

Mathieu Lirzin <mthl@gnu.org> skribis:

> ludo@gnu.org (Ludovic Courtès) writes:
>
>> Mathieu Lirzin <mthl@gnu.org> skribis:
>>
>>> Anyway, inspired by what is done by Automake for info manuals I have tried to
>>> build man pages in $(srcdir), which is fixing the issue too.  The bonus is
>>> that now all the documentation is consistently built in $(srcdir) and that we
>>> avoid adding another "case $? ..." trick.
>>
>> This sounds reasonable (in fact I wonder why we were not doing it
>> already given that things are supposed to live in $(srcdir)).
>
> Why were you expecting such thing?

Because as you wrote, it’s how the .info target works, and
understandably so.

>> Did you confirm that ‘make distcheck’ passes after that, and that
>> ‘help2man’ is not invoked when building from a tarball?
>
> I can't confirm for ‘make distcheck’ right now, because of:
>
> substitute: updating list of substitutes from 'http://hydra.gnu.org'...  33.3%
> 4 packages are not substitutable:
>   /gnu/store/5apc4w376ls7fhydg08plc20agry7pn4-emacs-24.5
>   /gnu/store/zfxj52lh6h6q7jmb1w2s34h004zsbaw3-emacs-24.5
>   /gnu/store/10qcwd0gxypm977ksbvhjrpa4m1xk334-emacs-24.5
>   /gnu/store/r8xphs9ka0lwmwhzxv6mfs9j8nm91843-emacs-24.5
>
> Makefile:4913 : la recette pour la cible « assert-binaries-available » a échouée

I’m sure you’ll easily find how to annihilate the
‘assert-binaries-available’.  Find another excuse.  ;-)

> However I have manually checked that with 'make dist' + (regular build or
> VPATH build) 'help2man' is not invoked.

Good.

>> Also, do these changes preserve the benefits of
>> 36629097523b0abd89d1b931293150cb9c1f242d (“build: Generate man pages
>> after compiling Guile objects.”)?
>
> Yes it is.  That would be unacceptable if not.  ;)

Wonderful!

So we’re all set, aren’t we?

Thanks,
Ludo’.

Re: [PATCH 0/4] Build man pages in $(srcdir).

[Mathieu Lirzin]

ludo@gnu.org (Ludovic Courtès) writes:

> Mathieu Lirzin <mthl@gnu.org> skribis:
>
>> substitute: updating list of substitutes from 'http://hydra.gnu.org'...  33.3%
>> 4 packages are not substitutable:
>>   /gnu/store/5apc4w376ls7fhydg08plc20agry7pn4-emacs-24.5
>>   /gnu/store/zfxj52lh6h6q7jmb1w2s34h004zsbaw3-emacs-24.5
>>   /gnu/store/10qcwd0gxypm977ksbvhjrpa4m1xk334-emacs-24.5
>>   /gnu/store/r8xphs9ka0lwmwhzxv6mfs9j8nm91843-emacs-24.5
>>
>> Makefile:4913 : la recette pour la cible « assert-binaries-available » a échouée
>
> I’m sure you’ll easily find how to annihilate the
> ‘assert-binaries-available’.  Find another excuse.  ;-)

Sure. :)

I have overcame my laziness and I can now confirm ‘make distcheck’
works.

> So we’re all set, aren’t we?

Yes we are.  Pushed!

-- 
Mathieu Lirzin