modify functions hierarchy (was: Install run-help and *.zwc files system wide in build system)

[Martin Vaeth <vaeth@mathematik.uni-wuerzburg.de>]

This patch implements a mechanism which supports "source/" subdirs
in the function hierarchy:

The "source/" directories are included from installation, and for
source/*.in files corresponding sources are generated after
corresponding substitutions.
Currently, the only substitution made is for @runhelpdir@.

The patch uses the new mechanism to hardcode the configured
default of HELPDIR.

The patch also fixes minor issues related to the previous commits:

1. Since "helpdir" now tests for ztcp, also the Makefile.in
   now checks for the same file for consistency reasons.

2. The special symbols '.' and ':' are added to the _run-help completion

3. In the previous commits, the new files Doc/help/{.distfiles,.cvsignore}
   of the patch were not added to git; the patch produces them again.

Please do not forget the following things after applying the patch
and before commiting:

(a) rm Functions/Misc/run-help Completion/Zsh/Command/_run-help
    because patch will just create 0-size files from them

(b) chmod a+x Config/cleanfuncs.sh Config/createfuncs.sh
    not strictly necessary but for consistency

(c) Something like "git add --all ." so that the new files will really
    be added to git (so that 3. above does not happen again.)


Bart Schaefer <schaefer@brasslantern.com> wrote:
>
> Wouldn't the path of least resistence be to put _run_help.in in another
> directory and simply write it into the Completion tree from configure or
> Makefile?
>
> I'm having a bit of angst about how this interacts with having separate
> build and source trees, a build feature which I use frequently.

I have not tested the latter, but unless I have used false variables
by mistake, it should work as good (or, more precisely: as bad)
as your suggested "path of least resistence":

In any case the Completion tree (which is a "source" directory) is
modified (the new files are created or removed, respectively).
This is not really optimal, since it would be preferrable that
no produced files are written to any "source" directory.
However, "fixing" this would need a completely modified approach
of copying the whole functions hierarchy to the build directory
which is not good, either. I do not want to suggest that a
fundamental change to the build system.

--- 1/.gitignore
+++ 1/.gitignore
@@ -25,6 +25,8 @@
 /stamp-h.in
 /autom4te.cache
 
+Completion/Zsh/Command/_run-help
+
 Config/defs.mk
 
 CVS
@@ -73,6 +75,8 @@
 Etc/FAQ
 Etc/FAQ.html
 
+Functions/Misc/run-help
+
 Src/*.epro
 Src/*.export
 Src/*.mdh
--- 1/Completion/Zsh/Command/.cvsignore
+++ 1/Completion/Zsh/Command/.cvsignore
@@ -0,0 +1 @@
+_run-help
--- 1/Completion/Zsh/Command/_run-help
+++ 1/Completion/Zsh/Command/_run-help
@@ -1,7 +0,0 @@
-#compdef run-help
-local d expl
-local HELPDIR=${HELPDIR:-/usr/share/zsh/$ZSH_VERSION/help}
-[[ -d $HELPDIR ]] && {
-	d=($HELPDIR/*(:t))
-	(($#d)) && _wanted commands expl 'command' compadd -a d
-} || _man
--- 1/Completion/Zsh/Command/source/.distfiles
+++ 1/Completion/Zsh/Command/source/.distfiles
@@ -0,0 +1,4 @@
+DISTFILES_SRC='
+.distfiles
+_run-help.in
+'
--- 1/Completion/Zsh/Command/source/_run-help.in
+++ 1/Completion/Zsh/Command/source/_run-help.in
@@ -0,0 +1,7 @@
+#compdef run-help
+local d expl
+local HELPDIR=${HELPDIR:-@runhelpdir@}
+[[ -d $HELPDIR ]] && {
+	d=($HELPDIR/*(:t))
+	(($#d)) && d+=('.' ':') && _wanted commands expl 'command' compadd -a d
+} || _man
--- 1/Config/cleanfns.sh
+++ 1/Config/cleanfns.sh
@@ -0,0 +1,22 @@
+#!/bin/sh
+
+allfuncs="`grep ' functions=.' ${dir_top}/config.modules |
+  sed -e '/^#/d' -e '/ link=no/d' -e 's/^.* functions=//'`"
+
+allfuncs="`cd $sdir_top; echo ${allfuncs}`"
+
+for file in $allfuncs; do
+  if test -d $sdir_top/$file; then
+    case "$file" in
+      */CVS/*|*/source/*)
+        continue
+      ;;
+      */source)
+        for source in $sdir_top/$file/*.in; do
+          destfile=$sdir_top/`echo $source | sed -e 's%source/\([^/]*\)\.in$%\1%'`
+          rm -f "$destfile"
+        done
+      ;;
+    esac
+  fi
+done
--- 1/Config/createfns.sh
+++ 1/Config/createfns.sh
@@ -0,0 +1,28 @@
+#!/bin/sh
+
+test "x$runhelpdir" = x && runhelpdir='/usr/share/zsh/$ZSH_VERSION/help'
+
+allfuncs="`grep ' functions=.' ${dir_top}/config.modules |
+  sed -e '/^#/d' -e '/ link=no/d' -e 's/^.* functions=//'`"
+
+allfuncs="`cd $sdir_top; echo ${allfuncs}`"
+
+for file in $allfuncs; do
+  if test -d $sdir_top/$file; then
+    case "$file" in
+      */CVS/*|*/source/*)
+        continue
+      ;;
+      */source)
+        for source in $sdir_top/$file/*.in; do
+          destfile=$sdir_top/`echo $source | sed -e 's%source/\([^/]*\)\.in$%\1%'`
+          rm -f "$destfile"
+          sed -e "s'@runhelpdir@'${runhelpdir}'" "$sdir_top/$source" >"$destfile" || {
+            echo "sed failed for $destfile"
+            exit 1
+          }
+        done
+      ;;
+    esac
+  fi
+done
--- 1/Config/installfns.sh
+++ 1/Config/installfns.sh
@@ -15,7 +15,7 @@
 for file in $allfuncs; do
   if test -f $sdir_top/$file; then
     case "$file" in
-      */CVS/*) continue;;
+      */CVS/*|*/source|*/source/*) continue;;
     esac
     if test x$FUNCTIONS_SUBDIRS != x && test x$FUNCTIONS_SUBDIRS != xno; then
       case "$file" in
--- 1/Doc/Makefile.in
+++ 1/Doc/Makefile.in
@@ -187,10 +187,10 @@
 
 runhelp: man
 	test x"$(runhelpdir)" = x"" || { \
-	    test -r $(sdir)/help.txt && test -r $(sdir)/help/zmodload; \
+	    test -r $(sdir)/help.txt && test -r $(sdir)/help/ztcp; \
 	} || perl $(sdir_top)/Util/helpfiles \
 	    $(sdir)/zshbuiltins.1 $(sdir)/help $(sdir)/help.txt \
-	    || { rm -f $(sdir)/help.txt $(sdir)/help/zmodload; false; }
+	    || { rm -f $(sdir)/help.txt $(sdir)/help/ztcp; false; }
 .PHONY: runhelp
 
 $(MAN): zmacros.yo zman.yo
--- 1/Doc/help/.cvsignore
+++ 1/Doc/help/.cvsignore
@@ -0,0 +1 @@
+[_a-zA-Z0-9]*
--- 1/Doc/help/.distfiles
+++ 1/Doc/help/.distfiles
@@ -0,0 +1,4 @@
+DISTFILES_SRC='
+    .cvsignore .distfiles
+    [_a-zA-Z0-9]*
+'
--- 1/Functions/Misc/.cvsignore
+++ 1/Functions/Misc/.cvsignore
@@ -0,0 +1 @@
+run-help
--- 1/Functions/Misc/.distfiles
+++ 1/Functions/Misc/.distfiles
@@ -1,4 +1,5 @@
 DISTFILES_SRC='
+.cvsignore
 .distfiles
 add-zsh-hook
 allopt
@@ -12,7 +13,6 @@
 promptnl
 regexp-replace
 relative
-run-help
 run-help-git
 run-help-openssl
 run-help-p4
--- 1/Functions/Misc/run-help
+++ 1/Functions/Misc/run-help
@@ -1,126 +0,0 @@
-#!/bin/zsh
-#
-# Figure out where to get the best help, and get it.
-#
-# Install this function by placing it in your FPATH and then
-# adding to your .zshrc the lines:
-#	unalias run-help
-#	autoload -Uz run-help
-#
-
-emulate -RL zsh
-
-local HELPDIR="${HELPDIR:-/usr/share/zsh/$ZSH_VERSION/help}"
-
-[[ $1 == "." ]] && 1="dot"
-[[ $1 == ":" ]] && 1="colon"
-
-# Check whether Util/helpfiles has been used to generate zsh help
-if [[ $# == 0 || $1 == "-l" ]]
-then
-    if [[ -d $HELPDIR ]]
-    then
-	echo "Here is a list of topics for which special help is available:"
-	echo ""
-	print -rc $HELPDIR/*(:t)
-    else
-	echo "There is no list of special help topics available at this time."
-    fi
-    return 0
-elif [[ -n "${HELPDIR:-}" && -r $HELPDIR/$1 && $1 != compctl ]]
-then
-    ${=PAGER:-more} $HELPDIR/$1
-    return $?
-fi
-
-# No zsh help; use "whence" to figure out where else we might look
-local what places noalias newline='
-'
-integer i=0 didman=0
-
-places=( "${(@f)$(builtin whence -va $1)}" )
-if [[ $places = *"not found"* && $1 != ${(Q)1} ]]; then
-  # Different when unquoted, so try stripping quotes.
-  places=( "${(@f)$(builtin whence -va ${(Q)1})}" )
-  if (( ${#places} )); then
-      set -- "${(Q)@}"
-  fi
-  # Quotation is significant to aliases, so suppress lookup.
-  noalias=1
-fi
-
-{
-while ((i++ < $#places))
-do
-    what=$places[$i]
-    [[ -n $noalias && $what = *" is an alias "* ]] && continue
-    builtin print -r $what
-    case $what in
-    (*( is an alias for (noglob|nocorrect))*)
-	[[ ${what[(w)7]:t} != ${what[(w)1]} ]] &&
-	  run_help_orig_cmd=${what[(w)1]} run-help ${what[(w)7]:t}
-	;;
-    (*( is an alias)*)
-	[[ ${what[(w)6]:t} != ${what[(w)1]} ]] &&
-	  run_help_orig_cmd=${what[(w)1]} run-help ${what[(w)6]:t}
-	;;
-    (*( is a * function))
-	case ${what[(w)1]} in
-	(comp*) man zshcompsys;;
-	(zf*) man zshftpsys;;
-	(run-help) man zshcontrib;;
-	(*) builtin functions ${what[(w)1]} | ${=PAGER:-more};;
-	esac;;
-    (*( is a * builtin))
-	case ${what[(w)1]} in
-	(compctl) man zshcompctl;;
-	(comp*) man zshcompwid;;
-	(bindkey|vared|zle) man zshzle;;
-	(*setopt) man zshoptions;;
-	(cap|getcap|setcap) ;&
-	(clone) ;&
-	(ln|mkdir|mv|rm|rmdir|sync) ;&
-	(sched) ;&
-	(echotc|echoti|sched|stat|zprof|zpty|zsocket|zstyle|ztcp) man zshmodules;;
-	(zftp) man zshftpsys;;
-	(*) man zshbuiltins;;
-	esac
-	;;
-    (*( is hashed to *))
-	man ${what[(w)-1]:t}
-	;;
-    (*( is a reserved word))
-	man zshmisc
-	;;
-    (*)
-	if ((! didman++))
-	then
-	    if whence "run-help-$1:t" >/dev/null
-	    then
-		local cmd_args
-		builtin getln cmd_args
-		builtin print -z "$cmd_args"
-		cmd_args=( ${(z)cmd_args} )
-		# Discard environment assignments, etc.
-		while [[ $cmd_args[1] != ${run_help_orig_cmd:-$1} ]]
-		do
-		    shift cmd_args || return 1
-		done
-		eval "run-help-$1:t ${(q@)cmd_args[2,-1]}"
-	    else
-		POSIXLY_CORRECT=1 man $@:t
-	    fi
-	fi
-	;;
-    esac
-    if ((i < $#places && ! didman))
-    then
-	builtin print -nP "%SPress any key for more help or q to quit%s"
-	builtin read -k what
-	[[ $what != $newline ]] && echo
-	[[ $what == [qQ] ]] && break
-    fi
-done
-} always {
-  unset run_help_orig_cmd
-}
--- 1/Functions/Misc/source/.distfiles
+++ 1/Functions/Misc/source/.distfiles
@@ -0,0 +1,4 @@
+DISTFILES_SRC='
+.distfiles
+run-help.in
+'
--- 1/Functions/Misc/source/run-help.in
+++ 1/Functions/Misc/source/run-help.in
@@ -0,0 +1,126 @@
+#!/bin/zsh
+#
+# Figure out where to get the best help, and get it.
+#
+# Install this function by placing it in your FPATH and then
+# adding to your .zshrc the lines:
+#	unalias run-help
+#	autoload -Uz run-help
+#
+
+emulate -RL zsh
+
+local HELPDIR="${HELPDIR:-@runhelpdir@}"
+
+[[ $1 == "." ]] && 1="dot"
+[[ $1 == ":" ]] && 1="colon"
+
+# Check whether Util/helpfiles has been used to generate zsh help
+if [[ $# == 0 || $1 == "-l" ]]
+then
+    if [[ -d $HELPDIR ]]
+    then
+	echo "Here is a list of topics for which special help is available:"
+	echo ""
+	print -rc $HELPDIR/*(:t)
+    else
+	echo "There is no list of special help topics available at this time."
+    fi
+    return 0
+elif [[ -n "${HELPDIR:-}" && -r $HELPDIR/$1 && $1 != compctl ]]
+then
+    ${=PAGER:-more} $HELPDIR/$1
+    return $?
+fi
+
+# No zsh help; use "whence" to figure out where else we might look
+local what places noalias newline='
+'
+integer i=0 didman=0
+
+places=( "${(@f)$(builtin whence -va $1)}" )
+if [[ $places = *"not found"* && $1 != ${(Q)1} ]]; then
+  # Different when unquoted, so try stripping quotes.
+  places=( "${(@f)$(builtin whence -va ${(Q)1})}" )
+  if (( ${#places} )); then
+      set -- "${(Q)@}"
+  fi
+  # Quotation is significant to aliases, so suppress lookup.
+  noalias=1
+fi
+
+{
+while ((i++ < $#places))
+do
+    what=$places[$i]
+    [[ -n $noalias && $what = *" is an alias "* ]] && continue
+    builtin print -r $what
+    case $what in
+    (*( is an alias for (noglob|nocorrect))*)
+	[[ ${what[(w)7]:t} != ${what[(w)1]} ]] &&
+	  run_help_orig_cmd=${what[(w)1]} run-help ${what[(w)7]:t}
+	;;
+    (*( is an alias)*)
+	[[ ${what[(w)6]:t} != ${what[(w)1]} ]] &&
+	  run_help_orig_cmd=${what[(w)1]} run-help ${what[(w)6]:t}
+	;;
+    (*( is a * function))
+	case ${what[(w)1]} in
+	(comp*) man zshcompsys;;
+	(zf*) man zshftpsys;;
+	(run-help) man zshcontrib;;
+	(*) builtin functions ${what[(w)1]} | ${=PAGER:-more};;
+	esac;;
+    (*( is a * builtin))
+	case ${what[(w)1]} in
+	(compctl) man zshcompctl;;
+	(comp*) man zshcompwid;;
+	(bindkey|vared|zle) man zshzle;;
+	(*setopt) man zshoptions;;
+	(cap|getcap|setcap) ;&
+	(clone) ;&
+	(ln|mkdir|mv|rm|rmdir|sync) ;&
+	(sched) ;&
+	(echotc|echoti|sched|stat|zprof|zpty|zsocket|zstyle|ztcp) man zshmodules;;
+	(zftp) man zshftpsys;;
+	(*) man zshbuiltins;;
+	esac
+	;;
+    (*( is hashed to *))
+	man ${what[(w)-1]:t}
+	;;
+    (*( is a reserved word))
+	man zshmisc
+	;;
+    (*)
+	if ((! didman++))
+	then
+	    if whence "run-help-$1:t" >/dev/null
+	    then
+		local cmd_args
+		builtin getln cmd_args
+		builtin print -z "$cmd_args"
+		cmd_args=( ${(z)cmd_args} )
+		# Discard environment assignments, etc.
+		while [[ $cmd_args[1] != ${run_help_orig_cmd:-$1} ]]
+		do
+		    shift cmd_args || return 1
+		done
+		eval "run-help-$1:t ${(q@)cmd_args[2,-1]}"
+	    else
+		POSIXLY_CORRECT=1 man $@:t
+	    fi
+	fi
+	;;
+    esac
+    if ((i < $#places && ! didman))
+    then
+	builtin print -nP "%SPress any key for more help or q to quit%s"
+	builtin read -k what
+	[[ $what != $newline ]] && echo
+	[[ $what == [qQ] ]] && break
+    fi
+done
+} always {
+  unset run_help_orig_cmd
+}
--- 1/Makefile.in
+++ 1/Makefile.in
@@ -34,6 +34,7 @@
 VPATH           = @srcdir@
 sdir            = @srcdir@
 sdir_top        = @top_srcdir@
+runhelpdir      = @runhelpdir@
 INSTALL         = @INSTALL@
 
 @DEFS_MK@
@@ -41,11 +42,19 @@
 # ========== DEPENDENCIES FOR BUILDING ==========
 
 # default target
-all: config.h config.modules
+all: config.h config.modules create.fns
 	@for subdir in Src Doc; do \
 	  (cd $$subdir && $(MAKE) $(MAKEDEFS) $@) || exit 1; \
 	done
 
+# create recursively the shell functions from source/*.in
+create.fns: config.modules
+	sdir_top="$(sdir_top)" fndir="$(fndir)" dir_top="$(dir_top)" \
+	scriptdir="$(scriptdir)" \
+	runhelpdir="$(runhelpdir)" \
+	$(SHELL) $(sdir_top)/Config/createfns.sh
+.PHONY: create.fns
+
 # prepare module configuration
 prep:
 	@cd Src && $(MAKE) $(MAKEDEFS) $@
@@ -69,18 +78,22 @@
 # install/uninstall just the binary
 install.bin uninstall.bin:
 	@cd Src && $(MAKE) $(MAKEDEFS) $@
+.PHONY: install.bin uninstall.bin
 
 # install/uninstall just the modules
 install.modules uninstall.modules:
 	@cd Src && $(MAKE) $(MAKEDEFS) $@
+.PHONY: install.modules uninstall.modules
 
 # install/uninstall just the man pages
 install.man uninstall.man:
 	@cd Doc && $(MAKE) $(MAKEDEFS) $@
+.PHONY: install.man uninstall.man
 
 # install/uninstall just the runhelp files
 install.runhelp uninstall.runhelp:
 	@cd Doc && $(MAKE) $(MAKEDEFS) $@
+.PHONY: install.runhelp uninstall.runhelp
 
 # install/uninstall just the shell functions
 install.fns:
@@ -96,6 +109,7 @@
 	  $(SHELL) $(sdir_top)/Config/installfns.sh || exit 1; \
 	fi; \
 	exit 0
+.PHONY: install.fns
 
 uninstall.fns:
 	if test x$(fndir) != x && test x$(fndir) != xno; then \
@@ -106,14 +120,17 @@
 	  $(SHELL) $(sdir_top)/Config/uninstallfns.sh || exit 1; \
 	fi; \
 	exit 0
+.PHONY: uninstall.fns
 
 # install/uninstall just the info pages
 install.info uninstall.info:
 	@cd Doc && $(MAKE) $(MAKEDEFS) $@
+.PHONY: install.info uninstall.info
 
 # install/uninstall just the HTML manual
 install.html uninstall.html:
 	@cd Doc && $(MAKE) $(MAKEDEFS) $@
+.PHONY: install.html uninstall.html
 
 # ========== DEPENDENCIES FOR TESTING ==========
 check test:
@@ -123,6 +140,11 @@
 
 @CLEAN_MK@
 
+clean-here: config.modules
+	sdir_top="$(sdir_top)" fndir="$(fndir)" dir_top="$(dir_top)" \
+	scriptdir="$(scriptdir)" \
+	$(SHELL) $(sdir_top)/Config/cleanfns.sh
+
 distclean-here:
 	rm -f Makefile config.h config.status config.log config.cache config.modules config.modules.sh stamp-h Config/defs.mk
 	rm -rf autom4te.cache