Skip to content

Commit

Permalink
Item8805: Doc cleanup
Browse files Browse the repository at this point in the history 
git-svn-id: http://svn.foswiki.org/trunk/LocalTimePlugin@7060 0b4bb1d4-4e5a-0410-9cc4-b2b747904278
  • Loading branch information
BryanThale authored and BryanThale committed Apr 3, 2010
1 parent e4039d0 commit 196234e
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 37 deletions.
84 changes: 49 additions & 35 deletions data/System/LocalTimePlugin.txt
View file
Expand Up @@ -11,7 +11,7 @@ $SHORTDESCRIPTION from the .pm module.
-->
%SHORTDESCRIPTION%

%TOC{title="On this page:"}%
%TOC{title="On this page:" depth="2"}%

__Related topics:__
%STARTSECTION{"related"}%[[%SYSTEMWEB%.Macros#VarDATE][DATE]], [[%SYSTEMWEB%.Macros#VarDISPLAYTIME][DISPLAYTIME{"format"}]], [[%SYSTEMWEB%.Macros#VarGMTIME][GMTIME{"format"}]], [[%SYSTEMWEB%.Macros#VarSERVERTIME][SERVERTIME{"format"}]]%ENDSECTION{"related"}%
Expand All @@ -25,6 +25,7 @@ and locale to use when displaying the date/time may be specified when the macro
is used or determined by [[#PreferenceSettings][plugin preference settings]].

---++ Syntax

%STARTSECTION{"syntax"}% * Syntax: =%<nop>LOCALTIME%= or =%<nop>LOCALTIME{&hellip;}%=
* =%<nop>LOCALTIME%= expands to the current date and time using the default
format, time zone, and locale
Expand All @@ -33,14 +34,14 @@ is used or determined by [[#PreferenceSettings][plugin preference settings]].
* Supported parameters:
| *Parameter:* | *Description:* | *Default* |
| ="timezone"= | The name of the desired time zone such as ="Asia/Tokyo"= or ="CST6CDT"= or ="UTC"= | ="UTC"= |
| =datetime="&hellip;"= | The date and time to display. This parameter is assumed to be in UTC unless it contains a time zone specifier. <br /> %TWISTY{mode="div" showlink="Supported date/time formats" hidelink="Supported date/time formats" showimgleft="%ICONURLPATH{toggleopen-small}%" hideimgleft="%ICONURLPATH{toggleclose-small}%"}%<ul> <li>Foswiki default: <ul> <li> =31 Dec 2001 - 23:59 GMT= </li> </ul> </li> <li>ISO 8601: <ul> <li> =2001-12-31T23:59:59-0500= </li> </ul> </li> <li>Internet (RFC 822/1123/2616/2822/5322): <ul> <li> =Fri, 31 Dec 1999 23:59:59 -0500 (EST)= </li> </ul> </li> <li>RCS: <ul> <li> =1999/12/31 23:59:59 UTC= </li> </ul> </li> <li>Dotted decimal: <ul> <li> =1999.12.31.23.59.59 UTC= </li> </ul> </li></ul><br /> __Notes:__ <ul> <li>Dates must be between =<nobr>1901-12-17 00:00:00 UTC</nobr>= and =<nobr>2038-01-16 23:59:59 UTC</nobr>= </li> <li>Text in ()'s is ignored as are the day of the week and comma, if present.</li> <li>The time component is optional and defaults to midnight. If supplied, both hour and minute fields are required while seconds are optional.</li> <li>Time zone specifiers are optional and default to UTC. When specified as an offset from UTC, they may be specified as &plusmn;HHMM or &plusmn;HH:MM</li> <li>Time zones are part of the time specification, so you must specify a time in order to specify a time zone. If you desire a date to be interpreted locally, explicitly indicate midnight and the local time zone as in =<nobr>2010-03-24&nbsp;00:00&nbsp;-0600</nobr>= <li>Years may be specified using 2 or 4 digits. When only 2 digits are supplied: <ul> <li>00 to 38 are interpreted as the years 2000 to 2038</li> <li>39 to 60 are invalid and result in an error</li> <li>61 to 99 are interpreted as 1961 to 1999</li> </ul> <li>Months may be specified as numbers (1-12), short names (Jan-Dec), or long names (January-December), English month names only</li> <li>When both the month and day are specified as numbers, they are always interpreted assuming an American-style date format where the month comes before the day. (i.e. MM/DD/CCYY)</li> <li>When only a month and day are specified, the year is assumed to be the current year if the date falls within the current or a prior month and the prior year if the date falls within a subsequent month.</li> <li>When only a year is specified, January 1st is assumed.</li></ul>%ENDTWISTY% | Current&nbsp;time |
| =datetime="&hellip;"= | The date and time to display. This parameter is assumed to be in UTC unless it contains a time zone specifier. <br /> %TWISTY{mode="div" link="Supported date/time formats" showimgleft="%ICONURLPATH{toggleopen-small}%" hideimgleft="%ICONURLPATH{toggleclose-small}%"}%<ul> <li>Foswiki default: <ul> <li> =31 Dec 2001 - 23:59 GMT= </li> </ul> </li> <li>ISO 8601: <ul> <li> =2001-12-31T23:59:59-0500= </li> </ul> </li> <li>Internet (RFC 822/1123/2616/2822/5322): <ul> <li> =Fri, 31 Dec 1999 23:59:59 -0500 (EST)= </li> </ul> </li> <li>RCS: <ul> <li> =1999/12/31 23:59:59 UTC= </li> </ul> </li> <li>Dotted decimal: <ul> <li> =1999.12.31.23.59.59 UTC= </li> </ul> </li></ul><br /> __Notes:__ <ul> <li>Dates must be between =<nobr>1901-12-17 00:00:00 UTC</nobr>= and =<nobr>2038-01-16 23:59:59 UTC</nobr>= </li> <li>Text in ()'s is ignored as are the day of the week and comma, if present.</li> <li>The time component is optional and defaults to midnight. If supplied, both hour and minute fields are required while seconds are optional.</li> <li>Time zone specifiers are optional and default to UTC. When specified as an offset from UTC, they may be specified as &plusmn;HHMM or &plusmn;HH:MM</li> <li>Time zones are part of the time specification, so you must specify a time in order to specify a time zone. If you desire a date to be interpreted locally, explicitly indicate midnight and the local time zone as in =<nobr>2010-03-24&nbsp;00:00&nbsp;-0600</nobr>= <li>Years may be specified using 2 or 4 digits. When only 2 digits are supplied: <ul> <li>00 to 38 are interpreted as the years 2000 to 2038</li> <li>39 to 60 are invalid and result in an error</li> <li>61 to 99 are interpreted as 1961 to 1999</li> </ul> <li>Months may be specified as numbers (1-12), short names (Jan-Dec), or long names (January-December), English month names only</li> <li>When both the month and day are specified as numbers, they are always interpreted assuming an American-style date format where the month comes before the day. (i.e. MM/DD/CCYY)</li> <li>When only a month and day are specified, the year is assumed to be the current year if the date falls within the current or a prior month and the prior year if the date falls within a subsequent month.</li> <li>When only a year is specified, January 1st is assumed.</li></ul>%ENDTWISTY% | Current&nbsp;time |
| =format="&hellip;"= | The format specifier string defining how to display the date and/or time | ="$longdate"= |
| =locale="&hellip;"= | The locale to use when displaying the date/time | ="en_US"= |

* Deprecated parameters:
| *Parameter:* | *Description:* | *Deprecated* |
| =dateGMT="&hellip;"= | The same as =datetime=, use =datetime= instead | Since 1.1 |
| =fromtopic="&hellip;"= | The =web.topic= from which to get the value of the =TIMEZONE= variable, use the [[%SYSTEMWEB%.Macros#SettingPrefs][preference value]] =LOCALTIMEPLUGIN_TIMEZONE= instead | Since 1.1 |
| =fromtopic="&hellip;"= | The =web.topic= from which to get the value of the =TIMEZONE= variable, use the [[#PreferenceSettings][preference setting]] =LOCALTIMEPLUGIN_TIMEZONE= instead | Since 1.1 |
%ENDSECTION{"syntax"}%
* Supported format tokens:%STARTSECTION{"tokens"}%
| *Token:* | *Unit:* | *Example* |
Expand Down Expand Up @@ -83,14 +84,14 @@ __Current default settings:__
* LOCALTIMEPLUGIN_LOCALE is: %IF{"defined 'LOCALTIMEPLUGIN_LOCALE'" then="%LOCALTIMEPLUGIN_LOCALE%" else="en_US"}%
* LOCALTIMEPLUGIN_TIMEZONE is: %IF{"defined 'LOCALTIMEPLUGIN_TIMEZONE'" then="%LOCALTIMEPLUGIN_TIMEZONE%" else="UTC"}%

| *You want:* | *You type:* | *You get (if installed):* |
| Current time: | =%<nop>LOCALTIME%= | %LOCALTIME% |
| Current time in Tokyo: | =%<nop>LOCALTIME{"Asia/Tokyo"}%= | %LOCALTIME{"Asia/Tokyo"}% |
| Current time in US Central Time Zone: | =%<nop>LOCALTIME{"CST6CDT"}%= | %LOCALTIME{"CST6CDT"}% |
| Current time in Internet format: | =%<nop>LOCALTIME{format="$rfc"}%= | %LOCALTIME{format="$rfc"}% |
| Current time in Paris, France: | =%<nop>LOCALTIME{"Europe/Paris" locale="fr_FR" format="$rfc"}%= | %LOCALTIME{"Europe/Paris" locale="fr_FR" format="$rfc"}% |
| 2006-04-05T15:43:50Z in Sydney, Australia: | =%<nop>LOCALTIME{"Australia/Sydney" datetime="2006-04-05T15:43:50Z"}%= | %LOCALTIME{"Australia/Sydney" datetime="2006-04-05T15:43:50Z"}% |
| <nobr>Sun, 28 Mar 2010 05:58:38 -0500 (CDT)</nobr> in Sydney, Australia in HTTP format: | =%<nop>LOCALTIME{"Australia/Sydney" datetime="Sun, 28 Mar 2010 05:58:38 -0500 (CDT)" format="$http"}%= | %LOCALTIME{"Australia/Sydney" datetime="Sun, 28 Mar 2010 05:58:38 -0500 (CDT)" format="$http"}% |
| *You want:* | *You type:* | *You get:* |
| Current time: | =%<nop>LOCALTIME%= | %IF{"context LocalTimePluginEnabled" then='$percntLOCALTIME$percnt' else='$percntDISABLED$percnt'}% |
| Current time in Tokyo: | =%<nop>LOCALTIME{"Asia/Tokyo"}%= | %IF{"context LocalTimePluginEnabled" then='$percntLOCALTIME{"Asia/Tokyo"}$percnt' else='$percntDISABLED$percnt'}% |
| Current time in US Central Time Zone: | =%<nop>LOCALTIME{"CST6CDT"}%= | %IF{"context LocalTimePluginEnabled" then='$percntLOCALTIME{"CST6CDT"}$percnt' else='$percntDISABLED$percnt' }% |
| Current time in Internet format: | =%<nop>LOCALTIME{format="$rfc"}%= | %IF{ "context LocalTimePluginEnabled" then='$percntLOCALTIME{format="$rfc"}$percnt' else='$percntDISABLED$percnt' }% |
| Current time in Paris, France: | =%<nop>LOCALTIME{"Europe/Paris" locale="fr_FR" format="$rfc"}%= | %IF{ "context LocalTimePluginEnabled" then='$percntLOCALTIME{"Europe/Paris" locale="fr_FR" format="$rfc"}$percnt' else='$percntDISABLED$percnt' }% |
| 2006-04-05T15:43:50Z in Sydney, Australia <nobr>(April 6, 2006, 1:43:50 AM):</nobr> | =%<nop>LOCALTIME{"Australia/Sydney" datetime="2006-04-05T15:43:50Z"}%= | %IF{ "context LocalTimePluginEnabled" then='$percntLOCALTIME{"Australia/Sydney" datetime="2006-04-05T15:43:50Z"}$percnt' else='$percntDISABLED$percnt' }% |
| <nobr>Sun, 28 Mar 2010 05:58:38 -0500 (CDT)</nobr> in Sydney, Australia in HTTP format <nobr>(Sun, 28 Mar 2010 21:58:38 EST):</nobr> | =%<nop>LOCALTIME{"Australia/Sydney" datetime="Sun, 28 Mar 2010 05:58:38 -0500 (CDT)" format="$http"}%= | %IF{ "context LocalTimePluginEnabled" then='$percntLOCALTIME{"Australia/Sydney" datetime="Sun, 28 Mar 2010 05:58:38 -0500 (CDT)" format="$http"}$percnt' else='$percntDISABLED$percnt' }% |

#PreferenceSettings
---++ Preference Settings
Expand All @@ -99,7 +100,8 @@ The default expansion of the %<nop>LOCALTIME% macro may be altered by setting
[[%SYSTEMWEB%.PreferenceSettings][Foswiki preference settings]]. These settings
can be placed in your wiki's [[%LOCALSITEPREFS%][Site Preferences topic]], your
web's [[WebPreferences][Web Preferences topic]], your own
[[%WIKIUSERNAME%][User Preferences topic]], or any individual topic.
[[%WIKIUSERNAME%][User Preferences topic]], or the topic in which the
%<nop>LOCALTIME% macro is used.

| *Setting* | *Description* | *Default* |
| DATEFORMAT | The default output format specifier to use when formatting dates and/or times | =$longdate= |
Expand All @@ -126,23 +128,13 @@ the example assignment statements below to set the desired preference value.
%ASTERISK% Set LOCALTIMEPLUGIN_TIMEZONE = UTC
</pre>

#ConfigurationSettings
---++ Configuration Settings
---++ Installation

The following information is for the administrator who installs this plugin on
the server.
You do not need to install anything in the browser to use this extension.
The following instructions are for the site administrator who installs the
extension on the server.

!LocalTimePlugin makes use of the following configuration settings which may
be set to configure the plugin to work in your particular environment.

| *Setting* | *Description* |
| ={UseLocale}= | Enable/Disable use of locales for the site |
| ={Site}{Locale}= | The default locale for the site. This setting will be ignored if ={UseLocale}= is disabled. |
| ={DefaultDateFormat}= | The default date format for the site |
| ={Tools}{perlCmd}= | The path to the Perl interpreter if it isn't on the default path |
| ={Plugins}{LocalTimePlugin}{perlCmd}= | The path to the Perl interpreter if it isn't on the default path. If present, overrides the setting of ={Tools}{perlCmd}= |

---++ Installation
%TWISTY{mode="div" link="Installation instructions" showimgleft="%ICONURLPATH{toggleopen-small}%" hideimgleft="%ICONURLPATH{toggleclose-small}%"}%

%$INSTALL_INSTRUCTIONS%

Expand All @@ -155,26 +147,47 @@ attached to the Foswiki:Extensions.LocalTimePlugin topic.
directory of your Foswiki installation.
1. Unpack the distribution package
1. Using the Foswiki configuration utility, configure the values described
in [[#ConfigurationSettings][Configuration]] above and enable the plugin.
(If using an accellerator such as mod_perl, it may be necessary to
restart your server before your configuration changes will take effect.)
in [[#ConfigurationSettings][Configuration Settings]] below and enable
the plugin. (If using an accellerator such as mod_perl, it may be
necessary to restart your server before your configuration changes will
take effect.)
1. Set any default [[#PreferenceSettings][preference values]] in
[[%LOCALSITEPREFS%][Site]], Web, and User Preference topics as desired.

#ConfigurationSettings
---+++ Configuration Settings

!LocalTimePlugin makes use of the following configuration settings which may
be set to adapt the plugin to work in your particular environment.

| *Setting* | *Description* |
| ={UseLocale}= | Enable/Disable use of locales for the site |
| ={Site}{Locale}= | The default locale for the site. This setting will be ignored if ={UseLocale}= is disabled. |
| ={DefaultDateFormat}= | The default date format for the site |
| ={Tools}{perlCmd}= | The path to the Perl interpreter if it isn't on the default path |
| ={Plugins}{LocalTimePlugin}{perlCmd}= | The path to the Perl interpreter if it isn't on the default path. If present, overrides the setting of ={Tools}{perlCmd}= |

---+++ Installation Test

| Current time (UTC): | %LOCALTIME{"UTC"}% |
| Current time (Asia/Tokyo): | %LOCALTIME{"Asia/Tokyo"}% |
| Current time (!CST6CDT): | %LOCALTIME{"CST6CDT" format="$rfc"}% |
| 2010-03-24T12:34:56Z: | %LOCALTIME{datetime="2010-03-24T12:34:56Z" format="$iso"}% |
| Current time (UTC): | %IF{ "context LocalTimePluginEnabled" then='$percntLOCALTIME{"UTC"}$percnt' else='$percntDISABLED$percnt' }% |
| Current time (Asia/Tokyo): | %IF{ "context LocalTimePluginEnabled" then='$percntLOCALTIME{"Asia/Tokyo"}$percnt' else='$percntDISABLED$percnt' }% |
| Current time (!CST6CDT): | %IF{ "context LocalTimePluginEnabled" then='$percntLOCALTIME{"CST6CDT" format="$rfc"}$percnt' else='$percntDISABLED$percnt' }% |
| 2010-03-24T12:34:56Z: | %IF{ "context LocalTimePluginEnabled" then='$percntLOCALTIME{datetime="2010-03-24T12:34:56Z" format="$iso"}$percnt' else='$percntDISABLED$percnt' }% |

---+++ Manifest

| *File:* | *Description:* |
%$MANIFEST%
%ENDTWISTY%

#PluginInfo
---++ Plugin Info

| Author: | TWiki:Main.NathanOllerenshaw, Foswiki:Main.SvenDowideit, & Foswiki:Main.BryanThale |
| Copyright: | &copy; 2010, Foswiki Contributors |
| License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License, Version 3]]) |
| Version: | %$RELEASE% (%$VERSION%) |
| Release: | %$RELEASE% |
| Version: | %$VERSION% |
| Home: | Foswiki:Extensions.%TOPIC% |
| Support: | Foswiki:Support.%TOPIC% |
| Dependencies: | %$DEPENDENCIES% |
Expand All @@ -188,3 +201,4 @@ __Related Topics:__
%INCLUDE{"%TOPIC%" section="related"}%

%META:PREFERENCE{name="ASTERISK" title="ASTERISK" type="Set" value="*"}%
%META:PREFERENCE{name="DISABLED" title="DISABLED" type="Set" value="%RED%<nobr>%ICON{plugin}% Plugin disabled</nobr>%ENDCOLOR%"}%
4 changes: 2 additions & 2 deletions data/System/VarLOCALTIME.txt
View file
@@ -1,8 +1,8 @@
%META:TOPICINFO{author="ProjectContributor" date="1231502400" format="1.1" version="$Rev$"}%
%META:TOPICINFO{author="ProjectContributor" date="1270329174" format="1.1" version="1.1"}%
%META:TOPICPARENT{name="Macros"}%
#VarLOCALTIME
---+++ LOCALTIME{&hellip;} -- display formatted date and/or time
* The =%<nop>LOCALTIME%= macro is provided by the %SYSTEMWEB%.LocalTimePlugin
%INCLUDE{"%SYSTEMWEB%.LocalTimePlugin" section="syntax"}%
* %TWISTY{mode="div" showlink="Supported format tokens" hidelink="Supported format tokens" showimgleft="%ICONURLPATH{toggleopen-small}%" hideimgleft="%ICONURLPATH{toggleclose-small}%"}%%INCLUDE{"%SYSTEMWEB%.LocalTimePlugin" section="tokens"}%%ENDTWISTY%
* %TWISTY{mode="div" link="Supported format tokens" showimgleft="%ICONURLPATH{toggleopen-small}%" hideimgleft="%ICONURLPATH{toggleclose-small}%"}%%INCLUDE{"%SYSTEMWEB%.LocalTimePlugin" section="tokens"}%%ENDTWISTY%
* Related: %INCLUDE{"%SYSTEMWEB%.LocalTimePlugin" section="related"}%

0 comments on commit 196234e

Please sign in to comment.