[PATCH 0/4] updates to Util/helpfiles and its documentation

[PATCH 0/4] updates to Util/helpfiles and its documentation

[m0viefreak]

I've updated the documentation for helpfiles to reflect the latest
changes to it (autoinstalled by default).

Additionally there are two small improvements.

m0viefreak (4):
  Doc/Zsh/contrib.yo: Adjust man-page for the auto installed help files
  Util/helpfiles: use /usr/bin/env in shebang line
  Util/helpfiles: remove outdated example configuration
  Util/helpfiles: prefer 'col -bx' over 'colcrt'

 Doc/Zsh/contrib.yo | 27 +++++++++++++--------------
 Util/helpfiles     | 36 +++++++++++-------------------------
 2 files changed, 24 insertions(+), 39 deletions(-)

-- 
1.9.0

[PATCH 1/4] Doc/Zsh/contrib.yo: Adjust man-page for the auto installed help files

[m0viefreak]

---
 Doc/Zsh/contrib.yo | 27 +++++++++++++--------------
 1 file changed, 13 insertions(+), 14 deletions(-)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index bb6613e..bb294e5 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -45,9 +45,8 @@ shell features as well.  The autoloadable tt(run-help) function, found in
 tt(Functions/Misc), searches for these helpfiles and performs several
 other tests to produce the most complete help possible for the command.
 
-There may already be a directory of help files on your system; look in
-tt(/usr/share/zsh) or tt(/usr/local/share/zsh) and subdirectories below
-those, or ask your system administrator.
+Help files are installed by default to a subdirectory of tt(/usr/share/zsh)
+or tt(/usr/local/share/zsh).
 
 To create your own help files with tt(helpfiles), choose or create a
 directory where the individual command help files will reside.  For
@@ -55,22 +54,22 @@ example, you might choose tt(~/zsh_help).  If you unpacked the zsh
 distribution in your home directory, you would use the commands:
 
 example(mkdir ~/zsh_help
-cd ~/zsh_help
-man zshall | colcrt - | \ 
-perl ~/zsh-version()/Util/helpfiles)
+perl ~/zsh-version()/Util/helpfiles ~/zsh_help)
+
+vindex(HELPDIR)
+The tt(HELPDIR) parameter tells tt(run-help) where to look for the help
+files. When unset, it uses the default installation path.
+To use your own set of help files, set this to the appropriate path
+in one of your startup files:
+
+example(HELPDIR=~/zsh_help)
 
 findex(run-help, use of)
-Next, to use the tt(run-help) function, you need to add lines something
+To use the tt(run-help) function, you need to add lines something
 like the following to your tt(.zshrc) or equivalent startup file:
 
 example(unalias run-help
-autoload run-help
-HELPDIR=~/zsh_help)
-
-vindex(HELPDIR)
-The tt(HELPDIR) parameter tells tt(run-help) where to look for the help
-files.  If your system already has a help file directory installed, set
-tt(HELPDIR) to the path of that directory instead.
+autoload run-help)
 
 Note that in order for `tt(autoload run-help)' to work, the tt(run-help)
 file must be in one of the directories named in your tt(fpath) array (see
-- 
1.9.0

[PATCH 2/4] Util/helpfiles: use /usr/bin/env in shebang line

[m0viefreak]

This doesn't hard code the path to perl when called by ./helpfiles.

This also fixes execution of the script on systems like linux,
which do not support more than one argument in the #! lne.
---
 Util/helpfiles | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Util/helpfiles b/Util/helpfiles
index cdce888..9e611d7 100755
--- a/Util/helpfiles
+++ b/Util/helpfiles
@@ -1,4 +1,4 @@
-#!/usr/local/bin/perl -- -*-perl-*-
+#!/usr/bin/env perl
 
 # helpfiles:  make help files for Z-shell builtins from the manual entries.
 
-- 
1.9.0

[PATCH 3/4] Util/helpfiles: remove outdated example configuration

[m0viefreak]

---
 Util/helpfiles | 22 ++++------------------
 1 file changed, 4 insertions(+), 18 deletions(-)

diff --git a/Util/helpfiles b/Util/helpfiles
index 9e611d7..9909a1d 100755
--- a/Util/helpfiles
+++ b/Util/helpfiles
@@ -16,24 +16,10 @@
 # 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.
 
-# Example usage:
-#    cd ~/zsh-4.0.1				# or wherever
-#    mkdir Help
-#    cd Help
-#    man zshbuiltins | colcrt - | helpfiles
-#    run-help() {
-#      typeset zhelp=~/zsh-4.0.1/Help		# or wherever
-#      [[ $1 = . ]] && 1=dot
-#      [[ $1 = : ]] && 1=colon
-#      if [[ $1 = compctl ]]; then
-#         man zshcompctl
-#      elif [[ -f $zhelp/$1 ]]; then
-#    	  ${=PAGER:-more} $zhelp/$1
-#      else
-#    	  man $1
-#      fi
-#    }
-# now <Esc>-h works for shell builtins.
+# This script is called automatically during `make install'
+# unless specified otherwise.
+
+# For usage and and more information see zshcontrib(1).
 
 sub Usage {
     print(STDERR "Usage: helpfiles zshbuiltins.1 dest-dir [link-file]\n");
-- 
1.9.0

[PATCH 4/4] Util/helpfiles: prefer 'col -bx' over 'colcrt'

[m0viefreak]

Even when given the '-' option colcrt removes any underscore
characters from the text, ending up with all words like
'CHASE_LINKS' being converted to 'CHASE LINKS'.

'col -bx' works fine in those cases. Since as of the lastest
changes both variants are tried, avaibility of the command on
different systems is not an issue and it is safe to prefer 'col'.
---
 Util/helpfiles | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Util/helpfiles b/Util/helpfiles
index 9909a1d..699ca83 100755
--- a/Util/helpfiles
+++ b/Util/helpfiles
@@ -67,17 +67,17 @@ if(system('man ' . $args) || !(-s $mantmp)) {
 }
 $args = "$mantmp >$coltmp";
 unlink($coltmp);
-&Info('attempting colcrt - ', $args);
-if(system('colcrt - ' . $args) || !(-s $coltmp)) {
-    unlink($coltmp);
-    &Info('attempting col -bx <', $args);
+&Info('attempting col -bx <', $args);
 # 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).
-    if(system('col -bx <' . $args) || !(-s $coltmp)) {
+if(system('col -bx <' . $args) || !(-s $coltmp)) {
+    unlink($coltmp);
+    &Info('attempting colcrt - ', $args);
+    if(system('colcrt - ' . $args) || !(-s $coltmp)) {
         unlink($mantmp);
         unlink($coltmp);
-        &Die('colcrt and col -bx both failed');
+        &Die('col -bx and colcrt - both failed');
     }
 }
 unlink($mantmp) || &Die('cannot remove tempfile ', $mantmp);
-- 
1.9.0