GNU Source-highlight 1.4

April 26th, 2002

by Lorenzo Bettini

This program, given a source file, produces a document with syntax
highlighting.

At the moment this package can handle

   * Java
   * C/C++
   * Prolog
   * Perl
   * Php3 new

as source languages, and HTML as output format.

NOTICE: now the name of the program is source-highlight: there are no two
separate programs, namely java2html and cpp2html, anymore.  However there
are two shell scripts with the same name in order to facilitate the
migration (however their use is not advised).

GNU Source-highlight is free software. Please see the file COPYING for
details. For documentation, please read this file.

GNU Source-highlight is a GNU program and its main home page is at GNU site:

http://www.gnu.org/software/src-highlite/source-highlight.html

Download

You can download it from GNU's ftp site:
ftp://ftp.gnu.org/gnu/source-highlight/ or from one of its mirrors (see
http://www.gnu.org/prep/ftp.html).

I do not distribute Windows binaries anymore; since, they can be easily
built by using Cygnus C/C++ compiler, available at http://www.cygwin.com/.
However, if you don't feel like downloading such compiler, you can request
such binaries directly to me, by e-mail (bettini@gnu.org) and I can send
them to you.
An MS-Windows port of Source-highlight is available from
http://gnuwin32.sourceforge.net/.

You may also want to check the md5sum of the archives, which are also
digitally signed by me (Lorenzo Bettini) with GNU gpg
(http://www.gnupg.org). My GPG public key can be found at my home page (see
at the end of this doc).

You can also get the patches, if they are available for a particular release
(see below for patching from a previous version).

Changes in this release

   * fixed compilation error with some compilers due to headers istream.h
     and ostream.h (thanks to Dan barthel <dbarthel@mac.com>)
   * a scanner for Php3 has been written by Alain Barbet
     <alian@alianwebserver.com>
   * reading from stdin does not kill line numbers (notified by Keith
     Robertson <keithr@nortelnetworks.com>)
   * line number count is correctly reset when handling multiple files (bug
     fixed)
   * for Java sources, if, while, and other keywords that use '(' ')' are
     now correctly highlighted as keywords instead of as functions (reported
     by Manuel Kauers <manuel@kauers.de> and Fabio Calefato
     <calefato@libero.it>)
   * tabs are correctly handled for Prolog and Perl sources (reported by
     Martin Gebert <Murphy.Gebert@gmx.de>)

Changes in version 1.3

   * now there is only one program, namely source-highlight, that accepts a
     command line option, --src-lang or -s, specifying the source language
     (for the moment java, cpp and prolog).  Previous programs, java2html
     and cpp2html are provided as shell scripts, just for compatibility, but
     their use is not advised.
   * --out-format, -f, command line option added for specifying the output
     format (for the moment only html is accepted).  Though only html is
     handled, this option is required.
   * a scanner for Prolog has been written by Martin Gebert
     <Murphy.Gebert@gmx.de>.  This scanner is still to be considered beta,
     and actually it was written for Visual Prolog, so it should be tested
     against other Prolog dialects.
   * a scanner for Perl has been written by Alain Barbet
     <alian@alianwebserver.com>
   * Correctly check whether it is possible to write to a file (notified by
     Martin)
   * --tab option is correctly handled even for C/C++ files (bug fixed,
     notified by Martin)
   * Added option --line-number (-n) in order to print line numbers (as
     suggested by Ed Scott and Andre Charbonneau).
   * Man page added.

Changes in version 1.2.1

   * Fixed a problem of compilation for gcc 3.0 (thanks to Alexios Zavras
     <zvr@pobox.com> and Bruno Schweizer <bruno@smda.medizin.uni-ulm.de>)
   * much more recent versions of getopt.h, getopt.c, getopt1.c are provided
     (the previous ones were very very old!), that do not rely on alloca
     anymore.

Changes in version 1.2

   * Added normal text decoration (specify "normal" in tags.j2h) (suggested
     by Bernie Boudet <bboudet@bigfoot.com>).
   * fixed a bug for multiple input files (notified by Christian Paulsen
     <christian.paulsen@sdrc.com>)

Martin Gebert <Murphy.Gebert@gmx.de> is also implementing a KDE interface to
source-highlight programs, at the moment it is still in beta (but he did a
wonderful job!), and it is called ksrc2html; if you want to test it:
http://murphy.netsolution-net.de/Ksrc2.html.

CGI support was enabled thanks to Robert Wetzel
<rw8@mail.inf.tu-dresden.de>; I haven't tested it personally yet, so you may
ask him directly. Moreover he set up some examples at the page
http://www.inf.tu-dresden.de/~rw8/java2.html.

Moreover there's also a Java version of java2html, made by
bayard@generationjava.com, you can find it at
http://www.generationjava.com/java/Java2Html.shtml.

see also NEWS file and ChangeLog for the complete list of changes between
versions.  Previous changes are summarized in old_changes.html.

Installation

See the file INSTALL for detailed building and installation instructions;
anyway if you're used to compiling Linux software that comes with sources
you may simply follow the usual procedure:

cd <source code main directory>
./configure
make
make install

Note: unless you specify a different install directory by --prefix option of
configure (e.g. ./configure --prefix=<your home>), you must be root to 'make
install'.

It is also possible to specify as following option for configure:
--enable-input-chroot to hardcode in the program the path to prefix for
input files.

Before you run 'make install' you may want to check that the programs have
compiled fine, so you can run 'make check'.

Files will be installed in the following directories:

   * Executables          -> /prefix/bin
   * docs and samples     -> /prefix/share/doc/source-highlight
   * conf files           -> /prefix/share/source-highlight

Default value for prefix is /usr/local but you may change it with --prefix
option to configure (see above).

What you need to build source-highlight

Actually you need nothing more than a Unix C/C++ compiler

source-highlight has been developed under Linux, using gcc (C++), and bison
(yacc) and flex (lex), and ported under Win32 with Cygnus C/C++ compiler,
available at http://www.cygwin.com/ (a .DLL is also distributed together
with the .exe: you may simply copy it in the same place of the .exe). I used
the excellent GNU Autoconf and Automake. I also used Autotools
(ftp://ftp.ugcs.caltech.edu/pub/elef/autotools) which creates a starting
source tree (according to GNU standards) with autoconf, automake starting
files. Finally I used GNU gengetopt (http://www.gnu.org/software/gengetopt),
for command line parsing.

Actually, unless you want to develop source-highlight, you don't need all
these tools to build source-highlight because I provide generated sources;
you don't need neither bison (yacc) nor flex (lex), for the same reason.
Actually programs that use lex generated files need to link with library
libfl (or libl for lex); anyway configuration phase can discover if this
library is missing and in that case it sets the program to link with a
source file I provide. This hack works for flex: I don't know about lex
generated scanners. But, again, this is a problem only if you develop
source-highlight and you use lex.

Patching from a previous version

If you downloaded a patch, say source-highlight-1.3-1.3.1-patch.gz(i.e. the
patch to go from version 1.3 to version 1.3.1), cd to the directory with
sources from the previous version (source-highlight-1.3) and type:

gunzip -cd ../source-highlight-1.3-1.3.1.patch.gz | patch -p1

and restart the compilation process (if you had already run configure a
simple make will do).

Usage and examples

source-highlight only does a lexical analysis of the source code, so the
program source is assumed to be correct !

here's how to run source-highlight (for this example we will use C/C++ input
files, but this is valid also for other source-highlight input languages):

source-highlight --src-lang cpp --out-format html --input <file (a C++ prog)> --output <file (an html)> [options]

For input files you can also use regular expression.

If you do not specify the name of the output file, the name will be the one
of the source file with a .<ext> appended, where <ext> is the extension
chosen according to the output format specified (in this example it would be
.html).

Required command line options are:

  1. --src-lang (or -s) <lang>: where <lang> can be:
        o java (for Java)
        o cpp (for C/C++)
        o prolog (for Prolog)
        o perl (for Perl)
        o php3 (for Php3)
     This specifies the language used to write the sources that have to be
     processed.
  2. --out-format (or -f) <format>: where <format> can only be html.  This
     specifies the format for the output of the highlighter (for the moment
     only html output can be produced).

Other command line options:
If you want a real html document, specify --doc option at the end. Otherwise
you just get some text to copy and paste in you own html pages. If you
choose -doc option the page will have a white background and your source
file name as title. --tab n option apply a substitution of tab characters
with n spaces. You also may want to specify the title of the page with
--title "my title" option (this implies -doc). Now you can also generate an
html with CSS format, by using --css "url of .css" (try some .css files
included in the package). The order of the options is not relevant. You may
also want to customize the produced document: you can use --header and
--footer options that allow you to specify files to be included,
respectively, at the beginning and at the end of the document. --tags-file
allows to specify the location of the file for format options (see below).
--output-dir specifies the output directory (if the output option is not
specified the same directory of the source file is used).  --line-number
option enables generation of line numbers.

Here are some links to some of the C and C++ sources of source-highlight
colored with source-highlight itself:

     startapp.cc.html

generated with the following command

     source-highlight -s cpp -f html --doc startapp.cc

Obviously it works with C files as well:

     cmdline.c.html

Created with the command (notice that this one uses both CSS file and
headers and footers):

     source-highlight -s cpp -f html -i cmdline.c -o cmdline.c.html
                 --css="cpp2html.css"
                 --header="./header.html" --footer="./footer.html"

And obviously it works with header file as well:

     cmdline.h.html

created with the command:

     source-highlight -s cpp -f html *.h --css="mono.css"

Here are some examples of Java files processed with source-highlight: Use
Hello.java to make some test, if you want. Here's how Hello1.html,
Hello2.html, Hello3.html, Hello4.html, Hello5.html, Hello_h_f.html,
Hello_lines.html were created:

source-highlight -s java -f html -i Hello.java -o Hello1.html
source-highlight -s java -f html --input Hello.java --output Hello2.html --doc
source-highlight -s java -f html -i Hello.java -o Hello3.html --title "Happy Java with java2html :-)" --tab 3
source-highlight -s java -f html < Hello.java > Hello4.html --title "and what about CSS :-)" --css "Hello.css"
source-highlight -s java -f html < Hello.java > Hello5.html --title "Wooo... this is quite dark ;-D" --css "mono-alt.css"
source-highlight -s java -f html --doc *.java
Processed Hello.java   (creates Hello.java.html)
source-highlight -s java -f html --doc -i Hello.java -o Hello_h_f.html --tags-file="tags2.j2h" --header="header.html" --footer="footer.html"
source-highlight -s java -f html --line-number --doc -i Hello.java -o Hello_lines.html

Here's the output of source-highlight applied to a Prolog program (through
the option `source-highlight -s prolog`: test.pl.html.  This one is an
highlighted Perl program (through the option `source-highlight -s prolog`):
test.pm.html.  And here's an highlighted PHP3 program: test.php3.html.

And here's the output of `source-highlight --help`

GNU source-highlight 1.4

Purpose:
  Highlight the syntax of a source file (e.g. Java)
  into a specific format (e.g. HTML)

Usage: source-highlight [OPTIONS]... [FILES]...
   -h         --help               Print help and exit
   -V         --version            Print version and exit
   -iSTRING   --input=STRING       input file. default std input
   -oSTRING   --output=STRING      output file. default std output
   -sSTRING   --src-lang=STRING    source language (e.g. java, cpp, prolog, perl)
   -fSTRING   --out-format=STRING  output format (e.g. html)
   -v         --verbose            verbose mode on
   -d         --doc                create html with title and header
   -cSTRING   --css=STRING         use a css for formatting. Implies --doc
   -TSTRING   --title=STRING       give a title to the html. Implies --doc
   -tINT      --tab=INT            specify tab length. default 8
   -HSTRING   --header=STRING      file to insert as header
   -FSTRING   --footer=STRING      file to insert as footer
              --tags-file=STRING   specify format options (def. tags.j2h)
   -n         --line-number        number all output lines
              --output-dir=STRING  output directory

Maintained by Lorenzo Bettini <bettini@gnu.org>
Report bugs to <bug-source-highlight@gnu.org>

As it handles standard output and input you may also run it like

cat MyFile.cpp | source-highlight -s cpp -f html | lpr

You may want to specify your options for syntax highlighting in the file
tags.j2h. If this file is not present in the current directory, some default
colors will be used. Here's the tags.j2h file that comes with this
distribution:

keyword blue b ;      for language keywords
type darkgreen ;      for basic types
string red ;          for strings and chars
comment brown i ;     for comments
number purple ;       for literal numbers
preproc darkblue b ;  for preproc directives (e.g. #include, import)
symbol darkred ;      for simbols (e.g. <, >, +)
function black b;     for function calls and declarations
cbracket red;         for block brackets (e.g. {, })

tags2.j2h also specify the color of normal text, indeed it adds this line

normal darkblue ;

as you might see the syntax of this file is quite straightforward:

   * b = bold
   * i = italics
   * u = underline

You may also specify more than on of these options separated by commas
e.g.

keyword blue u, b ;

you may see all possible colors in the file colors.html but you can also use
the standard #<number> html syntax for specifying a color.

if something goes wrong with your options try to run source-highlight with
--verbose option enabled.

Credits

Some of these people helped me previously with java2html, and cpp2html, so
they implicitly helped me also for source-highlight:

   * Marcus G. Daniels <marcusd@gnu.org> who gave me some good advices about
     GNU standards,
   * Osvaldo Pinali Doederlein <osvaldo@visionnaire.com.br> for tab option
     idea,
   * Richard Freedman <rich_freedman@chiinc.com> for feed back and bug
     notifications
   * John Constantine <John.Constantine@mail.cc.trincoll.edu> for some great
     suggestions I'll surely apply.
   * Raymond Lambe <rlambe@morgan.ucs.mun.ca>, for quotation bug
     notification
   * Robert J. Clark <clark@klgroup.com> for adding -input, -output, -title
     options
   * Hans-Peter Bischof <hpb@cs.rit.edu> for suggestions (to apply).
   * Luc Maisonobe <Luc.Maisonobe@cnes.fr> for the patch for const char * in
     order to make it work under gcc 2.95
   * Jari Korva <jari.korva@iki.fi> for the bug of \" inside a string and &
     treatment, and especially for adding CSS options and handling
   * Kaloian Doganov <kaloian@stones.com> for .css suggestion and for
     providing some nice .css files
   * Ziv Caspi <zivc@peach-networks.com> found the bug of \\ in chars
   * Chris Mason <cjmaso@essex.ac.uk> found the darkgreen bug, and that
     --tab was not documented
   * Michael Gasche <mgasche@datacomm.ch> found the bug of /* comment inside
     another environment
   * Xavier Outhier <xouthier@yahoo.fr> added --header and --footer options
   * Tom Hull <thull@kscable.com> added hexadecimal and floating point
     handling
   * Maxim Dementiev <maxim@rtcomm.ru> reported bug in cmdline.c
   * Geurt Vos <geurt@xosl.org> sent me keywords file and added many
     highlightings and # color formats, and added some colors.
   * Aldo D. Longhi <aldo.longhi@alum.wpi.edu> reported alloca problem
   * Robert Wetzel <rw8@mail.inf.tu-dresden.de> added CGI support
   * Martin Gebert <Murphy.Gebert@gmx.de> notified some errors, and he's
     implementing ksrc2html, a KDE interface to these programs.  He also
     wrote the scanner for Prolog.
   * Arto Viitanen <av@cs.uta.fi> found some bugs
   * Bernie Boudet <bboudet@bigfoot.com> suggested customization of normal
     text
   * Christian Paulsen <christian.paulsen@sdrc.com> notified the error for
     multiple input files
   * Alexios Zavras <zvr@pobox.com> and Bruno Schweizer
     <bruno@smda.medizin.uni-ulm.de> notified the problem in compilation
     with gcc 3.0.
   * Ed Scott <edscott@worldnet.att.net> and Andre Charbonneau
     <andrec@xandros.com> suggested line number feature.
   * Alain Barbet <alian@alianwebserver.com> wrote the Perl scanner.
   * Dan barthel <dbarthel@mac.com> fixed a compilation error on some
     compilers
   * Keith Robertson <keithr@nortelnetworks.com> notified a bug in line
     numbering in the presence of I/O redirection
   * Manuel Kauers <manuel@kauers.de> and Fabio Calefato
     <calefato@libero.it> reported the bug of if, while, highlighting for
     Java sources.

See also THANKS  :-)

Feedback

Please tell me if you like this software :-)

Actually I want to extend it, so if you have some ideas...
The most import one will be to make source-highlight more customizable :-)

Please send all bug reports by electronic mail to:
bug-source-highlight@gnu.org

TODO

Here's the list of TODO stuff, if you'd like to contribute :-)

Mailing Lists

The following mailing lists are available:

   * help-source-highlight@gnu.org, for generic discussions about the
     program and for asking for help about it (open mailing list),
     http://mail.gnu.org/mailman/listinfo/help-source-highlight
   * info-source-highlight@gnu.org, for receiving information about new
     releases and features (read-only mailing list),
     http://mail.gnu.org/mailman/listinfo/info-source-highlight

if you want to subscribe to a mailing list just go to the URL and follow the
instructions, or send me an e-mail and I'll subscribe you.

My home page is
http://w3.newnet.it/bettini  or
http://infostud.dsi.unifi.it/~bettini (very fast if you're in University)

source-highlight is free software. See the file COPYING for copying
conditions. Anyway I won't get offended if you send me a postcard :-)

  ------------------------------------------------------------------------

Return to GNU's home page.

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also
other ways to contact the FSF.

Please send comments on these web pages to webmasters@gnu.org, send other
questions to gnu@gnu.org.

Copyright (C) 2001 Free Software Foundation, Inc., 59 Temple Place - Suite
330, Boston, MA 02111, USA

Verbatim copying and distribution of this entire article is permitted in any
medium, provided this notice is preserved.

Updated:9 Jan 2001 mhw
  ------------------------------------------------------------------------
