# GNU Source-highlight 3.1.2

by Lorenzo Bettini

This program, given a source file, produces a document with syntax highlighting. It also provides a C++ highlight library (new) (since version 3.0).

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

- Ada
- Asm (new)
- Applescript (new)
- Awk (new)
- Autoconf files
- Bat (new)
- Bib
- Bison
- C/C++
- C#
- Clipper (new)
- Cobol (new)
- Configuration files (generic)
- Caml
- Changelog
- Css
- D (new)
- Diff
- Erlang (new)
- errors (compiler output) (new)
- Flex
- Fortran
- GLSL
- Haskell
- Haxe
- Html
- ini files
- Java
- Javascript
- KDE desktop files
- Latex
- Ldap files
- Logtalk
- Log files
- lsm files (Linux Software Map)
- Lua
- Makefile
- Manifest (new)
- M4
- ML
- Oz
- Pascal
- Perl
- pkg-config files
- PHP
- Postscript
- Prolog
- Properties files
- Python
- RPM Spec files
- Ruby
- Scala
- Shell
- S-Lang
- Sql
- Tcl
- Texinfo
- VBscript (new)
- XML
- XOrg conf files

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

1. GNU Source-highlight
   1. On-line Manual
   2. Download
      1. Anonymous Git Checkout
      2. Installation
   3. Changes in this release
   4. What you need to build source-highlight
   5. Usage and examples
   6. Style files
   7. Related Software and Links
   8. Credits
   9. Feedback
   10. TODO
   11. Mailing Lists

## 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.

If you want to use source-highlight library inside your C++ programs, you may want to read the manual of the library and the API documentation.

## 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.

Language definition files and output language definition files, which are part of source-highlight distribution, can also be downloaded independently from, respectively:

- http://www.gnu.org/software/src-highlite/lang_files/
- http://www.gnu.org/software/src-highlite/outlang_files/

However, note that the files you find at the above urls are tested with the latest version of source-highlight (thus, e.g., they may require features that are not present in an earlier version of source-highlight);

### Anonymous Git Checkout

This project's git repository can be checked out through the following clone instruction:

    git clone git://git.savannah.gnu.org/src-highlite.git

Further instructions can be found at the address:

http://savannah.gnu.org/projects/src-highlite.

And the git repository can also browsed on-line at http://git.savannah.gnu.org/cgit/src-highlite.git.

NOTE: Since version 3.1.2 of Source-highlight the CVS repository was dismissed in favor of Git (http://git-scm.com/).

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 git repository sources.

If, on the contrary, you want to get the sources of a given release, through git, say, e.g., version X.Y.Z, you must specify the git tag `rel_X_Y_Z`.

When you compile the sources that you get from the git repository, before running the `configure` and `make` commands, you must run the command:

    autoreconf -i

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.

### Installation

Please, take a look at the Installation section of the manual. Since version 3.1.2, also a qmake based building mechanism is available, though discouraged.

## 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

## Related Software and Links

Here we list some software related to source-highlight in the sense that it uses it as a backend (i.e., provides an interface to source-highlight) or it uses some of its features (e.g., definition files):

- Source-highlight-qt is a library for performing syntax highlighting in Qt documents by relying on GNU Source-Highlight library. This library provides an implementation of the qt abstract class QSyntaxHighlighter class, and it deals both with Qt3 and Qt4.

  http://srchiliteqt.sourceforge.net.

- QSource-Highlight is a Qt4 front-end for GNU Source-Highlight (it relies on the library Source-Highlight-Qt). You can highlight your code on the fly, and have the highlighted output in all the formats supported by source-highlight (e.g., HTML, LaTeX, Texinfo, etc.). You can then copy the formatted output and paste it (e.g., in your blog), or save it to a file. A preview of the highlighted output is available for some output formats (e.g., HTML, XHTML, etc.).

  http://qsrchilite.sourceforge.net.

- SourceHighlightIDE is a small IDE (for KDE) I wrote for developing and debugging new language definitions for source-highlight:

  http://srchighliteide.sourceforge.net.

- Martin Gebert implemented a KDE interface to source-highlight programs (and he did a wonderful job!), and it is called Ksrc2highlight; if you want to test it:

  http://www.mgebert.de/Ksrc2highlight.

- There's also a Java version of java2html, you can find it at

  http://www.generationjava.com/projects/Java2Html.shtml.

- This web site provides a web interface to source-highlight so that you can highlight your code on-line:

  http://www.alaide.com/outils_colorsyntaxe.php

- SHJS is a JavaScript program that highlights source code passages in HTML documents. Documents using SHJS are highlighted on the client side by the web browser. SHJS uses language definitions from Source-highlight.

  http://shjs.sourceforge.net

- Code2blog is a pyGTK front-end to source-highlight for easy conversion from source code to HTML.

  http://code.google.com/p/code2blog

- Andy Buckley wrote a wrapper around source-highlight, which can be used as an Apache filter to highlight source code in Web pages on the fly.

  http://www.insectnation.org/projects/filter-src-highlight

- Roger Nilsson wrote a frontend for source-highlight that is used in a popular webdesign app for OSX called RapidWeaver. The frontend is called High-Light and allows users to easily add syntax-colored code inside RapidWeaver.

  http://nilrogsplace.se/webdesign/rapidweaver/plugins/high-light/index_en.html

- Mauricio Zepeda published in his blog an article with a script to automatically highlight a file and show it in Firefox:

  http://chillorb.com/?p=122

- Jason Blevins made a plugin for Ikiwiki that enables syntax highlighting of source code fragments and whole files via source-highlight.

  http://jblevins.org/projects/ikiwiki/code

- Pascal Bleser created a PHP extension that uses the GNU source-highlight library directly from PHP, instead of relying on spawning a process or using the source-highlight CGI.

  http://code.google.com/p/php-source-highlight/

## 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.

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