src2html Manual

Introduction

With src2html you can convert a Chill- or C-Sourcecode, to HTML-Code. Then it can be displayed with any HTML-Browser.

Available Functions

All function- and procedure calls are converted to hyperlinks to each definition. Chill, and C (incl. C++ Comments) will be supported.
Automatic detection of the programing language
The Code will be colored, different colors for
- Strings
- Digits
- Language keywords (expandable)
- Comments
- user defined keywords
are used.
Most of the HTML-Code can be predefined by the user
Javascript functions can be included
All names of functions and procedures are listed in a separat frame
Browsers which can't handle frames are supported

Restrictions

It must be possible to compile the source code error free
Functions with the same name, but different parameters are not detected as different
Using DOS, the name of the source code shall not longer then 5 chars. The reason is the 8.3 restriction in the DOS naming convention. "ABCDE.C" is ok. The *.htm file can be renamed afterwards.
Using Linux/Unix, hidden files (.xxx.c) or hidden directories are not suported as parameter
Include files are not included automaticly, but can be copied into the source by hand before src2html starts.
The INI-Files must be in the actual directory, where src2html will be started.

Delivered Files

3 INI-Files:

src2html.ini
langkeywords.ini
otherkeywords.ini

and one Javascript file

src2html.js

These files are not required, if you dont't like to change the default values.

Default values are used if the corresponding ini file was not found. Into the delivered files

src2html.ini
langkeywords.ini

are all the actual default values. So you don't need them until you change something. They are as information for you, to see all the default values.

The other files are handled like empty files, if one can not be found. There are no default values.

Starting src2html

src2html [Path]Sourcefile [[Path]Targetfile]

Using Linux/Unix, hidden files (.xxx.c) or hidden directories are not suported as parameter The target file get the extention .htm

If you like to use ini files, you must change the actual directory to that one, where the ini files reside. Start src2html from that directory. So it is possible to use different ini files only by changing the actual directory.

Changing Colors

In src2html.ini are (nearly) all HTML-codes defined, which are copied into the source. So it is easy to change something. It is possible to change the colors, fonts or anything else possible wit HTML.

Short explaination to the lines in src2html.ini:

A semicolon in column 1 starts a comment. The types of markings are numbered. These numbers are used by src2html to detect the type, but are not copied into the source. Preceding blanks are allowed. Anything behind the dot will be copied into the source. The max. length of a line in the ini files is 1024 characters.

 4, 5, 6 Definition of a procedure/function
;   <font color=purple><a name="targetdef">define target</a></font>
;   ----------------------------         --             -----------
;   4. (zs_html_proc_def_a)
4.<font color=purple><a name="
;   5. (zs_html_proc_def_b)
5.">
;   6. (zs_html_proc_def_c)
6.</a></font>

7, 8, 9 Hyperlink to a procedure/function
;   <a href="#targetdef">link to target</a>
;   ---------          --              ----
;   7. (zs_html_proc_use_a)
7.<a href="
;   8. (zs_html_proc_use_b)
8.">
;   9. (zs_html_proc_use_c)
9.</a>

10, 11, 12 Hyperlink to a procedure/function inside a comment

;   <a href="#targetdef"><font color=forestgreen>link to target</font></a>
;   ---------           -------------------------              -----------
;   10. (zs_html_cproc_use_a)
10.<a href="
;   11. (zs_html_cproc_use_b)
11."><font color=forestgreen>
;   12. (zs_html_cproc_use_c)
12.</font></a>

13, 14, 28 Keywords, defined in langkeywords.ini

Here is something special:

If 28 is not defined, the keyword is printed only ones. If you define 28, the keyword is printed behind the code of 15. again, followed by the code defined with 28.

Example without 28.:

;   <font color=blue>blue text</font>
;   -----------------         -------
;   13. (zs_html_keyword_def_a)
13.<font color=blue>
;   14. (zs_html_keyword_def_b)
14.</font>
  
Example with 28.:
; if you define 28, the keyword is printed twice!
; so 13 and 14 are used in another way  
; example:
;   <a href="javascript:q_help('keyword')" style="text-decoration: none;color:blue;">keyword</a>
;   ----------------------------       ----------------------------------------------       ----
;   13. (zs_html_other_keyword_def_a)
13.<a href="javascript:q_help('
;   14. (zs_html_keyword_def_b)
14.')" style="text-decoration: none;color:blue;">
;   28. (zs_html_keyword_def_c)
28.</a>

15, 16 Commented keywords, defined in langkeywords.ini
;   15, 16 color of comments
;   <font color=forestgreen>forestgreen text</font>
;   ------------------------                -------
;   15. (zs_html_comment_def_a)
15.<font color=forestgreen>
;   16. (zs_html_comment_def_b)
16.</font>

17, 18 Digits
;   17, 18 color of digits (e.g. 123 )
;   <font color=red>red text</font>
;   ----------------        -------
;   17 (zs_digitStart)
17.<font color=red>
;   18 (zs_digitEnd)
18.</font>

19, 20 Strings "ABC"
;   19, 20 color of strings (e.g. "ABC" )
;   <font color=dimgray>dimgray text</font>
;   --------------------            -------
;   19 (zs_StringStart)
19.<font color=dimgray>
;   20 (zs_StringEnd)
20.</font>

21, 22 Character 'A'
;   21, 22 color of char (e.g. 'A' )
;   <font color=dimgray>dimgray text</font>
;   --------------------            -------
;   21 (zs_CharStart)

21.<font color=dimgray>
;   22 (zs_CharEnd)
22.</font>

23, 24 Chill Binary- and Hex-digits H'FF 
;   23, 24 color of binary or hex digits in chill (e.g. H'FFFF)
;   <font color=red>red text</font>
;   ----------------        -------
;   23 (zs_ChillCharStart)
23.<font color=red>
;   24 (zs_ChillCharEnd)
24.</font>

25, 26, 27 Keywords, defined in otherkeywords.ini

Here is something special:

If 27 is not defined, the keyword is printed only ones. If you define 27, the keyword is printed behind the code of 26. again, followed by the code defined with 27.

Example without 27.:

;   25, 26 color of other keywords  (27 not defined)
;   declared in otherkeywords.ini
;   <font color=red>keyword</font>
;   ----------------       -------
;   25. (zs_html_other_keyword_def_a)
25.<font color=red>
;   26. (zs_html_other_keyword_def_b)
26.</font>

Example with 27.:
; if you define 27, the keyword is printed twice!
; so 25 and 26 are used in another way  
; example:
;   <a href="javascript:q_help('keyword')" style="text-decoration: none;color:blue;">keyword</a>
;   ----------------------------       ----------------------------------------------       ----
;   25. (zs_html_other_keyword_def_a)
25.<a href="javascript:q_help('
;   26. (zs_html_other_keyword_def_b)
26.')" style="text-decoration: none;color:blue;">
;   27. (zs_html_other_keyword_def_c)
27.</a>

Frames
The size and color of the frames can be changed, but the title is always the name of the source file.

Source Frame
;   1. Headerline of Source frame  (zs_first_line_a2)
1.</title></head><body bgcolor=#ffffff text=black link=purple vlink=purple alink=silver><font color=black><pre>

Left Frame with the list of procedures/functions
;   2. Headerline of left frame (zs_first_line_a2pl)
2.</title></head><body bgcolor=#ffffff text=black link=purple vlink=purple alink=silver><font color=black><pre>

Frame Size 
;   3. Frame definition (zs_FrameDef_a1)
3."</title></head><frameset cols="20%,*" border=1 frameborder=1 framespacing=1><frame src="

Example With Javascript

Into the directory example, you can see, how to call a javascript function with the help of the INI-Files. If a keyword is clicked, a new window info.html is opened. It is scrolled to that anchor, which has the same name than the keyword.

example.c was converted with the command ../src2html example.c

As result, example.htm was generated.
example.htm consist of 2 frames, which are filled with examplelf.htm and examplesrc.htm.

Definition of keywords

Into otherkeywords.ini are keywords defined. They are used as anchor in info.html.

A part of otherkeywords.ini :
anker1
anker2
anker3
anker4
anker5
anker6
anker7

Deklaration Of Javascript Function

In src2html.ini is the link to the javascript function defined. A part of src2html.ini :

  1.</title><script language="JavaScript" src="src2html.js" type="text/javascript"></script></head><body bgcolor=#ffffff text=black link=purple vlink=purple alink=silver><font color=black><pre> 
:
.
  25.<a href="javascript:q_help('
  ;   otherkeyword
  26.')" style="text-decoration: none;color:blue;">
  ;   other_keyword
  27.</a>

At 1. is the headline of the html file defined. here is the link to src2html.js inserted. At 25. is the call of q_help(), which is defined in src2html.js definiert. As parameter, we use the keyword which is defined in otherkeywords.ini and found into the source file.

Definition Of Javascript Function

The definition of the javascript function is defined in the file src2html.js, which is declared after 1.

function q_help( zp_anchor)
 {    
   MyWindow = window.open("info.html", "helpfile");
   MyWindow.focus();
   MyWindow.location.href = "info.html#"+zp_anchor;
 }

Editorial

This program was written by Jörg Feler.
From now on, (Version 0.1g) src2html is licensed by the GNU General Public License.


    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

You can download the GNU General Public License.

No software is error free, but src2html has been tested extensive. If you find an error, drop me a mail with a short description and the version please. All registered users will be informed, if a new version of src2html is available.

Find the latest version at http://www.feler.de/src2html/src2html.html

Have fun
Jörg Feler

by J. Feler