# -*-perl-*-
#/*@@
#  @file      grdoc_helpers
#  @date      Sun Apr 21 11:08:21 1996
#  @author    Paul Walker
#  @desc 
#  Helper routines for the grdoc system
#  @enddesc 
#  @comment
#  <code>$Id: grdoc_helpers,v 1.22 1996/04/22 01:14:49 pwalker Exp $</code>
#  @endcomment
#@@*/


#/*@@
#  @routine    html_head
#  @date       Sun Apr 21 11:09:07 1996
#  @author     Paul Walker
#  @desc 
#  Prints the head of an html document, including body, navigation etc...
#  Prints to OUT because I don't like select...
#  @enddesc 

#  @var     title
#  @vdesc   Title of the page
#  @vtype   string
#  @vio     in
#  @endvar 

#  @calledby   
#@@*/

sub
html_head
{
    local($title)=@_[0];
    print OUT "<html>\n<title>$title</title>\n<body bgcolor=\"#ffffff\">\n";
    print OUT "<!-- $title: created by grdoc -->\n";
    print OUT "<!-- For more on grdoc, see http://jean-luc.ncsa.uiuc.edu/Codes/grdoc/ -->\n";
    print OUT "<!-- grdoc Copyright University of Illinois Trustees -->\n";
    print OUT "<!-- grdoc by Paul Walker with Joan Masso -->\n";
}

#/*@@
#  @routine    html_foot
#  @date       Sun Apr 21 11:11:05 1996
#  @author     Paul Walker
#  @desc 
#  Prints the html footer for each page.  Also generates the "generated
#  on" date if it hasn't been done already.
#  @enddesc 

#  @var     code
#  @vdesc   String to print for code name
#  @vtype   string
#  @vio     in
#  @endvar 

#@@*/


sub
html_foot
{
    local($code)=@_[0];
    if (!$html_foot_date) {
	($s,$m,$h,$md,$mo,$y,$wd,$yd,$isdst) = localtime();
	@mo = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug",
	       "Sep", "Oct", "Nov", "Dec");
	$m = "0$m" if ($m < 10);
	$html_foot_date = "Created $mo[$mo] $md, 19$y at $h:$m";
	$html_foot_date = "$html_foot_date by <a href=\"http://jean-luc.ncsa.uiuc.edu/Codes/grdoc/\">grdoc</a>";
    }
    print OUT "<hr>\n";
    print OUT "<!-- Document End -->";
    print OUT "$code<br>\n";
    print OUT "$html_foot_date<br>\n";
    print OUT "$organization / \n<a href=\"mailto:$author\">$author</a>\n";
    print OUT "</body>\n</html>\n";
}

#/*@@
#  @routine    strip_dirs
#  @date       Sun Apr 21 11:12:20 1996
#  @author     Paul Walker
#  @desc 
#  Strips dirs out of a filename.  eg, given foo/bar/hootie, returns hootie.
#  @enddesc 
#
#  @var     stripthis
#  @vdesc   The thing to strip
#  @vtype   string
#  @vio     in
#  @endvar 
#
#  @returntype string
#  @returndesc
#  The stripped string
#  @endreturndesc
#@@*/

sub
strip_dirs
{
    local($stripthis) = @_[0];
    return ($stripthis) unless ($stripthis =~ m:/:);
    if ($stripthis =~ /\/$/) {
	$stripthis =~ m:/([^/]+)/$:;
	$result = $1;
    } else {
	$stripthis =~ m:/([^/]+)$:;
	$result = $1;
    }

    return ($result);
}

#/*@@
#  @routine    sub_dir
#  @date       Sun Apr 21 11:14:17 1996
#  @author     Paul Walker
#  @desc 
#  Returns the stuff not returned by @seeroutine strip_dirs, eg,
#  given foo/bar/hootie returns foo/bar
#  @enddesc 

#  @var     stripthis
#  @vdesc   The thing to extract the subdir from
#  @vtype   string
#  @vio     in
#  @endvar 

#  @returntype string
#  @returndesc
#  The subdir of the file in question
#  @endreturndesc

#@@*/

sub
sub_dir
{
    local ($stripthis) = @_[0];
    $stripthis =~ s:$opt_i::;
    $stripthis =~ m:^(.*)/([^/]+)$:;
    $result = $1;
    $result =~ s:^/::;
    return $result;
}

#/*@@
#  @routine    insert_readme
#  @date       Sun Apr 21 11:15:43 1996
#  @author     Paul Walker
#  @desc 
#  Inserts a readme.html into the current OUT if one exists in $dir
#  @enddesc 
#  @var     dir
#  @vdesc   The directory to check!
#  @vtype   string
#  @vio     in
#  @endvar 
#@@*/


sub
insert_readme
{
    local ($dir) = @_[0];
    if (-e "$dir/README.html") {
	open (IN, "<$dir/README.html")||die "$in/README.html: $!\n";
	print OUT "<hr>";
	while (<IN>) {
	    print OUT;
	}
	print OUT "<hr>";
	close IN;
    } else {
	print OUT "<hr>";
    }
}

#/*@@
#  @routine    insert_header
#  @date       Sun Apr 21 11:15:43 1996
#  @author     Paul Walker
#  @desc 
#  Inserts a header.html into the current OUT if one exists in $dir
#  @enddesc 
#  @var     dir
#  @vdesc   The directory to check!
#  @vtype   string
#  @vio     in
#  @endvar 
#@@*/

sub
insert_header
{
    local ($dir) = @_[0];
    if (-e "$dir/HEADER.html") {
	open (IN, "<$dir/HEADER.html")||die "$in/HEADER.html: $!\n";
	while (<IN>) {
	    print OUT;
	}
	close IN;
    } else {
	print OUT "<h1 align=center>$opt_c</h1>";
    }
}

#/*@@
#  @routine    make_dotdot
#  @date       Sun Apr 21 11:17:04 1996
#  @author     Paul Walker
#  @desc 
#  A broken routine which tried to make relative links.  This was
#  replaced in favor of the third pass (@seeroutine main) which turns
#  the GRDOCREPLACEWITHRELATIVEXREF with the correct thing when we're
#  done.
#  @enddesc 
#@@*/


sub
make_dotdot
{
    local ($infile) = @_[0];

    $result = $infile;
    $result =~ s:$opt_o/::;
    $result =~ s:$opt_i/::;
    $result =~ s:/([^/]+)$:/:;
    $result =~ s:([^/])+/:\.\./:g;
    return ($result);
}

#/*@@
#  @routine    navigation
#  @date       Sun Apr 21 11:18:06 1996
#  @author     Paul Walker
#  @desc 
#  Prints the navigation bar [ Top | ... to OUT.
#  @enddesc 
#@@*/

sub
navigation
# prints navigation for the indices to out, centered.
{
    print OUT <<EOM;
<div align=center>
[ <b><a href="${opt_t}/index.html" target="_top">Top</a></b> |
<b><a href="${opt_t}/Files.html" target="_top">Files</a></b> |
<b><a href="${opt_t}/Routines.html" target="_top">Routines</a></b> |
<b><a href="${opt_t}/Vars.html" target="_top">Vars</a></b> |
<b><a href="${opt_t}/Pars.html" target="_top">Pars</a></b> |
<b><a href="${opt_t}/Help.html" target="_top">Help</a></b> 
]
</div>
EOM
}

#/*@@
#  @routine    localnav
#  @date       Sun Apr 21 11:18:48 1996
#  @author     Paul Walker
#  @desc 
#  Prints the local navigation stuff for a routine of file.  This routine
#  calls @seeroutine resolve_XRefs to generate the Foo [rich|raw]
#  sort of things.  Prints to OUT.
#  @enddesc 
#  @calls    resolve_XRefs

#  @var     thing
#  @vdesc   The file or routine which we want to generate the thing for
#  @vtype   string
#  @vio     in
#  @endvar 

#  @var     brief
#  @vdesc   Basically a string which, if defined, will cause a brief listing
#  @vtype   anything
#  @vio     in
#  @vcomment 
#  Just a definition check here...  A brief listing lacks the [ | ]
#  after it.
#  @endvar 

#  @var     srcurl
#  @vdesc   A named link into the other frame for the richdoc
#  @vtype   string
#  @vio     in
#  @vcomment 
#  An existance check is done, which sees if it should use this to
#  generate the | show] link or not
#  @endvar 


#  @comment Sorry...
#  This is a little hairy...
#  @endcomment

#@@*/


sub
localnav
# prints navigation for a routine or file to OUT, noncentered
{
    local ($thing, $brief, $srcurl) = @_;
    local ($msd);

    if ($routine_home{$thing}) {
	# We're dealing with a routine
	$parent = $routine_home{$thing};
	$richfile= &resolve_XRefs("\@seefile $parent");
	$docfile = &resolve_XRefs("\@seefile $parent", "norich");
	$routdoc = &resolve_XRefs("\@seeroutine $thing", "norich");
	$rawsrc  = $docfile;
	$rawsrc  =~ s:_File_Doc:_src:;
	$rawsrc  =~ s:\.html:.html\#$thing:;
	$rawsrc  =~ s:$opt_t/:$opt_t/PROTECTED/:;
	$tree = $routdoc;
	$tree =~ s:_Routine_Doc:_Routine_Tree:;

	# OK, so now change the text
	$richfile =~ s:>$parent:>rich:;
	$rawsrc   =~ s:>$parent:>raw:;
	$tree     =~ s:>$thing:>tree:;

	# And make the link
	print OUT "<b>Routine</b> " if !$brief;
	print OUT "<font size=+1>$routdoc</font> <font size=-1>[$tree";
	if (!$brief) {
	    print OUT "]</font>\n in file ";
	    $msd = $mysubdir{$parent};
	    if ($msd =~ m:\S:) {
		print OUT "<a href=\"$opt_t/$msd/\">";
		print OUT "src/$msd</a>/";
	    } else {
		print OUT "<a href=\"$opt_t/\">";
		print OUT "src</a>/";
	    }		
	    print OUT "$docfile ";
	    print OUT "<font size=-1>[$richfile | $rawsrc]</font>\n";
	} else {
	    if ($srcurl) {
		print OUT " | <a href=\"$srcurl#$thing\" target=\"src\">";
		print OUT "show</a> ]</font>\n";
	    } else {
		print OUT "]</font>\n";
	    }
	}
    } elsif ($mysubdir{$thing} || $rootfiles{$thing}) {
	# We're dealing with a file
	$richfile= &resolve_XRefs("\@seefile $thing");
	$docfile = &resolve_XRefs("\@seefile $thing", "norich");
	$rawsrc  = $docfile;
	$rawsrc  =~ s:_File_Doc:_src:;
	$rawsrc  =~ s:$opt_t/:$opt_t/PROTECTED/:;

	# OK, so now change the text
	$richfile =~ s:>$thing:>rich:;
	$rawsrc   =~ s:>$thing:>raw:;

	# And make the link
	print OUT "<b>File</b> " if !$brief;
	print OUT "<font size=+1>$docfile</font> ";
	print OUT "<font size=-1>[$richfile | $rawsrc]</font>\n";
	if (!$brief) {
	    print OUT "in ";
	    $msd = $mysubdir{$thing};
	    if ($msd =~ m:\S:) {
		print OUT "<a href=\"$opt_t/$msd/\">";
		print OUT "src/$msd</a>/";
	    } else {
		print OUT "<a href=\"$opt_t/dirlisting.html\">";
		print OUT "src</a>/";
	    }		
	}
    } else {
	# We're dealing with an unresolved XRef
	print OUT "<b>Unknown</b> " if !$brief;
	print OUT "<font size=+1>$thing</font>";
	print OUT "</font>";
    }
}


#/*@@
#  @routine    html_safe
#  @date       Sun Apr 21 11:24:39 1996
#  @author     Paul Walker
#  @desc 
#  Makes stuff safe for inclusion in html (eg, turns < > & into &lt; etc..)
#  but still pays attention to img and a href tags, which live!
#  <p>
#  Note, if an optional second argument is passed, NO html survives!
#  @enddesc 
#@@*/

sub
html_safe
# Makes lines safe for html folks but protects hrefs, img src, and div.
{
    local ($value, $supersafe) = @_;
    $value =~ s:\&:\&amp\;:g;

    $value =~ s:<(/a|div|/div|img src=[^>]+|a href=[^>]+)>:\&LT\;\1\&GT\;:g
	if (!$supersafe);
    $value =~ s:<:\&lt\;:g;
    $value =~ s:>:\&gt\;:g;
    if (!$supersafe) {
	$value =~ s:\&LT\;:<:g;
	$value =~ s:\&GT\;:>:g;
    }
    return $value;
}    

#/*@@
#  @routine    indent
#  @date       Sun Apr 21 11:25:35 1996
#  @author     Paul Walker
#  @desc 
#  Makes a table to indent 5%.  Love those non-standard uses of html,
#  eh?
#  @enddesc 

#  @var     dome
#  @vdesc   The thing to indent!
#  @vtype   string
#  @vio     in
#  @endvar 

#  @returntype string
#  @returndesc
#  Returns $dome put in a 95% aligned table.
#  @endreturndesc

#  @comment
#  Before you complain that I shouldn't use tables for layout, please
#  consult the web page, where it says I don't care about what you
#  think about how grdoc uses html.
#  @endcomment
#@@*/

sub
indent
{
    local ($dome) = @_[0];
    $str = "<div align=right><table width=95%><tr><td>$dome</td></tr>";
    $str = "$str</table></div>";
    return $str;
}

#/*@@
#  @routine    de_punctualize
#  @date       Sun Apr 21 11:27:52 1996
#  @author     Paul Walker
#  @desc 
#  Strips punctuation out of end of a routine.  So if we pass foo, we
#  get back an array which is ("foo", ",").
#  @enddesc 

#  @var     value
#  @vdesc   The thing to depunct
#  @vtype   string
#  @vio     in
#  @endvar 

#  @returntype (string, string)
#  @returndesc
#  The first string is the depunctualized thing.  The second is the
#  punctuation which was stripped.
#  @endreturndesc

#  @comment
#  Punctuation is a strange word, so if I misused it, deal!
#  @endcomment
#@@*/

sub
de_punctualize
{
    local ($value) = @_[0];
    local ($nop, $punct);
    if ($value =~ m:[\.\,\?\!\)\(]+$:) {
	$nop = $value;
	$nop =~ s:([\.\,\?\!\)\(]+)$::g;
	$punct = $1;
    } else {
	$nop = $value;
	$punct = "";
    }
    return ($nop, $punct);
}

# ? I love perl. :
1;

