[OpenAFS-devel] pod2man vandalism

[C. Alex. North-Keys]

Russ Allbery wrote:
> Russ Allbery <rra@stanford.edu> writes:
> 
>>Well, if we're going to go to the trouble of running a script anyway,
>>why not just do all the work in the script and save the complexity?  The
>>only advantage to make at that point is to only rebuild the man pages
>>that have changed, but rebuilding all of them doesn't take very long.
> 
> Hm, actually, I take that back -- it looks like, depending on the tools
> one has installed, it can take a little while to rebuild man pages.  So
> maybe this is worthwhile doing.

[Omitting my own similar reply to the prior message]

> It would be so nice to use GNU make features for this sort of thing.
> $(notdir $(wildmat pod1/*.pod)) is *exactly* what one wants and is much
> more readable than the shell equivalent.  Oh well.

Well, the find is portable, and substantially more versatile.  Why 
restrict your .pod files to all being exactly one level down in a large 
project when you can litter the raw source directory with them so the 
developers might remember to update the per-sourcefile function docs? 
(Okay, so that doesn't work either - we had to embed the docs in the 
code to get developers to keep them current)

Anyway, put in the main Makefile a target that uses shell (or 
shell/perl) to generate a Makefile-pod with the right targets, then 
automatically calls make -f Makefile-pod to finish up.  This way you 
don't have to have a wart in your user-visible build process, and you 
don't have to mess with whether the system's variety of make can deal 
with run-time determined inclusions or something.

I also like to have an INSTALLS variable with a list of all the 
installed locations for the files (like /usr/man/man1/fluffy.1 or 
whatever), then a rule for copying from the source to the target 
locations, yielding:

install : $(INSTALLS)

And rules like (although these were from GNU make):

$(DESTDOC)/%: %
     $(insure_directory_exists_and_clear_target)
     $(INSTALL_DATA) $< $@

$(DESTLIB)/%: %
     $(insure_directory_exists_and_clear_target)
     $(INSTALL_DATA) $< $@
     @case $< in lib*.a) $(RANLIB) $@ ;; esac

So the delightful efficiency of make even works on the last step :-)

-- 
C. Alex. North-Keys
Catalis, Inc.
erlkonig@TheCatalis.com
512.874.7666