-----
Copyright (C) 1999, 2000 Florian Schintke
Copyright (C) 1999       Martin Kammerhofer for the CGI feature
Copyright (C) 2000       Rob Ewan           for the indexing feature

This is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2, or (at your option) any later
version.

This is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License with
the java2html source package as the file COPYING.  If not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.
-----

java2html
=========

Where to get java2html?
-----------------------
The homepage of java2html is
http://user.cs.tu-berlin.de/~schintke/x2html/index.html

You can get java2html also from the metalab server:
ftp://metalab.unc.edu/pub/Linux/apps/www/converters/

What is java2html? 
------------------

The java2html  program is a  syntax  highlighter for Java source  code
that produces a  highlighted  html file  as output. The  output can be
read by  any  graphical WWW-Browser.  If  the  browser understands the
tags to change  font colors (as  Netscape  does) the  output will look
like highlighted by  emacs.  Otherwise it will  not look so nice,  but
readability is increased too. 

Who uses java2html?
-------------------

Everyone who provides sources in the web.

How do I use java2html?
-----------------------

This is rather simple. If you start the program without any parameters
it will read the source from stdin and prints the output to stdout. 

If  you invoke java2html with  filenames  on the command  line it will
process every given file in sequence and  will store the output in new
files.  The  names of the new files  are built by appending ".html" to
the corresponding input filename. 

How do I convert my Java sources on demand only?
------------------------------------------------

You need a  webserver to do this.  The webserver must be configured to
INVOKE java2html as a CGI program to handle all *.java files.  If your
webserver is apache you can achieve this by adding lines 

  AddType text/x-java .java
  Action text/x-java /cgi-bin/java2html

to configuration file "http.conf".  The  java2html program expects the
pathname of its  input  file in environment variable  PATH_TRANSLATED.
CGI mode works by checking for environment variables GATEWAY_INTERFACE
and PATH_TRANSLATED. If both are set a HTTP header line 

  Content-Type: text/html

and  meta tags with the file's  last modification date and the program
that generated the html file are written to the html header. 

If you want to call the converter with  default parameters like -n you
have to  write a  wrapper script like  the following  (Notice that you
have to 'chmod +x' the script file): 

file java2html_wrap in the cgi-bin directory of your webserver:
--
#! /bin/sh
./java2html -n
--

Then you let apache call the wrapper script with the following entry: 

  Action text/x-java /cgi-bin/java2html_wrap

Since your sources are converted on-the-fly to HTML you don't need any
webspace  for your  html-ized  files. Furthermore  you  don't have  to
bother about keeping your published html-ized sources up to date. :)

If one wants  to save the html-ized source for compiling  it is best to
use the "Text" format when saving from the browser.

How can I save bandwidth using java2html as a CGI?
--------------------------------------------------

If java2html has been  compiled with -DCOMPRESSION=1 it  will compress
it's HTML output with gzip if your browser supports it. This will save
bandwidth  but add additional load  to  your webserver machine. If you
are connected to a server on 'localhost',  java2html will not compress
it's output by  gzip.  Larger values  for COMPRESSION  than 1  are not
recommended because it adds more CPU load to the server without saving
much bandwidth. 

How can I get an index at the top of the source?
------------------------------------------------

The  -i switch lets you add  a clickable index at the  top of the HTML
page.  The index is a list of the  labels that java2html generates for
your  source file.  Each label  is  converted into  an HTML list  item
(<li>-tag). To add the index, the program must make two passes through
the source file, so you will need a wrapper script like this one:

---
#! /bin/sh
echo "Content-type: text/html"
echo ""
echo "<html>"
echo "<head><title>$PATH_TRANSLATED</title>"
echo "<meta name=\"generator\" content=\"`java2html -V`\">"
echo "</head>"
echo "<body>"
echo "<h1>Source of $PATH_TRANSLATED</h1>"
echo "<ul>Structures and functions"
cat $PATH_TRANSLATED | java2html -isc
echo "</ul>"
echo "<hr></hr>"
cat $PATH_TRANSLATED | java2html -sc
echo "</body></html>"
exit
---