
  GNU Source-highlight 1.9

by Lorenzo Bettini <http://www.lorenzobettini.it>

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

At the moment this package can handle

    * /Java/
    * /Javascript/
    * /C/C++/
    * /Prolog/
    * /Perl/
    * /Php3/
    * /Python/
    * /Flex/
    * /ChangeLog/
    * /Ruby/
    * /Lua /*new*
    * /Caml /*new*

as source languages, and

    * /HTML/
    * /XHTML/
    * /ANSI color escape sequences/ (you can use this feature with less
      <#with_less>) / /*new***

as output formats.

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 <http://www.gnu.org> 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/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 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 <mailto: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 <#Patching%20from%20a%20previous%20version> for
patching from a previous version).


      Anonymous CVS Access

This project's CVS repository can be checked out through anonymous
(pserver) CVS with the following instruction set. When prompted for a
password for anoncvs, simply press the Enter key.

cvs -d:pserver:anoncvs@subversions.gnu.org:/cvsroot/src-highlite login

cvs -z3 -d:pserver:anoncvs@subversions.gnu.org:/cvsroot/src-highlite co src-highlite

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


    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


    Related Software and Links

Martin Gebert <Murphy.Gebert@gmx.de <mailto: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 <mailto: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
<http://www.inf.tu-dresden.de/%7Erw8/java2.html>. If you want to use
source-highlight as a CGI program, you have to use the executable
*source-highlight-cgi*.

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


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


      Building .rpm

Christian W. Zuckschwerdt added support for building an .rpm and an
.rpm.src.  You can issue the following command

rpm -tb source-highlight-1.9rc.tar.gz

for building an .rpm with binaries and

rpm -ts source-highlight-1.9rc.tar.gz

for building an .rpm.src with sources.


      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, apart from the /-i/ (/--input/) option and the standard
input redirection, you can simply specify some files at the command line
and also use regular expressions (for instance /*.java/).  In this case
the name for the output files will be formed using the name 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).

If STDOUT string is passed as /-o/ (/--output/) option, then the output
is forced to the standard output anyway.

*Required command line option* is:

   1. /--out-format/ (or /-f/) <format>: where <format> can only be:
          * /html/
          * /xhtml/
          * /esc
            /
      This specifies the format for the output of the highlighter (for
      the moment only html output can be produced). 

*Other command line options*:
/
/--src-lang (or /-s/) <lang>: where <lang> can be:

    * /java/ (for Java)
    * javascript (for Javascript)
    * /cpp/ (for C/C++)
    * /prolog/ (for Prolog)
    * /perl/ (for Perl)
    * /php3/ (for Php3)
    * /python/ (for Python)
    * /flex/ (for flex)
    * /changelog/ (for ChangeLog)
    * /ruby/ (for Ruby)
    * lua (for Lua)
    * caml (for Caml)

This specifies the language used to write the sources that have to be
processed.  If you do not specify this option, source-highlight will
guess the source language from the file extension.

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). You can also generate an html with CSS format, by using
*--css "url of .css"* (try some .css files included in the package). If
you want to cancel the --doc option when it is implied (e.g. with
--title and --css) you can do that with *--no-doc*. 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, Hello_xhtml.html, Hello_xhtml2.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
source-highlight -s java -f xhtml --doc -i Hello.java -o Hello_xhtml.html --css xhtml.css
../src/source-highlight -s java -f xhtml --doc -i Hello.java -o Hello_xhtml2.html --tags-file tags.j2h

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

You can pass the output of source-highlight, when using esc as output
format (that generates ANSI color escape sequences), directly to less,
this way:

source-highlight -f esc -i Hello.java -s java | less -R

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

GNU source-highlight 1.9rc
 
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
  -i, --input=STRING       input file. default std input
  -o, --output=STRING      output file. default std output
  -s, --src-lang=STRING    source language (e.g. java, javascript, cpp, 
                             prolog, perl, php3, python, ruby, flex, 
                             changelog,lua,caml).   If not specified, the source 
                             language will be guessed from the file extension.
  -f, --out-format=STRING  output format (e.g. html, xhtml, esc)
  -v, --verbose            verbose mode on
  -d, --doc                create html with title and header
      --no-doc             cancel the --doc option even if it is implied
                             (e.g., when css is given)
  -c, --css=STRING         use a css for formatting. Implies --doc
  -T, --title=STRING       give a title to the html. Implies --doc
  -t, --tab=INT            specify tab length. default 8
  -H, --header=STRING      file to insert as header
  -F, --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
      --gen-version        put gengetopt version in the generated file
                             (default=on)
 
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.


    Use source-highlight with less

This was suggested by Konstantine Serebriany.
The script src-hilite-lesspipe.sh will be installed together with
source-highlight.
You can use the following environment variables:

export LESSOPEN="| /path/to/src-hilite-lesspipe.sh %s"
export LESS=' -R '

This way, when you use less to browse a file, if it is a source file
handled by source-highlight, it will be automatically highlighted.


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

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


  TODO

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


  Mailing Lists

The following mailing lists are available:

    * help-source-highlight@gnu.org
      <mailto: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
      <mailto: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://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 </home.html>.

Please send FSF & GNU inquiries & questions to /gnu@gnu.org
<mailto:gnu@gnu.org>/. There are also other ways to contact
<http://www.gnu.org/home.html#ContactInfo> the FSF.

Please send comments on these web pages to /webmasters@gnu.org
<mailto:webmasters@gnu.org>/, send other questions to /gnu@gnu.org
<mailto: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

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






