Appendix A: TWiki Filesystem

Annotated directory and file listings, for the 01-Dec-2001 TWiki production release.

Who and What is This Good For?

Interested Users and Site Administrators can find out in simple terms what each part of TWiki actually does. Adventurous Adminstrators with server access to files (eg: FTP) can also figure out where to look to make minor modifications, like changing hardcode text or color. Software Developers can get an at-a-glance overview of TWiki code architecture.

Directory Structure

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 five main subdirectories intact:

Directory:	Files:	Used for:
`twiki`	list	Start-up info
`twiki/bin`	list	Perl scripts
`twiki/lib`	list	Configuration file, main library, Perl system modules, Plugins directory
`twiki/pub`	list	Public files (eg: images) and FileAttachments and their RCS histories
`twiki/data`	list	Individual topics (page content) and their RCS histories
`twiki/templates`	list	HTML templates, used by TWiki scripts

File Descriptions

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

Files in `twiki`

Application info and the current reference documentation. Full file list:

File:	Used for:
`index.html`	Links to launch TWiki after install and for files in this directory
`license.txt`	GNU General Public License and TWiki-specific info
`readme.txt`	General TWiki start-up info with relevant URLs
`TWikiDocumentation.html`	All documentation packaged as a single page
`TWikiHistory.html`	TWiki development timeline: versions, features, developers

Files in `twiki/bin`

Perl CGI scripts. Full file list:

File:	Used for:
`.htaccess.txt`	Authentication. Rename to .htaccess and customize if used
`attach`	Shows the attach file page (FileAttachment)
`edit`	Edit a topic
`geturl`	Fetch URL data
`installpasswd`	Install new password by admin
`mailnotify`	Script called by cron job to notify users of changes
`oops`	Shows an OK or oops dialog
`passwd`	Reset and change password
`preview`	Preview topic after edit
`rdiff`	See differences of topics
`register`	Register new users
`rename`	Rename/move topics and move attachments
`save`	Saves a topic, called by preview
`search`	Displays search results
`statistics`	Create statistics topic
`testenv`	Test CGI environment variables
`upload`	Does file upload (FileAttachment)
`view`	View a topic ( the script )
`viewfile`	View a file attachment

Files under `twiki/lib`

The new lib/TWiki/Plugins directories contain configuration, library and function files, and TWikiPlugins. Full file list:

File:	Used for:
`TWiki.cfg`	Main configuration, used by `TWiki.pm`
`TWiki.pm`	Main TWiki library
`TWiki/Access.pm`	Access control
`TWiki/Attach.pm`	Attachment handling
`TWiki/Form.pm`	Form handling
`TWiki/Func.pm`	Public functions that Plugins may use
`TWiki/Meta.pm`	Meta data in topics
`TWiki/Net.pm`	SMTP mail handling
`TWiki/Plugins.pm`	Plugin handling
`TWiki/Prefs.pm`	Preferences handling
`TWiki/Search.pm`	Search engine, used by wiki.pm
`TWiki/Store.pm`	Back-end storage, `.txt` text file and `.txt,v` RCS repository file handling
`TWiki/Store/RcsFile.pm`	Generic file handling code, a class
`TWiki/Store/RcsWrap.pm`	Wrappers around RCS executables, a class that inherits from RcsFile?
`TWiki/Store/RcsLite.pm`	A Perl RCS implemention, a class that inherits from RcsFile?
`TWiki/Plugins/DefaultPlugin.pm`	Handles some legacy rules
`TWiki/Plugins/EmptyPlugin.pm`	Empty plugin, use to create your own
`TWiki/Plugins/InterwikiPlugin.pm`	Use aliases as links for predefined URLs

Files under `twiki/pub`

The pub directory stores topic-related files, including images used by TWiki and FileAttachments. Attachments are stored in subdirectories created with the related topic name. You can also upload files directly for and link manually (but not through Attach) Partial file list:

File:	Used for:
`favicon.ico`	ICO file
`twikilogo.gif`	GIF file
`twikilogo1.gif`	GIF file
`twikilogo2.gif`	GIF file
`twikilogo3.gif`	GIF file
`twikilogo4.gif`	GIF file
`twikilogo88x31`	GIF file
`wikiHome.gif`	GIF file
`icn/_filetypes.txt`	GIF file
`icn/bat.gif`	GIF file
`icn/bmp.gif`	GIF file
...	...
`TWiki/FileAttachment/Sample.txt`	TEXT file: sample
`TWiki/FileAttachment/Smile.gif`	GIF image: sample
`TWiki/PreviewBackground/blankltgraybg.gif`	GIF image
`TWiki/PreviewBackground/blankwhitebg.gif`	GIF image
`TWiki/PreviewBackground/previewbg.gif`	GIF image: Preview view background
`TWiki/WabiSabi/wabisabi.gif`	GIF image: illustration
`Know/IncorrectDllVersionW32PTH10DLL/W32PTH10.DLL`	DLL file: sample

Files under `twiki/data`

TWiki topics: data stored as individual text files and rendered by TWiki for display as regular Web pages. Each active web has its own subdirectory. The TWiki distribution includes four start-up webs - Main, TWiki, Know, Test - with documentation and demo content, a Trash web for browser-based, recoverable topic deletion, and a _default directory containing core topic set required to start a new web. Partial file list:

File:	Used for:
`.htpasswd`	Basic Authentication (htaccess) users file with username and encrypted password pairs
`debug.txt`	Program-generated messages useful for debugging
`mime.types`	Recognized file formats
`warning.txt`	Diagnostic messages for identifying problems
_default directory can be copied to empty directory when creating new webs
`_default/.changes`	Per web record of topic changes
`_default/.mailnotify`	Per web timestamp of most recent email notification
`_default/WebChanges.txt`	Display most recent topic changes in web
`_default/WebChanges.txt,v`	Revisions history (RCS)
`_default/WebHome.txt`	Default web home page
`_default/WebHome.txt,v`	Revisions history (RCS)
`_default/WebIndex.txt`	Lists all topics in a web
`_default/WebIndex.txt,v`	Revisions history (RCS)
`_default/WebNotify.txt`	Subscribe/unsubscribe to web changes email alert
`_default/WebNotify.txt,v`	Revisions history (RCS)
`_default/WebPreferences.txt`	Per web Preference Settings
`_default/WebPreferences.txt,v`	Revisions history (RCS)
`_default/WebSearch.txt`	Per web search options
`_default/WebSearch.txt,v`	Revisions history (RCS)
`_default/WebStatistics.txt`	Generates web usage statistics
`_default/WebStatistics.txt,v`	Revisions history (RCS)
...	...

Files in `twiki/templates`

Templates used to control appearance of topics rendered as Web pages. Full file list:

File:	Used for:
`attach.tmpl`	`Attach` (FileAttachments) control screen
`attachagain.tmpl`	Attachment control screen
`attachnew.tmpl`	Attachment control screen
`changeform.tmpl`	Control screen
`changes.tmpl`	Displays WebChanges links list of recently changed topics
`edit.iejs.tmpl`	Edit window with IE-specific JavaScript
`edit.tmpl`	Main edit window
`mailnotify.tmpl`	Email notification
`moveattachment.tmpl`	Control screen
`oopsaccesschange.tmpl`	Error message
`oopsaccessgroup.tmpl`	Error message
`oopsaccessrename.tmpl`	Error message
`oopsaccessview.tmpl`	Error message
`oopsauth.tmpl`	Error message
`oopsbadpwformat.tmpl`	Error message
`oopschangepasswd.tmpl`	Error message
`oopsempty.tmpl`	Error message
`oopslocked.tmpl`	Error message
`oopslockedrename.tmpl`	Error message
`oopsmissing.tmpl`	Error message
`oopsmore.tmpl`	More topic actions message
`oopsmoveerr.tmpl`	Error message
`oopsnoformdef.tmpl`	Error message
`oopsnotwikiuser.tmpl`	Error message
`oopsnoweb.tmpl`	Error message
`oopspreview.tmpl`	Error message
`oopsregexist.tmpl`	Error message
`oopsregpasswd.tmpl`	Error message
`oopsregrequ.tmpl`	Error message
`oopsregthanks.tmpl`	Error message
`oopsregwiki.tmpl`	Error message
`oopsrenameerr.tmpl`	Error message
`oopsresetpasswd.tmpl`	Error message
`oopsrev.tmpl`	Error message
`oopssave.tmpl`	Error message
`oopssaveerr.tmpl`	Error message
`oopssendmailerr.tmpl`	Error message
`oopstopicexists.tmpl`	Error message
`oopsupload.tmpl`	Error message
`oopswrongpassword.tmpl`	Error message
`preview.tmpl`	Preview Changes screen
`rdiff.tmpl`	Displays text changes before & after `Diffs`
`register.tmpl`	User registration page
`registernotify.tmpl`	Registration notification
`rename.tmpl`	`Rename/move` control screen (choose web & new topic tile
`renamebase.tmpl`	Used by other rename templates
`renameconfirm.tmpl`	Confirms a pre-specified rename, ex: undoing a rename
`renamerefs.tmpl`	Display if rename done, but some references not changed (topics were locked)
`search.tmpl`	Search screen
`searchbookview.tmpl`	Search results with full topic content
`searchmeta.tmpl`	Search screen
`searchrenameview.tmpl`	Used by `rename` to list references to topic being renamed
`twiki.tmpl`	Master template: definitions are used by other templates
`view.plain.tmpl`	Printable topic view with simplified header/footer
`view.print.tmpl`	Printable topic view with no header/footer
`view.tmpl`	Main topic view - the standard regular Web page

TWiki File System Snapshot

The following partial directory listings from a Linux installation show typical file permissions and ownership. This is provided for general debugging use only and isn't an exact representation of the current distribution.

On an ISP installation... The user and group - twiki twiki - will probably be your domain or login name, eg: yourdomain yourdomain and can't be changed; same for nobody nobody files further down. Also, in the bin directory, scripts need a .cgi (sometimes .pl) extension._

Directory twiki/bin:

drwxrwxr-x    2 twiki twiki    4096 Sep 14 22:45 .
drwxrwxr-x    5 twiki twiki    4096 Aug  3 01:57 ..
-rw-rw-r--    1 twiki twiki     895 Aug 25 01:32 .htaccess
-rw-rw-r--    1 twiki twiki     782 Aug 25 01:32 .htaccess.txt
-rw-rwxr-x    1 twiki twiki    4819 Sep  7 01:44 attach
-rwxrwxr-x    1 twiki twiki    3381 Jul 21 18:41 changes
-rw-rwxr-x    1 twiki twiki    8056 Sep  3 22:44 edit
-rwxrwxr-x    1 twiki twiki    1736 Nov 17  2000 geturl
-rwxrwxr-x    1 twiki twiki    4481 Aug 21 19:10 installpasswd
-rwxrwxr-x    1 twiki twiki    5829 Aug 21 22:03 mailnotify
-rwxrwxr-x    1 twiki twiki    4512 Aug 25 22:10 makedistrib
-rw-rwxr-x    1 twiki twiki    2254 Aug 21 19:25 oops
-rwxrwxr-x    1 twiki twiki    6399 Aug 22 18:31 passwd
-rw-rwxr-x    1 twiki twiki    5315 Sep  3 22:45 preview
-rwxrwxr-x    1 twiki twiki    8946 Sep  8 18:35 rdiff
-rw-rwxr-x    1 twiki twiki    9199 Aug 25 21:02 register
-rwxrwxr-x    1 twiki twiki   13481 Sep  7 21:17 rename
-rw-rwxr-x    1 twiki twiki    4645 Sep  7 01:44 save
-rwxrwxr-x    1 twiki twiki    4166 Jul 21 18:45 search
-rw-rwxr-x    1 twiki twiki   10006 Sep  7 01:42 statistics
-rwxrwxr-x    1 twiki twiki    9356 Aug 31 10:04 testenv
-rw-rwxr-x    1 twiki twiki   13782 Aug 21 22:17 upload
-rwxrwxr-x    1 twiki twiki   10164 Sep  8 18:24 view
-rw-rwxr-x    1 twiki twiki    2773 Sep 13 17:21 viewfile

Directory twiki/templates/:

drwxrwxr-x    2 twiki twiki    4096 Sep  8 00:47 .
drwxrwxr-x    4 twiki twiki    4096 Sep 10 23:21 ..
-rw-rw-r--    1 twiki twiki    2573 Aug 31 13:06 attach.tmpl
-rw-rw-r--    1 twiki twiki    1604 Aug  3 14:52 attachagain.tmpl
-rw-rw-r--    1 twiki twiki     449 Aug  3 14:47 attachnew.tmpl
-rw-rw-r--    1 twiki twiki    1309 Sep  3 22:47 changeform.tmpl
-rw-rw-r--    1 twiki twiki    1619 Aug 31 13:16 changes.tmpl
-rw-rw-r--    1 twiki twiki   11842 Sep 10 19:00 edit.iejs.tmpl
-rw-rw-r--    1 twiki twiki    2603 Sep  3 22:48 edit.tmpl
-rw-rw-r--    1 twiki twiki     981 May 28 20:14 mailnotify.tmpl
-rw-rw-r--    1 twiki twiki    1499 Aug 31 13:16 moveattachment.tmpl
-rw-rw-r--    1 twiki twiki     570 Aug  1 01:24 oopsaccesschange.tmpl
-rw-rw-r--    1 twiki twiki     586 Aug  1 01:24 oopsaccessgroup.tmpl
-rw-rw-r--    1 twiki twiki     573 Aug  1 01:47 oopsaccessrename.tmpl
-rw-rw-r--    1 twiki twiki     573 Aug  1 01:24 oopsaccessview.tmpl
-rw-rw-r--    1 twiki twiki    1014 Aug  1 01:25 oopsauth.tmpl
-rw-rw-r--    1 twiki twiki     405 Aug  1 01:49 oopsbadpwformat.tmpl
-rw-rw-r--    1 twiki twiki     344 Jul 31 10:16 oopschangepasswd.tmpl
-rw-rw-r--    1 twiki twiki     624 Jul 31 02:09 oopsempty.tmpl
-rw-rw-r--    1 twiki twiki     918 Jul 31 02:20 oopslocked.tmpl
-rw-rw-r--    1 twiki twiki     590 Jul 31 10:25 oopslockedrename.tmpl
-rw-rw-r--    1 twiki twiki     328 Jul 31 10:26 oopsmissing.tmpl
-rw-rw-r--    1 twiki twiki    2158 Sep 13 02:03 oopsmore.tmpl
-rw-rw-r--    1 twiki twiki     407 Aug  1 10:22 oopsmoveerr.tmpl
-rw-rw-r--    1 twiki twiki    1136 Aug  1 01:30 oopsnoformdef.tmpl
-rw-rw-r--    1 twiki twiki     522 Aug  1 01:31 oopsnotwikiuser.tmpl
-rw-rw-r--    1 twiki twiki     413 Jul 31 02:07 oopsnoweb.tmpl
-rw-rw-r--    1 twiki twiki     393 Aug  1 01:32 oopspreview.tmpl
-rw-rw-r--    1 twiki twiki     462 Aug  1 01:32 oopsregexist.tmpl
-rw-rw-r--    1 twiki twiki     345 Aug  1 00:52 oopsregpasswd.tmpl
-rw-rw-r--    1 twiki twiki     356 Aug  1 00:53 oopsregrequ.tmpl
-rw-rw-r--    1 twiki twiki     540 Aug  1 01:57 oopsregthanks.tmpl
-rw-rw-r--    1 twiki twiki     679 Aug  1 01:02 oopsregwiki.tmpl
-rw-rw-r--    1 twiki twiki     411 Aug  1 10:23 oopsrenameerr.tmpl
-rw-rw-r--    1 twiki twiki     483 Aug  1 01:59 oopsresetpasswd.tmpl
-rw-rw-r--    1 twiki twiki     921 Sep  7 23:47 oopsrev.tmpl
-rw-rw-r--    1 twiki twiki     774 Aug  1 01:35 oopssave.tmpl
-rw-rw-r--    1 twiki twiki     477 Aug  1 02:01 oopssaveerr.tmpl
-rw-rw-r--    1 twiki twiki     452 Aug  1 01:37 oopssendmailerr.tmpl
-rw-rw-r--    1 twiki twiki     379 Aug  1 10:23 oopstopicexists.tmpl
-rw-rw-r--    1 twiki twiki     342 Jul 31 10:09 oopsupload.tmpl
-rw-rw-r--    1 twiki twiki     364 Aug  1 02:05 oopswrongpassword.tmpl
-rw-rw-r--    1 twiki twiki    2584 Sep  3 22:49 preview.tmpl
-rw-rw-r--    1 twiki twiki    1539 Sep  8 18:29 rdiff.tmpl
-rw-rw-r--    1 twiki twiki     552 Jul 14 19:23 register.tmpl
-rw-rw-r--    1 twiki twiki    1151 Aug 23 16:38 registernotify.tmpl
-rw-rw-r--    1 twiki twiki     789 Aug  8 23:32 rename.tmpl
-rw-rw-r--    1 twiki twiki    2310 Sep 10 14:56 renamebase.tmpl
-rw-rw-r--    1 twiki twiki     475 Aug  3 16:53 renameconfirm.tmpl
-rw-rw-r--    1 twiki twiki     589 Aug  8 23:32 renamerefs.tmpl
-rw-rw-r--    1 twiki twiki    1792 Aug 31 18:38 search.tmpl
-rw-rw-r--    1 twiki twiki    1650 Aug 31 18:38 searchbookview.tmpl
-rw-rw-r--    1 twiki twiki     149 Sep 13 02:00 searchmeta.tmpl
-rw-rw-r--    1 twiki twiki    2044 Aug 31 18:38 searchrenameview.tmpl
-rw-rw-r--    1 twiki twiki    2246 Aug 31 13:08 twiki.tmpl
-rw-rw-r--    1 twiki twiki     418 Aug 31 13:07 view.plain.tmpl
-rw-rw-r--    1 twiki twiki     826 Aug 31 13:08 view.print.tmpl
-rw-rw-r--    1 twiki twiki    1770 Sep  8 00:32 view.tmpl

Directory twiki/data/:

drwxrwxr-x    8 nobody nobody  4096 Sep  7 01:04 .
drwxrwxr-x    4 nobody nobody  4096 Sep 10 23:21 ..
-rw-rw-rw-    1 twiki  twiki    159 Aug 24 19:49 .htpasswd
drwxrwxr-x    2 nobody nobody  4096 Sep  9 02:45 Know
drwxrwxr-x    2 nobody nobody  4096 Sep  9 02:45 Main
drwxrwxr-x    2 nobody nobody  8192 Sep 14 23:22 TWiki
drwxrwxr-x    2 nobody nobody  4096 Sep  9 02:45 Test
drwxrwxr-x    2 nobody nobody  4096 Sep 14 12:04 Trash
drwxrwxr-x    2 nobody nobody  4096 Sep  9 02:45 _default
-rw-rw-rw--   1 twiki  twiki      0 Jul  1 02:20 debug.txt
-rw-rw-r--    1 twiki  twiki    3419 Aug 13 00:15 mime.types
-rw-rw-rw--   1 twiki  twiki      0 Jul  1 02:19 warning.txt

Partial file list for twiki/data/Main:

Included files come with their RCS versions histories .txt,v. If you don't need the changes history of each one, you can delete them and save a lot of space. New RCS files will be created automatically, only when a topic is next edited.

drwxrwxrwx   2 nobody  nobody  4096 Aug 19 04:15 .
drwxrwxrwx   6 nobody  nobody  4096 Aug  3 01:09 ..
-rw-rw-rw-   1 twiki twiki     3716 Aug 19 02:19 .changes
-rw-rw-rw-   1 twiki twiki        9 Aug 19 02:45 .mailnotify
-rw-r--r--   1 nobody  nobody   358 Aug 18 17:22 OfficeLocations.txt
-r--r--r--   1 nobody  nobody   878 Aug 18 17:22 OfficeLocations.txt,v
-rw-r--r--   1 nobody  nobody   680 Aug 18 17:36 TWikiGuest.txt
-r--r--r--   1 nobody  nobody  1989 Aug 18 17:36 TWikiGuest.txt,v
-rw-r--r--   1 nobody  nobody   459 Aug 18 17:19 TWikiUsers.txt
-r--r--r--   1 nobody  nobody  3840 Aug 18 17:19 TWikiUsers.txt,v
-rw-r--r--   1 nobody  nobody    95 Aug 19 03:06 WebChanges.txt
-r--r--r--   1 nobody  nobody   284 Aug 19 03:06 WebChanges.txt,v
-rw-r--r--   1 nobody  nobody  1853 Aug 18 18:08 WebHome.txt
-r--r--r--   1 nobody  nobody  6523 Aug 18 18:08 WebHome.txt,v

Directory twiki/pub/:

drwxrwxrwx   6 nobody  nobody  4096 Aug  3 01:21 .
drwxrwxr-x   3 twiki   twiki   4096 Jun 17 16:35 ..
drwxrwxrwx   3 nobody  nobody  4096 Jun 17 16:35 Know
drwxrwxrwx   3 nobody  nobody  4096 Aug  3 01:21 TWiki
-rw-rw-r--   1 twiki   twiki   1078 Jan 14  2000 favicon.ico
drwxrwxr-x   2 twiki   twiki   4096 Jun 17 16:35 icn
-rw-rw-r--   1 twiki   twiki   3016 Oct  5  1999 twikilogo.gif
-rw-rw-r--   1 twiki   twiki   5320 Oct  5  1999 twikilogo1.gif
-rw-rw-r--   1 twiki   twiki   6125 Oct  5  1999 twikilogo2.gif
-rw-rw-r--   1 twiki   twiki   7218 Oct  5  1999 twikilogo3.gif
-rw-rw-r--   1 twiki   twiki   6710 Oct  5  1999 twikilogo4.gif
-rw-rw-r--   1 twiki   twiki   3501 Sep 14 11:57 twikilogo88x31.gif
-rw-rw-r--   1 twiki   twiki   2877 Jun  7  1999 wikiHome.gif

Partial file list for twiki/pub/icn/:

drwxrwxr-x   2 twiki   twiki   4096 Jun 17 16:35 .
drwxrwxrwx   6 nobody  nobody  4096 Aug  3 01:21 ..
-rw-rw-r--   1 twiki   twiki    801 Mar 26  1999 _filetypes.txt
-rw-rw-r--   1 twiki   twiki    143 Mar  9  1999 bat.gif
-rw-rw-r--   1 twiki   twiki    926 Mar  9  1999 bmp.gif
-rw-rw-r--   1 twiki   twiki    141 Mar 25  1999 c.gif
-rw-rw-r--   1 twiki   twiki    144 Mar  9  1999 dll.gif
-rw-rw-r--   1 twiki   twiki    152 Mar  9  1999 doc.gif

-- PeterThoeny - 14 Sep 2001
-- MikeMannix - 16 May 2002

----- Revision r1.9 - 31 May 2002 - 06:19 GMT - PeterThoeny