README for libformat
====================

libformat is an adaptation of mod_format (see README below) to do syntax
highlighting of source code using HTML outside of Apache.  libformat is 
capable of syntax highlighting C, C++, Java, Python, Verilog and VHDL 
source code.

API description
---------------

The libformat API contains five functions:

int   format_valid_lang ( const char *language );

The above function may be used to determine whether a particular language
is supported by libformat.  It returns a 1 if the requested language is 
supported, and a 0 otherwise.

char *format_fd     ( int   fd,       const char *language );
char *format_fp     ( FILE *fp,       const char *language );
char *format_file   ( char *filename, const char *language );
char *format_string ( char *str,      const char *language );

The output of each of the four functions above is a memory-allocated string 
of HTML text.  This is the syntax-highlighted source code, where the source 
code is read from the first argument to the function.  The syntax 
highlighting is done by enclosing sections of the source code in CSS font 
tags of the form <FONT class="xyz">...</FONT> throughout, and the entire 
input is then enclosed in <PRE>...</PRE> for fixed-width formatting.  

HTML output
-----------

Note that these functions do not produce complete HTML documents.  However, 
turning their output into a complete HTML document is a simple task.  The 
"srcformat" utility prints complete HTML documents when supplied with a 
language and a filename.  The most important thing you will need to generate 
complete HTML is a suitable cascading style sheet (CSS) document.  One such 
document is provided with libformat as "format.css" in the docs directory.  
This file is installed as $(datadir)/libformat/format.css by default.  

Current language capabilities
-----------------------------

Currently, the valid values for the char *language argument to the API 
functions are:

"c"        for C source and header files
"c++"      for C++ source and header files
"java"     for Java
"python"   for Python
"verilog"  for Verilog
"vhdl"     for VHDL


Feedback
--------

Please send bugs, suggestions, comments to Dave Bailey <dave@daveb.net>
or Robert Helgesson <rycee@home.se>.


Information about the mod_format Apache module (from the mod_format README)
===========================================================================

mod_format is a flex-based Apache module for formatting C, C++, and Java
source code using HTML.  Once installed into an Apache server,
mod_format will format HTTP requests for source code using HTML.
mod_format performs the following functions:

 - Performs language-sensitive syntax highlighting
 - Indents code blocks uniformly
 - Highlights URLS present in code

Please send bug reports, suggestions, and comments to
<sfbooth@earthlink.net>

There is a small site dedicated to mod_format at 
http://home.earthlink.net/~sfbooth/mod_format/