--- loncom/build/lpml_parse.pl	2001/09/08 22:47:38	1.7
+++ loncom/build/lpml_parse.pl	2001/11/16 21:10:32	1.18
@@ -5,6 +5,11 @@
 # May 2001
 # 06/19/2001,06/20,06/24 - Scott Harrison
 # 9/5/2001,9/6,9/7,9/8 - Scott Harrison
+# 9/17,9/18 - Scott Harrison
+# 11/4,11/5,11/6,11/7,11/16 - Scott Harrison
+#
+# $Id: lpml_parse.pl,v 1.18 2001/11/16 21:10:32 harris41 Exp $
+###
 
 ###############################################################################
 ##                                                                           ##
@@ -14,6 +19,8 @@
 ## 3. First pass through (grab distribution-specific information)            ##
 ## 4. Second pass through (parse out what is not necessary)                  ##
 ## 5. Third pass through (translate markup according to specified mode)      ##
+## 6. Functions (most all just format contents of different markup tags)     ##
+## 7. POD (plain old documentation, CPAN style)                              ##
 ##                                                                           ##
 ###############################################################################
 
@@ -81,7 +88,7 @@ $targetroot=~s/\/$//;
 
 my $invocation;
 # --------------------------------------------------- Record program invocation
-if ($mode eq 'install') {
+if ($mode eq 'install' or $mode eq 'configinstall' or $mode eq 'build') {
     $invocation=(<<END);
 # Invocation: STDINPUT | lpml_parse.pl
 #             1st argument (mode) is: $mode
@@ -177,7 +184,8 @@ while ($token = $parser->get_token()) {
     }
 }
 $cleanstring=&trim($cleanstring);
-$cleanstring=~s/\s*\n\s*//g;
+$cleanstring=~s/\>\s*\n\s*\</\>\</g;
+
 # ---------------------------------------------------- Start final pass through
 
 # storage variables
@@ -219,6 +227,7 @@ my $target;
 my $source;
 my $note;
 my $build;
+my $buildlink;
 my $commands;
 my $command;
 my $status;
@@ -227,6 +236,11 @@ my $dependency;
 my @links;
 my %categoryhash;
 
+my @buildall;
+my @buildinfo;
+
+my @configall;
+
 # Make new parser with distribution specific input
 undef $parser;
 $parser = HTML::TokeParser->new(\$cleanstring) or
@@ -271,6 +285,7 @@ $parser->{textify}={
     build => \&format_build,
     status => \&format_status,
     dependencies => \&format_dependencies,
+    buildlink => \&format_buildlink,
     glob => \&format_glob,
     sourcedir => \&format_sourcedir,
     filenames => \&format_filenames,
@@ -295,9 +310,12 @@ while ($token = $parser->get_tag('lpml')
 }
 exit;
 
+# ---------- Functions (most all just format contents of different markup tags)
+
+# ------------------------ Final output at end of markup parsing and formatting
 sub end {
     if ($mode eq 'html') {
-	return "THE END\n";
+	return "<br />THE END\n";
     }
     if ($mode eq 'install') {
 	return '';
@@ -316,13 +334,29 @@ sub format_lpml {
     my (@tokeninfo)=@_;
     my $date=`date`; chop $date;
     if ($mode eq 'html') {
-	$lpml = "LPML BEGINNING: $date";
+	$lpml = "<br />LPML BEGINNING: $date";
     }
     elsif ($mode eq 'install') {
 	print '# LPML install targets. Linux Packaging Markup Language,';
 	print ' by Scott Harrison 2001'."\n";
 	print '# This file was automatically generated on '.`date`;
 	print "\n".$invocation;
+	$lpml .= "SHELL=\"/bin/bash\"\n\n";
+    }
+    elsif ($mode eq 'configinstall') {
+	print '# LPML configuration file targets (configinstall).'."\n";
+	print '# Linux Packaging Markup Language,';
+	print ' by Scott Harrison 2001'."\n";
+	print '# This file was automatically generated on '.`date`;
+	print "\n".$invocation;
+	$lpml .= "SHELL=\"/bin/bash\"\n\n";
+    }
+    elsif ($mode eq 'build') {
+	$lpml = "# LPML build targets. Linux Packaging Markup Language,";
+	$lpml .= ' by Scott Harrison 2001'."\n";
+	$lpml .= '# This file was automatically generated on '.`date`;
+	$lpml .= "\n".$invocation;
+	$lpml .= "SHELL=\"/bin/sh\"\n\n";
     }
     else {
 	return '';
@@ -334,9 +368,10 @@ sub format_targetroot {
     $text=$targetroot if $targetroot;
     $parser->get_tag('/targetroot');
     if ($mode eq 'html') {
-	return $targetroot="\nTARGETROOT: $text";
+	return $targetroot="\n<br />TARGETROOT: $text";
     }
-    elsif ($mode eq 'install') {
+    elsif ($mode eq 'install' or $mode eq 'build' or
+	   $mode eq 'configinstall') {
 	return '# TARGET INSTALL LOCATION is "'.$targetroot."\"\n";
     }
     else {
@@ -349,9 +384,10 @@ sub format_sourceroot {
     $text=$sourceroot if $sourceroot;
     $parser->get_tag('/sourceroot');
     if ($mode eq 'html') {
-	return $sourceroot="\nSOURCEROOT: $text";
+	return $sourceroot="\n<br />SOURCEROOT: $text";
     }
-    elsif ($mode eq 'install') {
+    elsif ($mode eq 'install' or $mode eq 'build' or
+	   $mode eq 'configinstall') {
 	return '# SOURCE CODE LOCATION IS "'.$sourceroot."\"\n";;
     }
     else {
@@ -363,7 +399,8 @@ sub format_categories {
     my $text=&trim($parser->get_text('/categories'));
     $parser->get_tag('/categories');
     if ($mode eq 'html') {
-	return $categories="\nBEGIN CATEGORIES\n$text\nEND CATEGORIES\n";
+	return $categories="\n<br />BEGIN CATEGORIES\n$text\n".
+	    "<br />END CATEGORIES\n";
     }
     else {
 	return '';
@@ -378,8 +415,8 @@ sub format_category {
     $parser->get_text('/category');
     $parser->get_tag('/category');
     if ($mode eq 'html') {
-	return $category="\nCATEGORY $category_att_name $category_att_type ".
-	    "$chmod $chown";
+	return $category="\n<br />CATEGORY $category_att_name ".
+	    "$category_att_type $chmod $chown";
     }
     else {
 	if ($category_att_type eq $categorytype) {
@@ -417,7 +454,7 @@ sub format_rpm {
     my $text=&trim($parser->get_text('/rpm'));
     $parser->get_tag('/rpm');
     if ($mode eq 'html') {
-	return $rpm="\nBEGIN RPM\n$text\nEND RPM";
+	return $rpm="\n<br />BEGIN RPM\n$text\n<br />END RPM";
     }
     else {
 	return '';
@@ -428,7 +465,7 @@ sub format_rpmSummary {
     my $text=&trim($parser->get_text('/rpmSummary'));
     $parser->get_tag('/rpmSummary');
     if ($mode eq 'html') {
-	return $rpmSummary="\nRPMSUMMARY $text";
+	return $rpmSummary="\n<br />RPMSUMMARY $text";
     }
     else {
 	return '';
@@ -439,7 +476,7 @@ sub format_rpmName {
     my $text=&trim($parser->get_text('/rpmName'));
     $parser->get_tag('/rpmName');
     if ($mode eq 'html') {
-	return $rpmName="\nRPMNAME $text";
+	return $rpmName="\n<br />RPMNAME $text";
     }
     else {
 	return '';
@@ -450,7 +487,7 @@ sub format_rpmVersion {
     my $text=$parser->get_text('/rpmVersion');
     $parser->get_tag('/rpmVersion');
     if ($mode eq 'html') {
-	return $rpmVersion="\nRPMVERSION $text";
+	return $rpmVersion="\n<br />RPMVERSION $text";
     }
     else {
 	return '';
@@ -461,7 +498,7 @@ sub format_rpmRelease {
     my $text=$parser->get_text('/rpmRelease');
     $parser->get_tag('/rpmRelease');
     if ($mode eq 'html') {
-	return $rpmRelease="\nRPMRELEASE $text";
+	return $rpmRelease="\n<br />RPMRELEASE $text";
     }
     else {
 	return '';
@@ -472,7 +509,7 @@ sub format_rpmVendor {
     my $text=$parser->get_text('/rpmVendor');
     $parser->get_tag('/rpmVendor');
     if ($mode eq 'html') {
-	return $rpmVendor="\nRPMVENDOR $text";
+	return $rpmVendor="\n<br />RPMVENDOR $text";
     }
     else {
 	return '';
@@ -483,7 +520,7 @@ sub format_rpmBuildRoot {
     my $text=$parser->get_text('/rpmBuildRoot');
     $parser->get_tag('/rpmBuildRoot');
     if ($mode eq 'html') {
-	return $rpmBuildRoot="\nRPMBUILDROOT $text";
+	return $rpmBuildRoot="\n<br />RPMBUILDROOT $text";
     }
     else {
 	return '';
@@ -494,7 +531,7 @@ sub format_rpmCopyright {
     my $text=$parser->get_text('/rpmCopyright');
     $parser->get_tag('/rpmCopyright');
     if ($mode eq 'html') {
-	return $rpmCopyright="\nRPMCOPYRIGHT $text";
+	return $rpmCopyright="\n<br />RPMCOPYRIGHT $text";
     }
     else {
 	return '';
@@ -505,7 +542,7 @@ sub format_rpmGroup {
     my $text=$parser->get_text('/rpmGroup');
     $parser->get_tag('/rpmGroup');
     if ($mode eq 'html') {
-	return $rpmGroup="\nRPMGROUP $text";
+	return $rpmGroup="\n<br />RPMGROUP $text";
     }
     else {
 	return '';
@@ -516,7 +553,7 @@ sub format_rpmSource {
     my $text=$parser->get_text('/rpmSource');
     $parser->get_tag('/rpmSource');
     if ($mode eq 'html') {
-	return $rpmSource="\nRPMSOURCE $text";
+	return $rpmSource="\n<br />RPMSOURCE $text";
     }
     else {
 	return '';
@@ -527,7 +564,7 @@ sub format_rpmAutoReqProv {
     my $text=$parser->get_text('/rpmAutoReqProv');
     $parser->get_tag('/rpmAutoReqProv');
     if ($mode eq 'html') {
-	return $rpmAutoReqProv="\nRPMAUTOREQPROV $text";
+	return $rpmAutoReqProv="\n<br />RPMAUTOREQPROV $text";
     }
     else {
 	return '';
@@ -538,7 +575,7 @@ sub format_rpmdescription {
     my $text=$parser->get_text('/rpmdescription');
     $parser->get_tag('/rpmdescription');
     if ($mode eq 'html') {
-	return $rpmdescription="\nRPMDESCRIPTION $text";
+	return $rpmdescription="\n<br />RPMDESCRIPTION $text";
     }
     else {
 	return '';
@@ -549,7 +586,7 @@ sub format_rpmpre {
     my $text=$parser->get_text('/rpmpre');
     $parser->get_tag('/rpmpre');
     if ($mode eq 'html') {
-	return $rpmpre="\nRPMPRE $text";
+	return $rpmpre="\n<br />RPMPRE $text";
     }
     else {
 	return '';
@@ -560,7 +597,8 @@ sub format_directories {
     my $text=$parser->get_text('/directories');
     $parser->get_tag('/directories');
     if ($mode eq 'html') {
-	return $directories="\nBEGIN DIRECTORIES\n$text\nEND DIRECTORIES\n";
+	return $directories="\n<br />BEGIN DIRECTORIES\n$text\n<br />".
+	    "END DIRECTORIES\n";
     }
     elsif ($mode eq 'install') {
 	return "\n".'directories:'."\n".$text;
@@ -576,11 +614,12 @@ sub format_directory {
     $parser->get_text('/directory');
     $parser->get_tag('/directory');
     if ($mode eq 'html') {
-	return $directory="\nDIRECTORY $targetdir $categoryname $description";
+	return $directory="\n<br />DIRECTORY $targetdir $categoryname ".
+	    "$description";
     }
     elsif ($mode eq 'install') {
-	return "\t".'install '.$categoryhash{$categoryname}.' -d /'.
-	    $targetroot.$targetdir."\n";
+	return "\t".'install '.$categoryhash{$categoryname}.' -d '.
+	    $targetroot.'/'.$targetdir."\n";
     }
     else {
 	return '';
@@ -612,7 +651,7 @@ sub format_categoryname {
 sub format_description {
     my @tokeninfo=@_;
     $description='';
-    my $text=&trim($parser->get_text('/description'));
+    my $text=&htmlsafe(&trim($parser->get_text('/description')));
     if ($text) {
 	$parser->get_tag('/description');
 	$description=$text;
@@ -624,12 +663,63 @@ sub format_files {
     my $text=$parser->get_text('/files');
     $parser->get_tag('/files');
     if ($mode eq 'html') {
-	return $directories="\nBEGIN FILES\n$text\nEND FILES\n";
+	return $directories="\n<br />BEGIN FILES\n$text\n<br />END FILES\n";
     }
     elsif ($mode eq 'install') {
 	return "\n".'files:'."\n".$text.
 	    "\n".'links:'."\n".join('',@links);
     }
+    elsif ($mode eq 'configinstall') {
+	return "\n".'configfiles: '.
+	join(' ',@configall).
+	"\n\n".$text.
+	"\n\nalwaysrun:\n\n";
+    }
+    elsif ($mode eq 'build') {
+	my $binfo;
+	my $tword;
+	my $command2;
+	my @deps;
+	foreach my $bi (@buildinfo) {
+	    my ($target,$source,$command,$trigger,@deps)=split(/\;/,$bi);
+	    $tword=''; $tword=' alwaysrun' if $trigger eq 'always run'; 
+	    $command=~s/\/([^\/]*)$//;
+	    $command2="cd $command; sh ./$1;\\";
+	    my $depstring;
+	    my $depstring2="\t\t\@echo '';\\\n";
+	    my $olddep;
+	    foreach my $dep (@deps) {
+		unless ($olddep) {
+		    $olddep=$deps[$#deps];
+		}
+		$depstring.="\telif !(test -r $command/$dep);\\\n";
+		$depstring.="\t\tthen echo ".
+		"\"**** WARNING **** missing the file: ".
+ 	        "$command/$dep\";\\\n";
+		$depstring.="\t\ttest -e $source || test -e $target || echo ".
+		    "'**** ERROR **** neither source=$source nor target=".
+		    "$target exist and they cannot be built';\\\n";
+		$depstring.="\t\tmake -f Makefile.build ${source}___DEPS;\\\n";
+		if ($olddep) {
+		    $depstring2.="\t\tECODE=0;\\\n";
+		    $depstring2.="\t\t! test -e $source && test -r $command/$olddep &&".
+			" { perl filecompare.pl -b2 $command/$olddep $target ||  ECODE=\$\$?; } && { [ \$\$ECODE != \"2\" ] || echo \"**** WARNING **** dependency $command/$olddep is newer than target file $target; SOMETHING MAY BE WRONG\"; };\\\n";
+		}
+		$olddep=$dep;
+	    }
+	    $binfo.="$source: $tword\n".
+		"\t\@if !(echo \"\");\\\n\t\tthen echo ".
+		"\"**** WARNING **** Strange shell. ".
+ 	        "Check your path settings.\";\\\n".
+		$depstring.
+		"\telse \\\n\t\t$command2\n\tfi\n\n";
+	    $binfo.="${source}___DEPS:\n".$depstring2."\t\tECODE=0;\n\n";
+	}
+	return 'all: '.join(' ',@buildall)."\n\n".
+  	        $text.
+		$binfo."\n".
+		"alwaysrun:\n\n";
+    }
     else {
 	return '';
     }
@@ -644,7 +734,7 @@ sub format_links {
     my $text=$parser->get_text('/links');
     $parser->get_tag('/links');
     if ($mode eq 'html') {
-	return $links="\nBEGIN LINKS\n$text\nEND LINKS\n";
+	return $links="\n<br />BEGIN LINKS\n$text\n<br />END LINKS\n";
     }
     elsif ($mode eq 'install') {
 	return "\n".'links:'."\n\t".$text;
@@ -659,23 +749,91 @@ sub format_file {
     $file=''; $source=''; $target=''; $categoryname=''; $description='';
     $note=''; $build=''; $status=''; $dependencies='';
     my $text=&trim($parser->get_text('/file'));
+    my $buildtest;
     if ($source) {
 	$parser->get_tag('/file');
 	if ($mode eq 'html') {
-	    return ($file="\nBEGIN FILE\n".
+	    return ($file="\n<br />BEGIN FILE\n".
 		"$source $target $categoryname $description $note " .
 		"$build $status $dependencies" .
 		"\nEND FILE");
 	}
 	elsif ($mode eq 'install' && $categoryname ne 'conf') {
-	    return "\t".'@test -e '.$sourceroot.$source.
-		' && install '.
-		$categoryhash{$categoryname}.' '.
-		$sourceroot.$source.' '.
-		$targetroot.$target.
-		' || echo "**** LON-CAPA WARNING '.
-		'**** CVS source file does not exist: '.$sourceroot.'/'.
-		$source.'"'."\n";
+	    if ($build) {
+		my $bi=$sourceroot.'/'.$source.';'.$build.';'.
+		    $dependencies;
+		my ($source2,$command,$trigger,@deps)=split(/\;/,$bi);
+		$tword=''; $tword=' alwaysrun' if $trigger eq 'always run'; 
+		$command=~s/\/([^\/]*)$//;
+		$command2="cd $command; sh ./$1;\\";
+		my $depstring;
+		foreach my $dep (@deps) {
+		    $depstring.=<<END;
+		ECODE=0; DEP=''; \\
+		test -e $command/$dep || (echo '**** WARNING **** cannot evaluate status of dependency $command/$dep (for building ${sourceroot}/${source} with)'); DEP="1"; \\
+		[ -n DEP ] && { perl filecompare.pl -b2 $command/$dep ${targetroot}/${target} || ECODE=\$\$?; } || DEP="1"; \\
+		case "\$\$ECODE" in \\
+			2) echo "**** WARNING **** dependency $command/$dep is newer than target file ${targetroot}/${target}; you may want to run make build";; \\
+		esac; \\
+END
+		}
+                chomp $depstring;
+		$buildtest=<<END;
+	\@if !(test -e "${sourceroot}/${source}") && !(test -e "${targetroot}/${target}"); then \\
+		echo "**** ERROR **** ${sourceroot}/${source} is missing and is also not present at target location ${targetroot}/${target}; you must run make build"; exit; \\
+END
+                $buildtest.=<<END if $depstring;
+	elif !(test -e "${sourceroot}/${source}"); then \\
+$depstring
+END
+                $buildtest.=<<END;
+	fi
+END
+	    }
+            my $bflag='-b1';
+            $bflag='-b3' if $dependencies or $buildlink;
+	    return <<END;
+$buildtest	\@if !(test -e "${sourceroot}/${source}"); then \\
+		echo "**** WARNING **** CVS source file does not exist: ${sourceroot}/${source}"; \\
+	else \\
+		ECODE=0; \\
+		perl filecompare.pl $bflag ${sourceroot}/${source} ${targetroot}/${target} || ECODE=\$\$?; \\
+		case "\$\$ECODE" in \\
+			1) echo "${targetroot}/${target} is unchanged";; \\
+			2) echo "**** WARNING **** target file ${targetroot}/${target} is newer than CVS source; creating ${targetroot}/${target}.lpmlnewfile instead" && install -o www -g www -m 0500 ${sourceroot}/${source} ${targetroot}/${target}.lpmlnewfile;; \\
+			0) echo "install -o www -g www -m 0500 ${sourceroot}/${source} ${targetroot}/${target}" && install -o www -g www -m 0500 ${sourceroot}/${source} ${targetroot}/${target};; \\
+		esac; \\
+	fi
+END
+#	    return "\t".'@test -e '.$sourceroot.'/'.$source.
+#		' && perl filecompare.pl -b '.$sourceroot.'/'.$source.' '.
+#		$targetroot.'/'.$target.
+#		' && install '.
+#		$categoryhash{$categoryname}.' '.
+#		$sourceroot.'/'.$source.' '.
+#		$targetroot.'/'.$target.
+#		' || echo "**** LON-CAPA WARNING '.
+#		'**** CVS source file does not exist: '.$sourceroot.'/'.
+#		$source.'"'."\n";
+	}
+	elsif ($mode eq 'configinstall' && $categoryname eq 'conf') {
+	    push @configall,$targetroot.'/'.$target;
+	    return $targetroot.'/'.$target.': alwaysrun'."\n".
+		"\t".'@echo -n ""; ECODE=0 && { perl filecompare.pl -b4 '.$sourceroot.'/'.$source.' '.$targetroot.'/'.$target.' || ECODE=$$?; } && { [ $$ECODE != "2" ] || (install '.$categoryhash{$categoryname}.' '.
+		$sourceroot.'/'.$source.' '.
+		$targetroot.'/'.$target.'.lpmlnewconf'.
+		' && echo "*** CONFIGURATION FILE CHANGE ***" && echo "'.
+		'You likely need to compare contents of '.
+		''.$targetroot.'/'.$target.' with the new '.
+                ''.$targetroot.'/'.$target.'.lpmlnewconf"'.
+		"); };\n\n";
+	}
+	elsif ($mode eq 'build' && $build) {
+	    push @buildall,$sourceroot.'/'.$source;
+	    push @buildinfo,$targetroot.'/'.$target.';'.$sourceroot.'/'.
+		$source.';'.$build.';'.
+		$dependencies;
+#	    return '# need to build '.$source.";
 	}
 	else {
 	    return '';
@@ -692,13 +850,13 @@ sub format_link {
     if ($linkto) {
 	$parser->get_tag('/link');
 	if ($mode eq 'html') {
-	    return $link="\nBEGIN LINK\n".
+	    return $link="\n<br />BEGIN LINK\n".
 		"$linkto $target $categoryname $description $note " .
 		"$build $status $dependencies" .
 		    "\nEND LINK";
 	}
 	elsif ($mode eq 'install') {
-	    my @targets=split(/\;/,$target);
+	    my @targets=map {s/^\s*//;s/\s$//;$_} split(/\;/,$target);
 	    foreach my $tgt (@targets) {
 		push @links,"\t".'ln -fs /'.$linkto.' /'.$targetroot.$tgt.
 		    "\n";
@@ -722,7 +880,7 @@ sub format_fileglob {
     if ($sourcedir) {
 	$parser->get_tag('/fileglob');
 	if ($mode eq 'html') {
-	    return $fileglob="\nBEGIN FILEGLOB\n".
+	    return $fileglob="\n<br />BEGIN FILEGLOB\n".
 		"$glob sourcedir $targetdir $categoryname $description $note ".
 		"$build $status $dependencies $filenames" .
 		    "\nEND FILEGLOB";
@@ -730,7 +888,7 @@ sub format_fileglob {
 	elsif ($mode eq 'install') {
 	    return "\t".'install '.
 		$categoryhash{$categoryname}.' '.
-		$sourceroot.'/'.$sourcedir.$glob.' '.
+		$sourceroot.'/'.$sourcedir.'[^C][^V][^S]'.$glob.' '.
 		$targetroot.'/'.$targetdir.'.'."\n";
 	}
 	else {
@@ -791,7 +949,18 @@ sub format_build {
     my $text=&trim($parser->get_text('/build'));
     if ($text) {
 	$parser->get_tag('/build');
-	$build=$text;
+	$build=$sourceroot.'/'.$text.';'.$tokeninfo[2]{'trigger'};
+    }
+    return '';
+}
+# -------------------------------------------------------- Format build section
+sub format_buildlink {
+    my @tokeninfo=@_;
+    $buildlink='';
+    my $text=&trim($parser->get_text('/buildlink'));
+    if ($text) {
+	$parser->get_tag('/buildlink');
+	$buildlink=$sourceroot.'/'.$text;
     }
     return '';
 }
@@ -813,7 +982,8 @@ sub format_dependencies {
     my $text=&trim($parser->get_text('/dependencies'));
     if ($text) {
 	$parser->get_tag('/dependencies');
-	$dependencies=$text;
+	$dependencies=join(';',
+			      (map {s/^\s*//;s/\s$//;$_} split(/\;/,$text)));
     }
     return '';
 }
@@ -848,7 +1018,85 @@ sub format_linkto {
     }
     return '';
 }
+# ------------------------------------- Render less-than and greater-than signs
+sub htmlsafe {
+    my $text=@_[0];
+    $text =~ s/</&lt;/g;
+    $text =~ s/>/&gt;/g;
+    return $text;
+}
 # --------------------------------------- remove starting and ending whitespace
 sub trim {
     my ($s)=@_; $s=~s/^\s*//; $s=~s/\s*$//; return $s;
 } 
+
+# ----------------------------------- POD (plain old documentation, CPAN style)
+
+=head1 NAME
+
+lpml_parse.pl - This is meant to parse files meeting the lpml document type.
+See lpml.dtd.  LPML=Linux Packaging Markup Language.
+
+=head1 SYNOPSIS
+
+Usage is for lpml file to come in through standard input.
+
+=over 4
+
+=item *
+
+1st argument is the mode of parsing.
+
+=item * 
+
+2nd argument is the category permissions to use (runtime or development)
+
+=item *
+
+3rd argument is the distribution
+(default,redhat6.2,debian2.2,redhat7.1,etc).
+
+=item *
+
+4th argument is to manually specify a sourceroot.
+
+=item *
+
+5th argument is to manually specify a targetroot.
+
+=back
+
+Only the 1st argument is mandatory for the program to run.
+
+Example:
+
+cat ../../doc/loncapafiles.lpml |\\
+perl lpml_parse.pl html default /home/sherbert/loncapa /tmp/install
+
+=head1 DESCRIPTION
+
+I am using a multiple pass-through approach to parsing
+the lpml file.  This saves memory and makes sure the server
+will never be overloaded.
+
+=head1 README
+
+I am using a multiple pass-through approach to parsing
+the lpml file.  This saves memory and makes sure the server
+will never be overloaded.
+
+=head1 PREREQUISITES
+
+HTML::TokeParser
+
+=head1 COREQUISITES
+
+=head1 OSNAMES
+
+linux
+
+=head1 SCRIPT CATEGORIES
+
+Packaging/Administrative
+
+=cut