.\"   -*- nroff -*-
.TH SOURCE-HIGHLIGHT 1 2002-05-19 "GNU" "Programmer's Manual"   
.SH NAME
source-highlight \- produce a document with syntax highlighting. 
.SH SYNOPSIS
.B source-highlight
.RI [ OPTIONS... "] [" files ]
.SH "DESCRIPTION"
\fBsource-highlight\fP given a source file, produces a document with syntax highlighting. 
.PP
\fBsource-highlight\fP supports the following source languages:
\fBJava\fP, \fBJavascript\fP, \fBC/C++\fP, \fBProlog\fP, \fBPerl\fP, \fBPHP3\fP, \fBPython\fP, \fBRuby\fP, \fBFlex\fP, \fBChangeLog\fP, \fBLua\fP, \fBCaml\fP, \fBSml\fP, \fBLog\fP
and produces a file with syntax highlighting.  The supported
output languages are: \fBHTML\fP, \fBXHTML\fP, \fBANSI color escape sequences\fP
.PP
\fBsource-highlight\fP is a GNU program.  See COPYING.
.PP
\fBTHIS MAN PAGE IS NOT COMPLETE.\fP 
.PP
\fBTexinfo documentation will be released soon, but meanwhile
please refer to README file or to the html documentation that you
can find in @prefix@/share/doc/source-highlight.\fP 
.SH OPTIONS
\fBsource-highlight\fP accepts some options.
.sp
.nf
  -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, sml, log)
  -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
      --line-number-ref    number all output lines and generate an anchor that
                             can be referred to from another document
      --output-dir=STRING  output directory
      --gen-version        put source-highlight version in the generated file
                             (default=on)
.fi
.SH REQUIRED OPTIONS
.TP
.I --src-lang (-s)
java, javascript, cpp, prolog, perl, php3, python, ruby, flex, changelog, lua, caml,sml.
 If you do not specify this option, source-highlight will guess the source language from the file extension.
.TP
.I --out-format (-f)
html, xhtml, esc.
.SH 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). 
.SH FORMAT OPTION FILE
.sp
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: 
.PP
.nf
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. {, })
.fi
.PP
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. 
.PP
when using \fBesc\fP as output format, you can pass the output of source-highlight directly to \fBless\fP, this way:

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

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

.SH "SEE ALSO"
HTML documentation in \fI@prefix@/share/doc/source-highlight\fP.
.SH "VERSION INFORMATION"
This man page (partially) documents \fBsource-highlight\fP, version @VERSION@.
TexInfo documentation will be released soon.
.SH AUTHOR
GNU Source-highlight (originally known as two
separate programs, java2html and cpp2html) is developed
by \fBLorenzo Bettini <bettini@gnu.org>\fP
the current maintainer.
See THANKS and CREDITS file for contributions.
.SH BUG REPORT
Please send all bug reports by electronic mail to:
.br
\fBbug-source-highlight@gnu.org\fP
.SH MAILING LISTS
The following mailing lists are available: 
.br
\fBhelp-source-highlight@gnu.org\fP, 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 
.br
\fBinfo-source-highlight@gnu.org\fP, for receiving information 
about new releases and features
(read-only mailing list), 
http://mail.gnu.org/mailman/listinfo/info-source-highlight 

