@perl -x %0.bat %1 %2 %3 %4 %5 %6 %7 %8 %9

@quit

#! perl



#  This perl script updates an Epsilon edoc file from a set of files

#  that contain nothing but documention for commands.  These files

#  contain documentation in the same format as the edoc file itself,

#  except that the topics do not have to be in alphabetic order.



#  Usage:

#			edoc-upd file1 file2 ...



#  file1, file2, etc contain new help topics that are to be merged

#  into an existing edoc file.  All the topics in file1, file2, etc.,

#  are read in and sorted into alphabetic order.  Then the edoc file

#  is read, with the new topics replacing or adding to any already

#  there, maintaining alphabetic order, of course.  



#  The existing edoc file is not modified.  Rather a new edoc file,

#  called "edoc.new" is created.  You can copy it to "edoc" when you

#  are sure that it is OK.  



#  The EPSPATH environment variable is used to locate the "edoc" file.



	# by Neal Holtz, Department of Civil Engineering, Carleton

	# University, Ottawa.  nholtz@civeng.carleton.ca

	# September 28, 1993



################################################################



	# go through all files on command line, read all topics



while( $ARGV = shift ) {

	open( IN, $ARGV ) || warn "$0: Couldn't open $ARGV\n";

	$heading = "";

	while( ($topic, $doc) = &read_topic() ) {

		$newdoc{$topic} = $doc;

		print "New topic: $topic\n";

	}

	close( IN );

}



	# prepare a sorted list of topic (command) names



@topics = sort keys %newdoc;



die "Usage:  $0 docfile ...\n" if $#topics < 0;

print "*****\n";



	# locate and open old and new edoc files



$dir = $ENV{"EPSPATH"} || ".";

$old = "$dir\\edoc";

$new = "$dir\\edoc.new";



die "Unable to find original edoc ($old)" if !-e $old;

die "New edoc ($new) already exists" if -e $new;



open( IN, "<$old" ) || die "Unable to open $old";

open( NEW, ">$new" ) || die "Unable to open $new";



	# Read each topic in the old "edoc" file.  For each one, write

	# all new topics that are to precede it, then write the old topic

	# into the new edoc file (unless it is to be replaced).



$heading = "";

while( ($oldtopic,$olddoc) = &read_topic() ) {

	while( $#topics >= 0 && $topics[0] le $oldtopic ) {

		$newtopic = shift @topics;

		if( $newtopic eq $oldtopic ) {

			print "Replacing ";

			$olddoc = "";

		}

		else {

			print "Adding    ";

		}

		print "$newtopic\n";

		print NEW $newdoc{$newtopic};

	}

	(print NEW $olddoc) if $olddoc;

}



	# If there are any remaining new topics, output them all.



while( $newtopic=shift @topics ) {

	print NEW $newdoc{$newtopic};

}



close(IN); close(NEW);

print "\nYour new edoc file is:  $new\n";

print "You must copy it to \"$old\" to make the changes have effect.\n";



################################################################



	# subroutine to read one complete topic from the IN file handle.

	# It returns an empty array if no more topics, else a 2-element

	# array containing the topic name and the complete documentation

	# (including the header line).  It ensures that the topic ends

	# with at least one blank line.



	# global $heading contains the first line of the next topic to

	# come.  It should be set to the empty string before the first

	# read of each new file.  global IN is a file handle that must be

	# opened before this subroutine is called.



sub read_topic {

	return () if eof(IN);

	local( $topic, $doc, $nbl );

	if( !$heading ) {		# $heading is null for 1st topic from a file

		while( <IN> ) {			# so go looking for the heading for it.

			$heading = $_, last if /^~/;

		}

		return () if !$heading;

	}

	($topic) = $heading =~ /^~\s*(\S+)\s/;

	$doc = $heading;

	while( <IN> ) {			# read up to the next heading line

		$heading = $_, last if /^~/;	# remembering it for next time

		$doc .= $_;						# concating lines into one string

		/^\s*$/ ? $nbl++ : ($nbl = 0);	# counting blank lines @ end

	}

	$doc .= "\n" if !$nbl;		# append a trailing blank line, if necessary

	return ($topic,$doc);

}