GNU Source-highlight - GNU Project - Free Software Foundation (FSF)
Author: Lorenzo Bettini

# GNU Source-highlight 1.2.1

December 21st, 2001

by Lorenzo Bettini

This package is a collection of programs that given a source file, produces a document with syntax highlighting.

At the moment this package contains GNU java2html 1.10 and GNU cpp2html 1.6.

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.cygnus.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 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>)

## Changes in version 1.1

- Included some standard headers; otherwise gcc 2.96 didn't compile (thanks to Arto Viitanen <av@cs.uta.fi>).
- fixed bug (seg.fault) with foreign character, such as ü (thanks to Martin Gebert <Murphy.Gebert@gmx.de>).
- --output-dir added to specify the output directory.
- --enable-input-chroot configure option to hardcode the path to prepend for input files (useful when the programs are built for CGI, as suggested by Robert Wetzel <rw8@mail.inf.tu-dresden.de>).

## Changes in version 1.0

- This is the first release of source-highlight, but it includes already existing programs (cpp2html and java2html), so the changes are related to these programs.
- CGI support enabled (thanks to Robert Wetzel <rw8@mail.inf.tu-dresden.de>); I haven't tested it personally yet, so you may ask him directly.
- newline handled correctly according to HTML specifications (again thanks to Robert Wetzel).
- Added preprocessor highlighting [preproc], symbol (+,-,^, etc.) highlighting [symbol], curly bracket highlighting [cbracket], function highlighting [function] (thanks to Geurt Vos <geurt@xosl.org>).
- for tags.j2h, added support to enter direct RGB color values (#rrggbb) and colors teal, gray, and darkblue added (thanks to Geurt Vos <geurt@xosl.org>).
- green, darkgreen and brightgreen handled correctly (thanks to Martin Gebert <Murphy.Gebert@gmx.de>).

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.

## 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 prepend 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.cygnus.com/ (a .DLL is also distributed togheter 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 programs only does a lexical analisys of the source code, so the program source is assumed to be correct !

here's how to run a source-highlight program (for this example we will use cpp2html, but this is valid also for other source-highlight programs):

    cpp2html --input <file (a C++ prog)> --output <file (an html)> [options]

or

    cpp2html [options] <input-files>

As 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 .html appended.
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).

Here are some links to some of the sources of source-highlight colored with cpp2html itself:

> startapp.cc.html

generated with the following command

>     cpp2html --doc startapp.cc

Obviosly 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):

>     cpp2html -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:

>     cpp2html *.h --css="mono.css"

Here are some examples of java2html: 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 were created:

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

And here's the output of ``cpp2html --help``

    GNU cpp2html 1.6 (GNU source-highlight 1.2.1)
    source-highlight 1.0

    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
       -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
       -iSTRING   --input=STRING      input file. default std input
       -oSTRING   --output=STRING     output file. default std output
       -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)
                  --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 | cpp2html | 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 cpp2html with `--verbose` option enabled.

## Credits

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 bugs signalations
- 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 signalation
- 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 & treatme nt, 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
- 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.

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