
                       ********** mmoodd__ddttccll IInnssttaallllaattiioonn **********
   1. CChheecckk ddeeppeennddeenncciieess
      To install mod_dtcl, you will need TTccll 88..22 or greater and AAppaacchhee 11..33..xxxx.
      It is known to run on Linux, FreeBSD, OpenBSD, and Solaris and HPUX. NT
      is also possible - please see the directions in the distribution.
   2. GGeett mmoodd__ddttccll
      If you are running a Debian or FreeBSD system, there are pre-built
      packages available at: _h_t_t_p_:_/_/_w_w_w_._d_e_b_i_a_n_._o_r_g_/_P_a_c_k_a_g_e_s_/_u_n_s_t_a_b_l_e_/_w_e_b_/
      _l_i_b_a_p_a_c_h_e_-_m_o_d_-_d_t_c_l_._h_t_m_l or _h_t_t_p_:_/_/_w_w_w_._f_r_e_e_b_s_d_._o_r_g_/_c_g_i_/
      _p_o_r_t_s_._c_g_i_?_q_u_e_r_y_=_m_o_d___d_t_c_l.
      Otherwise, download the sources at _h_t_t_p_:_/_/_t_c_l_._a_p_a_c_h_e_._o_r_g_/_m_o_d___d_t_c_l_/
      _d_o_w_n_l_o_a_d_/.
   3. UUnnccoommpprreessss tthhee ssoouurrcceess
      gunzip apache-1.3.X.tar.gz
      tar -xvf apache-1.3.X.tar.gz
       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.
      gunzip mod_dtcl-X.X.X.tar.gz
      tar -xvf mod_dtcl-X.X.X.tar.gz
   4. CCoonnffiigguurriinngg,, bbuuiillddddttccll..sshh,, eettcc......
      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
      _m_a_n_u_a_l which explains things in detail.
          o FFoorr sshhaarreedd oobbjjeeccttss
            cd ../mod_dtcl/
             Edit the builddtcl.sh script. The 3 variables you may need to
            change are:
                # TCLSH
                  Name of the tclsh program on your computer.
                # APACHE
                  Location of the Apache sources (for static builds only).
                # INC
                  Location of the Apache headers (you will need this even for
                  building shared objects).
            ./builddtcl.sh shared
            cp mod_dtcl.so /usr/lib/apache/wherever/the/other/shared/objects/
            reside 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
            /usr/lib/apache/1.3/.
          o FFoorr ssttaattiicc bbuuiillddss
            cd apache-1.3.X/
            ./configure
             cd ../mod_dtcl/
             Edit the builddtcl.sh script. The 3 variables you may need to
            change are:
                # TCLSH
                  Name of the tclsh program on your computer.
                # APACHE
                  Location of the Apache sources (for static builds only).
                # INC
                  Location of the Apache headers (you will need this even for
                  building shared objects).
            ./builddtcl.sh static
            ./builddtcl.sh install
            cd ../apache-1.3.X
             ./configure --activate-module=src/modules/mod_dtcl/mod_dtcl.a
            [ other configure options ]
             export EXTRA_LIBS="-ltcl8.X -lm"
            make -e
             make install
   5. CCoonnffiigguurree AAppaacchhee
          o hhttttpp..ccoonnff
            LoadModule dtcl_module /usr/lib/apache/1.3/mod_dtcl.so
            This points Apache to the shared object if mod_dtcl is being used
            as a loadable module. In some cases, adding AddModule mod_dtcl.c
            seems to also have positive effects.
          o ssrrmm..ccoonnff
            AddType application/x-httpd-tcl .ttml
            AddType application/x-dtcl-tcl .tcl (optional)
            These add the .ttml and .tcl (if desired) types to Apache, so that
            they are processed by mod_dtcl.
                    ********** mmoodd__ddttccll AAppaacchhee ddiirreeccttiivveess **********
    * DDttccll__SSccrriipptt GGlloobbaallIInniittSSccrriipptt ""ssccrriipptt""
    *
      Tcl script that is run when each interpreter is initialized. "script" is
      actual Tcl script, so to run a file, you would do Dtcl_Script
      GlobalInitScript "source /var/www/foobar.tcl".
    * DDttccll__SSccrriipptt CChhiillddIInniittSSccrriipptt ""ssccrriipptt""
       Script to be evaluated when each apache child is initialized. This is
      the best place to load modules.
    * DDttccll__SSccrriipptt CChhiillddEExxiittSSccrriipptt ""ssccrriipptt""
       Script to be evaluated when each apache child exits.
    * DDttccll__SSccrriipptt BBeeffoorreeSSccrriipptt ""ssccrriipptt""
       Script to be evaluated before each .ttml page. NNoottee that you cannot use
      hputs in the BeforeScript, but must instead use buffer_add.
    * DDttccll__SSccrriipptt AAfftteerrSSccrriipptt ""ssccrriipptt""
       Script to be called after each .ttml page.
    * DDttccll__SSccrriipptt EErrrroorrSSccrriipptt ""ssccrriipptt""
       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.
    * DDttccll__CCaacchheeSSiizzee ccaacchheessiizzee
      Number of ttml scripts to cache as Tcl Objects. Default is
      MaxRequestsPerChild / 2, or 50, if MaxRequestsPerChild is 0.
    * DDttccll__UUppllooaaddFFiilleessTTooVVaarr oonn//ooffff
      If on, files will be uploaded to the variable UPLOAD(data). Be careful
      with this, as large files could use up your memory.
    * DDttccll__SSeeppeerraatteeVViirrttuuaallIInntteerrppss oonn//ooffff
      If on, each VirtualHost will have its own Tcl interpreter.
           ********** mmoodd__ddttccll ssppeecciiffiicc TTccll ccoommmmaannddss aanndd vvaarriiaabblleess **********
    * bbuuffffeerr__aadddd ssttrriinngg
       Add text to output_buffer for later printing. Used internally.
    * hhppuuttss ??--eerrrroorr?? tteexxtt
      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.
    * vvaarr
      These commands retrieve or retrieve information about "CGI" variables
      that are passed to the dtcl script via GET or POST operations.
    * vvaarr ggeett vvaarrnnaammee
      Returns the value of variable 'varname' as a string (even if there are
      multiple values).
    * vvaarr lliisstt vvaarrnnaammee
      Returns the value of variable 'varname' as a list, if there are multiple
      values.
    * vvaarr eexxiissttss vvaarrnnaammee
      Returns 1 if varname exists, 0 if it doesn't.
    * vvaarr nnuummbbeerr
      Returns the number of variables.
    * vvaarr aallll
      Return a list of variable names and values.
    * uuppllooaadd
      These commands retrieve or retrieve information about files that have
      been uploaded to the server. They replace the UPLOAD variable.
    * uuppllooaadd ggeett vvaarrnnaammee cchhaannnneell
      Returns a Tcl channel that can be used to access the uploaded file.
    * uuppllooaadd ggeett vvaarrnnaammee ssaavvee nnaammee
      Moves the uploaded file to the give name.
    * uuppllooaadd ggeett vvaarrnnaammee ddaattaa
      Returns data uploaded to the server. This is binary clean.
    * uuppllooaadd iinnffoo vvaarrnnaammee eexxiissttss
      Returns 1 if the variable exists, 0 if not.
    * uuppllooaadd iinnffoo vvaarrnnaammee ssiizzee
      Returns the size of the file uploaded.
    * uuppllooaadd iinnffoo vvaarrnnaammee ttyyppee
      If the Content-type is set, it is returned, otherwise, an empty string.
    * uuppllooaadd iinnffoo vvaarrnnaammee ffiilleennaammee
      Returns the filename on the remote host that uploaded the file.
    * uuppllooaadd nnaammeess
      Returns the variable names, as a list, of all the files uploaded.
    * hhggeettvvaarrss
      Get environmental, 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
      and COOKIES are the associative arrays created. ENVS contains
      environmental variables, and COOKIES contains any cookies recieved from
      the client.
    * iinncclluuddee ffiilleennaammee
       Include a file without parsing it. This is the best way to include an
      HTML file or any other static content.
    * ppaarrssee ffiilleennaammee
       "Source" a .ttml file. This is the way to include other .ttml files.
    * hhfflluusshh
       Flush the output buffers to the client. Use this if you want to
      incrementally update a page.
    * hheeaaddeerrss rreeddiirreecctt uurrii
       Redirect from the current page to a new URI. MMuusstt be done in the first
      block of TCL code.
    * hheeaaddeerrss sseettccooookkiiee --nnaammee ccooookkiiee--nnaammee --vvaalluuee ccooookkiiee--vvaalluuee ??--eexxppiirreess ddaattee//
      ttiimmee?? ??--ddoommaaiinn ddoommaaiinn?? ??--ppaatthh ppaatthh?? ??--sseeccuurree??
      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).
    * hheeaaddeerrss ttyyppee ccoonntteenntt--ttyyppee
      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.
    * hheeaaddeerrss sseett hheeaaddeerrnnaammee vvaalluuee
      Set arbitrary header names and values.
    * mmaakkeeuurrll ffiilleennaammee
      Create a self referencing URL from a filename. For example: makeurl /
      tclp.gif returns http://[hostname]:[port]/tclp.gif.
    * ddttccll__iinnffoo
       Prints information on the internals of the module in HTML. Currently,
      only the PID and size of the object cache are reported.
********** OOtthheerr mmoodd__ddttccll DDooccuummeennttaattiioonn **********
******** IInntteerrnnaallss ********
    * RReeaadd tthhee ccooddee!!
    *  IInniittiiaalliizzaattiioonn
      When Apache is started, (or when child Apache processes are started if a
      threaded Tcl is used), tcl_init_stuff is called, which creates a new
      interpreter, and initializes various things, like the apache_channel
      channel system. The caching system is also set up, and if there is a
      GlobalScript, it is run.
    * AAcchhaann//aappaacchhee__cchhaannnneell
      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.
    * PPaaggee ppaarrssiinngg//eexxeeccuuttiioonn
      In send_parsed_file 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 <? and ?>
      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.
    * BBiinnaarryy ddaattaa
      mod_dtcl is capable of outputing binary data, such as images, or loading
      binary data with 'include'.
******** UUppggrraaddiinngg FFrroomm OOllddeerr ((<< 00..99..33)) VVeerrssiioonnss ********
    * NNeeww ttaaggss
      As of version 0.9.4, mod_dtcl uses <? and ?> instead of <+ and +> to
      delimit sections of Tcl code. By default, dtcl is still compiled with
      code to parse the <? ?> tags, but it will run faster if USE_OLD_TAGS is
      set to 0 in mod_dtcl.h. You can automatically change your .ttml files to
      the new format by using the newtags.sh script in the contrib/ directory.
      Run it at the top level of your DocumentRoot.
    * hheeaaddeerrss sseettccooookkiiee
      The headers setcookie command now uses the -name and -value flags for
      those arguments, whereas this was not necessary in the past.
