


                                             WEBCPP 0.5.0 USER'S MANUAL



By jeffrey bakker <jefskey@yahoo.com>
Created August 3rd, 2001
Last modified October 8th, 2001
Document version 1.6


 TABLE OF CONTENTS

  1. Introduction
  2. Prerequisites
  3. General Usage
  4. Example 1 - Windows
  5. Example 2 - UNIX/Linux
  6. Filetype Support
  7. Options Table
  8. Hyperlinking new! in v0.5
  9. I/O Redirection new! in v0.4
 10. Creating Colour Schemes
 11. Hexidecimal Colours
 12. Webcpp Secrets
 

=================
 1. INTRODUCTION
=================

Whether you're using webcpp for Windows or for Linux, it will be used the same way - through the terminal, or console. For
Windows, there will be a shortcut in Start Menu -> Programs -> webcpp called "Webcpp Console". Launch this to start the
webcpp command line. 

Don't be scared away by the command line, there are many features that webcpp has to offer: 

  Syntax highlighting 
  Colour schemes loaded from a file, or made on the fly 
  Multiple language support for C/C++, Java, Markup, Perl, Python, and Shell 
  Automatic filetype detection for higlighting 
  The ability to force the filetype for highlighting 
  The ability to pipe the input or output 
  The ability to copy files 
  The ability to backup existing html files 
  The ability of hyperlinking to lines of code and external files 
  Generic support for unknown text based files 

==================
 2. PREREQUISITES
==================

I reccommend that you at least know how to use the basic DOS commands. This way, you'll find that using webcpp is very
easy. It is also a good idea to have the latest stable version of webcpp installed. 

==================
 3. GENERAL USAGE
==================

To use webcpp, type the following format to the command line (without any brackets): 

 webcpp <inputfile.cpp> <outputfile.html> [options]

where <inputfile.cpp> is the name of your source file to read, and <outputfile.html> is the name of the HTML file to create, and
[options] is optional (see options table). That is all!! Very simple if you are familiar to using the command line. Below are some
examples. 

=========================
 4. Example 1 - Windows:
=========================

Let us assume that you are in windows, and you have a DOS command prompt open. Your source code file named "main.cpp"
is in C:\sources, and you want to genreate an html file called "main.html" in D:\website. let's type the following... 

 webcpp C:\sources\main.cpp D:\website\main.html

Note: You must include the pathname to the file, otherwise it will use the current directory. 

============================
 5. Example 2 - UNIX/Linux:
============================

Let's say you are already in the directory which contains the source file "source.c" and you want to make an html file
"colour.html" just in the same directory, AND...you want to use a colour scheme file you previously created called
"myscheme.scs" in your home directory. All you need to do is type the following into the command line: 

 webcpp source.c colour.html -c=/home/yourname/myscheme.scs

It's that easy! For more info on colour schemes, see section 9. 

=====================
 6. FILETYPE SUPPORT
=====================

Remember, despite its name, webcpp can also Java, Markup, Perl, Python, and UNIX shell files as well. 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. If you must know EXACTLY which types are supported, they are listed here: 

"C"      .c
C++      .cc, .c++, .coo, .cpp, .cxx
Headers  .h, .hh, .hpp, .hxx
Java     .java
Markup   .htm, .html, .php, .php3, .php4, .sgml, .xml
Perl     .pl, .pm, .cgi
Python   .py
Shell    .sh

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. 

As for the colour schemes, you MUST use a filename with a ".scs" extension. 

==================
 7. OPTIONS TABLE
==================

 ===========================================================
  Name  Long Name      Description
 ===========================================================

  -d    --dupe         duplicate the file.
  -b    --backup       backup the existing html file.
  -h    --hyperlink    Create hyperlinks to #include files.
  -s    --set-colours  lets you manually enter hex colours.
  -l    --line-numbers shows the line numbers in the code.
  -     --pipe         replaces filename to redirect I/O.

  -t=<extension>       force the filetype for highlighting.
  -p=<imagefile>       use a picture as the background.
  -c=<filename>        use the specified colour scheme file.
 ===========================================================



===========================
 8. HYPERLINKING YOUR CODE
===========================

Now you can document and link your online source code, without having to type a single line of html code. Webcpp v0.5.0
introduces the ability of hyperlinking your beautifully coloured source code. There are two ways to make hyperlinks in
webcpp: by using the -h or --hyperlink switch, or by using labels in your souce code. 

Using the -h or --hyperlink 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. Here's a trick: if you use a small shell script to generate html of whole directories of code with webcpp and the
--hyperlink switch, all the #include files will be hyperlinked together. :) 

The other way is also quite simple. 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 {  // LinkMe:#Person
 ...
};


Wow! Doesn't that look easy? The line of code which contains the declaration of the Student class will be linked to the line
which declares the Person class. And it won't mess up the way your code compiles, as long as you place the NameMe: and
LinkMe: labels inside of a comment. All you have to do is put the labels in your source code, and webcpp will generate the
anchor names and hyperlinks. 


====================
 9. I/O Redirection
====================

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

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 "-t=<extension>" switch. 

The following command will generate an html file from all the source and include files in the directory: 

 $ cat *.h *.cpp | webcpp - everything.html -t=cpp


=============================
 10. CREATING COLOUR SCHEMES
=============================

I have recently made a program called mkscs, which generates webcpp colour schemes by asking the user to choose from a
list of colours. It is menu driven, and makes it easy to generate colour scheme files. 

Of course, I could not possibly include every colour in mkscs, that is why starting v2.2 the colours will be loaded from a file
(which can be modified). Mkscs (v2.0+) also allows you to modify a colour once you pick it. You can play around with the
R/G/B values by using the +/- keys and preview what the scheme looks like with a HTML file of a C++ "Hello world". Using
mkscs this way may help you understand how hex-colours work. If you don't quite understand hex colours, I will also make an
attempt to explain in section 9... 

If you know how hexidecimal works, then creating colour schemes for webcpp is simple. A .scs (Syntax Colour Scheme) file
contains 7 hex colour codes for the background, preproceessor, text, keys, numbers, strings, and comments (they appear in
this order). 

To use the colour scheme, just use the -c option with webcpp: 

 webcpp <inputfile.cpp> <outputfile.html> -c=<schemefile.scs>

 *Note: if the path to the scheme file is not given, webcpp will look in the default directory.


=========================
 11. HEXIDECIMAL COLOURS
=========================

Just think of it 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. But the thing 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. Hex, on the other
hand, goes up to 16 (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

Here 16 is F. Can you guess what 17 would be? it would be 10, and 18 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. 

====================
 12. WEBCPP SECRETS
====================

Here are a few features of webcpp which are not so obvious: 

In webcpp for Windows, the "--dupe" option will only copy text-based files and not binary files BUT...it also converts UNIX text
to DOS text so it can be readable in Windows!! The UNIX webcpp CAN copy binary files, such as RPM or MP3. 

If the input file has HTML tags in it, webcpp will convert them so they are readable in the browser window. This also means that
you can display HTML source with an HTML file, or make HTML programming tutorials in HTML. 

