31959 (plus tweak to .gitignore): make help files during installation

.gitignore

@@ -30,6 +30,10 @@ Config/defs.mk
 CVS
 .#*
 
+Doc/help.txt
+Doc/help
+Doc/help/[_a-zA-Z0-9]*
+
 Doc/intro.a4.pdf
 Doc/intro.a4.ps
 Doc/intro.us.pdf

ChangeLog

@@ -1,5 +1,11 @@
 2013-11-12  Peter Stephenson  <p.w.stephenson@ntlworld.com>
 
+	* Martin Vaeth: 31959: .gitignore,
+	Completion/Zsh/Command/_run-help, Doc/.cvsignore,
+	Doc/.distfiles, Doc/Makefile.in, Makefile.in,
+	StartupFiles/zshrc, Util/helpfiles, configure.ac: make help
+	files during installation.
+
 	* 31961: Src/Zle/zle.h, Src/Zle/zle_main.c,
 	Src/Zle/zle_thingy.c: rationalise fd watch to use structures.
 

Completion/Zsh/Command/_run-help

@@ -0,0 +1,7 @@
+#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

Doc/.cvsignore

@@ -1,4 +1,5 @@
 Makefile
+help.txt
 version.yo
 zsh*.1
 zsh.texi

Doc/.distfiles

@@ -11,6 +11,7 @@ DISTFILES_SRC='
     zshcompctl.1 zshcompsys.1 zshcompwid.1 zshexpn.1
     zshmisc.1 zshmodules.1 zshoptions.1 zshparam.1 zshroadmap.1
     zshzle.1 zshall.1 zshzftpsys.1 zshcontrib.1 zshtcpsys.1
+    help.txt
 '
 
 DISTFILES_DOC='

Doc/Makefile.in

@@ -33,7 +33,9 @@ dir_top = ..
 VPATH           = @srcdir@
 sdir            = @srcdir@
 sdir_top        = @top_srcdir@
+runhelpdir      = @runhelpdir@
 INSTALL         = @INSTALL@
+LN_S            = @LN_S@
 
 @DEFS_MK@
 
@@ -82,7 +84,7 @@ Zsh/seealso.yo Zsh/tcpsys.yo Zsh/zftpsys.yo Zsh/zle.yo
 
 # ========== DEPENDENCIES FOR BUILDING ==========
 
-all: man texi ../META-FAQ
+all: man runhelp texi ../META-FAQ
 .PHONY: all
 
 everything: all dvi html pdf info
@@ -183,6 +185,14 @@ $(sdir)/zsh.texi: $(YODLSRC)
 man: $(MAN)
 .PHONY: man
 
+runhelp: man
+	test x"$(runhelpdir)" = x"" || { \
+	    test -r $(sdir)/help.txt && test -r $(sdir)/help/zmodload; \
+	} || perl $(sdir_top)/Util/helpfiles $(lc_ctype) -- \
+	    $(sdir)/zshbuiltins.1 $(sdir)/help $(sdir)/help.txt \
+	    || { rm -f $(sdir)/help.txt $(sdir)/help/zmodload; false; }
+.PHONY: runhelp
+
 $(MAN): zmacros.yo zman.yo
 
 zsh.1 zshall.1: Zsh/intro.yo Zsh/metafaq.yo Zsh/invoke.yo Zsh/files.yo \
@@ -285,12 +295,12 @@ Zsh/manmodmenu.yo: $(MODDOCSRC)
 
 # ========== DEPENDENCIES FOR INSTALLING ==========
 
-# install just installs the manual pages
-install: install.man
+# install just installs the manual and runhelp pages
+install: install.man install.runhelp
 .PHONY: install
 
-# uninstall just unistalls the manual pages
-uninstall: uninstall.man
+# uninstall just uninstalls the manual and runhelp pages
+uninstall: uninstall.man uninstall.runhelp
 .PHONY: uninstall
 
 # install man pages, creating install directory if necessary
@@ -302,6 +312,18 @@ install.man: man
 	done
 .PHONY: install.man
 
+# install runhelp pages, creating install directory if necessary
+install.runhelp: runhelp
+	if test x"$(runhelpdir)" != x""; then \
+	    ${SHELL} $(sdir_top)/mkinstalldirs $(DESTDIR)$(runhelpdir); \
+	    $(INSTALL_DATA) $(sdir)/help/* $(DESTDIR)$(runhelpdir); \
+	    while read from to; do \
+	        rm -f $(DESTDIR)$(runhelpdir)/$$to || : ; \
+	        $(LN_S) $$from $(DESTDIR)$(runhelpdir)/$$to; \
+	    done < $(sdir)/help.txt; \
+	fi
+.PHONY: install.runhelp
+
 # install info pages, creating install directory if necessary
 install.info: texi
 	${SHELL} $(sdir_top)/mkinstalldirs $(DESTDIR)$(infodir)
@@ -334,6 +356,11 @@ uninstall.man:
 	done
 .PHONY: uninstall.man
 
+# uninstall runhelp pages
+uninstall.runhelp:
+	test x"$(runhelpdir)" = x"" || rm -rf -- $(DESTDIR)$(runhelpdir)
+.PHONY: uninstall.runhelp
+
 # uninstall info pages
 uninstall.info:
 	rm -f $(DESTDIR)$(infodir)/$(tzsh).info

Makefile.in

@@ -63,8 +63,8 @@ install-strip:
 	$(MAKE) install STRIPFLAGS="-s"
 
 # install/uninstall most things
-install: install.bin install.modules install.fns install.man
-uninstall: uninstall.bin uninstall.modules uninstall.fns uninstall.man
+install: install.bin install.modules install.fns install.man install.runhelp
+uninstall: uninstall.bin uninstall.modules uninstall.fns uninstall.man uninstall.runhelp
 
 # install/uninstall just the binary
 install.bin uninstall.bin:
@@ -78,6 +78,10 @@ install.modules uninstall.modules:
 install.man uninstall.man:
 	@cd Doc && $(MAKE) $(MAKEDEFS) $@
 
+# install/uninstall just the runhelp files
+install.runhelp uninstall.runhelp:
+	@cd Doc && $(MAKE) $(MAKEDEFS) $@
+
 # install/uninstall just the shell functions
 install.fns:
 	if test x$(fndir) != x && test x$(fndir) != xno; then \

StartupFiles/zshrc

@@ -75,7 +75,7 @@ RPROMPT=' %~'     # prompt for right side of screen
 # Some environment variables
 export MAIL=/var/spool/mail/$USERNAME
 export LESS=-cex3M
-export HELPDIR=/usr/local/lib/zsh/help  # directory for run-help function to find docs
+export HELPDIR=/usr/share/zsh/$ZSH_VERSION/help  # directory for run-help function to find docs
 
 MAILCHECK=300
 HISTSIZE=200

Util/helpfiles

@@ -2,8 +2,10 @@
 
 # helpfiles:  make help files for Z-shell builtins from the manual entries.
 
-# Create help files for zsh commands in the current directory;
-# assumes no other files are present.
+# Create help files for zsh commands for the manpage file of zshbuildins.1
+# passed as the first arg.
+# The second arg is the directory in which the help files will be created.
+# Assumes no other files are present.
 # No overwriting check;  `.' becomes `dot', `:' becomes `colon'.
 
 # Any command claiming to be `same as <foo>' or `equivalent to <foo>'
@@ -11,14 +13,11 @@
 # link to <foo>.  (Arguably the help file should be put at the start
 # instead.)
 
-# Takes one filename argument, or stdin: the zsh manual page as a plain
-# ascii file: `man zshbuiltins | colcrt -' (remember the -) should do
-# the trick.
+# If a third arg is given, the symlink is not created, but a
+# list of symlinks is put into the file specified by that arg.
 
-# If you don't have colcrt, try 'col -bx'.  The x is necessary so that
-# spaces don't turn into tabs, which messes up the calculations of
-# indentation on machines which randomly wrap lines round to the
-# previous line (so you see what we're up against).
+# Optionally, you can pass -fLC_CTYPE as an additional first argument.
+# If do that, this LC_CTYPE is used instead of one specified by a heuristic.
 
 # Example usage:
 #    cd ~/zsh-4.0.1				# or wherever
@@ -39,7 +38,82 @@
 #    }
 # now <Esc>-h works for shell builtins.
 
-while (<>) {
+sub Usage {
+    print(STDERR "Usage: helpfiles [-fLC_CTYPE] zshbuiltins.1 dest-dir [link-file]\n");
+    exit(1);
+}
+
+sub Info {
+    print('helpfiles: ', @_, "\n");
+}
+
+sub Die {
+    print(STDERR 'helpfiles: ', @_, "\n");
+    exit(1);
+}
+
+&Usage() unless(@ARGV);
+delete($ENV{'LC_ALL'});
+$ENV{'LANG'} = 'C';
+if($ARGV[0] =~ /-f(.*)/) {
+    $lc_type = $1;
+    shift(@ARGV);
+    &Usage() unless(@ARGV);
+    if($lc_type eq '') {
+        $lc_type = shift(@ARGV);
+        &Usage() unless(@ARGV);
+    }
+} else {
+    open(LOCALE, '-|', 'locale', '-a') || &Die('cannot execute locale -a');
+    $lc_ctype = '';
+    $choice = 0;
+    while(<LOCALE>) {
+        if(/en.*utf8/i) {
+            $lc_ctype = $_;
+            last;
+        } elsif(/utf8/i) {
+            $lc_ctype = $_;
+            $choice = 2;
+        } elsif(($choice < 1) && (/(en)|\./i)) {
+            $lc_ctype = $_;
+            $choice = 1;
+        }
+    }
+    close(LOCALE);
+}
+&Info("using LC_CTYPE=$lc_ctype");
+$ENV{'LC_CTYPE'} = $lc_ctype unless($lc_ctype eq '');
+shift(@ARGV) if($ARGV[0] eq '--');
+&Usage() unless(@ARGV);
+$manfile = shift(@ARGV);
+&Usage() unless(@ARGV);
+$destdir = shift(@ARGV);
+$linkfile = ((@ARGV) ? shift(@ARGV) : '');
+unless(-d $destdir) {
+    mkdir($destdir) || &Die("$destdir is not a directory and cannot be created");
+}
+
+delete($ENV{'MANPL'});
+delete($ENV{'MANROFFSEQ'});
+$ENV{'MANWIDTH'} = '80';
+$ENV{'GROFF_NO_SGR'} = ''; # We need "classical" formatting of man pages.
+
+unless(open(MANPAGE, '-|', "man $manfile | colcrt -")) {
+    close(MANPAGE);
+    open(MANPAGE, '-|', "man $manfile | col -bx")
+# The x is necessary so that spaces don't turn into tabs, which messes
+# up the calculations of indentation on machines which randomly wrap lines
+# round to the previous line (so you see what we're up against).
+     || &Die('can run neither "man | colcrt -" nor "man | col -bx"');
+}
+
+unless($linkfile eq '') {
+    open(LINKFILE, '>', $linkfile) || &Die("cannot open $linkfile for writing")
+}
+
+chdir($destdir) || &Die("cannot cd to $destdir");
+
+while (<MANPAGE>) {
     last if /^\s*SHELL BUILTIN COMMANDS/;
     /zshbuiltins/ && $zb++;
     last if ($zb && /^\s*DESCRIPTIONS/);
@@ -93,7 +167,7 @@ sub doprint {
     print;
 }
 
-while (<>) { last unless /^\s*$/; }
+while (<MANPAGE>) { last unless /^\s*$/; }
 
 /^(\s+)(\S+)/;
 $indentstr = $1;
@@ -101,13 +175,13 @@ $indent = length($1);
 &newcmd($2);
 print if $print;
 
-BUILTINS: while (<>) {
+BUILTINS: while (<MANPAGE>) {
     next if /^\w/;
 
     undef($undented);
     if (/^\s*$/ || ($undented = (/^(\s*)/  && length($1) < $indent))) {
 	$undented && &doprint($_);
-	while (defined($_ = <>) && /(^\w)|(^\s*$)/) {
+	while (defined($_ = <MANPAGE>) && /(^\w)|(^\s*$)/) {
 	    # NAME is the start of the next section when in zshall.
 	    # (Historical note: we used to exit on the page header,
 	    # but text from the old section can continue to the
@@ -118,11 +192,11 @@ BUILTINS: while (<>) {
 	}
         if (/^\s*Page/ || /^zsh.*\s\d$/) {
 	    do {
-		$_ = <>;
+		$_ = <MANPAGE>;
 	    } while (defined($_) && /^\s*$/);
 	    if (/^\s*ZSHBUILTINS/) {
 		do {
-		    $_ = <>;
+		    $_ = <MANPAGE>;
 		} while (defined($_) && /^\s*$/);
 	    }
 	}
@@ -132,7 +206,7 @@ BUILTINS: while (<>) {
 	    s/^\s*/ /;
 	    $defer = $_;
 	    do {
-		$_ = <>;
+		$_ = <MANPAGE>;
 	    } while (defined($_) && /^\s*$/);
 	    last unless defined($_);
 	}
@@ -157,6 +231,7 @@ BUILTINS: while (<>) {
 
 select STDOUT;
 close OUT;
+close MANPAGE;
 
 foreach $file (<*>) {
     open (IN, $file);
@@ -176,8 +251,16 @@ foreach $file (<*>) {
 
 	# Make this a link to that.
 	unlink $file;
-	symlink ($sameas, $file);
+	if($linkfile eq '') {
+	    symlink ($sameas, $file);
+	} else {
+	    print(LINKFILE "$sameas $file\n");
+	}
     }
 }
+close(LINKFILE) unless($linkfile eq '');
+
+# Make one sanity check
+&Die('not all files were properly generated') unless(-r 'zmodload');
 
 __END__

configure.ac

@@ -258,6 +258,18 @@ AC_ARG_ENABLE(ansi2knr,
 AC_HELP_STRING([--enable-ansi2knr], [translate source to K&R C before compiling]),
 [ansi2knr="$enableval"], [ansi2knr=default])
 
+ifdef([runhelpdir],[undefine([runhelpdir])])dnl
+AC_ARG_ENABLE(runhelpdir,
+AC_HELP_STRING([--enable-runhelpdir=DIR], [the directory in which to install run-help files]),
+[if test x"$enableval" = xno; then
+  runhelpdir=
+else
+  runhelpdir="$enableval"
+fi], [runhelpdir=yes])
+if test x"$runhelpdir" = xyes; then
+  runhelpdir=${datadir}/${tzsh_name}/'${VERSION}'/help
+fi
+
 ifdef([fndir],[undefine([fndir])])dnl
 AC_ARG_ENABLE(fndir,
 AC_HELP_STRING([--enable-fndir=DIR], [the directory in which to install functions]),
@@ -297,6 +309,7 @@ else
   additionalfpath="${enableval}"
 fi], [additionalfpath=""])
 
+AC_SUBST(runhelpdir)dnl
 AC_SUBST(additionalfpath)dnl
 AC_SUBST(fndir)dnl
 AC_SUBST(sitefndir)dnl
@@ -559,6 +572,7 @@ AC_PROG_MAKE_SET            dnl Does make define $MAKE
 AC_PROG_INSTALL             dnl Check for BSD compatible `install'
 AC_PROG_AWK                 dnl Check for mawk,gawk,nawk, then awk.
 AC_PROG_LN                  dnl Check for working ln, for "make install"
+AC_PROG_LN_S                dnl Use ln -s/ln/cp for "make install.runhelp"
 AC_PROG_EGREP               dnl sets $EGREP to grep -E or egrep
 AC_CHECK_PROGS([YODL], [yodl], [: yodl])