Web C Plus Plus © Copyright 2001 Jeffrey Bakker | ||
|
By jeffrey bakker <jefskey at yahoo dot com> Created August 3rd, 2001 Last modified November 18th, 2001 Document version 1.8.0
<TABLE OF CONTENTS/> |
1. Introduction updated! 2. Prerequisites 3. General Usage 4. Example 1 - Windows 5. Example 2 - UNIX/Linux 6. Filetype Support updated! 7. Options Table updated! 8. Hyperlinking and HTML tags updated! 9. I/O Redirection hot! 10. Creating Colour Schemes updated! 11. Hexidecimal Colours 12. Webcpp Secrets |
1. INTRODUCTION |
A simple description will tell you that webcpp is a command-line utility that converts source code to syntax highlighted HTML, and supports multiple languages and also colour schemes.
Even if you thought that was enough, there is a whole lot more to webcpp than just that.
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: If you're still not convinced about using a powerful command-line program, don't leave just yet! I've made easy-to-use graphical programs which provide an interface and pass commands to webcpp. The is one made in Gnome for UNIX, and one made for Windows 9x/Me. Take a look at them here. These programs are capable of sending options and even custom options to webcpp, but they lack in some areas (namely I/O redirection). |
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...] are optional (see options table). That is all!! Very simple if you are familiar to using the command line. Below are some examples. For more info on options, see section 7. |
4. EXAMPLE 1 - Windows: |
For Windows, there will be a shortcut in Start Menu -> Programs -> webcpp called "Webcpp Console". Launch this to start the webcpp command line.
Let us assume that you are in windows, and you have a webcpp console 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.htmlNote: 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.scsIt's that easy! For more info on colour schemes, see section 10. |
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, .shtml, .sgml, .xml Perl .pl, .pm, .cgi PHP .php, .php3, .php4, .inc Python .py, .pyw Shell .shif 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" or ".css" 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=<file.scs> use a native colour scheme file. -C=<file.css> use a CSS colour scheme file. -w=<file.css> equivalent to -l -h -c=<file.css> . =========================================================== |
8. WEBCPP, HYPERLINKING YOUR CODE & HTML TAGS | ||
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. Starting with webcpp 0.5.2, the LinkMe: and NameMe: labels are self cleaning; they erase themselves after processing anchor tags and will not show up in your HTML file. Also starting with webcpp 0.5.2, you can now also insert other HTML tags into you code using the TagME: label. By default, webcpp will strip the meaning of any HTML tags in your code, so it doesn't interfere with its HTML processing. With the TagMe: label, you can insert any kind of HTML tag into your code to be processed by the browser. With this, you can do some crazy things to your code: #include <stdio.h> /* TagMe:<hr size=5 noshade> */ int main() { printf("Webcpp is cool."); return 0; } /* TagMe:<hr size=5 noshade> */ would show up as: #include <stdio.h> /*
|
9. 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 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 Or generate an HTML file of the contents in your home directory: $ ls $home | webcpp - myfiles.html |
10. 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 in the next section...
Webcpp uses its own native file format (*.scs) to store colour scheme information. And starting with webcpp 0.6x, there is now support for Cascading Style Sheets (CSS) to store colour schemes. Both of these formats will pretty much look the same once webcpp generates the HTML file. Each of the formats have their benefits over the other. SCS files are very small (56 bytes) and very easy to create. Webcpp will hard-code SCS colours into the HTML file, making it independent of the scheme file. CSS colour schemes for webcpp are quite the opposite. The HTML files are generated in such a way with tags that refer to the external colour scheme file, which will be needed in the same directory as the HTML file in order to resolve the colours. The benefit of CSS is that you can change colour schemes for the same HTML file, without having to re-run Webcpp. The HTML files generated by Webcpp with either SCS or CSS are roughly about the same size. The choice of which format to use is simply just over personal preferences. An SCS (Syntax Colour Scheme) file contains 7 hex colour codes in the following order: The Anatomy of an SCS file. #ffffff #00b800 #000000 #0000ff #a900a9 #ff0000 #666666 The Anatomy of a Webcpp 0.6 compatible CSS file. body { background-color: #dfdfdf } a:link {color:green} a:visited {color:yellow} a:active {color:blue} a:hover {color:black} pre { font-size:100%; color: #ff0000 } font { font-size:100% } font.preproc /* preprocessor */ { font-size:100%; color: #aaff33 } font.text /* text */ { font-size:100%; color: #00ff00 } font.keys /* keyword */ { font-size:100%; font-weight: bold; color: #0000ff } font.number /* number */ { font-size:100%; color: #ffff00 } font.string /* string */ { font-size:100%; color: #cd00ff } font.comment /* comment */ { font-size:100%; font-style: italic; color: #00ff00 }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 templates until you get the hang of it, unless... 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. The newest version at this time (v2.3) is able to export SCS files to webcpp 0.6x compatible stylesheets (CSS). 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, To use an SCS colour scheme, just use the -c option with webcpp: webcpp <inputfile.cpp> <outputfile.html> -c=<schemefile.scs>To use a CSS colour scheme, just use the -C option (uppercase 'C'): webcpp <inputfile.cpp> <outputfile.html> -C=<schemefile.css>*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,FHere 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 orangeThere 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. |
| ||
Web design version 3.0, by Jeffrey Bakker |