Cpp2html - GNU Project - Free Software Foundation (FSF)

# GNU cpp2html 1.2

by Lorenzo Bettini

This is a simple program that, given a source C/C++ file, produces an html source with syntax highlighting.

cpp2html is free software. Please see the file COPYING for details. For documentation, please read this file. As it is a GPL program, I provide sources (~70k), but if you don't fell like compiling it, you can download Win32 executable (~100k) (new).

Cpp2html is a GNU program, so you can download it also fro GNU's ftp site:
ftp://ftp.gnu.org/gnu/cpp2html/

or from here:

- Latest Version (sources, .tar.gz) - md5sum - signature of md5sum
- Latest Version (win32 executable, zipped) - md5sum - signature of md5sum
- Cygnus DLL for win32 (needed for win32 executable, zipped)

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

Cpp2html main home page is at GNU site:
http://www.gnu.org/software/cpp2html/cpp2html.html

you can also get the pacthes (see below for patching from a previous version).

## Changes in this release

- Fixed bug in number scanning (reported by Curtis Weyant <dylan38@angelfire.com>)
- Fixed bug in #include scanning (reported by Martin Gebert <Murphy.Gebert@gmx.de>)
- Added TODO list (thanks Xavier Outhier <xavier.outhier@anfdata.cz>)

## Changes in release 1.1

- `--header` and `--footer` options added by Xavier Outhier <xouthier@yahoo.fr>, that allow to specify files to be included at the beginning and at the end of the generated document.
- GNU gengetopt is used for command line parsing.
- hexadecimal and floating point numbers are treated (Tom Hull <thull@kscable.com>).
- fixed the bug of /* comment in another environment (notified by Michael Gasche <mgasche@datacomm.ch>)

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

Files will be installed in the following directories:

- `Executables -> /prefix/bin`
- `docs and samples -> /prefix/share/doc/cpp2html`
- `conf files -> /prefix/share/cpp2html`

Default value for prefix is `/usr/local` but you may change it with --prefix option to configure (see above).

### What you need to build cpp2html

Actually you need nothing more than a Unix C/C++ compiler

cpp2html 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. Here's a document for compiling cpp2html with Visual C++ 6.0, by Nazar Gabriel <nazargabriel@hotmail.com>.

Actually, unless you want to develop cpp2html, you don't need all these tools to build cpp2html 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 cpp2html and you use lex.

### Patching from a previous version

If you downloaded a pacth, say `cpp2html-1.3-1.3.1-patch.gz` (i.e. the pacth to go from version 1.3 to version 1.3.1), cd to the directory with sources from the previous version (`cpp2html-1.3`) and type:

    gunzip -cd ../cpp2html-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

cpp2html only does a lexical analisys of the source code, so the C++ program is assumed to be correct !

here's how to run it:

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

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.

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

- main.cc.html
- generators.cc.html
- tags.cc.html
- messages.cc.html

These files have been generated with the following commands:

    cpp2html --doc main.cc
    cpp2html --doc generators.cc
    cpp2html --doc tags.cc
    cpp2html --doc messages.cc

Obviosly it works with C files as well:

- cmdline.c.html

Created with the command:

    cpp2html -i cmdline.c -o cmdline.c.html --css="cpp2html.css"
                --header="./header.html" --footer="./footer.html"

And obviously it works with header files as well (which we colored in black and white :-)

- main.h.html
- decorators.h.html
- generators.h.html
- list.h.html
- tags.h.html
- cmdline.h.html

created with the command:

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

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

    Usage: cpp2html [OPTION]... [INPUT-FILE]...
           cpp2html < INPUT-FILE > OUTPUT-FILE [OPTION]...

    given a source C/C++ file, produces an html source with syntax highlighting.

      -v, --verbose           verbose mode on
      -d, --doc               creates html with title, header...
      -c, --css=URL           use a css for formatting (implies --doc)
      -T, --title=TITLE       give title to the html (implies --doc)
      -i, --input=FILE        input file (default standard input)
      -o, --output=FILE       output file (default standard output)
      -t, --tab=TABLEN        specify tab length (default 8)
      -V, --version           print version

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 ;
    type green ;
    string red ;
    comment brown i ;
    number purple ;

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

if something goes wrong with your options try to run cpp2html with `--verbose` option enabled.

## Credits

These people helped me with java2html, and I used such features in cpp2html as well, so:

- 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

See also THANKS :-)

## Feedback

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

Please send all bug reports by electronic mail to:
bug-cpp2html@gnu.org

See also java2html http://www.gnu.org/software/java2html/java2html.html.

# TODO

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

# Mailing Lists

The following mailing lists are available:

- help-cpp2html@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-cpp2html
- info-cpp2html@gnu.org, for receiving information about new releases and features (read-only mailing list), http://mail.gnu.org/mailman/listinfo/info-cpp2html

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)

cpp2html 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@www.gnu.org, send other questions to gnu@gnu.org.

Copyright (C) 1999 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: 27 Mar 1999 jonas