diff options
| -rw-r--r-- | doc/rt-liberation.texinfo | 130 |
1 files changed, 96 insertions, 34 deletions
diff --git a/doc/rt-liberation.texinfo b/doc/rt-liberation.texinfo index 1b7cbf5..168e68c 100644 --- a/doc/rt-liberation.texinfo +++ b/doc/rt-liberation.texinfo @@ -63,9 +63,9 @@ Extensions Copying and license * Copying:: The GNU General Public License gives you - permission to redistribute rt-liberation - on certain terms; it also explains that - there is no warranty. + permission to redistribute rt-liberation + on certain terms; it also explains that + there is no warranty. * The GNU FDL:: The license for this documentation. @@ -127,25 +127,87 @@ operations on the ticket. @cindex dependencies -rt-liberation has been tested exclusively on GNU/Emacs, with very -recent versions. +rt-liberation has been tested exclusively on GNU/Emacs. -Since rt-liberation uses the command line interface as a backend to -communicate with the RT server it will need a local copy of the RT -software on the machine running rt-liberation. RT is available at -@uref{http://bestpractical.com/rt/download.html} +rt-liberation uses the RT command line interface (RT CLI) as a back-end +to communicate with the RT server. rt-liberation will need a local +copy of the RT software on the machine running rt-liberation. RT is +available at @uref{http://bestpractical.com/rt/download.html} -At the time of writing the recommended version of RT to use as a -backend for rt-liberation is 3.8.2. Version 3.8.2 will provide -shorter response times and less calls out to the server. +@menu +* RT CLI Setup:: Getting the RT Command Line Interface to work +@end menu + + + + +@node RT CLI Setup +@section RT CLI Setup + +The following is a short description of how to get the RT CLI setup on +the machine where rt-liberation will be running. It assumes a +GNU/Linux distribution such as Trisquel @uref{http://trisquel.info/}. + +You need the address of the remote RT server (note whether it's an +HTTP or HTTPS address), and the username and password for the user +account on that server. + +Download a local copy of RT (version 4.2.3 happened to be extant at +the time of writing). + +@example +$ wget http://download.bestpractical.com/pub/rt/release/rt-4.2.3.tar.gz +$ tar xzf rt-4.2.3.tar.gz +@end example + +Navigate down to the ``bin'' directory and try to run the RT CLI. + +@example +$ cd rt-4.2.3/bin +$ ./rt +@end example + +If you don't already have Perl LWP installed it will fail to run, in +which case you have to satisfy this dependency. The following command +should do it on a Trisquel GNU/Linux or similar system: + +@example +sudo apt-get install liblwp-protocol-https-perl +@end example + +Trying to run the RT CLI at this point should work, and you will be +greeted by the friendly RT CLI prompt ``rt>''. Feel free to hit Ctrl-C +at this point because while the RT CLI is running it is still +unconfigured. -Please check that the RT CLI runs from the shell and can communicate -with the server in question. If that doesn't work neither will -rt-liberation. +The RT CLI looks for a file named ``.rtrc'' in your home directory, so +create an ``~/.rtrc'' file and, using the information collected +earlier, fill in the details. +@example +server https://rt.server.somewhere +user USERNAME-ON-RT +passwd PASSWORD-ON-RT +@end example +Now back to running the RT CLI we can enter a simple RT query to check +the setup. If everything is set up correctly then the result will be a +list of tickets. +@example +rt> ls "Queue=sprockets and Status=new" +Ticket Owner Queue Age Told Status Requestor Subject +-------------------------------------------------------------------------------- +========== 2 unowned tickets ========== + 701 sproc 5 min new admin@@no. foo + 702 sproc 4 min new john.foo@@ john's foo +@end example +At this point you know that rt-liberation has everything it needs to +call into the server@footnote{Implementing rt-liberation in this way +has the additional benefit of isolating the rt-liberation code +somewhat from changes in the way the RT CLI communicates with the RT +server.}. @c -------------------------------------------------- @@ -252,7 +314,7 @@ For example here is a query with both Boolean and LIKE tokens: @lisp (rt-liber-compile-query (and (queue "bugs") - (content "gnu"))) + (content "gnu"))) ==> "Queue = 'bugs' AND Content LIKE 'gnu'" @end lisp @@ -290,11 +352,11 @@ Here is a slightly more involved example to illustrate: (owner "me@@myaddress.com") (status "open") (lastupdated nil - (format-time-string - "%Y-%m-%d" - (seconds-to-time - (- (time-to-seconds (current-time)) - (* 60 60 24 7))))))) + (format-time-string + "%Y-%m-%d" + (seconds-to-time + (- (time-to-seconds (current-time)) + (* 60 60 24 7))))))) ==> "Queue = 'bugs' AND Owner = 'me@@myaddress.com' AND Status = 'open' AND LastUpdated > '2009-03-30'" @end lisp @@ -310,7 +372,7 @@ in function calls: (rt-liber-browse-query (rt-liber-compile-query (and (queue "complaints") - (id ticket-id))))) + (id ticket-id))))) @end lisp @@ -345,7 +407,7 @@ example: (rt-liber-browse-query (rt-liber-compile-query (and (queue "bugs") - (content "gnu"))) + (content "gnu"))) @end lisp @@ -505,8 +567,8 @@ would break the font-locking regular expressions. "Display TICKET." (insert (rt-liber-format "[%c] %i" ticket)) (add-text-properties (point-at-bol) - (point-at-eol) - '(face rt-liber-ticket-face)) + (point-at-eol) + '(face rt-liber-ticket-face)) (newline) (insert (rt-liber-format " [%S] %s" ticket)) (newline) @@ -572,7 +634,7 @@ signaled). (rt-liber-sort-ticket-list ticket-list #'(lambda (a b) - (rt-liber-time-lessthan-p a b "Created"))))) + (rt-liber-time-lessthan-p a b "Created"))))) @end lisp @end defun @@ -610,8 +672,8 @@ to be filtered. (defun rt-liber-browser-deleted-filter (ticket) (not (and ticket - (string= (cdr (assoc "Status" ticket)) - "deleted")))) + (string= (cdr (assoc "Status" ticket)) + "deleted")))) @end lisp Then we assign that function to be our default filtering function: @@ -647,16 +709,16 @@ buffers will be created displaying the query results and named (rt-liber-browse-query (rt-liber-compile-query (and (queue "complaints") - (owner "lem.e.tweakit") - (status "open") - (lastupdatedby "molly.manager"))) + (owner "lem.e.tweakit") + (status "open") + (lastupdatedby "molly.manager"))) "*updated by supervisor*") (rt-liber-browse-query (rt-liber-compile-query (and (queue "complaints") - (owner "Nobody") - (status "new"))) + (owner "Nobody") + (status "new"))) "*new tickets*")) @end lisp @@ -807,7 +869,7 @@ variables followed by a more thorough description of the variables: rt-liber-gnus-address "our-rtserver@@ourserver.org" rt-liber-gnus-subject-name "ourserver.org" rt-liber-gnus-answer-headers '(("Gcc" . "nnml:Send-Mail") - ("X-Ethics" . "Use GNU")) + ("X-Ethics" . "Use GNU")) rt-liber-gnus-signature "Kind Regards") @end lisp |