-----
Copyright (C) 1999, 2000 Florian Schintke
Copyright (C) 1999       Martin Kammerhofer for the CGI 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 perl2html 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.
-----

perl2html
=========

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

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

What is perl2html? 
------------------

The perl2html program is a   syntax highlighter for Perl 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 perl2html?
-------------------

Everyone who provides sources in the web.

How do I use perl2html?
-----------------------

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  perl2html 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 Perl sources on demand only?
------------------------------------------------

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

  AddType text/x-perl .pl .pm
  Action text/x-perl /cgi-bin/perl2html

to configuration file "http.conf".   The perl2html 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 perl2html_wrap in the cgi-bin directory of your webserver:
--
#! /bin/sh
./perl2html -n
--

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

  Action text/x-perl /cgi-bin/perl2html_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 perl2html as a CGI?
--------------------------------------------------

If  perl2html 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', perl2html   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. 
