Make documentation of nhgitset.pl easier to find and

find out about.

DEVEL/Developer.txt

@@ -58,6 +58,11 @@ NOTE: These instructions assume you are on the default branch; this _is_
 NOTE: The following instructions require perl.  If you do not have perl on
       your system, please install it before proceeding.
 
+NOTE: More information on nhgitset.pl is available before installation via:
+           perldoc DEVEL/nhgitset.pl
+      After installation, the same information is available with:
+           git nhhelp nhgitset
+
 A. If you have never set up git on this machine before:
    (This assumes you will only be using git for NetHack.  If you are going to
    use it for other projects as well, think before you type.)

DEVEL/VERSION

@@ -1,40 +1,4 @@
-4
+5
-Fixes:
+Please see "git log DEVEL" for previous changes.
-- "nhcommit -a" has been fixed
+Make documentation of nhgitset.pl easier to find and
-- NHDT was hardwired in places
+find out about.
-- no longer complain about a missing dat directory outside of the
-    NetHack source tree
-- make update of gitinfo atomic
-- Replace some hardwired directory separators with OS-dependent constructs
-
-Backwards Incompatibilities:
-- NH_DATESUB's DATE() is now Date() to match the other variables
-- MSYS2 requires an additional Perl package - the MSYS2 docs have
-    been updated
-
-New Help System:
-- git nhhelp
-   This command mirrors "git help" for nh* commands.
-- See git nhhelp nhsub for general help on substitution variables
-
-New Substitution Variables:
--Brev()
-    An aBREViation of $PREFIX-Branch$:$PREFIX-Revision$ - this
-    may help get line length under control in file headers.
--Assert(TYPE=VALUE)
-    If TYPE does not match VALUE, do not substitute on this line.
-    TYPE P checks VALUE against nethack.substprefix
--Project(arg)
-    Returns nethack.projectname if there is no arg and an uppercase
-    version if arg is uc.
-
-Other New Features:
-- Add nethack.projectname
-- Documentation updates - see "git nhhelp nhsub"
-- On checkout or merge of a branch, check for nhgitset version updates
-- Move NH_DATESUB substitutions here from cron job to keep dates in sync
-- PREFIX-* keywords now available in NH_DATESUB templates
-- Support use of nhgitset.pl from a different repo; note that update
-  checks will be dependent on keeping the original source repo up-to-date
-  and in the same location.
-

DEVEL/nhgitset.pl

@@ -153,6 +153,7 @@ my $nhsub = catfile(curdir(),'.git','hooks','nhsub');
 
 &add_help('NHsubst', 'NHsubst');
 &add_help('NHgithook', 'NHgithook.pm');
+&add_help('nhgitset', 'gitsetdocs', '../../DEVEL/nhgitset.pl');
 
 
 # removed at version 3
@@ -183,7 +184,7 @@ $cmd = catfile(curdir(),'.git','hooks','NHsubst');
 
 print STDERR "Running directories\n" if($opt_v);
 
-# copy directories into .git (right now that's just hooks
+# copy directories into .git (right now that's just hooks and nhgitset.pl)
 my @gitadd = length($gitadddir)?glob("$gitadddir$DS*"):undef;
 foreach my $dir ( (glob("$srcdir$DS*"), @gitadd) ){
     next unless(-d $dir);
@@ -209,6 +210,7 @@ foreach my $dir ( (glob("$srcdir$DS*"), @gitadd) ){
 	&process_override($enddir, "POST");
     }
 }
+&do_file_nhgitset();
 
 &check_gitvars;	# for variable substitution
 
@@ -219,26 +221,31 @@ if($version_old != $version_new or $opt_f){
 
 exit 0;
 
+# @files: [0] is the name under .git/hooks; others are places to
+#  check during configuration
 sub add_help {
-    my($cmd, $file) = @_;
+    my($cmd, @files) = @_;
 
-    &add_config("nethack.aliashelp.$cmd", $file);
+    &add_config("nethack.aliashelp.$cmd", $files[0]);
 	# pull out =for nhgitset CMD description...
-    my $desc = '';
+    my $desc;
-    open my $fh, "<", "$DEVhooksdir/$file";
+    foreach my $file (@files){
-    if($fh){
+	open my $fh, "<", "$DEVhooksdir/$file";
-	while(<$fh>){
+	if($fh){
-	    m/^=for\s+nhgitset\s+\Q$cmd\E\s+(.*)/ && do {
+	    while(<$fh>){
-		$desc = $1;
+		m/^=for\s+nhgitset\s+\Q$cmd\E\s+(.*)/ && do {
-		last;
+		    $desc = $1;
+		    goto found;
+		}
 	    }
+	    close $fh;
+	} else {
+	    warn "Can't open: '$DEVhooksdir/$file' ($!)\n";
 	}
-	close $fh;
-    } else {
-	warn "Can't open: '$DEVhooksdir/$file' ($!)\n";
     }
+found:
 
-    if(length $desc){
+    if($desc){
 	&add_config("nethack.aliasdesc.$cmd", $desc);
     } else {
 	&add_config("nethack.aliasdesc.$cmd", "(no description available)");
@@ -344,13 +351,25 @@ sub do_dir_hooksdir {
     }
 }
 
+sub do_file_nhgitset {
+    my $infile = "DEVEL/nhgitset.pl";
+    my $outfile = ".git/hooks/gitsetdocs";
+    open IN, "<", $infile or die "Can't open $infile:$!";
+    open OUT, ">", $outfile or die "Can't open $outfile:$!";
+    my $started;
+    print IN "die \"DO NOT RUN THIS FILE\n\"";
+    while(<IN>){
+	m/^__END__/ && do {$started =1; next};
+	print OUT if($started);
+    }
+    close OUT;
+    close IN;
+}
+
+#(can we change the .gitattributes syntax to include a comment character?)
+#maybe [comment]  attr.c:parse_attr_line
+#grr - looks like # is the comment character
 __END__
-(can we change the .gitattributes syntax to include a comment character?)
-maybe [comment]  attr.c:parse_attr_line
-grr - looks like # is the comment character
-
-
-
 =head1 NAME
 
 nhgitset.pl - Setup program for NetHack git repositories
@@ -363,9 +382,10 @@ nhgitset.pl - Setup program for NetHack git repositories
 
 =head1 DESCRIPTION
 
-nhgitset.pl installs NetHack-specific setup after a C<git clone> (or after
+nhgitset.pl installs NetHack-specific setup after a C<git clone> or after
-changes to the desired configuration, which are installed by re-running
+changes to the setup, which are installed by re-running nhgitset.pl.  If
-nhgitset.pl).
+an upgrade is needed, you will be informed during a C<git pull> or similar
+operation.
 
 The following options are available:
 
@@ -445,3 +465,5 @@ nethack.aliasdesc.*
 1	Fail.
 
 2	Intervention required.
+
+=for nhgitset nhgitset NetHack git helper installer