3 files changed, 375 insertions, 0 deletions
diff --git a/rt/docs/customizing/articles_introduction.pod b/rt/docs/customizing/articles_introduction.pod
new file mode 100644
index 000000000..ea49b05de
--- /dev/null
+++ b/rt/docs/customizing/articles_introduction.pod
@@ -0,0 +1,155 @@
+
+=head1 Articles
+
+Articles are a way of managing stock answers or frequently asked
+questions.  Articles are a collection of custom fields whose values can
+be easily inserted into ticket replies or searched and browsed within
+RT.  They are organized into classes and topics.
+
+=head2 UI
+
+The user interface to Articles is available from the Tools -> Articles
+menu.  Admin functionality can be found under Tools -> Configuration ->
+Articles.  Once configured, articles will become available for searching
+on the Reply/Comment page on tickets.  There are configuration variables
+to make Articles available on ticket creation.
+
+=head2 Basics
+
+You will need to make some decisions about how to organize your
+articles.  Articles will be organized into one Class and multiple
+Topics.  They will use Custom Fields to store their article data.
+These Custom Fields can be configured on a Class by Class basis.
+Classes can be made available globally or on a per-Queue basis.
+
+=head2 Organization
+
+=head3 Classes
+
+Classes are equivalent to RT's queues.  They can be created by going
+to Tools -> Configuration -> Articles -> Classes -> New Class.  Articles
+are assigned to one Class.  When you create Custom Fields for use with
+Articles, they will be applied Globally or to a Class, like Custom
+Fields are applied to a Queue in RT.  Each class also controls what
+information is included into a reply (such as the Class header and
+footer) and the Article.
+
+Classes need to be Applied, just like a Custom Field by using the
+Applied To link.  You can apply them globally or on a queue-by-queue
+basis.
+
+hotlist.
+
+=head3 Topics
+
+You can also use Topics to organize your Articles.  While editing a
+Class, there is a Topic tab for Class specific Topics.  You can create
+global Topics from the Global tab under Tools -> Configuration.
+
+When editing Topics, type the name (and optionally description) of the
+Topic, and then click the button at the appropriate location in the
+Topic hierarchy. This should allow you to build a tree of Topics. This
+tree of Topics should show up when creating or modifying articles in
+the class. These can be arbitrarily nested.
+
+Global Topics will be available for all Articles, regardless of their
+Class.  Articles can belong to both global and class-specific Topics.
+
+Articles topics can be set from the 'Modify' screen for the article --
+simply select as many topics as you desire from the list at the bottom
+of the screen.
+
+=head2 Custom Fields
+
+Articles don't have a single "body" section for each
+article. Everything is a custom field (except for name, summary and
+some other basic metadata). So, you need to create some custom
+fields to hold the Article body and other data.  These Custom Fields
+should have "Applies To" be "RTFM Articles".
+
+Once you've created your custom fields, go into your classes and click
+on "Custom Fields" and add the Custom Fields you want to each class.
+Alternatively, use the Applies To link from each Custom Field.
+
+=head2 Creating Articles
+
+You can create an article from scratch by going to Tools -> Articles ->
+New Article and then picking which Class to create the Article under.
+The Summary, Description and Custom Fields will all be searchable when
+including an Article and you can control what Custom Fields end up in
+your Ticket from the Class configuration page.
+
+=head3 Extracting an Article
+
+You can extract the body of a ticket into an article. Within RT, you
+should now see an "Extract to article" button in the upper right hand
+corner of RT's UI when working with tickets. When you click that
+button, RT will ask you which Class to create your new article in.
+Once you click on a class name, the Ticket's transactions will be
+displayed, along with a set of select boxes. For each transaction, you
+can pick which Custom Field that transaction should be extracted to.
+From there on in, it's just regular article creation.
+
+=head2 Including an Article
+
+When replying to or commenting on tickets or creating tickets, there
+is a UI widget that lets you search for and include Articles in
+your reply.  (They're editable, of course).  
+
+Articles can be included by searching for them, knowing the Id of the
+article, using the Article Hotlist and using the Queue specific
+dropdown.
+
+=head2 Queue Specific List of Articles 
+
+You can use Topics to organize a set of Queue specific Articles.
+Simply create a global Topic called 'Queues' and then create Topics
+under Queues named after each of your Queues.  Within each Queue named
+Topic, create some Topics and then assign Articles to those
+sub-topics.  This creates a hierarchy like this:
+
+Queues
+\-> General
+    \-> Topic 1
+    \-> Topic 2
+
+If you are replying to a Ticket in the General Queue you will be
+offered a choice of Topic 1 and Topic 2 along with the searching.
+After choosing Topic 1 or Topic 2, you will be given a list of
+relevant articles to choose.
+
+Alternately, you can now implement this by applying a single class to
+your queue and using the L<Article Hotlist> feature described below.
+
+=head2 Article Hotlist
+
+If you enable "All articles in this class are on dropdown on ticket
+reply page" option, there will be a dropdown on the Create or Update
+page which allows users to quickly include Articles.
+
+=head2 SelfService Interface
+
+If you grant the Unprivileged user group the right ShowArticle, they
+will get a Search box at the top of their interface.  This allows users
+to look for answer to questions before creating a Ticket.
+
+=head1 Configuration options
+
+=head2 ArticleOnTicketCreate
+
+Set this to a true value to display the Article include interface on the
+Ticket Create page in addition to the Reply/Comment page (Create.html
+in addition to Update.html)
+
+=head2 HideArticleSearchOnReplyCreate
+
+On Ticket Reply (and Create if you set the above config var)
+RTFM normally displays a search box and an include box (for
+inputting an article id) and configurable dropdowns
+of articles.  These can be configured using Global Topics or
+on the Class page.
+
+If you set this to a true value, RTFM will only display
+dropdowns and hide the search boxes
+
+=cut
diff --git a/rt/docs/customizing/templates.pod b/rt/docs/customizing/templates.pod
new file mode 100644
index 000000000..5733f606c
--- /dev/null
+++ b/rt/docs/customizing/templates.pod
@@ -0,0 +1,132 @@
+=head1 Templates
+
+Each template is split into two sections. A block of headers and a body. These
+sections are separated by a blank line.
+
+Templates are processed by the L<Text::Template> module. This module
+allows you to embed arbitrary Perl code into your templates. Text wrapped
+in curly braces, C<{...}> is interpreted as Perl. See L<Text::Template>
+for more information.
+
+=head2 Headers
+
+Your template may specify arbitrary email headers. Each header is a name, a
+colon, then a value. So, for example, to specify a subject, you can use:
+
+    Subject: Thanks for your bug report.
+
+=head3 Special Headers
+
+=over
+
+=item Content-Type: text/html
+
+The special header "Content-Type: text/html" tells RT that the template should
+be parsed as HTML. RT will automatically make the outgoing message multipart.
+That way, recipients who can read only plaintext email will receive something
+readable, while users with clients which can display HTML will receive the full
+experience. Please be aware that HTML support in mail clients varies greatly,
+much more so than different web browsers.
+
+We welcome contributions of HTML-ization of builtin templates.
+
+=back
+
+=head2 Template Types
+
+Templates have a Type which dictates which level of code execution is
+allowed.
+
+Templates of type C<Perl> are evaluated using L<Text::Template>
+which allows arbitrary code execution. Only users which have the global
+C<ExecuteCode> privilege may write templates of type C<Perl>. Prior to
+RT 4.0, this was the only type of Template available.
+
+Templates of type C<Simple> permit only simple variable interpolation.
+No special privilege beyond C<ModifyTemplate> is needed to write C<Simple>
+templates.
+
+For both types of templates, text between curly braces C<{ ... }> is
+interpolated. For C<Perl> templates, this text can be any code (see
+L<Text::Template/Details>). For C<Simple> templates, only simple variables
+are permitted; for example C<{ $TicketSubject }>.
+
+=head2 Variables
+
+=head3 Perl templates
+
+The variables that your templates may use include:
+
+=over 4
+
+=item C<$Transaction>
+
+The transaction object.
+
+=item C<$rtname>
+
+The value of the "rtname" config variable.
+
+=item C<$Ticket>
+
+The ticket object. This is only set during a ticket transaction.
+
+=item C<$Requestor>
+
+This is not an object, but the name of the first requestor on the ticket.
+If this is not what you need, inspect C<< $Ticket->Requestors >>.
+
+=item C<loc("text")>
+
+A localization function. See L<Locale::Maketext>.
+
+=back
+
+=head3 Selected Simple template variables
+
+Since method calls are not allowed in simple templates, many common
+method results have been placed into scalar variables for the template's
+use.  Among them:
+
+=over 4
+
+=item $TicketId
+
+=item $TicketSubject
+
+=item $TicketStatus
+
+=item $TicketQueueName
+
+=item $TicketOwnerName
+
+=item $TicketOwnerEmailAddress
+
+=item $TicketCF(Name)
+
+For example, C<$TicketCFDepartment>.
+
+=item $TransactionType
+
+=item $TransactionField
+
+=item $TransactionOldValue
+
+=item $TransactionNewValue
+
+=item $TransactionData
+
+=item $TransactionContent
+
+=item $TransactionDescription
+
+=item $TransactionBriefDescription
+
+=item $TransactionCF(Name)
+
+For example, C<$TransactionCFLocation>.
+
+=back
+
+=cut
+
diff --git a/rt/docs/customizing/timezones_in_charts.pod b/rt/docs/customizing/timezones_in_charts.pod
new file mode 100644
index 000000000..47c3a096f
--- /dev/null
+++ b/rt/docs/customizing/timezones_in_charts.pod
@@ -0,0 +1,88 @@
+=head1 INTRODUCTION
+
+Every date in RT's DB is stored in UTC format. This affects charts
+grouped by time periods (Annually, Monthly, etc.), in that they are by
+default shown in UTC. To produce charts that are in a specific timezone,
+we have to use database-specific functions to convert between timezones;
+unsurprisingly, each DB has very different requirements.
+
+=head1 CONFIGURATION
+
+This code is experimental; you can enable it using the
+C<$ChartsTimezonesInDB> configuration option.
+
+=head1 DATABASE SPECIFIC NOTES
+
+=head2 mysql
+
+The time adjustment cannot simply be converted using a numeric time
+shift, as this shift value depends on the daylight saving time
+properties of the time zone.
+
+mysql since 4.1.3 supports named timezones, but you have to fill special
+tables with up-to-date timezone data. On modern systems, this is usually
+a simple case of:
+
+    mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql
+
+mysql's doc recommends you restart server after running this; you can
+read more about mysql's timezone support at
+L<http://dev.mysql.com/doc/refman/5.0/en/time-zone-support.html>
+
+=head2 PostgreSQL
+
+PostgreSQL uses your operating system's functions to convert timezones.
+Thus, you don't need to do anything in particular except to make sure
+that the data in F</usr/share/zoneinfo> is up to date. On some systems
+this may mean upgrading a system package.
+
+=head3 Note for users of Pg 7.2 and older or users upgraded from those
+
+You should be sure that timestamps in RT DB have no TZ set. The
+TIMESTAMP column type in PostgreSQL prior to Pg 7.3 had timezone info by
+default; this has been removed in more recent versions.  If your RT
+database has this embedded timezone info, you will need to alter the
+columns to remove them before enabling this feature.
+
+=head2 Other databases
+
+There is no implementation for Oracle or SQLite at current.
+
+=head1 FOR DEVELOPERS
+
+=head2 PostgreSQL
+
+We use the timestamp type for all datetime fields. It either has
+timezone info or not, since by default Pg 7.3 and above have no
+timezone. Conversion is kinda tricky:
+
+    timezone('Europe/Moscow', timezone('UTC', column_without_tz_info))
+    timezone('to_tz', timezone('from_tz', column_without_tz_info))
+
+This function flips the HAS_TZ flag on the argument, and moves the
+timestamp to UTC. The first call makes no conversion, but flips the
+HAS_TZ flag; the second call flips it back and does actual conversion.
+
+For more information, See
+L<http://www.postgresql.org/docs/7.4/static/functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT>
+and
+L<http://www.postgresql.org/docs/7.4/static/datatype-datetime.html#DATATYPE-TIMEZONES>
+
+=head2 mysql
+
+Once timezone information is loaded into tables on the server,
+we have all the same set of named timezones in the system
+and DateTime (DateTime project has copy of the TZ data in a module).
+
+CONVERT_TZ(TS, from, to) exists since mysql 4.1.3. Note that it takes a
+timestamp, so it only supports limitted date range (usuall 1970-2038).
+
+=head2 Oracle
+
+Look at FROM_TZ function.
+
+=head2 SQLite
+
+Has no apparent timezone support.
+
+=cut