-----
Copyright (C) 1999 - 2006 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 c2html 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.
-----

c2html
======

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

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

What is c2html?
---------------

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

Everyone who provides sources in the web.

How do I use c2html?
--------------------

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  c2html  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 C sources on demand only?
---------------------------------------------

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

  AddType text/x-c .c .h
  Action text/x-c /cgi-bin/c2html

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

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

  Action text/x-c /cgi-bin/c2html_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 c2html as a CGI?
-----------------------------------------------

If c2html 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',  c2html 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 c2html 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=\"`c2html -V`\">"
echo "</head>"
echo "<body>"
echo "<h1>Source of $PATH_TRANSLATED</h1>"
echo "<ul>Structures and functions"
cat $PATH_TRANSLATED | c2html -isc
echo "</ul>"
echo "<hr></hr>"
cat $PATH_TRANSLATED | c2html -sc
echo "</body></html>"
exit
---