New version of `helpfiles'

[pws@xxxxxx (Peter William Stephenson)]

Here is a new version of the perl script `helpfiles', which you can
use to generate indvidual help files for zsh builtins out of the
`zshbuiltins' manual page for use with run-help, or whatever:  see
instructions in the script.

The main change is to introduce compatibility for the SGI which is now
my main log-in machine.  This has an even more rampantly unhelpful
version of nroff than most machines, which is saying a lot:  the title
line for the `read' built-in was being wrapped round to the *previous*
line with a smaller indentation.  As observed, there's no colcrt
either.

In the process I may have improved compatibility with other machines.
In particular, page throws (of the sort the SGI produces, anyway) are
now stripped out.


#!/usr/local/bin/perl -- -*-perl-*-

# helpfiles:  make help files for Z-shell builtins from the manual entries.
# Author:  Peter Stephenson <pws@xxxxxx>

# Create help files for zsh commands in the current directory;
# 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>'
# has its help file appended to the end of <foo>'s and replaced by a
# 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 zsh | colcrt -' (remember the -) should do the trick.
# The builtin descriptions have recently moved to a separate manual
# page,  zshbuiltins, so use that if necessary.

# 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).

# Example usage:
#    cd ~/zsh-2.6-beta4				# or wherever
#    mkdir Help
#    cd Help
#    man zsh | colcrt - | helpfiles
#    run-help() {
#      typeset zhelp=~/zsh-2.6-beta4/Help	# or wherever
#      [[ $1 = . ]] && 1=dot
#      [[ $1 = : ]] && 1=colon
#      if [[ -f $zhelp/$1 ]]; then
#    	  ${=PAGER:-more} $zhelp/$1
#      else
#    	  man $1
#      fi
#    }
# now <Esc>-h works for shell builtins.

while (<>) {
    last if /^SHELL BUILTIN COMMANDS/;
    /zshbuiltins/ && $zb++;
    last if ($zb && /^\s*DESCRIPTIONS/);
}

$print = 0;

sub namesub {
    local($cmd) = shift;
    if ($cmd =~ /^\w+$/) {
	$cmd;
    } elsif ($cmd eq '.') {
	'dot';
    } elsif ($cmd eq ':') {
	'colon';
    } else {
	undef;
    }
}

sub getsame {
    local($_) = shift;
    if (/same\s*as\s*(\S+)/i || /equivalent\s*to\s*(\S+)/i) {
	local($name) = $1;
	($name =~ /[.,]$/) && chop($name);
	return $name;
    } else {
	return undef;
    }
}

sub newcmd {
    local($_) = shift;
    local($cmd);
    # new command
    if (defined($cmd = &namesub($_))) {
	# in case there's something nasty here like a link..
	unlink $cmd;
	open (OUT, ">$cmd");
	select OUT;
	$print = 1;
    } else {
	$print = 0;
    }
}

while (<>) { last unless /^\s*$/; }

/^(\s+)(\S+)/;
$indent = length($1);
&newcmd($2);
print if $print;

BUILTINS: while (<>) {
    next if /^\w/;

    undef($undented);
    if (/^\s*$/ || ($undented = (/^(\s*)/  && length($1) < $indent))) {
	$undented && print;
	while (defined($_ = <>) && /(^\w)|(^\s*$)/) { 
	    last BUILTINS if /^STARTUP\/SHUTDOWN FILES/;
	}
        if (/^\s*Page/) {
	    do {
		$_ = <>;
	    } while (defined($_) && /^\s*$/);
	    if (/^\s*ZSHBUILTINS/) {
		do {
		    $_ = <>;
		} while (defined($_) && /^\s*$/);
	    }
	}
	if (/^(\s*)/ && length($1) < $indent) {
	    # This may be just a bug on the SGI, or maybe something
	    # more sinister (don\'t laugh, this is nroff).
	    s/^\s*/ /;
	    $defer = $_;
	    do {
		$_ = <>;
	    } while (defined($_) && /^\s*$/);
	}
	if (/^(\s+)(\S+)/ && length($1) == $indent) {
	    &newcmd($2);
	} else {
	    print "\n";
	}
        if ($print) {
	    if (defined($defer)) {
		chop;
		print "$_$defer";
		undef($defer);
	    } else {
		print;
	    }
	}
    } else {
	print if $print;
    }
}

select STDOUT;
close OUT;

foreach $file (<*>) {
    open (IN, $file);
    if ($sameas = (&getsame($_ = <IN>) || &getsame($_ = <IN>))) {
	defined($sameas = &namesub($sameas)) || next;
#	print "$file is the same as $sameas\n";
	seek (IN, 0, 0);

	# Copy this to base builtin.
	open (OUT, ">>$sameas");
	select OUT;
	print "\n";
	while (<IN>) { print; }
	close IN;
	select STDOUT;
	close OUT;

	# Make this a link to that.
	unlink $file;
	symlink ($sameas, $file);
    }
}

__END__