<!-- $Id$ -->
      <h2>mod_dtcl Documentation</h2>
      
      <h3>1) Installation</h3>
      <ol>
	<li><b>Check dependencies</b><br>
	  
	  To install mod_dtcl, you will need <b>Tcl 8.2</b> or greater
	  and <b>Apache 1.3.xx</b>.  It is known to run on Linux,
	  FreeBSD, OpenBSD, and Solaris and HPUX.  NT is also possible -
	  please see the directions in the distribution.
	</li>

	<li><b>Get mod_dtcl</b><br>

	  If you are running a Debian or FreeBSD system, there
	  are pre-built packages available at:
	  <a href="http://www.debian.org/Packages/unstable/web/libapache-mod-dtcl.html">http://www.debian.org/Packages/unstable/web/libapache-mod-dtcl.html</a> 

	  or
	  
	  <a
	    href="http://www.freebsd.org/cgi/ports.cgi?query=mod_dtcl">http://www.freebsd.org/cgi/ports.cgi?query=mod_dtcl</a>.<br>
	  Otherwise, download the sources at <a href="download/">http://tcl.apache.org/mod_dtcl/download/</a>.
	  <br>
	</li>
	<li><b>Uncompress the sources</b><br>
	  <code>
	    gunzip apache-1.3.X.tar.gz<br>
	    tar -xvf apache-1.3.X.tar.gz<br>
	  </code>
	  You don't need the Apache sources if you are building a shared
	  object module.  You do, however, need the header files.
	  Some systems, such as Debian GNU/Linux, provide these
	  independently - otherwise, you probably still need the sources.<br>
	  <code>
	    gunzip mod_dtcl-X.X.X.tar.gz<br>
	    tar -xvf mod_dtcl-X.X.X.tar.gz<br>
	  </code>
	</li>

	<li><b>Configuring, builddtcl.sh, etc...</b><br> 

	  Do you want to build mod_dtcl as a shared object (such as a
	  .so file on Linux, or a .dll on windows), or compile it
	  directly as a part of the Apache executable?  The Apache
	  Software Foundation has put together a nice <a
	  href="http://httpd.apache.org/docs/dso.html">manual</a>
	  which explains things in detail.

	  <ul>
	    <li><b>For shared objects</b><br>
	      
	      <code>cd ../mod_dtcl/<br></code>
	      Edit the <code>builddtcl.sh</code> script.  The 3
	      variables you may need to change are: 
	      <ul>
		<li><code>TCLSH</code><br>
		  Name of the tclsh program on your computer.
		</li>
		<li><code>APACHE</code><br>
		  Location of the Apache sources (for static builds only).
		</li>
		<li><code>INC</code><br>
		  Location of the Apache headers (you will need this even
		  for building shared objects).
		</li>
	      </ul>

	      <code>
		./builddtcl.sh shared
	      </code><br>

	      <code>
		cp mod_dtcl.so
		/usr/lib/apache/wherever/the/other/shared/objects/reside
		</code> For shared object builds, you need to copy the
		object into the directory where the other shared
		objects are kept for your Apache build.  On Debian
		GNU/Linux systems, for instance, this is in
		<code>/usr/lib/apache/1.3/</code>.

	    </li>
	    
	    <li><b>For static builds</b><br>
	      <code>
		cd apache-1.3.X/<br>
		./configure<br>
	      </code>

	      <code>cd ../mod_dtcl/<br></code>
	      Edit the <code>builddtcl.sh</code> script.  The 3
	      variables you may need to change are: 
	      <ul>
		<li><code>TCLSH</code><br>
		  Name of the tclsh program on your computer.
		</li>
		<li><code>APACHE</code><br>
		  Location of the Apache sources (for static builds only).
		</li>
		<li><code>INC</code><br>
		  Location of the Apache headers (you will need this even
		  for building shared objects).
		</li>
	      </ul>

	      <code>
		./builddtcl.sh static
	      </code><br>

	      <code>
		./builddtcl.sh install
	      </code><br>

	      <code>cd ../apache-1.3.X<br></code>
	      <code>./configure
		--activate-module=src/modules/mod_dtcl/mod_dtcl.a [ other configure
		options ]<br></code>
	      <code>export EXTRA_LIBS="-ltcl8.X -lm"</code><br>
	      <code>make -e<br></code>
	      <code>make install<br></code>
	      
	    </li>
	  </ul>
	</li>
	<li><b>Configure Apache<br></b>		
	  <ul>
	    <li>
	      <b>http.conf</b><br> <code>LoadModule dtcl_module
		/usr/lib/apache/1.3/mod_dtcl.so</code><br> 
	      This points Apache to the shared object if
	      mod_dtcl is being used as a loadable module.
	    </li>
	    <li>
	      <b>srm.conf</b><br> 
	      <code>AddType application/x-httpd-tcl .ttml</code><br>
	      <code>AddType application/x-dtcl-tcl .tcl</code>
	      (optional)<br>
	      These add the .ttml and .tcl (if desired) types to
	      Apache, so that they are processed by mod_dtcl.
	    </li>
	  </ul>
	</li>

      </ol>


      <h3>2) Apache Directives</h3>

      <ul>
	<li>
	  <code><b>Dtcl_Script GlobalInitScript <i>"script"</i></code></b><br>
	  Tcl script that is run when each interpreter is
	  initialized.  <code>"script"</code> is actual Tcl
	  script, so to run a file, you would do
	  <code>Dtcl_Script GlobalInitScript "source /var/www/foobar.tcl"</code>.
	</li>

	<li>
	  <code><b>Dtcl_Script ChildInitScript <i>"script"</i></b></code><br>		
	  Script to be evaluated when each apache child is
	  initialized. This is the best place to load modules.
	</li>

	<li>
	  <code><b>Dtcl_Script ChildExitScript <i>"script"</i></b></code><br>	      
	  Script to be evaluated when each apache child exits.
	</li>

	<li>
	  <code><b>Dtcl_Script BeforeScript <i>"script"</i></b></code><br>		
	  Script to be evaluated before each .ttml page.
	  <strong>Note</strong> that you cannot use
	  <code>hputs</code> in the BeforeScript, but must
	  instead use <code>buffer_add</code>.
	</li>

	<li>
	  <code><b>Dtcl_Script AfterScript <i>"script"</i></b></code><br>	      
	  Script to be called after each .ttml page.
	</li>

	<li>
	  <code><b>Dtcl_Script ErrorScript <i>"script"</i></b></code><br>	      
	  This code is called in place of the standard 'error' pages
	  generated for mod_dtcl.  This directive may be useful if you
	  have sensitive logic that you wish to protect.
	</li>
	
	<li>
	  <code><b>Dtcl_CacheSize <i>cachesize</i></b></code><br> 
	  Number of ttml scripts to cache as Tcl Objects.
	  Default is MaxRequestsPerChild / 2, or 50, if
	  MaxRequestsPerChild is 0.
	</li>


	<li>
	  <code><b>Dtcl_UploadFilesToVar <i>1/0</i></b></code><br> 
	  If set to 1, files will be uploaded to the variable
	  UPLOAD(data).  Be careful with this, as large files could
	  use up your memory.
	</li>

      </ul>

      <h3>3) mod_dtcl specific Tcl commands and variables</h3>

      <ul>
	<li>
	  <code><b>buffer_add <i>string</i></b></code><br>	      
	  Add text to output_buffer for later printing. Used
	  internally.
	</li>

	<li>
	  <code><b>hputs <i>?-error? text</i></b></code><br>	      
	  The mod_dtcl version of "puts".  Outputs to the
	  client, instead of to stdout.
	  The error option permits you to send an 'error message' to the
	  apache log file, at the NOTICE level.
	</li>
	<li>
	  <code><b>hgetvars</b></code><br>
	  Get environmental, CGI and Cookie variables. This is
	  in a seperate command so as not to make the server do
	  this every time you load a .ttml file. ENVS, VARS, and
	  COOKIES are the associative arrays created.  ENVS
	  contains environmental variables, VARS contains all
	  the 'cgi' variables, and COOKIES, any cookies recieved
	  from the client. 
	</li>
	<li>
	  <code><b>include <i>filename</i></b></code><br>	      
	  Include a file without parsing it.  This is the best
	  way to include an HTML file or any other static content.
	</li>
	<li>
	  <code><b>parse <i>filename</i></b></code><br>	      
	  "Source" a .ttml file.  This is the way to include
	  other .ttml files.
	</li>
	<li>
	  <code><b>hflush</b></code><br>	      
	  Flush the output buffers to the client.  Use this if
	  you want to incrementally update a page.
	</li>
	<li>
	  <code><b>headers redirect <i>uri</i></b></code><br>	      

	  Redirect from the current page to a new
	  URI. <b>Must</b> be done in the first block of TCL code.
	</li>
	<li>
	  <code><b>headers setcookie <i>-name cookie-name
		-value cookie-value ?-expires date/time? ?-domain domain?
		?-path path? ?-secure?</i></b></code><br>

	  This command is for setting cookies.  Cookie-name is
	  the name of the cookie, cookie-value is the data
	  associated with the variable.  Expires sets an
	  expiration date for the cookie, and must be in the
	  format 'DD-Mon-YY HH:MM:SS', path sets the path for
	  which the cookie is valid, and secure specifies that
	  the cookie is only to be transmitted if the connection
	  is secure (HTTPS).
	</li>
	<li>
	  <code><b>headers type
	      <i>content-type</i></b></code><br>

	  This command sets the "Content-type:" header returned
	  by the script, which is useful if you wish to create a
	  PNG (image), for example, with mod_dtcl.
	</li>
	<li>
	  <code><b>headers set <i>headername value</i></b></code><br>

	  Set arbitrary header names and values.
	</li>

	<li>
	  <code><b>dtcl_info</b></code><br>	      

	  Prints information on the internals of the module in
	  HTML.  Currently, only the PID and size of the object
	  cache are reported.
	</li>

	<li>
	  Note that these variables may be lists if more than one file
	  is uploaded at a time.<br>
	  <code><b>$::request::UPLOAD(filename)</b></code><br>
	  The filename of the uploaded file.<br>

	  <code><b>$::request::UPLOAD(name)</b></code><br>
	  The form variable name of the upload.<br>

	  <code><b>$::request::UPLOAD(size)</b></code><br>
	  The size of the uploaded file.<br>

	  <code><b>$::request::UPLOAD(type)</b></code><br>
	  The content type of the file upload. <i>Not always available!</i><br>

	  <code><b>$::request::UPLOAD(channelname)</b></code><br> The
	  name of a Tcl channel which may be used to manipulate the
	  uploaded file.  If Dtcl_UploadFilesToVar is set, this
	  variable doesn't get created.  If no file is passed to the
	  server, this variable does not exist!  Be sure to check for
	  this.<br>

	  <code><b>$::request::UPLOAD(data)</b></code><br>
	  Contents of the uploaded file, if Dtcl_UploadFilesToVar is
	  set.<br>
	</li>

      </ul>

      <h3>4) Internals</h3>
      <ul>
	<li><b>Read the code!</b></li>
	<li>		
	  <b>Initialization</b><br>

	  When Apache is started, (or when child Apache
	  processes are started if a threaded Tcl is used),
	  <code>tcl_init_stuff</code> is called, which creates
	  a new interpreter, and initializes various things,
	  like the <code>apache_channel</code> channel system.
	  The caching system is also set up, and if there is a
	  GlobalScript, it is run.
	</li>
	<li><b>Achan/apache_channel</b><br>

	  The "Apache Channel" system was created so that it is
	  possible to have an actual Tcl channel that we could
	  redirect standard output to.  This lets us use, for
	  instance, the regular "puts" command in .ttml pages.
	  It works by creating commands that write to memory
	  that is slated to be sent to the client.
	</li>

	<li><b>Page parsing/execution</b><br>

	  In <code>send_parsed_file</code> Each .ttml file is
	  loaded and run within its own namespace.  No new
	  interpreter is created for each page.  This lets you
	  share variables, and most importantly, loaded modules,
	  from a common parent (such as one of the InitScripts).
	  When a file is loaded, it is transformed into a Tcl
	  script by putting everything outside of &lt;? and
	  ?&gt; into large hputs statements.  When the script is
	  complete, it is then inserted into the cache, for
	  future use.  In fact, if the file modification
	  information doesn't change, mod_dtcl will execute the
	  cached version of the script the next time it is
	  encountered.
	</li>
	<li><b>Binary data</b><br>
	  mod_dtcl is capable of outputing binary data, such as
	  images, or loading binary data with 'include'.
	</li>
      </ul>

      <h3>5) Upgrading From Older (< 0.9.3) Versions</h3>
      <ul>
	<li><b>New tags</b><br> As of version 0.9.4, mod_dtcl uses
	  &lt;? and ?&gt; instead of &lt;+ and +&gt; to delimit
	  sections of Tcl code.  By default, dtcl is still compiled
	  with code to parse the &lt;?  ?&gt; tags, but it will run
	  faster if <code>USE_OLD_TAGS</code> is set to 0 in
	  <code>mod_dtcl.h</code>.  You can automatically change your
	  .ttml files to the new format by using the
	  <code>newtags.sh</code> script in the contrib/ directory.
	  Run it at the top level of your DocumentRoot.
	</li>
	<li><b>headers setcookie</b><br>
	  The <code>headers setcookie</code> command now uses the
	  <code>-name</code> and <code>-value</code> flags for those
	  arguments, whereas this was not necessary in the past.
	</li>
      </ul>

      <h3>6) Getting Help</h3>
      <ul>
	<li><b>Mailing list</b><br>
	  <p>
	    The mod_dtcl mailing list is the best place to go for help
	    when you have problems.
	  </p>
	  <p>
	    See the <a
		       href="http://tcl.apache.org/mod_dtcl/contact.html">Contact</a>
		       page for information on sending
		       mail/subscribing.
	  </p>
	  <p>
	    Mailing list archives are also available at <a
	    href="http://archive.covalent.net">http://archive.covalent.net</a>,
	    at the bottom of the page.
	  </p>
	</li>
      </ul>

      
      <!-- The load dtd is so that I can work on the documentation
      with emacs' SGML in all its glory - davidw  -->

      <!-- Local Variables: -->
      <!-- eval: (sgml-load-dtd "~/html.ced") -->
      <!-- End: -->