GNU Source-highlight 2.11

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

Source-highlight reads source language specifications dynamically, thus it can be easily extended (without recompiling the sources) for handling new languages. It also reads output format specifications dynamically, and thus it can be easily extended (without recompiling the sources) for handling new output formats. The syntax for these specifications is quite easy (take a look at the manual).

Source-highlight is a command line program, and it can also be used as a CGI.

Notice that source-highlight can also be used as a formatter (i.e., without highlighting): you can, for instance, format a txt file in HTML (and it will take care of translating special characters, such as, <, >, &).

Since version 2.2, source-highlight can also generate cross references; in order to do this it relies on GNU Ctags, http://ctags.sourceforge.net.

These are the output formats already supported:

HTML
XHTML
LATEX
TEXINFO
ANSI color escape sequences (you can use this feature with less)
DocBook

These are the input languages (or input formats) already supported (in alphabetical order):

Autoconf files
C/C++
C#
Bib
Bison
Caml
Changelog
Css
Diff
Flex
Fortran
GLSL
Haxe
Html
ini files
Java
Javascript
KDE desktop files
Latex
Ldap files
Logtalk
Log files
lsm files (Linux Software Map)
Lua
Makefile
M4
ML
Pascal
Perl
PHP
Postscript
Prolog
Properties files
Python
RPM Spec files
Ruby
Scala (new)
Shell
S-Lang
Sql
Tcl
XML
XOrg conf files (new)

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

For further information, please consult the manual.

GNU Source-highlight 2.7

On-line Manual

This is the complete manual shipped with source-highlight. It details all the file formats used by source-highlight and also contains documentation on how to create your own language definitions.

Download

You can download it from GNU's ftp site:
ftp://ftp.gnu.org/gnu/src-highlite/ 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 built by using Cygnus C/C++ compiler, available at http://www.cygwin.com. However, if you don't feel like downloading such compiler or you experience problems with the Boost Regex library (please also keep in mind that if you don't have these libraries installed, and your C/C++ compiler distribution does not provide a prebuilt package, it might take some time, even hours, to build the Boost libraries from sources), you can request such binaries directly to me, by e-mail (find my e-mail at my home page) and I'll be happy to send them to you. An MS-Windows port of Source-highlight is available from http://gnuwin32.sourceforge.net; however, I don't maintain those binaries personally, and they might be out of date.

Anonymous CVS Access

This project's CVS repository can be checked out through anonymous (pserver) CVS with the following instruction:

cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/sources/src-highlite co src-highlite

Further instructions can be found at the address: http://savannah.gnu.org/projects/src-highlite.

Please notice that this way you will get the latest development sources of Source-highlight, which may also be unstable. This solution is the best if you intend to correct/extend this program: you should send me patches against the latest cvs repository sources.

If, on the contrary, you want to get the sources of a given release, through cvs, say, e.g., version X.Y.Z, you must specify the tag rel_X_Y_Z when you run the cvs command or the cvs update command.

NOTICE: This convention holds since release 2.1.

When you compile the sources that you get through the cvs repository, before running the configure and make commands, you should, at least the first time, run the command:

 sh autogen.sh

This will run the autotools commands in the correct order, and also copy possibly missing files. You should have installed recent versions of automake, autoconf and libtool in order for this to succeed. You will also need flex and bison.

Changes in this release

see NEWS file for a summary of new features in this release and
see ChangeLog for the complete list of changes sources

You can also find details about new features of source-highlight on my blog, in this area: http://tronprog.blogspot.com/search/label/source-highlight.

What you need to build source-highlight

Since version 2.0 Source-highlight relies on regular expressions as provided by boost (http://www.boost.org), so you need to install at least the regex library from boost. Most GNU/Linux distributions provide this library already in a compiled form.

Usage and examples

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

Finally, there is texinfo documentation. It is also available as an html file, and it is also available on-line.

Here we only show some examples of generated files.

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

source-highlight.cc.html

generated with the following command

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

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 (in most of them we have used the Hello.java to make some test). Here's how Hello1.html, Hello2.html, Hello3.html, Hello4.html, Hello5.html, Hello_h_f.html, Hello_lines.html, Hello_xhtml.html, Hello_xhtml2.html, Hello_notfixed.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 --style-file="default.style" --header="header.html" --footer="footer.html"
source-highlight -s java -f html --line-number --doc -i Hello.java -o Hello_lines.html
source-highlight -s java -f xhtml --doc -i Hello.java -o Hello_xhtml.html --css xhtml.css
source-highlight -s java -f xhtml --doc -i Hello.java -o Hello_xhtml2.html --style-file default.style
source-highlight -s java --outlang-def=html_notfixed.outlang -i Hello.java -o Hello_notfixed.html --style-file default.style

Here's another example:

Hello_h_f.html

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

source-highlight -s java -f html -i Hello.java -o Hello_h_f.html 
            --css="cpp2html.css"
            --header="./header.html" --footer="./footer.html"

Source-highlight can also generate HTML code to be embedded (i.e., copied and pasted) inside a Javadoc comment (or another kind of comment framework such as Doxygen). This way, when you run javadoc on such a file, the resulting generated html documentation files will have the code snippets highlighted. For instance, consider this piece of code, UsageExample.java, representing an example of usage of the class SimpleClass; we would like to embed this code (formatted) into a javadoc comment of SimpleClass, so we process it with the option -f javadoc and we copy the result into the comment, as illustrated in SimpleClass.java. When we process this file with javadoc, we obtain that code formatted in the documentation html file: SimpleClass-doc.html. Doesn't it look nice :-)

You can also specify several line ranges, so that you produce an output only with those specific lines of your input file; you can specify a number of lines for the sorrounding context, and the separator of ranges; for instance, this output was produced with the following command (note how the context is shown in gray, as specified in the style file):

ssource-highlight -s java -f html 
            --line-range="12-18","29-34" --line-number --range-context=3 --range-separator="<...>" 
            -i test.java -o test_linerange_sep.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. Here's an highlighted PHP3 program: test.php3.html. And here's a Python program: test.py.html. This the flex scanner for flex files flex_scanner.ll.html. This is a Ruby program: test.rb.html. This is a Javascript program test.js.html. This is a Lua test program test.lua.html. This is a Caml test program test.ml.html and this is an Sml test program test.sml.html.

Here are some log files formatted using the color file syslog.style:

This is the language definition file for C/C++: cpp.lang.html, the one for the log files above, log.lang.html, and the language definition file for the language definition syntax itself: langdef.lang.html.

Here's the html output of test.java.html formatted in html itself: test.htm.html.

and here's the output of test.java.tex formatted in html: test.java.tex.html

These HTML outputs contain cross references, test_refs.h.html, test_refs.cpp.html, generated with the following command:

source-highlight -s cpp -f html --title="Contains references to tags" 
 --gen-references=inline test_refs.h test_refs.cpp

Style files

Since version 2.6, source-highlight can use CSS style files (limited support) as style files for coloring and formatting the output. Here you can find the output using all these files shipped with source-highlight (these were adapted from those provided by SHJS):

Style examples (huge file).

Credits

See CREDITS for detailed contributions and THANKS for a complete list of people that helped me with Source-highlight :-)

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

Please send all bug reports by electronic mail to:
bug-source-highlight at gnu dot 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 at gnu dot 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 at gnu dot 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://www.lorenzobettini.it

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.

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

Updated:9 Jan 2001 mhw