Documentation of the TWiki Implementation

• (1) Login Username vs. Wiki Username
• (2) Wiki Variables
• (3) Notification of Changes by Email
• (4) TWiki Category Table
• (5) Implementation Notes
• (6) Installation Notes

Related Topics: TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests.

• Login username: When you login to the Intranet you use your login username, e.g. thoeny. TWiki uses this name internally to log who changed topics.
• Wiki username: Is your name in WikiNotation, e.g. PeterThoeny. When you create your own home page topic, you should use your WikiName for the topic name. Like that, your name will be linked automatically where ever it is used. Please create your home page in TWiki.Main, not any other TWiki web.

Note: When you write a WikiName of a user (your own or somebody else's) be sure to specify the Main web in front of the Wiki user name, e.g. write it as Main.wikiUsername. This assures that the name will be linked automatically to the TWiki.Main web, even if the text is written in a different Wiki web.

TWiki can map the Intranet username to the Wiki username automatically, provided that the Login username and Wiki username pair has been entered in the TWikiUsers topic.

TWiki Variables

Special text strings expand on the fly to display dynamic content, such as user data or system info

TWikiVariables are text strings - %VARIABLE% or %VARIABLE{ parameter="value" }% - that expand into content whenever a topic is rendered for viewing. There are two types of variables:

1. Preferences variables: Can be defined and changed by the user.
   Example: %T% renders as
2. Predefined variables: Defined by the TWiki system or by extensions.
   Example: %CALCULATE{}% is handled by the SpreadSheetPlugin

See list of all TWiki Variables currently defined in this TWiki installation.

TWiki Variables Wizard — to Find and Compose Variables

Categories: all Administration Applications & Components Attachments & Files Charting & Drawing Database & Forms Date & Time Development Editing & Content Update Email & Notification Export & Publishing Formatting & Rendering Import Linking & Navigation Searching & Listing Security & Access Control Skins & Templates System Information Tables & Spreadsheets UI& Visualization Users & Authentication Workflow & Automation

Variables:

Pre-load image:

Using Variables

To use a variable type its name. For example,

• type %T% to get (a preferences variable)
• type %TOPIC% to get TWikiVariables (a predefined variable)
• type %CALCULATE{ "$UPPER(Text)" }% to get TEXT (a variable defined by a plugin)

Note:

• To leave a variable unexpanded, precede it with an exclamation point, e.g. type !%TOPIC% to get %TOPIC%
• Variables are expanded relative to the topic they are used in, not the topic they are defined in
• Type %ALLVARIABLES% to get a full listing of all variables defined for a particular topic

Variable Names

Variable names must start with a letter, optionally followed by letters, numbers and underscore '_' characters. Both upper-case and lower-case characters can be used, %MYVAR%, %MyVar%, %My2ndVar%, and %My_Var% are valid names. Variables are case sensitive, e.g. %MyVAR% and %MYVAR% are not the same.

By convention all settings, predefined variables and variables handled by extensions are always UPPER-CASE.

Preferences Variables

Unlike predefined variables, preferences variables can be defined by the user in various places.

Setting Preferences Variables

You can set variables in all the following places:

1. system level in TWiki.TWikiPreferences
2. plugin topics (see TWikiPlugins)
3. local site level in Main.TWikiPreferences
4. user level in individual user topics in Main web
   • If UserSubwebs is in effect, the topic specified by %USERPREFSTOPIC% in the user's subweb is read instead
   • If $TWiki::cfg{DemoteUserPreferences} is true, this step is deferred to a later step. On this TWiki installation, $TWiki::cfg{DemoteUserPreferences} is false
5. web level in WebPreferences of each web
6. If EXTRAPREFERENCES is defined at this point, it's regarded as having comma separated list of topics. Those topics are read in the listed order as if they were WebPreferences
7. topic level in topics in webs
8. session variables (if sessions are enabled)
9. user level preferences are set at this point if $TWiki::cfg{DemoteUserPreferences} is true as mentioned at the step 4

Settings at higher-numbered levels override settings of the same variable at lower numbered levels, unless the variable was included in the setting of FINALPREFERENCES at a lower-numbered level, in which case it is locked at the value it has at that level.

If you are setting a variable and using it in the same topic, note that TWiki reads all the variable settings from the saved version of the topic before it displays anything. This means you can use a variable anywhere in the topic, even if you set it somewhere inconspicuous near the end. But beware: it also means that if you change the setting of a variable you are using in the same topic, preview will show the wrong thing, and you must save the topic to see it correctly.

The syntax for setting variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets):
[multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [space] value

Examples:

   * Set VARIABLENAME1 = value
      * Set VARIABLENAME2 = value

Spaces between the = sign and the value will be ignored. You can split a value over several lines by indenting following lines with spaces - as long as you don't try to use * as the first character on the following line.

Example:

   * Set VARIABLENAME = value starts here
     and continues here

Whatever you include in your variable will be expanded on display, exactly as if it had been entered directly.

Example: Create a custom logo variable

• To place a logo anywhere in a web by typing %MYLOGO%, define the Variable on the web's WebPreferences topic, and upload a logo file, ex: mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, e.g. LogoTopic. Sample variable setting in WebPreferences:

      * Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gif

You can also set preferences variables on a topic by clicking the link Edit topic preference settings under More topic actions. Use the same * Set VARIABLENAME = value syntax. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.

Controlling User Level Preferences Override

By default, user level variables are set at the step 4 as stated in the previous section. That means a user can finalise some preferences variables so that web level or topic level setting cannot override it. This may result in a situation the web or page owner doesn't expect. $TWiki::cfg{DemoteUserPreferences} has been introduced to avoid it. If it's set to true, user level variables are set at the last step instead of the step 4.

But this is not enough. To guarantee a certain result, you need to finalise critical preferences variables set at the web or topic level, which is cumbersome. So preferences variables DENYUSERPREFEENCES and ALLOWUSERPREFERENCES have been introduced.

• DENYUSERPREFEENCES and ALLOWUSERPREFERENCES may have comma separated list of variable names
• If a preferences variable is listed in DENYUSERPREFEENCES, the variable cannot be overridden at the user level. There is a special value "all", which means no preferences variables can be overridden at the user level
• If ALLOWUSERPREFERENCES is set and not empty, only the listed preferences variables can be overridden. There is a special value "all", which means any preferences variable can be overridden at the user level. But actually, "all" is not necessary since a blank value or not setting ALLOWUSERPREFERENCES has the same effect
• DENYUSERPREFEENCES takes precedence over ALLOWUSERPREFERENCES. If a variable is listed on both, it cannot be overridden. If DENYUSERPREFEENCES is "all", the value of ALLOWUSERPREFERENCES doesn't matter.

   * Set DENYUSERPREFERENCES = all

   * Set ALLOWUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKIN

   * Set DENYUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKIN

You will get the most benefit of DENYUSERPREFEENCES and ALLOWUSERPREFERENCES by setting $TWiki::cfg{DemoteUserPreferences} to true. That way, each web can specify how much user level preferences overriding is allowed.

Parameterized Variables (Macros)

It is possible to pass parameters to TWiki variables. This is called a macro in a programming language.

To define a parameterized variable, set a variable that contains other variables, such as:

   * Set EXAMPLE = Example variable using %DEFAULT%, %PARAM1% and %PARAM2%
   * Set DEMO = Demo using %DEFAULT{ default="(undefined)" }%,
                %PARAM1{ default="(undefined)" }% and %PARAM2{ default="(undefined)" }%

A special %DEFAULT% variable denotes the default (nameless) parameter of the calling variable. Variables optionally may list a default="..." parameter that gets used in case the calling variable does not specify that parameter.

To use a parameterized variable (or call a macro), add parameters within the curly brackets, such as:

   * %EXAMPLE{ "foo" PARAM1="bar" PARAM2="baz" }%
   * %DEMO{ "demo" PARAM2="parameter 2" }% -- note that PARAM1 is missing

• %EXAMPLE{ "foo" PARAM1="bar" PARAM2="baz" }%
• %DEMO{ "demo" PARAM2="parameter 2" }% -- note that PARAM1 is missing

Parameters in the variable definition are expanded using the following sequence:

1. Parameter from variable call. In above example, %PARAM1% gets expanded to bar.
2. Session variable and preferences settings

Example

Define variables:

   * Set DRINK = red wine
   * Set FAVORITE = My %DEFAULT{default="favorite"}% dish is %DISH{default="steak"}%,
                    my %DEFAULT{default="favorite"}% drink is %DRINK%.

Use Variables:

%FAVORITE{ DISH="Sushi" DRINK="Sake" }%

%FAVORITE{}%

%FAVORITE{ "preferred" }%

Access Control Variables

These are special types of preferences variables to control access to content. TWikiAccessControl explains these security settings in detail.

Local values for variables

Certain topics (a users home topic, web site and default preferences topics) have a problem; variables defined in those topics can have two meanings. For example, consider a user topic. A user may want to use a double-height edit box when they are editing their home topic - but only when editing their home topic. The rest of the time, they want to have a normal edit box. This separation is achieved using Local in place of Set in the variable definition. For example, if the user sets the following in their home topic:

   * Set EDITBOXHEIGHT = 10
   * Local EDITBOXHEIGHT = 20

Use this powerful feature with great care! %ALLVARIABLES% can be used to get a listing of the values of all variables in their evaluation order, so you can see variable scope if you get confused.

Frequently Used Preferences Variables

The following preferences variables are frequently used. They are defined in TWikiPreferences#Miscellaneous_Settings:

• %BB% - line break and bullet combined
• %BB2% - level 2 bullet with line break
• %BB3% - level 3 bullet with line break
• %BB4% - level 4 bullet with line break
• %BR% - line break
• %BULLET% - bullet sign
• %CARET% - caret symbol
• %VBAR% - vertical bar
• %H% - Help icon
• %I% - Idea icon
• %M% - Moved to icon
• %N% - New icon
• %P% - Refactor icon
• %Q% - Question icon
• %S% - Pick icon
• %T% - Tip icon
• %U% - Updated icon
• %X% - Alert icon
• %Y% - Done icon
• %RED% text %ENDCOLOR% - colored text (also %YELLOW%, %ORANGE%, %PINK%, %PURPLE%, %TEAL%, %NAVY%, %BLUE%, %AQUA%, %LIME%, %GREEN%, %OLIVE%, %MAROON%, %BROWN%, %BLACK%, %GRAY%, %SILVER%, %WHITE%)
• %REDBG% text %ENDBG% - colored background (also %YELLOWBG%, %ORANGEBG%, %PINKBG%, %PURPLEBG%, %TEALBG%, %NAVYBG%, %BLUEBG%, %AQUABG%, %LIMEBG%, %GREENBG%, %OLIVEBG%, %MAROONBG%, %BROWNBG%, %BLACKBG%, %GRAYBG%, %SILVERBG%, %WHITEBG%)

There are additional useful preferences variables defined in TWikiPreferences, in Main.TWikiPreferences, and in WebPreferences of every web.

Predefined Variables

Most predefined variables return values that were either set in the configuration when TWiki was installed, or taken from server info (such as current username, or date and time). Some, like %SEARCH%, are powerful and general tools.

• Show all TWiki Variables
• Predefined variables can be overridden by preferences variables (except a few such as TOPIC and WEB)
  • This has long been the case but may not be desirable since even something as fundamental as %IF{...}%, %SCRIPT{...}%, and %INCLUDE{...}% can be overridden
  • So TWiki-6.0.1 has introduced a way to protect predefined variables from being overridden by preferences variables
  • The preferences variable OVERRIDABLEPREDEFINEDVARIABLES having a comma separated list of predefined variables specifies which predefined variables are overridable
  • By default, it's set to "all" (set at TWiki.TWikiPreferences), which means any predefined variable can be overridden, which is for compatibility with prior releases. You can set it to a different value in Main.TWikiPreferences and you may finalise it
  • If it's set as below, all predefined variables are protected

       * Set OVERRIDABLEPREDEFINEDVARIABLES =
    

  • If it's set as below, DATE and LANGUAGE predefined variables can be overridden but all the other predefined variables cannot

       * Set OVERRIDABLEPREDEFINEDVARIABLES = DATE, LANGUAGE
    

• Extensions may extend the set of predefined variables (see individual extension topics for details)
• Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see %INCLUDINGTOPIC%, %INCLUDE%, and the mighty %SEARCH%.

Search or List Variables by Category

All TWiki Variables: ACTIVATEDPLUGINS, ADDTOHEAD, ALLVARIABLES, AQUA, ATTACHURL, ATTACHURLPATH, AUTHREALM, BASETOPIC, BASEWEB, BB, BB2, BB3, BB4, BLACK, BLUE, BR, BROWN, BUBBLESIG, BULLET, CALC, CALCULATE, CARET, CHILDREN, COLORPICKER, COMMENT, CONTENTMODE, COPY, DASHBOARD, DATE, DATEPICKER, DISPLAYTIME, DISPLAYTIME2, EDITACTION, EDITFORM, EDITFORMFIELD, EDITTABLE, ENCODE, ENDBG, ENDCOLOR, ENDCOLUMNS, ENDSECTION, ENTITY, ENV, EXAMPLEVAR, FAILEDPLUGINS, FORM, FORMFIELD, FOURCOLUMNS, GET, GMTIME, GMTIME2, GRAY, GREEN, GROUPS, H, HEADLINES, HIDE, HIDEINPRINT, HOMETOPIC, HTTP, HTTPHOST, HTTPS, I, ICON, ICONURL, ICONURLPATH, IF, INCLUDE, INCLUDINGTOPIC, INCLUDINGWEB, JQENDTAB, JQENDTABPANE, JQTAB, JQTABPANE, LANGUAGE, LANGUAGES, LAQUO, LIME, LOCALSITEPREFS, LOGIN, LOGINURL, LOGOUT, LOGOUTURL, M, MAINWEB, MAKETEXT, MAROON, MDREPO, META, METASEARCH, N, NAVY, NBSP, NOP, NOTIFYTOPIC, OLIVE, ORANGE, P, PARENTBC, PARENTTOPIC, PINK, PLUGINDESCRIPTIONS, PLUGINVERSION, PUBURL, PUBURLPATH, PURPLE, Q, QUERYPARAMS, QUERYSTRING, RAQUO, RED, REDBG, REG, REMOTEADDR, REMOTEPORT, REMOTEUSER, RENDERLIST, REVINFO, REVINFO2, S, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURL, SCRIPTURL2, SCRIPTURLPATH, SCRIPTURLPATH2, SEARCH, SERVERTIME, SERVERTIME2, SESSIONID, SESSIONVAR, SESSIONVARIABLE, SET, SETGETDUMP, SILVER, SITENAME, SITESTATISTICSTOPIC, SLIDESHOWEND, SLIDESHOWSTART, SPACEDTOPIC, SPACEOUT, STARTINCLUDE, STARTSECTION, STATISTICSTOPIC, STOPINCLUDE, SYSTEMWEB, T, TABLE, TEAL, THREECOLUMNS, TM, TOC, TOC2, TOPIC, TOPICLIST, TOPICTITLE, TOPICURL, TWIKISHEET, TWIKIWEB, TWISTY, TWOCOLUMNS, U, URLPARAM, USERINFO, USERNAME, USERREPORT, USERSIG, USERSWEB, VAR, VBAR, WEB, WEBLIST, WEBPREFSTOPIC, WHITE, WIKIHOMEURL, WIKILOGOALT, WIKILOGOIMG, WIKILOGOURL, WIKINAME, WIKIPREFSTOPIC, WIKITOOLNAME, WIKIUSERNAME, WIKIUSERSTOPIC, WIKIVERSION, WIKIWEBMASTER, WIKIWEBMASTERNAME, WIP, X, Y, YELLOW, total 190 variables

Documenting TWiki Variables

This section is for people documenting TWiki variables of the TWiki core and TWiki extensions.

Each variable is documented in a topic named Var<name> in the TWiki web. For example, a %LIGHTSABER% variable has a documentation topic called VarLIGHTSABER. The topic is expected to have a specific format so that reports in this TWikiVariables topic, in TWikiVariablesSearch and in category topics work as expected.

Basic structure of a variable documentation topic:

• Parent set to TWikiVariables
• An anchor named the same like the topic, such as #VarLIGHTSABER
• A ---+++ (level 3) heading with variable name, --, short description
• A bullet with description of the variable (optional)
• A Syntax: bullet with example syntax
• A Parameters: bullet with a table explaining the parameters (optional)
• An Example: bullet or two with examples
• An Expands to: bullet with expanded variable (optional)
• A Note: bullet with notes (optional)
• A Category: bullet with one or more of the TWiki variables categories:
  AdministrationVariables, ApplicationsAndComponentsVariables, AttachmentsAndFilesVariables, ChartingAndDrawingVariables, DatabaseAndFormsVariables, DateAndTimeVariables, DevelopmentVariables, EditingAndContentUpdateVariables, EmailAndNotificationVariables, ExportAndPublishingVariables, FormattingAndRenderingVariables, ImportVariables, LinkingAndNavigationVariables, SearchingAndListingVariables, SecurityAndAccessControlVariables, SkinsAndTemplatesVariables, SystemInformationVariables, TablesAndSpreadsheetsVariables, UIAndVisualizationVariables, UsersAndAuthenticationVariables, WorkflowAndAutomationVariables
• A Related: bullet with related links. Links have conditional IF so that links work properly locally in variable documentation topics and in the TWikiVariables topic

Example content of a VarLIGHTSABER topic:

#VarLIGHTSABER
---+++ LIGHTSABER -- laser sword to fend of unethical competition
   * The =%<nop>LIGHTSABER{}%= variable is handled by the LightsaberPlugin.
   * Syntax: =%<nop>LIGHTSABER{ _parameters_ }%=
   * Parameters:
     | *Parameter* | *Description* | *Default* |
     | =color="..."= | Color: =red=, =glue=, =green= | =white= |
     | =sound="..."= | Sound: =none=, =standard=, =loud= | =none= |
   * Example: =%<nop>LIGHTSABER{ color="red" }%= shows a red Lightsaber
   * Expands to: =%LIGHTSABER{ color="red" }%=
   * Note: The Lightsaber is a fictional weapon in the Star Wars universe, a "laser sword."
   * Category: FormattingAndRenderingVariables, UIAndVisualizationVariables
   * Related: [[%IF{"'%INCLUDINGTOPIC%'='TWikiVariables'" then="#"}%VarPLASMA][PLASMA]], LightsaberPlugin

Each TWiki web does an automatic email notification of recent changes. Users can subscribe / unsubscribe themselves in WebNotify of each TWiki web. The Perl script mailnotify is called by a deamon once every 60 minutes. For each Twiki web mailnotify is sending an automated email to subscribed users in case some topics changed within these 60 minutes.

Implementation note: Edit the cron table so that mailnotify is called every 60 minutes. Please consult man crontab of how to modify the table that schedules program execution at certain intervals. Example:

% crontab -e
15,45 * * * * (cd ~twiki/public_html/bin; ./mailnotify)

select|{name}|{selSize}|{val1}|{val2}|{val3}...
checkbox|{name}|{checkFlag}|{itemsPerLine}|{val1}|{val2}|{val3}...
radio|{name}|{itemsPerLine}|{val1}|{val2}|{val3}...
text|{name}|{charSize}
# comments start with a # character

  {name}				 name of tag
  {selSize}			 vertical size of SELECT tag
  {val1}|{val2}...	values
  {checkFlag}		  set to true for [Set] [Clear] buttons, else set to false
  {itemsPerLine}	  input items per line before wrap around, 0 if no wrap around
  {charSize}			number of characters for text fields

radio|UseCategory|0|Yes|No, delete this category table
select|TopicClassification|1|Select one...|NoDisclosure|PublicSupported|PublicFAQ
checkbox|OperatingSystem|true|5|OsSolaris|OsSunOS|OsHPUX|OsWin
text|OsVersion|16

<!--TWikiCat--> <h4> TWikiCategory </h4>
<table border="2" cellspacing="1" cellpadding="1">
%REPEAT%<tr>
<td valign="top" align="right"> %CATNAME%:  <br>%CATMODIFIER%</td><td>  %CATVALUE% </td>
</tr>%REPEAT%
</table><!--TWikiCat-->

TWikiCategory

Above template files will result in the following table when _editing_ a topic:

Note: It is possible to force the values of a category table when creating a new topic. This is useful to create new topics using a form for the topic name. The default values of the category table can be specified as hidden fields if needed, i.e. <input type="hidden" name="someCategory" value="someValue">

Example (edit this page to see the source) :

• New PublicFAQ topic:

• Request the TWiki distribution (in Unix ZIP format) from http://www.mindspring.com/~peterthoeny/twiki/ .
• Create directory /home/httpd/twiki and unzip the TWiki distribution to this directory.
• The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to /etc/httpd/conf/access.conf with only ExecCGI option.
• The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki/pub to /etc/httpd/conf/access.conf with normal access options (copy from /home/httpd/html).
• Now add Alias for /twiki/pub and ScriptAlias for /twiki/bin to /etc/httpd/conf/srm-conf .
• Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
• Make sure PERL and the PERL CGI library is installed on your system. Default location of PERL executable is /usr/bin/perl . In case PERL is installed in a different location, the first line of all perl scripts in the twiki/bin directory need to be changed (alternatively you can create a symbolic link from /usr/bin/perl ).
• Test if the twiki/bin directory is cgi-enabled:
  • Enter the URL of that directory into your browser ( http://your.domain.com/twiki/bin ). It is not set correctly as cgi-bin in case you get something like "Index of /twiki/bin" . It is OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server."
  • Execute the testenv script from your browser ( http://your.domain.com/twiki/bin/testenv ). It should show a table of all CGI environment variables.
• On systems where the Perl scripts require a file extension you need to:
  • Rename all scripts in the twiki/bin directory to have a file extension, i.e. rename view to view.cgi .
  • Specify this file extension in the $scriptSuffix variable in twiki/bin/wikicfg.pm .
• To be able to edit the perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
• The scripts execute as nobody . Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rw-r-xr-x .
• Set the file permission of all files below twiki/data to 666 ( -rw-rw-rw- ).
• Set the file permission of the twiki/data directory and all its subdirectories to 777 ( drwxrwxrwx ).
• Set the file permission of the twiki/pub directory to 777 ( drwxrwxrwx ).
• Edit the file twiki/bin/wikicfg.pm and set the variables at the beginning of the file to your needs.
• Make sure RCS is installed. In case RCS is not in the path environment variable, add it to path . Alternatively, add the full path name to the rcs, ci, co, rlog, rcsdiff commands in the variables of twiki/bin/wikicfg.pm .
• Point your browser at http://your.domain.com/twiki/bin/view and start wiki-ing away!
• Note in case cgi user is not nobody : The *,v RCS repository files delivered with the installation package are locked by user nobody . In case the user is different (e.g. www-data ), it is not possible to check in files, this has the effect that the topic version number does not increase when saving a topic. In this case you need to unlock all repository files and lock them as user www-data , or simply delete all the repository files.
• Security issue: Directories twiki/data , twiki/templates and all its subdirectories should be set so that they are not visible as a URL. (Alternatively, move the directries to a place where they are not visible, and change the variables in twiki/bin/wikicfg.pm accordingly)

• Optional: You can add new rendering rules or new %variables%. To insure an easy upgrade of TWiki it is recommended to do this customization in twiki/bin/wikicfg.pm , not twiki/bin/wiki.pm .

• Optional: If you are on a public server and you would like to authenticate users you need to rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details consult the HTTP server documentation (for Apache server: [1], [2], [3]). Note: In case .htaccess does not have any effect you need to enable it: Add "AllowOverride All" to the Directory section of access.conf for your twiki/bin directory.

• Optional: You can automatically generate usage statistics for all webs. To enable this:
  • Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in wikicfg.pm are set. This will generate log entries in file twiki/data/log<date>.txt .
  • Topic WebStatistics must be present in all webs where you want to have statistics. You can use the topic in the Main web as a template.
  • Call the twiki/bin/statistics script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
  • Attention: The script must run as the same user as the CGI scripts are running, which is user nobody on most systems. Example crontab entry:
    0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
  • There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example:
    0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)
  • The twiki/bin/statistics script can also be executed as a CGI script, just enter the URL in your browser. Examples:
    • Update current month for all webs:
      http://twiki.oats.inaf.it/twiki/bin/statistics
    • Update current month for Main web only:
      http://twiki.oats.inaf.it/twiki/bin/statistics/Main
    • Update January 2000 for Main web:
      http://twiki.oats.inaf.it/twiki/bin/statistics/Main?logdate=200001

• To create a new web:
  • Use a name for the web consisting of characters A..Z , a..z but not in WikiNotation.
  • Create a new template directory under twiki/templates .
  • Create a new data directory under twiki/data and check the file permission of the directory.
  • Copy the files WebHome.txt , WebNotify.txt , WebSearch.txt , WebStatistics.txt , webcolor.inc and weblist.inc from the twiki/data/Main directory to the new data directory, preserving the original files' owner, group and permissions ( on Unix use cp -p ). The data files must be writable by the owner the CGI scripts are running on ( usually nobody ). Hint: You can set permissions of .txt and .txt,v files to -rw-rw-rw- and then edit the topic using your browser, RCS will restore the file permission correctly when saving the topic.
  • Change webcolor.inc to a color of your taste. The number represents the unique color for the web (consult an HTML book for colors.) Note: The file must not have a new line, just the number without a return.
  • Customize weblist.inc (web specific links on top) if needed.
  • Add the new web in twiki/data/wikiwebs.inc (web specific links on top) and twiki/data/wikiwebtable.inc (table of all webs at the end of the WebHome topics).
  • In case you need a web specific copyright notice (at the bottom), copy file webcopyright.inc from the twiki/data directory to the new data directory, and customize it.
  • If needed, create customized templates in the new templates directory. (Non existing templates are inherited from twiki/templates )
  • If you want to use a category table, copy the three files twikicatitems.tmpl , twikicatedit.tmpl and twikicatview.tmpl from the twiki/templates/Know directory to the new templates directory, and customize it. The TWiki Category Table section has more.
  • In case you want usage statistics for this web: Copy file WebStatistics.txt from the twiki/data/Main directory to the new data directory. Edit topic WebStatistics and delete old usage entries.

Here are contents of directories with file permissions. Please note that this is for debugging reasons only and does not exactly reflect the distribution:

directory twiki/bin :

drwxr-xr-x	5 twiki	 t5				512 Nov 11 02:52 .
drwxr-xr-x	5 twiki	 t5				512 Nov  6 02:57 ..
-rw-r--r--	1 twiki	 t5				430 Oct 21 18:51 .htaccess
-rw-r-xr-x	1 twiki	 t5			  3752 Mar 27 02:21 attach
-rw-r-xr-x	1 twiki	 t5			  2810 Oct 21 18:51 changes
-rw-r-xr-x	1 twiki	 t5			  1244 Mar 27 02:21 delete
-rw-r-xr-x	1 twiki	 t5			  2589 Nov  6 03:05 edit
-rwxr--r--	1 twiki	 t5			  1811 Feb  4 12:15 geturl
-rwxr-xr-x	1 twiki	 t5			  4614 Oct 21 18:52 mailnotify
-rw-r-xr-x	1 twiki	 t5			  1353 Oct 23 20:19 oops
-rw-r-xr-x	1 twiki	 t5			  2043 Nov  6 03:05 preview
-rw-r-xr-x	1 twiki	 t5			  6249 Aug  3 04:34 register
-rw-r-xr-x	1 twiki	 t5			  6890 Nov 11 03:06 rdiff
-rw-r-xr-x	1 twiki	 t5			  1819 Nov  6 03:06 save
-rw-r-xr-x	1 twiki	 t5			  3174 Oct 21 18:51 search
-rw-r-xr-x	1 twiki	 t5			  9774 Feb  4 12:26 statistics
-rwxr-xr-x	1 twiki	 t5				509 Feb  7 18:55 testenv
-rw-r-xr-x	1 twiki	 t5			  6696 Mar 27 02:22 upload
-rw-r-xr-x	1 twiki	 t5			  3878 Nov 11 03:06 view
-rw-r-xr-x	1 twiki	 t5			  1538 Mar 27 02:22 viewfile
-rw-r-xr-x	1 twiki	 t5			 16169 Nov  7 01:43 wiki.pm
-rw-r-xr-x	1 twiki	 t5			  3945 Jun 23 01:24 wikicfg.pm
-rw-r-xr-x	1 twiki	 t5			  5127 Feb  4 11:37 wikisearch.pm

directory twiki/templates/ :

drwxr-xr-x	6 twiki	 t5				512 Nov  4 20:34 .
drwxr-xr-x	5 twiki	 t5				512 Nov 11 02:52 ..
drwxr-xr-x	2 twiki	 t5				512 Oct 23 20:57 Know
drwxr-xr-x	2 twiki	 t5				512 Nov  4 20:35 Main
-rw-r--r--	1 twiki	 t5			  2232 Mar 27 02:03 attach.tmpl
-rw-r--r--	1 twiki	 t5			  1200 Mar 27 02:03 attachtable.tmpl
-rw-r--r--	1 twiki	 t5			  1751 Nov 11 02:41 changes.tmpl
-rw-r--r--	1 twiki	 t5			  1711 Nov  6 03:01 edit.tmpl
-rw-r--r--	1 twiki	 t5				896 Oct 21 18:51 mailnotify.tmpl
-rw-r--r--	1 twiki	 t5				 25 Oct 21 18:51 notedited.tmpl
-rw-r--r--	1 twiki	 t5				 21 Oct 21 18:51 notext.tmpl
-rw-r--r--	1 twiki	 t5				157 Oct 23 21:05 notwiki.tmpl
-rw-r--r--	1 twiki	 t5				218 Oct 23 20:06 noweb.tmpl
-rw-r--r--	1 twiki	 t5				279 Oct 23 20:29 oops.tmpl
-rw-r--r--	1 twiki	 t5				833 Mar 27 02:03 oopsdel.tmpl
-rw-r--r--	1 twiki	 t5			  1331 Oct 23 20:29 oopslocked.tmpl
-rw-r--r--	1 twiki	 t5			  1026 Aug 03 08:21 oopsregexist.tmpl
-rw-r--r--	1 twiki	 t5				935 Aug 03 08:23 oopsregpasswd.tmpl
-rw-r--r--	1 twiki	 t5				924 Aug 03 08:26 oopsregrequ.tmpl
-rw-r--r--	1 twiki	 t5				931 Aug 03 08:29 oopsregwiki.tmpl
-rw-r--r--	1 twiki	 t5				868 Mar 27 02:03 oopsupload.tmpl
-rw-r--r--	1 twiki	 t5			  2010 Nov  6 03:01 preview.tmpl
-rw-r--r--	1 twiki	 t5			  1501 Nov 12 22:56 rdiff.tmpl
-rw-r--r--	1 twiki	 t5				263 Aug  3 02:44 register.tmpl
-rw-r--r--	1 twiki	 t5			  1548 Oct 23 21:10 search.tmpl
-rw-r--r--	1 twiki	 t5			  1541 Oct 26 21:07 view.tmpl

directory twiki/templates/Main :

drwxr-xr-x	2 twiki	 t5				512 Nov  4 20:35 .
drwxr-xr-x	6 twiki	 t5				512 Nov  4 20:34 ..
-rw-r--r--	1 twiki	 t5			  2328 Nov  6 03:03 edit.tmpl

directory twiki/templates/Know (has a TWiki Category Table) :

drwxr-xr-x	2 twiki	 t5				512 Nov  4 20:35 .
drwxr-xr-x	6 twiki	 t5				512 Nov  4 20:34 ..
-rw-r--r--	1 twiki	 t5				611 Dec  7 20:59 notedited.tmpl
-rw-r--r--	1 twiki	 t5				210 Dec 24 23:22 twikicatedit.tmpl
-rw-r--r--	1 twiki	 t5			  1887 Jan  6 20:54 twikicatitems.tmpl
-rw-r--r--	1 twiki	 t5				245 Dec 24 23:27 twikicatview.tmpl

directory twiki/data/ :

drwxrwxrwx	6 twiki	 t5				512 Nov 19 01:01 .
drwxr-xr-x	5 twiki	 t5				512 Nov 11 02:52 ..
drwxrwxrwx	2 twiki	 t5			  9216 Nov 13 13:55 Know
drwxrwxrwx	2 twiki	 t5			  4608 Nov 15 21:42 Main
-rw-r--r--	1 nobody	65535			 53 Aug 03 08:31 .htpasswd
-rw-rw-rw-	1 twiki	 t5			  1091 Nov  6 04:15 debug.txt
-rw-r--r--	1 nobody	65535		  4153 Nov 19 01:01 log199810.txt
-rw-r--r--	1 nobody	65535		  7189 Nov 19 01:01 log199811.txt
-rw-r--r--	1 twiki	 t5			  2356 Oct 22 00:56 webcopyright.inc
-rw-r--r--	1 twiki	 t5				276 Oct 22 00:28 wikiwebs.inc
-rw-r--r--	1 twiki	 t5			  1484 Oct 22 01:11 wikiwebtable.inc

part of directory twiki/data/Main :

drwxrwxrwx	2 twiki	 t5			  4608 Nov 19 00:56 .
drwxrwxrwx	6 twiki	 t5				512 Nov 19 01:01 ..
-rw-rw-rw-	1 twiki	 t5			  5974 Nov 15 21:42 .changes
-rw-rw-rw-	1 twiki	 t5				  9 Nov 15 23:00 .mailnotify
-rw-r--r--	1 nobody	65535		  3991 Jul 22 04:33 FileAttachment.txt
-r--r--r--	1 nobody	65535		  4173 Jul 22 04:33 FileAttachment.txt,v
-rw-r--r--	1 nobody	65535		  6773 Aug  5 16:18 TWikiRegistration.txt
-r--r--r--	1 nobody	65535		  6960 Aug  5 16:18 TWikiRegistration.txt,v
-rw-r--r--	1 nobody	65535		  1990 Nov  6 18:25 TWikiUsers.txt
-r--r--r--	1 nobody	65535		  3045 Nov  6 18:25 TWikiUsers.txt,v
-rw-r--r--	1 nobody	65535		  1181 Oct 29 20:54 WebHome.txt
-r--r--r--	1 nobody	65535		  1537 Oct 29 20:54 WebHome.txt,v
-rw-r--r--	1 nobody	65535			454 Oct 21 18:52 WebNotify.txt
-r--r--r--	1 nobody	65535			638 Oct 27 02:45 WebNotify.txt,v
-rw-r--r--	1 nobody	65535		  3653 Oct 21 18:52 WebSearch.txt
-r--r--r--	1 nobody	65535		  3835 Oct 27 02:45 WebSearch.txt,v
-rw-r--r--	1 nobody	65535		  4282 Feb  4 15:08 WebStatistics.txt
-r--r--r--	1 nobody	65535		  4471 Feb  4 15:08 WebStatistics.txt,v
-rw-r--r--	1 twiki	 t5				  7 Oct 21 18:52 webcolor.inc
-rw-r--r--	1 twiki	 t5				278 May 20 17:42 webcopyright.inc
-rw-r--r--	1 twiki	 t5				402 Oct 26 07:45 weblist.inc

directory twiki/pub/ :

drwxrwxrwx	4 twiki	 t5			  1024 Mar 27 02:58 .
drwxr-xr-x	4 twiki	 t5			  1024 Mar 27 02:08 ..
drwxrwxrwx	4 nobody	nobody		 1024 Mar 27 03:54 Main
-rw-r--r--	1 twiki	 t5			  2877 Mar 27 02:27 wikiHome.gif
drwxr-xr-x	2 twiki	 t5			  1024 Mar 27 03:17 icn

directory twiki/pub/icn/ :

drwxr-xr-x	2 twiki	 t5			  1024 Mar 27 03:17 .
drwxrwxrwx	4 twiki	 t5			  1024 Mar 27 02:58 ..
-rw-r--r--	1 twiki	 t5				801 Mar 27 03:02 _filetypes.txt
-rw-r--r--	1 twiki	 t5				143 Mar 27 03:16 bat.gif
-rw-r--r--	1 twiki	 t5				926 Mar 27 03:16 bmp.gif
-rw-r--r--	1 twiki	 t5				141 Mar 27 03:16 c.gif
-rw-r--r--	1 twiki	 t5				144 Mar 27 03:16 dll.gif
-rw-r--r--	1 twiki	 t5				152 Mar 27 03:16 doc.gif
-rw-r--r--	1 twiki	 t5				130 Mar 27 03:16 else.gif
-rw-r--r--	1 twiki	 t5				876 Mar 27 03:16 exe.gif
-rw-r--r--	1 twiki	 t5				147 Mar 27 03:16 fon.gif
-rw-r--r--	1 twiki	 t5				142 Mar 27 03:16 h.gif
-rw-r--r--	1 twiki	 t5				156 Mar 27 03:16 hlp.gif
-rw-r--r--	1 twiki	 t5				186 Mar 27 03:16 html.gif
-rw-r--r--	1 twiki	 t5				144 Mar 27 03:16 java.gif
-rw-r--r--	1 twiki	 t5				148 Mar 27 03:16 mov.gif
-rw-r--r--	1 twiki	 t5				150 Mar 27 03:16 pdf.gif
-rw-r--r--	1 twiki	 t5				146 Mar 27 03:16 pl.gif
-rw-r--r--	1 twiki	 t5				150 Mar 27 03:16 ppt.gif
-rw-r--r--	1 twiki	 t5				148 Mar 27 03:16 ps.gif
-rw-r--r--	1 twiki	 t5				148 Mar 27 03:16 py.gif
-rw-r--r--	1 twiki	 t5				130 Mar 27 03:17 ram.gif
-rw-r--r--	1 twiki	 t5				154 Mar 27 03:17 reg.gif
-rw-r--r--	1 twiki	 t5				147 Mar 27 03:17 sh.gif
-rw-r--r--	1 twiki	 t5				155 Mar 27 03:17 sniff.gif
-rw-r--r--	1 twiki	 t5				149 Mar 27 03:17 ttf.gif
-rw-r--r--	1 twiki	 t5				134 Mar 27 03:17 txt.gif
-rw-r--r--	1 twiki	 t5				154 Mar 27 03:17 wav.gif
-rw-r--r--	1 twiki	 t5				152 Mar 27 03:17 wri.gif
-rw-r--r--	1 twiki	 t5				152 Mar 27 03:17 xls.gif
-rw-r--r--	1 twiki	 t5				144 Mar 27 03:17 zip.gif

-- PeterThoeny - 11 Feb 2000