path: root/TWiki/TWikiImplementationNotes.mdwn

%TOC% %STARTINCLUDE%

# <a name="TWiki_Application_Environment"> TWiki Application Environment </a>

_Server and client system requirements; file system structure_

## <a name="Overview"> Overview </a>

Maintaining minimum client and server requirements is necessary to keep TWiki deployment as broad as possible.

## <a name="Server_Side_Requirements"> Server-Side Requirements </a>

TWiki is written in Perl 5 and uses a number of shell commands. It requires GNU RCS (Revision Control System) to be installed on the same system. TWiki is developed in a standard Linux/Apache environment. It can also work with Microsoft Windows and other platforms.

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC" colspan="3"><strong>Required Server Environment</strong></th>
  </tr>
  <tr>
    <th bgcolor="#99CCCC"><strong>Resource</strong></th>
    <th bgcolor="#99CCCC"><strong>Unix</strong></th>
    <th bgcolor="#99CCCC"><strong>Windows</strong></th>
  </tr>
  <tr>
    <td> Perl </td>
    <td align="center" colspan="2"> 5.005_03 or higher </td>
  </tr>
  <tr>
    <td> Non standard Perl modules </td>
    <td align="center"><code>Net::SMTP</code> (or <code>sendmail</code>) </td>
    <td align="right"><code>Net::SMTP</code>, <code>MIME::Base64</code>, <code>Digest::SHA1</code></td>
  </tr>
  <tr>
    <td> RCS </td>
    <td align="center" colspan="2"> 5.7 or higher </td>
  </tr>
  <tr>
    <td> Other external programs </td>
    <td align="center" colspan="2"><code>ls, fgrep, egrep</code></td>
  </tr>
  <tr>
    <td> Web server </td>
    <td align="center" colspan="2"> Apache; others (with support for CGI, authentication, extended path) <strong>*</strong></td>
  </tr>
</table>

Current documentation covers Linux only. Compiling a basic [TWikiOnWindows](http://twiki.org/cgi-bin/view/Codev/TWikiOnWindows) installation guide is an ongoing effort.

## <a name="Client_Side_Requirements"> Client-Side Requirements </a>

The TWiki standard installation has extremely low browser requirements:

* HTML 3.2 compliant
* minimal use of JavaScript in the user interface (degrades gracefully)
* no cookies
* no CSS

TWiki generates XHTML 1.0 code as long as it is compatible with HTML 3.2.

### <a name="Known_Issues"> Known Issues </a>

* The new [[TWikiPlugins]] feature currently does not have any compatibility guidelines for developers. Plugins can require just about anything: browser-specific functions, stylesheets (CSS), Java, cookies, etc.

## <a name="TWiki_File_System"> TWiki File System </a>

You can rename the root TWiki directory - `twiki` - to whatever you like by changing it in the `twiki.cfg` configuration file. However, to keep the current installation and future upgrades simple, you should leave the subdirectory structure intact:

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>Directory:</strong></th>
    <th bgcolor="#99CCCC"><strong>Files:</strong></th>
    <th bgcolor="#99CCCC"><strong>Used for:</strong></th>
  </tr>
  <tr>
    <td><code>twiki</code></td>
    <td align="center"> list </td>
    <td> Start-up info </td>
  </tr>
  <tr>
    <td><code>twiki/bin</code></td>
    <td align="center"> list </td>
    <td> Perl scripts </td>
  </tr>
  <tr>
    <td><code>twiki/lib</code></td>
    <td align="center"> list </td>
    <td> Configuration file, main library, Perl system modules, Plugins </td>
  </tr>
  <tr>
    <td><code>twiki/pub</code></td>
    <td align="center"> list </td>
    <td> Public support files (ex: <span style="background:"><font color="">File Attachments</font></span><a href="http://LOCATION/FileAttachments">?</a>, images) and RCS histories) </td>
  </tr>
  <tr>
    <td><code>twiki/data</code></td>
    <td align="center"> list </td>
    <td> Topic text (page content) and RCS histories; </td>
  </tr>
  <tr>
    <td><code>twiki/templates</code></td>
    <td align="center"> list </td>
    <td> HTML templates, used by TWiki scripts </td>
  </tr>
</table>

### <a name="File_Descriptions"> File Descriptions </a>

A rundown of the individual files included in the current 01-Sep-2001 distribution, organized by TWiki root directories.

<a name="TWikiFiles"></a>

#### <a name="Files_in_twiki_code_"> Files in `twiki` </a>

Application info and the current reference documentation. _Full file list:_

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>File:</strong></th>
    <th bgcolor="#99CCCC"><strong>Used for:</strong></th>
  </tr>
  <tr>
    <td><code>index.html</code></td>
    <td> A page with a link to first launch TWiki after install </td>
  </tr>
  <tr>
    <td><code>license.txt</code></td>
    <td> GNU General Public License and TWiki-specific info </td>
  </tr>
  <tr>
    <td><code>readme.txt</code></td>
    <td> General TWiki start-up info with relevant URLs </td>
  </tr>
  <tr>
    <td><code>TWikiDocumentation.html</code></td>
    <td> All documentation packaged as a single page </td>
  </tr>
  <tr>
    <td><code>TWikiHistory.html</code></td>
    <td> TWiki development timeline </td>
  </tr>
</table>

<a name="BinFiles"></a>

#### <a name="Files_in_twiki_bin_code_"> Files in `twiki/bin` </a>

Perl CGI scripts. _Full file list:_

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>File:</strong></th>
    <th bgcolor="#99CCCC"><strong>Used for:</strong></th>
  </tr>
  <tr>
    <td><code>.htaccess.txt</code></td>
    <td> Authentication. Rename to .htaccess and customize if used </td>
  </tr>
  <tr>
    <td><code>attach</code></td>
    <td> Script that shows the attach file page (<span style="background:"><font color="">File Attachment</font></span><a href="http://LOCATION/FileAttachment">?</a>) </td>
  </tr>
  <tr>
    <td><code>delete</code></td>
    <td> (not used yet) </td>
  </tr>
  <tr>
    <td><code>edit</code></td>
    <td> Script to edit a topic </td>
  </tr>
  <tr>
    <td><code>geturl</code></td>
    <td> Script to fetch URL data </td>
  </tr>
  <tr>
    <td><code>mailnotify</code></td>
    <td> Script called by cron job to notify users of changes </td>
  </tr>
  <tr>
    <td><code>oops</code></td>
    <td> Script that shows an OK or oops dialog </td>
  </tr>
  <tr>
    <td><code>preview</code></td>
    <td> Script to preview topic after edit </td>
  </tr>
  <tr>
    <td><code>rdiff</code></td>
    <td> Script to see differences of topics </td>
  </tr>
  <tr>
    <td><code>rename</code></td>
    <td> Script to rename/move topics and move attachments </td>
  </tr>
  <tr>
    <td><code>register</code></td>
    <td> Script to register new users </td>
  </tr>
  <tr>
    <td><code>save</code></td>
    <td> Script that saves a topic, called by preview </td>
  </tr>
  <tr>
    <td><code>search</code></td>
    <td> Script that displays search results </td>
  </tr>
  <tr>
    <td><code>statistics</code></td>
    <td> Script to create statistics topic </td>
  </tr>
  <tr>
    <td><code>testenv</code></td>
    <td> Script to test CGI environment variables </td>
  </tr>
  <tr>
    <td><code>upload</code></td>
    <td> Script that does file upload (<span style="background:"><font color="">File Attachment</font></span><a href="http://LOCATION/FileAttachment">?</a>) </td>
  </tr>
  <tr>
    <td><code>view</code></td>
    <td> Script to view a topic ( <strong>the</strong> script ) </td>
  </tr>
  <tr>
    <td><code>viewfile</code></td>
    <td> Script to view an file attachment </td>
  </tr>
</table>

<a name="LibFiles"></a>

#### <a name="Files_under_twiki_lib_code_"> Files under `twiki/lib` </a>

The new `lib/TWiki/Plugins` directories contain configuration, library and function files, and [[TWikiDocumentation]]. _Full file list:_

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>File:</strong></th>
    <th bgcolor="#99CCCC"><strong>Used for:</strong></th>
  </tr>
  <tr>
    <td><code>TWiki.pm</code></td>
    <td> Main TWiki library </td>
  </tr>
  <tr>
    <td><code>TWiki.cfg</code></td>
    <td> For configuration, used by <code>TWiki.pm</code></td>
  </tr>
  <tr>
    <td><code>TWiki/Access.pm</code></td>
    <td> Access control </td>
  </tr>
  <tr>
    <td><code>TWiki/Attach.pm</code></td>
    <td> Attachment handling </td>
  </tr>
  <tr>
    <td><code>TWiki/Form.pm</code></td>
    <td> Form handling </td>
  </tr>
  <tr>
    <td><code>TWiki/Meta.pm</code></td>
    <td> Meta data in topics </td>
  </tr>
  <tr>
    <td><code>TWiki/Net.pm</code></td>
    <td> SMTP mail handling </td>
  </tr>
  <tr>
    <td><code>TWiki/Plugins.pm</code></td>
    <td> Plugin handling </td>
  </tr>
  <tr>
    <td><code>TWiki/Prefs.pm</code></td>
    <td> Preferences handling </td>
  </tr>
  <tr>
    <td><code>TWiki/Search.pm</code></td>
    <td> Search engine, used by wiki.pm </td>
  </tr>
  <tr>
    <td><code>TWiki/Store.pm</code></td>
    <td> Back-end storage, <code>*.txt</code> text file and <code>*.txt,v</code> RCS repository file handling </td>
  </tr>
  <tr>
    <td><code>TWiki/Plugins/DefaultPlugin.pm</code></td>
    <td> Handles some legacy rules </td>
  </tr>
  <tr>
    <td><code>TWiki/Plugins/EmptyPlugin.pm</code></td>
    <td> Empty plugin, use to create your own </td>
  </tr>
  <tr>
    <td><code>TWiki/Plugins/InterwikiPlugin.pm</code></td>
    <td> Use aliases as links for predefined URLs </td>
  </tr>
</table>

<a name="PubFiles"></a>

#### <a name="Files_under_twiki_pub_code_"> Files under `twiki/pub` </a>

The `pub` directory stores data-related files, including images used by TWiki and [[FileAttachments]]. Attachments are stored in sub-directories created with the related topic name. _Partial file list:_

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>File:</strong></th>
    <th bgcolor="#99CCCC"><strong>Used for:</strong></th>
  </tr>
  <tr>
    <td><code>favicon.ico</code></td>
    <td> ICO file </td>
  </tr>
  <tr>
    <td><code>twikilogo.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>twikilogo1.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>twikilogo2.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>twikilogo3.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>twikilogo4.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>wikiHome.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>icn/_filetypes.txt</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>icn/bat.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>icn/bmp.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <th align="center" bgcolor="#99CCCC"><strong>...</strong></th>
    <th align="center" bgcolor="#99CCCC"><strong>...</strong></th>
  </tr>
  <tr>
    <td><code>TWiki/FileAttachment/Sample.txt</code></td>
    <td> TEXT file </td>
  </tr>
  <tr>
    <td><code>TWiki/FileAttachment/Smile.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>TWiki/PreviewBackground/blankltgraybg.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>TWiki/PreviewBackground/blankwhitebg.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>TWiki/PreviewBackground/previewbg.gif</code></td>
    <td> GIF file </td>
  </tr>
  <tr>
    <td><code>TWiki/WabiSabi/wabisabi.gif</code></td>
    <td> GIF file </td>
  </tr>
</table>

<a name="DataFiles"></a>

#### <a name="Files_under_twiki_data_code_"> Files under `twiki/data` </a>

TWiki page data stored as individual text files. Each active web has its own subdirectory. The TWiki distribution includes four start-up webs - `Main`, `TWiki`, `Know`, `Test` - with documentation and demo content, and a `_default` directory containing all topics required to start a new web. _Partial file list:_

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>File:</strong></th>
    <th bgcolor="#99CCCC"><strong>Used for:</strong></th>
  </tr>
  <tr>
    <td><code>.htpasswd</code></td>
    <td> Basic Authentication (htaccess) password file </td>
  </tr>
  <tr>
    <td><code>debug.txt</code></td>
    <td> Program messages useful for debugging </td>
  </tr>
  <tr>
    <td><code>mime.types</code></td>
    <td> Recognized file formats </td>
  </tr>
  <tr>
    <td><code>warning.txt</code></td>
    <td> Diagnostic messages for identifying problems </td>
  </tr>
  <tr>
    <td colspan="2"> _default directory can be copied to empty directory when creating new Webs </td>
  </tr>
  <tr>
    <td><code>_default/.changes</code></td>
    <td> Web-level record of topic changes </td>
  </tr>
  <tr>
    <td><code>_default/WebChanges.txt</code></td>
    <td> Display most recent topic changes in web </td>
  </tr>
  <tr>
    <td><code>_default/WebChanges.txt,v</code></td>
    <td> Revisions history (RCS) </td>
  </tr>
  <tr>
    <td><code>_default/WebHome.txt</code></td>
    <td> Default web home page </td>
  </tr>
  <tr>
    <td><code>_default/WebHome.txt,v</code></td>
    <td> Revisions history (RCS) </td>
  </tr>
  <tr>
    <td><code>_default/WebIndex.txt</code></td>
    <td> Lists all topics in a web </td>
  </tr>
  <tr>
    <td><code>_default/WebIndex.txt,v</code></td>
    <td> Revisions history (RCS) </td>
  </tr>
  <tr>
    <td><code>_default/WebNotify.txt</code></td>
    <td> Subscribe/unsubscribe to web changes email alert </td>
  </tr>
  <tr>
    <td><code>_default/WebNotify.txt,v</code></td>
    <td> Revisions history (RCS) </td>
  </tr>
  <tr>
    <td><code>_default/WebPreferences.txt</code></td>
    <td> Web-level preference settings </td>
  </tr>
  <tr>
    <td><code>_default/WebPreferences.txt,v</code></td>
    <td> Revisions history (RCS) </td>
  </tr>
  <tr>
    <td><code>_default/WebSearch.txt</code></td>
    <td> Web-level search options </td>
  </tr>
  <tr>
    <td><code>_default/WebSearch.txt,v</code></td>
    <td> Revisions history (RCS) </td>
  </tr>
  <tr>
    <td><code>_default/WebStatistics.txt</code></td>
    <td> Generates web usage statistics </td>
  </tr>
  <tr>
    <td><code>_default/WebStatistics.txt,v</code></td>
    <td> Revisions history (RCS) </td>
  </tr>
  <tr>
    <th align="center" bgcolor="#99CCCC"><strong>...</strong></th>
    <th align="center" bgcolor="#99CCCC"><strong>...</strong></th>
  </tr>
</table>

<a name="TemplatesFiles"></a>

#### <a name="Files_in_twiki_templates_code_"> Files in `twiki/templates` </a>

Templates used to control appearance of all rendered pages. _Full file list:_

<table border="1" cellpadding="1" cellspacing="0">
  <tr>
    <th bgcolor="#99CCCC"><strong>File:</strong></th>
    <th bgcolor="#99CCCC"><strong>Used for:</strong></th>
  </tr>
  <tr>
    <td><code>oopsbadpwformat.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>attachagain.tmpl</code></td>
    <td> Control screen </td>
  </tr>
  <tr>
    <td><code>attachnew.tmpl</code></td>
    <td> Control screen </td>
  </tr>
  <tr>
    <td><code>changeform.tmpl</code></td>
    <td> Control screen </td>
  </tr>
  <tr>
    <td><code>changes.tmpl</code></td>
    <td> Displays <span style="background:"><font color="">Web Changes</font></span><a href="http://LOCATION/WebChanges">?</a> list of recently changed topics </td>
  </tr>
  <tr>
    <td><code>edit.iejs.tmpl</code></td>
    <td> xxxx </td>
  </tr>
  <tr>
    <td><code>edit.tmpl</code></td>
    <td> Main edit window </td>
  </tr>
  <tr>
    <td><code>mailnotify.tmpl</code></td>
    <td> xxxx </td>
  </tr>
  <tr>
    <td><code>moveattachment.tmpl</code></td>
    <td> Control screen </td>
  </tr>
  <tr>
    <td><code>oopsaccesschange.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsaccessgroup.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsaccessrename.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsaccessview.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsauth.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>attach.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopschangepasswd.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsempty.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopslocked.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopslockedrename.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsmissing.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsmoveerr.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsnoformdef.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsnotwikiuser.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsnoweb.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopspreview.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsregexist.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsregpasswd.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsregrequ.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsregthanks.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsregwiki.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsrenameerr.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsresetpasswd.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsrev.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopssave.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopssaveerr.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopssendmailerr.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopstopicexists.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopsupload.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>oopswrongpassword.tmpl</code></td>
    <td> Error message </td>
  </tr>
  <tr>
    <td><code>preview.tmpl</code></td>
    <td> Preview Changes screen </td>
  </tr>
  <tr>
    <td><code>rdiff.tmpl</code></td>
    <td> Displays text changes before &amp;amp; after (Diffs) </td>
  </tr>
  <tr>
    <td><code>register.tmpl</code></td>
    <td> Registration page </td>
  </tr>
  <tr>
    <td><code>registernotify.tmpl</code></td>
    <td> xxxx </td>
  </tr>
  <tr>
    <td><code>rename.tmpl</code></td>
    <td> Doing a new topic rename, user chooses web &amp;amp; topic </td>
  </tr>
  <tr>
    <td><code>renamebase.tmpl</code></td>
    <td> Used by other rename templates </td>
  </tr>
  <tr>
    <td><code>renameconfirm.tmpl</code></td>
    <td> Confirms a pre-specified rename, ex: undoing a rename </td>
  </tr>
  <tr>
    <td><code>renamerefs.tmpl</code></td>
    <td> Rename done, but some references not changed (topics were locked) </td>
  </tr>
  <tr>
    <td><code>search.tmpl</code></td>
    <td> xxxx </td>
  </tr>
  <tr>
    <td><code>searchbookview.tmpl</code></td>
    <td> Search results with full topic content </td>
  </tr>
  <tr>
    <td><code>searchmeta.tmpl</code></td>
    <td> xxxx </td>
  </tr>
  <tr>
    <td><code>searchrenameview.tmpl</code></td>
    <td> Used by <code>rename</code> to list references to topic being renamed </td>
  </tr>
  <tr>
    <td><code>twiki.tmpl</code></td>
    <td> Base template definitions used by other templates </td>
  </tr>
  <tr>
    <td><code>view.plain.tmpl</code></td>
    <td> Alternate topic header/footer view </td>
  </tr>
  <tr>
    <td><code>view.print.tmpl</code></td>
    <td> Alternate topic header/footer view </td>
  </tr>
  <tr>
    <td><code>view.tmpl</code></td>
    <td> Main topic view </td>
  </tr>
</table>

-- [[MikeMannix]] - 29 Aug 2001