Web C Plus Plus 0.8.2 Manual
By jeffrey bakker <jefskey at yahoo dot com>

Document version 2.1.0
Document created 8.3.2001
Document last modified 8.5.2003



<TABLE OF CONTENTS/>
  1. Introduction
  2. Prerequisites
  3. General Usage
  4. Filetype Support
  5. Inline Languages
  6. Hyperlinking and HTML tags
  7. I/O Redirection
  8. Creating Colour Schemes
  9. Hexidecimal Colours


INTRODUCTION
A simple description from any free software download site will tell you that webcpp converts source code to syntax highlighted HTML, and supports multiple languages and also colour schemes. And maybe that's all you're looking for, but there is a whole lot more to webcpp than just that. It's likely that webcpp even has features or functionality that you wouldn't have expected...
  • Specific support for over 30 programming, scripting, and shading languages
  • An 11-element syntax highlighting engine
  • Dynamic colour schemes using embedded Stylesheets, or external Stylesheets
  • Batch conversions
  • Automatic filetype detection for higlighting
  • Filetype forcing for syntax highlighting
  • Automatic #include file hyperlinking and file generation
  • Piping the input or output to or from STDIN/STDOUT to collaborate with other programs
  • The ability of allowing custom HTML tags to be added
  • Generic support for unknown text based files
  • Available on various operating systems
Command line
Whether you're using webcpp for Windows or on some type of Unix, the webcpp engine will be used the same way: through the command-line. In either Windows or Unix, the format of the commands will be the same. For Windows, there will be a shortcut to it at the Start Menu -> Programs -> Webcpp -> Webcpp Command Console. Launch this to start the webcpp command line, then you'll be ready to start typing in webcpp commands.

User interfaces
If you're still not convinced about using a powerful command-line program, don't close this window and never come back just yet! There are programs which provide a graphical interface and pass the commands to webcpp. There is one made in Gnome for UNIX (Webcpp GnoGUI), and one made for Windows (called Webcpp WinGUI). These programs are capable of sending options and even custom options to webcpp, but they lack in some areas such as I/O redirection, which is a powerful feature because it lets you streamline the output to another program and vice versa. There is also a standalone Webcpp that has the engine built in (called Webcpp for Win32), you can take a look at the screenshots in the manual for the windows one here.

Windows users
Webcpp already includes the WinGUI program (mentioned above), and another program, WinMkScs2, for visually creating and editing colour shemes. How to use these programs are out of the scope of this document, there is separate documentation for each. However, the information in this document will provide you with a better understanding of what's going on behind the scenes in these graphical tools.
PREREQUISITES
Hardware
Even a 386 or 486 computer with a keyboard and monitor will do just fine, no mouse needed. And it's okay if you have something alot better, don't go tyring to replace your computer if you "only" have an Athlon or Pentium 4. Hard drive space is not a big concern, as the Unix version is under 400KB (including schemes and documentation), and the Windows version is just over 1MB (including source code, schemes, and docementaion).

Software
Operating systems that are supported are Windows, Linux, and quite possibly many other variants of Unix. Webcpp comes in pre-compiled binary form for FreeBSD, Linux, and Windows on the i386 platform. If you have an operating system which is neither of these, you can download the source and compile it, which is actually recommended over binary distribution. It should compile on most *NIX systems, given that you have the proper compiler tools (gcc3 or later). There is even a site that has a binary of Webcpp for AIX.

As for additional software (other than operating system or compiler), you should have a web browser. Technically, you don't need a browser to use webcpp, but if you want to look at the output you will definitely want a web broswer. The browser must support Cascading Stylesheets (and every modern browser does), as webcpp uses stylesheets to store the syntax highlighting information. It is also a good idea to have the latest stable version of webcpp installed on your operating system. The latest stable version can always be found at http://webcpp.sourceforge.net/download.php.

Experience
I strongly suggest that you at least know how to use the basics of DOS or UNIX (if so, then you can skip this paragraph). Familiarity with any type of command prompt is helpful. This way, you'll find that using webcpp is very easy. Of course, since most of the target audience are software engineers and web developers, I'm sure that using the command line pales in comparison to the complexity of your work. Yet, there may be those of you that have never used computers during the DOS or UNIX days, and have only used Windows exclusively.
GENERAL USAGE
To use webcpp, type the following format to the command line (without any brackets):
 webcpp <infile> <outfile> [options...]
where <infile> is the name of your source file to read, and <outfile> is the name of the HTML file to create, and [options...] are optional (see options table).

Options can be parameters to pass to webcpp (such as scheme files or filetype forcing), but options can also be switches to turn features on or off. There are also options that are special switches to use in place of filenames that make webcpp do some very neat tricks, and make it a handy, "must-have" tool. These options can be viewed any time by typing the `webcpp` command without any arguments.

Options Table
  -c=<scheme>        Use a webcpp colour scheme.
  -w=<scheme>        The works, same as -m -l -a -h -c=<scheme>.
  -i=<filename>      Use an image for the background.
  -t=<width>         Convert tabs to spaces using the specified width.
  -x=<extension>     Force the filetype for syntax highlighting.

  -X,--external-css  Generate an external stylesheet.
  -s,--snippet-only  Don't generate HTML or BODY tags.
  -w,--the-works     The works (sans scheme) -m -l -h -a.
  -l,--line-numbers  Print the line numbers in the left margin.
  -a,--anchor-lines  Create anchors to line numbers.
  -h,--hyperinclude  Create hyperlinks to #include files (C/C++).
  -H,--superinclude  Hyperinclude that recursively generates files.
  -t,--tabs-spaces   Convert tabs to spaces (use for Opera).
  -m,--made-with     Show made with webcpp footer.
  -A,--auto          Automatic naming in place of the output file.
  - ,--pipe          Use STDIN or STDOUT in place of the filename.
Note that these switches are toggle switches. If you are using the -w or -w= switch, it toggles on the -m, -l, -h, & -a switches. You can use boolean math here to exclude a switch from the works. Say for example you want to use -m, -l, & -a, but not -h...what you can do is use -w -h, which will equivalent to the works but minus the hyperinclude. This also means that if you have two of the same switch, they'll cancel eachother out.

Generating Code Snippets
If you don't want to make standalone HTML files, but just pieces of HTML code that can be pasted into your own .html files, then use the "-s" or "--snippet-only" option. This will generate code without HTML, HEAD, or BODY tags.

Using colour themes
To use a theme, all is needed is a theme file, and to use one of the many theme options. Webcpp uses SCS (Syntax Colour Sheme) files to indentify colours. Passing the theme name with the -c=shceme or -w=scheme options is all that is required. You don't need to use the ".scs" part, but just make sure it's pointing to the right directory where the scs file is. Note that you can also use the -c=shceme and -w=scheme options with uppercase letters. Using an uppercase 'C' or 'W' will make webcpp generate an external Stylesheet for the colour scheme. The Stylesheet should be placed in the same directory of the output file. Another way of making external Stylesheets is to use the -X switch (just don't do both, or they cancel eachother out). Webcpp already comes with over 50 colour schemes. They are installed in /usr/local/share/webcpp/ on Unix, and C:\Program Files\Jeffrey Bakker\Webcpp\ in Windows by default. Creating your own themes is covered later in this manual.

Special file switches
For the input filename, there can be wildcards, if you need to process many files at once. To use the wildcard, you must put the wildcard phrase in quotes like this: "*.cpp". The -A or --auto can be used for the output filename to let webcpp decide what the file should be named. Webcpp will use the input filename, then append a ".html" to come up with the output filename. So if you did something like this: webcpp "*.h *.cpp" -A, you can process all the C++ source files in the current directory and automatically name the output files. There is also the - or --pipe file switch. This is a whole topic within itself, and will be discussed in I/O redirection.

File flags
A webcpp file flag is simply a colon followed by a character at the end of the output filename. Currently, there is ':f' to force overwrite on an existing file, and ':k' to keep the existing file and abort. An example would be: webcpp main.cpp main.cpp.html:f. If no flag is given, webcpp will do the normal and ask you whether or not you would like to overwrite if the file does happen to exist. If you use an invalid flag, you will get an I/O mode error.
FILETYPE SUPPORT
Remember, despite its name, web c plus plus can also handle many languages other than C++. And you don't have to tell it whether to use Java or C or C++ highlighting, because webcpp will determine the file by it's extension (.java, .cpp, .h, .c). Just don't worry about it, it's all taken care of by autodetection. Here are the supported types in groups (you can always see this list by typing `webcpp --languages`) :

Language Filter
Ada95*.adb,*.ads,*.ali
Assembly*.asm,*.s
Asp*.asp,*.asa
Basic*.bas
C Source*.c,*.rc
C#*.cs
C++ Source*.cc,*.cpp,*.cxx
C/C++ Header*.h,*.hh,*.hpp,*.hxx
Objective-C*.m
Cg (Nvidia)*.cg
CLIPS (Nasa)*.clp
DOS Batch*.bat,*.cmd
Euphoria*.e,*.eu,*.ex
Haskell*.hs,*.lhs
Java*.java
JavaScript*.js
Fortran*.f,*.f77,*.f90,*.for,*.ftn
Markup*.htm,*.html,*.shtml,*.sgml,*.xml
Modula2*.def,*.mod
Pascal*.pas
Perl Script*.cgi,*.pl,*.plx,*.plex,*.pm
PHP Script*.inc,*.php,*.php3,*.php4
Power Builder 6*.pbl, *.pbr
Python Script*.py, *.pyw
Renderman*.rib,*.sl
Ruby*.rb
SQL*.sql
Tcl*.tcl,*.tk
Unix Shell*.sh
Unreal Script*.uc
VHDL*.v,*.vhd,*.vhdl

Forcing filetypes
As described above, webcpp automatically detects the filetype from the extension of the given input file. If the extension of your source file is none of the above, webcpp will still generate an html file, but just not with any syntax highlighting. This means you can create html files from plain text files. You can always force the filetype with the -x=<extension> option if webcpp can't recognize your file or if you'd like to highlight it as another language.
INLINE LANGUAGES
So, how about those languages that are inlined into source code from another language? Yes, Webcpp can do that too...best of all, it does it automatically. The new engine makes it possible for 2 or more languages to access the same I/O object, meaning, it can support inline code for different languages. Currently, Webcpp supports MSVC/Borland style inline Assembly code within C++ files, and JavaScript code in HTML files.

Webcpp will search where the other language starts, and parse it until it ends. The start for a block of Assembly code in C++ is "asm" or "__asm", and the end is designated by a "}". For JavaScript, the start is "text/javascript", like in the phrase '<script type="text/javascript">' and the end is designated by "/script".
HYPERLINKING YOUR CODE AND HTML TAGS
HyperInclude
Using the -h or --hyperinclude switch will automatically generate htyperlinks to html files of your #include statements in C/C++. for example, if you had something like #include "socket.h" in your source code, it will automatically link the phrase "socket.h" to socket.h.html. This is especially a very useful feature if you are generating HTML for whole directories of C/C++ code, because you can have all your files linked together.

Anchoring lines
You can also have webcpp automatically anchor code by using the -a or --anchor-lines switch. This powerful switch will create an anchor for every line in your code, named after the line number. This means you can jump to any line of code in the file by using its line number. For example, the link http://foo.bar.com/code.c.html#line203 will directly jump to line 203 of the code.c HTML file.

Labels for tags
If you are attracted to the two features above, but still need something that specifically fits your needs, you can use custom anchoring and linking. On any line of your source code, you can put a label in which can name the line, or link to another line of code. There are two labels you can use... The NameMe: label will name a line of code, and the LinkMe: label will create a hyperlink. To make sure the labels won't effect the syntax of your code, place the labels in a comment. Here is an example of naming and linking lines of code:
class Person  // NameMe:Person
{
 public:
	Person();
 ...
};

class Student
 : public Person {  // LinkMe:#Person
 public:
	Student();
 ...
};


...
//TagMe:<hr noshade><a href="http://webcpp.sf.net">Get Webcpp!</a><hr noshade>
...
And yet, there is a third type of webcpp label, TagMe:, which simlpy prevents webcpp from stripping any meaning of HTML tags on a single line. By default, webcpp has to strip HTML to be able to parse and highlight source code properly. However, there may come a time when you actually want your own custom HTML tags in your generated document, and this is when you use TagMe:, you can even use it to insert images. The webcpp tags are also self-cleaning, meaning that the label itself will erase itself after processing its task.
I/O REDIRECTION
One of the most powerful things about webcpp is its ability to integrate with other command-line tools for data piping. This will allow you to pipe data in from another program instead of a file, and vice versa (pipe data to other programs).

It is possible to redirect the Input and/or Output of webcpp to the STDIN or STDOUT. This feature can be very useful to interact with other UNIX utilities. The use of the "-" or "--pipe" switch in place of the filename will redirect the input or output.

Standard in
Be careful when you're redirecting input from the STDIN. Remember that webcpp determines the filetype by extension, and uses this determine how to do the syntax highlighting. When you use the STDIN as input, there is no filetype specified. To use syntax highlighting when you're using STDIN as your input, you must pass the filetype using the -x=<extension> option to force the filetype.

The following command will generate a single html file from all the source and include files in the directory:
 $ cat *.h *.cpp | webcpp - everything.html -x=cpp

Or generate an HTML file of the contents in your home directory:
 $ ls $home | webcpp - myfiles.html
Standard out and standard error
And there's also redirecting the output to STDOUT. Just use the redirector switch as the output filename, and webcpp will print all the output to the screen (or whatever your operating environment is using as STDOUT). From here, you can use the operating system to catch the output and decide what to do with it. Take note that webcpp prints messages to the screen like "C++ file detected" and "57% complete @ line 160". Now you may be thinking "Then how will I separate webcpp's messages from the generated output?". All messages from webcpp are printed to STDERR, so the answer is to use your operating system to handle it. For instance if you append >output.html to your command, all STDOUT will be caught and placed into a file called output.html. Similarly, if 2>messages.txt is used, then all webcpp messages to STDERR will be caught and placed in a messages.txt file. This works in both UNIX and DOS. Now, what if you needed the output printed to your screen, but didn't want to see webcpp's messages on the screen neither have them stored in a messages.txt file? In UNIX, you can execute this:
webcpp main.c --pipe 2>/dev/null
This will process main.c and print the HTMLized output to the screen, and send all of webcpp's messages to the "black hole".
CREATING COLOUR SCHEMES
If you know how hexidecimal works, then creating colour schemes for webcpp is simple. If you don't, then don't worry, I will also make an attempt to explain it in the next section.

The format
Webcpp uses its own file format, Scs2 (Syntax Colour Scheme version 2), to store colour scheme information. The file extension for these files is *.Scs2. To make your own Syntax Colour Scheme, you should first learn the basics of the file format. The Scs2 format is now stored as XML data, meaning that the values are stored between tags. Because of it's nature, it is easy to read XML, even to those who have never seen markup language code before. Since XML is a standard, that is also why it has been chosen to base the Scs2 format on. And unlike the original SCS format (from older versions of webcpp), the highlighting data does not need to be in any specific order. Here is what the inside of an Scs2 file is like...

<?xml version="1.0"?>
<!DOCTYPE SyntaxColourScheme2 SYSTEM "WebcppScheme2.dtd">
<SyntaxColourScheme2>
  <bgcolor>f1f1f1</bgcolor>
  <preproc>a900a9</preproc>
  <nortext>000000</nortext>
  <symbols>0077dd</symbols>
  <keyword>224fff</keyword>
  <keytype>ff9933</keytype>
  <integer>ff0032</integer>
  <floatpt>ff23a6</floatpt>
  <dblquot>00b800</dblquot>
  <sinquot>00b86b</sinquot>
  <comment>666666</comment>
  <background>C:\Backgrounds\looseleaf3low.bmp</background>
</SyntaxColourScheme2>
Notice that the first two lines identify the format of the file, this is standard for XML. The third and the last line envelopes the document data itself as a whole. The lines in between the third and last represent the colour scheme elements. Also notice that there is no ambiguity here, each piece of data is identified by its surrounding tags. The values of the colour element data are stored as hexidecmial characters, and can start with a '#' symbol, but it is not necessary to do so. Each of the elements will be explained below (and remember, they don't have to be in any specific order) :

  • bgcolor - the background colour of the html file
  • preproc - the colour of preprocessor statements, backquoted strings, and $,@,% variables (language specific)
  • nortext - the colour of the normal, non-highlighted text
  • symbols - the colour of symbols (eg. =,+,-,!=,++,etc.)
  • keyword - the colour of the language's keywords
  • keytype - the colour of the language's primitive data types, or commands for scripting languages
  • integer - the colour of integer numbers
  • floatpt - the colour of floating point numbers
  • dblquot - the colour of double quoted strings
  • sinquot - the colour of single quoted strings
  • comment - the colour of the comments in te code
  • background - a link to a background picture file (optional)

Stylesheets
Webcpp uses the Scs2 information to generate Cascading Stylesheets on-the-fly when it's creating HTML files. Webcpp stylesheet data is put into a webcpp namespace, so the data will not interfere with other stylesheet information on your webpage. The Stylesheet information can be generated for use in two ways: 1) Embedded Stylesheet, and 2) External Stylesheet. So, which is "better" to use? Well, embedded stylesheets are good, because the HTML file has no dependency on any other external files. However, external can make it easier to change themes, and also is good if you have many HTML files using the same scheme, they can all share the same Stylesheet. As mentioned above, stylesheets are automatically generated by webcpp and placed in the same directory as the output file. However, if you'd like to create your own, there is a format to follow. This is a stylesheet generated by webcpp...

/*
Webcpp v0.8.0 compatible StyleSheet
http://webcpp.sf.net
Theme: C:\bg.Scs2
*/

div.webcpp
{
background-color: #f1f1f1;
background-image: url("C:\Backgrounds\looseleaf3low.bmp");
background-attachment: fixed
}

.webcpp a:link    {color:#00b800}
.webcpp a:visited {color:#666666}
.webcpp a:active  {color:#224fff}
.webcpp a:hover   {color:#a900a9}

.webcpp pre
{
color: #000000
}

.webcpp font
{
font-size:100%
}

.webcpp font.symbols
{
color: #0077dd
}

.webcpp font.preproc
{
color: #a900a9
}

.webcpp font.integer
{
color: #ff0032
}

.webcpp font.floatpt
{
color: #ff23a6
}

.webcpp font.dblquot
{
color: #00b800
}

.webcpp font.sinquot
{
color: #00b86b
}

.webcpp font.keyword
{
color: #224fff;
font-weight: bold
}

.webcpp font.keytype
{
color: #ff9933;
font-weight: bold
}

.webcpp font.comment
{
color: #666666;
font-style: italic
}

The original SCS format
Finally, there's the old SCS format, which webcpp still supports. It has 4 less elements than the Scs2 format, and no support for background images. The SCS data has to be in a specific order, and the colours must begin with the '#' symbol. When using an old SCS file, webcpp translates the data, but doesn't make use of the floating point, types, single quotes, and symbol highlighting. These files have the *.scs extension. For historical purposes, here is The anatomy of an SCS file.
#ffffff
#00b800
#000000
#0000ff
#a900a9
#ff0000
#666666
The order of the SCS files are as follows...from the top to bottom, they are: Background, Preproceessor, Normal text, Keywords, Numbers, Strings, and Comments.

Creating these files is just a matter of knowing what colours you want your code to look like, and a little bit of Hexidecimal knowledge. Feel free to use the above examples as a templates until you get the hang of it. If you use Webcpp on windows, you can use WinMkScs2, which can help you easily create colour schemes the visual way, by using colour pickers or even random colour generation. It can load and save .Scs2 files so they can be modified. WinMkScs2 can also import old .scs files, and export to webcpp 0.8.0 compatible sytlesheets.
HEXIDECIMAL COLOURS
Just think of hexidecimal colours as a colour mixer. You have red, green, and blue. And you can give each colour a certain value, ranging from 0 to 255, where 0 is the darkest, and 255 is the lightest. Just modify the values to get different colours. But the catch is, that we don't use decimals for these values. Hexidecimal is used instead.

Hexidecimal is different from decimal. Decimal goes up to 9, then goes back to 0 and add 1 to the next digit, making it a 10-based number system. Hexidecimal, on the other hand, is 16-based (Hexi-decimal). Let's count to 16 in hex:
 0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F,10
Here 10 is A, 15 is F, and 16 is 10, and 17 would be 11. 64 would be 41. I guess they do this because it would be more efficient for the computer; you can store a number like 200 by just using 2 digits instead of 3.

Back to the colour mixer thing. Each colour has a value. They are represented with 2 hexidecimal digits, ranging from 00 to FF. If you got the hang of hexidecimal, you may have guessed that FF is actually equal to 255. Red is represented first, then Green, then Blue.
 #000000 is black, becuase all red, green and blue values are set to zero.
 #ffffff is white, becuase all red, green and blue values are set to max.

 #ff0000 is bright red because the red value is at it's highest, ff(255).
 #008100 is green, becuase the green value is 81, which is equivalent to 128 in decimal.
 #000040 is about navy or dark blue, because the blue value is rather low.
If you want something like yellow, you'd have to mix red and green, and if you want orange, you'd do the same, but just add less green...
 #ffff00 is a bright yellow
 #ffbb00 would be a bright orange
There are so many possible colours with hexidecimal. The best way to learn how to get the colours you want is to experiment with it yourself.



This document can be found online @ http://webcpp.sourceforge.net/docs.html