<html>
<head>
<title>Architecture of the CVSTrac Program</title>
</head>
<body bgcolor="white">
<h1 align="center">
Architecture of the CVSTrac Program
</h1>

<h2>1.0 &nbsp; Introduction</h2>

<p>This note gives a high-level overview of how the CVSTrac program works
and how it is put together. 
It is assumed that the reader is already familiar with what CVSTrac
does.  The purpose of this document is to provide some additional
background information on the internal operation of CVSTrac in order
to guide potential contributors in making improvements to the code.
</p>

<h2>2.0 &nbsp; Design Rules</h2>

<p>CVSTrac is designed so that each incoming HTTP request is handled by
a separate process.  No attempt is made to avoid memory leaks, since the
process will terminate as soon as the HTTP request is finished.  Global
variables are used where it is convenient since only a single thread
will be running in the address space.</p>

<p>Some people have worried that using
a separate process for each HTTP request is inefficient.  It may be true
that one process per request is not the most efficient design, but it
appears to be efficient enough.  A 166MHz Pentium with 32MB of RAM has
proven to be more than adequate to service a large development group.  
So for now, CVSTrac will stick with a simple but adequate design that
avoids subtle bugs rather than push the envelope with a high-performance
design that is harder to work with and more prone to errors.</p>

<p>The program is designed for Unix.  No thought has been given to making
it run on the "other platform", though there have been reports of success
getting it to work using Cygwin.</p>

<h2>3.0 &nbsp; Code Generators And Preprocessors</h2>

<p>The programming language is C.  But most of the code that actually
reaches the C compiler is either automatically generated or preprocessed.
The source code that you, the programmer, look at in an editor is not
the same source code that the C compiler works with.</p>

<p>CVSTrac currently uses five different code generators and
preprocessors:</p>

<ul>
<li><p>Most of the header files (the *.h files) are generated by 
    the <a href="makeheaders.html">makeheaders</a> program.</p></li>
<li><p>The C source files contain embedded HTML text.  This text
    is converted into special function calls using the
    "<tt>translate</tt>" preprocessor.</p></li>
<li><p>Each CVSTrac webpage is handled by a different subroutine.
    The page handler subroutine each have a special header comment
    that identifies them as such.  The <tt>mkindex</tt> program
    scans the source files for these header comments and constructs
    a table of webpages used by by the dispatcher.</p></li>
<li><p>The text of the initial wiki that are created when a new
    project is initialized is contained in the "<tt>wikiinit.c</tt>"
    source file.  That source file is created by editing the wiki
    in a working CVSTrac project, then running the "<tt>makewikiinit</tt>"
    program over the project database.</p></li>
<li><p>The "<tt>main.mk</tt>" makefile is generated by a Tcl script
    "<tt>makemake.tcl</tt>".</p></li>
</ul>

<p>A few of these code generators and preprocessors are explained
in added detail by the following subheadings.</p>

<h3>3.1 &nbsp Extracting embedded HTML using <tt>translate</tt></h3>

<p>The CVSTrac program deals with a lot of text - mostly HTML but
also a fair amount of SQL.  But large blocks of text (where large
means hundreds or thousands of characters or dozens of lines) are
difficult to deal with in C.  All the text must be enclosed in
double-quotes and special characters, such as newlines and the
double-quote character itself, must be escaped by using a backslash.
The net result is that the text becomes difficult to read and edit.</p>

<p>The <tt>translate</tt> program tries to make the code more readable
by converting all lines that begin with a "<tt>@</tt>" character into code that
appends the text on that line to the HTML document being generated.
This makes the output text more readable by avoiding the
need to write "<tt>\n</tt>" and "<tt>\"</tt>".  Furthermore, the
line of <tt>@</tt> at the left margin allows the eye to quickly see
what code is C executable and what is HTML text.  Consider this
example (taken from <tt>ticket.c</tt>):</p>

<blockquote><pre>
  @
  @ Description:
  @ (&lt;small&gt;See &lt;a href="#format_hints"&gt;formatting hints&lt;/a&gt;&lt;/small&gt;)&lt;br&gt;
  if( isPreview ){
    @ &lt;table border=1 cellpadding=15 width="100%%"&gt;&lt;tr&gt;&lt;td&gt;
    output_formatted(aParm[10].zNew);
    @ &nbsp;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&lt;br&gt;
    @ &lt;input type="hidden" name="c" value="%h(aParm[10].zNew)"&gt;
  }else{
    @ &lt;textarea name="c" rows="8" cols="70" wrap="virtual"&gt;
    @ %h(aParm[10].zNew)
    @ &lt;/textarea&gt;&lt;br&gt;
  }
</pre></blockquote>

<p>This is a block of code that generates the "Description:" section of
a ticket display in CVSTrac.  The text of the description will appear 
formatted as HTML if the "isPreview" boolean is true or as an editable
textarea if "isPreview" is false.</p>

<p>The embedded HTML text can contain references to C variables.
For example, "<tt>%s(z)</tt>" will insert the content of the string
variable "z".  "<tt>%d(n)</tt>" will insert the content of integer n.
The "<tt>%</tt>" character is generated by putting two percent signs
in a row, like this: "<tt>%%</tt>".  
Of special note is the sequence "<tt>%h(z)</tt>" which inserts the 
content of string variable z, but also translates that content by
escaping characters that have special meaning to HTML.  So if you
write code like this:</p>

<blockquote><pre>
  z = "<yes> & <no>";
  @ The string is: %h(z)
</pre></blockquote>

<p>The generated HTML will look like this:</p>

<blockquote><pre>
The string is &amp;lt;yes&amp;gt; &amp;amp; &amp;lt;no&amp;gt;
</pre></blockquote>

<p>The <tt>%h</tt> substitution is used extensively in CVSTrac
to make user-entered text safe for inclusing in an HTML document.</p>

<p>From this short example,
it may not be immediately clear that the <tt>translate</tt> program helps
the readability of the code.  But if you examine a larger section of the
source and compare it to the real C code that <tt>translate</tt> outputs,
you will find that the code with embedded HTML is much easier to work with.<p>

<p>Additional information about <tt>translate</tt> can be found in the
header comments of the program's source file: <tt>translate.c</tt>.</p>


<big><i>To be continued...</i></big>
