#!/usr/bin/perl
# 
# helpztags generates tags for Vim helpfiles, for both .txt and .txt.gz files
# Author: Jakub Turski <yacoob@chruptak.plukwa.net>
#         Artur R. Czechowski <arturcz@hell.pl>
# Version: 0.4

# Please use following command for generate a manual file:
# pod2man -c "User Commands" -s 1 -q none -r "vim 6.2" -d "September 2003" helpztags helpztags.1

=head1 NAME

helpztags - generate the help tags file for directory

=head1 SYNOPSIS

helpztags F<DIRS>...

=head1 DESCRIPTION

F<helpztags> scans given directories for F<*.txt> and F<*.txt.gz> files.
Each file is scanned for tags used in F<vim> help files. For each directory
proper F<tags> file is generated.

There should be at least one directory given. In other case program exits
with error.

=head1 AUTHORS

Written by Jakub Turski and Artur R. Czechowski based on idea
contained in C<vim> sources for its C<:helptags command>.

=head1 REPORTING BUGS

Please use a Debian C<reportbug> command or procedure described at
C<http://bugs.debian.org/>.

=head1 SEE ALSO

Read C<:help helptags> in F<vim> for detailed information about helptags.

=cut

use strict;
use warnings;
use File::Glob ':globally';
use POSIX qw(getcwd);

die "Error: no directories given. Check manpage for details.\n" unless @ARGV;

my $startdir=getcwd();
my %tags;

foreach my $dir (@ARGV) {
  chdir $dir or next;
  print "Processing ".$dir."\n";
  foreach my $file (<*.{gz,txt,??x}>) {
    next unless $file =~ m/^[\w.-]+\.(?:txt|([[:alpha:]]{2})x)(?:.gz)?$/;
    my $suffix = '';
    if ($1) {
      $suffix = "-$1";
    }
    my $open = ($file =~ /\.gz$/) ? open(GZ, '-|', 'zcat', $file) : open(GZ, $file);
    if (!$open) {
      chdir $startdir;
      next;
    }
    while (<GZ>) {
        # From vim73/src/ex_cmds.c, helptags_one, lines 6443-6445
        # 
        # Only accept a *tag* when it consists of valid
        # characters, there is white space before it and is
        # followed by a white character or end-of-line.
      while (/(?:(?<=^)|(?<=\s))\*([^*\s|]+?)\*(?:(?=\s)|(?=$))/g) {
        $tags{"tags$suffix"}{$1}=$file;
      }
    }
    close(GZ);
  }
  while (my ($tagfile, $tags) = each %tags) {
    next unless %{$tags};
    open(TAGSFILE, '>', $tagfile) || die "Error: Cannot open $dir/$tagfile for writing.\n";
    foreach my $tag (sort keys %{$tags}) {
      print TAGSFILE "$tag\t$tags->{$tag}\t/*";
      $tag =~ s/\\/\\\\/g;
      $tag =~ s@/@\/@g;
      print TAGSFILE "$tag*\n";
    }
    close TAGSFILE;
  }
  chdir $startdir;
}