Re: Installing gnulib from git

[Bruno Haible]

Hi Jim,

> Do you mind if I factor that?
> 
>     html info:
>             cd doc && $(MAKE) $@
> 
>     dvi pdf:
>             cd doc && $(MAKE) $@ && $(MAKE) mostlyclean

No problem with this.

> or even (with or without the mostlyclean):
> 
>     dvi html info pdf:
>             cd doc && $(MAKE) $@

Actually the 'mostlyclean' is needed also for the 'html' and 'info' targets,
in order to remove the 'updated-stamp' file created by doc/Makefile. I've
applied the appended patch.

> But I'd leave out the mostlyclean

The toplevel Makefile is meant for the casual user. He certainly does not
want "ls doc" or "git status" to display a dozen (or even a single)
uncommitted file that he has not asked for.

> or rename it to something 
> less suspicious sounding.  In automake-generated Makefiles,
> mostlyclean removes far more than the hand-coded rule in
> gnulib's doc/Makefile does.

'mostlyclean' cleans all files that are created by "make", except those
that people normally want to keep. It's the target people are meant to
invoke when they see "There's too much clutter in this directory".
This is what doc/Makefile does.

By comparison, the automake generated gettext/gettext-tools/doc/Makefile
does this:

$ make -n mostlyclean
rm -rf gettext.am gettext.ams gettext.aux gettext.cp gettext.cps gettext.ef \
          gettext.em gettext.ems gettext.ev gettext.fn gettext.kw \
          gettext.ky gettext.kys gettext.log gettext.op gettext.ops \
          gettext.pg gettext.pgs gettext.tmp gettext.toc gettext.tp \
          gettext.tps gettext.vr gettext.vrs gettext.dvi gettext.pdf \
          gettext.ps gettext.html
test -z "gettext.am gettext.ams gettext.cp gettext.cps gettext.ef gettext.efs 
gettext.em gettext.ems gettext.ev gettext.evs gettext.fn gettext.fns gettext.kw 
gettext.kws gettext.op gettext.ops gettext.pg gettext.pgs gettext.vr 
gettext.vrs" || rm -f gettext.am gettext.ams gettext.cp gettext.cps gettext.ef 
gettext.efs gettext.em gettext.ems gettext.ev gettext.evs gettext.fn 
gettext.fns gettext.kw gettext.kws gettext.op gettext.ops gettext.pg 
gettext.pgs gettext.vr gettext.vrs
rm -f *.lo
rm -f vti.tmp

So, it removes the temporary files and also the {html,dvi,ps,pdf} formatted
documentation but keeps the info formatted documentation. Why does it treat
the various formats differently? For the {dvi,ps} formats this is (arguably)
a bug in automake, and for the {html,pdf} formats a bug in gettext's
doc/Makefile.am.

> A doc-*creation* rule like "make info" that automatically runs any
> "clean"-like rule would seem to violate the principle of least surprise.

In contrary, a "make info" rule that creates other files out of the blue,
than the actual info files, and does not remove them, violates the principle
of least surprise. Which is acceptable for a experienced user, but unwanted
for a casual user like Reuben Thomas who looked around how he could create
the documentation.

Bruno


2009-04-02  Bruno Haible  <address@hidden>

        * Makefile (info, html, dvi, pdf): Combine the rules.
        Suggested by Jim Meyering.

--- Makefile.orig       2009-04-02 12:37:46.000000000 +0200
+++ Makefile    2009-04-02 12:36:52.000000000 +0200
@@ -9,14 +9,8 @@
 all:
 
 # Produce the documentation in readable form.
-info:
-       cd doc && $(MAKE) info
-html:
-       cd doc && $(MAKE) html
-dvi:
-       cd doc && $(MAKE) dvi && $(MAKE) mostlyclean
-pdf:
-       cd doc && $(MAKE) pdf && $(MAKE) mostlyclean
+info html dvi pdf:
+       cd doc && $(MAKE) $@ && $(MAKE) mostlyclean
 
 # Perform some platform independent checks on the gnulib code.
 check: