branch: externals/rt-liberation commit b3f34ab05e5d44a16e4085431cf5bdaac2c65bb6 Author: Yoni Rabkin <y...@rabkins.net> Commit: Yoni Rabkin <y...@rabkins.net>
update documentation across the board --- doc/developer-release.txt | 6 ++ doc/rt-liber.texinfo | 74 ++++++------------ rt-liber.info | 189 ++++++++++++++++++++-------------------------- 3 files changed, 110 insertions(+), 159 deletions(-) diff --git a/doc/developer-release.txt b/doc/developer-release.txt index 81b275e..14c4096 100644 --- a/doc/developer-release.txt +++ b/doc/developer-release.txt @@ -17,6 +17,12 @@ Update the NEWS file to tell all of the people the Good News. Update the manual, compile it, and update the copy of the info file in the root directory so that ELPA can install it. +Compile an HTML version of the manual and update it on the Website: + + $ cvs commit -m "update manual" rt-liber.html + + $ cvs commit -m "update website" index.html + * push Push these updates to the git repo. diff --git a/doc/rt-liber.texinfo b/doc/rt-liber.texinfo index 0436425..bc2a095 100644 --- a/doc/rt-liber.texinfo +++ b/doc/rt-liber.texinfo @@ -48,7 +48,8 @@ This is the Manual for the rt-liberation system @menu * Introduction:: Introduction to rt-liberation. -* Installation:: Setup rt-liberation to work on the system. +* Installation:: Install rt-liberation on the system. +* Configuration:: Setup rt-liberation to work on the system. Using rt-liberation * Queries:: Retrieve particular tickets from the server. @@ -117,10 +118,12 @@ operations on the tickets. @chapter Installation @cindex installation -rt-liberation is available via GNU ELPA. +rt-liberation is available via GNU ELPA. Invoke @kbd{M-x +list-packages} and choose to install the rt-liberation package. -If you install rt-liberation manually instead you'll need to tell -Emacs where to find it, and tell Emacs to load the package: +If you install rt-liberation manually, by copying the code to your +machine, instead you'll need to tell Emacs where to find it, and then +tell Emacs to load the package: @lisp (add-to-list 'load-path "/PATH/TO/rt-liberation/") @@ -131,6 +134,11 @@ Emacs where to find it, and tell Emacs to load the package: @end lisp +@c -------------------------------------------------- +@node Configuration +@chapter Configuration +@cindex configuration + rt-liberation needs to be configured in your ~/.emacs, an ~/.rt-liber file, or similar. @@ -622,10 +630,8 @@ buffers will be created displaying the query results and named @chapter Ticket Viewer @cindex ticket viewer -The ticket viewer is an interface for viewing the contents of a -ticket. It provides font-locking to make reading the contents easier -via @var{rt-liber-viewer-font-lock-keywords} and a number of -key-bindings. +The ticket viewer is an interface for viewing the contents of a ticket +and for sending answers. The ticket viewer provides key-bindings to help compose emails to send to the RT email interface. The key-bindings for composing email @@ -634,34 +640,26 @@ them depends on the email-backend system you have installed into rt-liberation. @file{rt-liberation-gnus.el} provides integration with Gnus, @xref{Gnus Integration}. -Setting @var{rt-liber-jump-to-latest} to `t' will cause the viewer to -automatically scroll to the latest comment in a ticket when that -ticket is visited. By default @var{rt-liber-jump-to-latest} is set to -`nil'. - -When in the ticket viewer buffer, invoking -@dfn{rt-liber-viewer-take-ticket} will ``take'' the ticket. - @table @kbd @item q @kindex q (ticket viewer) -@findex rt-liber-viewer-mode-quit +@findex rt-liber-viewer2-mode-quit Bury the ticket viewer buffer. @item n @kindex n (ticket viewer) -@findex rt-liber-next-section-in-viewer -Move point to the next section in ticket. +@findex rt-liber-viewer2-next-section-in +Move to the next section in ticket. @item N @kindex N (ticket viewer) -@findex rt-liber-jump-to-latest-correspondence -Move point to the newest correspondence section, if any. +@findex rt-liber-viewer2-last-section-in +Move to the last section. @item p @kindex p (ticket viewer) -@findex rt-liber-previous-section-in-viewer +@findex rt-liber-viewer2-previous-section-in Move point to the previous section in ticket. @item V @@ -669,43 +667,15 @@ Move point to the previous section in ticket. @findex rt-liber-viewer-visit-in-browser Visit the current ticket in a Web browser. -@item m -@kindex m (ticket viewer) -@findex rt-liber-viewer-answer -Compose an answer to the current ticket. - @item M @kindex M (ticket viewer) -@findex rt-liber-viewer-answer-this +@findex rt-liber-viewer2-answer Compose an answer to the current ticket. The content section around point will be inserted into the email body and commented out. -@item t -@kindex t (ticket viewer) -@findex rt-liber-viewer-answer-provisionally -Compose a provisional answer to the current ticket. - -@item T -@kindex t (ticket viewer) -@findex rt-liber-viewer-answer-provisionally-this -Compose a provisional answer to the current ticket. The content -section around point will be inserted into the email body and -commented out. - -@item F -@kindex F (ticket viewer) -@findex rt-liber-viewer-answer-verbatim-this -Compose an answer to the current ticket. The content section around -point will be inserted into the email body verbatim. - -@item c -@kindex c (ticket viewer) -@findex rt-liber-viewer-comment -Compose a comment for the current ticket. - @item C @kindex C (ticket viewer) -@findex rt-liber-viewer-comment-this +@findex rt-liber-viewer2-comment Comment on the ticket using the current context @item g diff --git a/rt-liber.info b/rt-liber.info index d227b86..c2df1d8 100644 --- a/rt-liber.info +++ b/rt-liber.info @@ -36,7 +36,8 @@ Foundation, Inc. * Menu: * Introduction:: Introduction to rt-liberation. -* Installation:: Setup rt-liberation to work on the system. +* Installation:: Install rt-liberation on the system. +* Configuration:: Setup rt-liberation to work on the system. Using rt-liberation * Queries:: Retrieve particular tickets from the server. @@ -95,21 +96,29 @@ browsing the resulting tickets, viewing the tickets' contents and performing operations on the tickets. -File: rt-liber.info, Node: Installation, Next: Queries, Prev: Introduction, Up: Top +File: rt-liber.info, Node: Installation, Next: Configuration, Prev: Introduction, Up: Top 2 Installation ************** -rt-liberation is available via GNU ELPA. +rt-liberation is available via GNU ELPA. Invoke 'M-x list-packages' and +choose to install the rt-liberation package. - If you install rt-liberation manually instead you'll need to tell -Emacs where to find it, and tell Emacs to load the package: + If you install rt-liberation manually, by copying the code to your +machine, instead you'll need to tell Emacs where to find it, and then +tell Emacs to load the package: (add-to-list 'load-path "/PATH/TO/rt-liberation/") (require 'rt-liberation) - rt-liberation needs to be configured in your ~/.emacs, an ~/.rt-liber + +File: rt-liber.info, Node: Configuration, Next: Queries, Prev: Installation, Up: Top + +3 Configuration +*************** + +rt-liberation needs to be configured in your ~/.emacs, an ~/.rt-liber file, or similar. Tell rt-liberation where to find the RT server's REST interface: @@ -142,9 +151,9 @@ to work the base URL needs to be set in RT-LIBER-BASE-URL. For example: (setq rt-liber-base-url "https://rt.foo.org/") -File: rt-liber.info, Node: Queries, Next: Ticket Browser, Prev: Installation, Up: Top +File: rt-liber.info, Node: Queries, Next: Ticket Browser, Prev: Configuration, Up: Top -3 Queries +4 Queries ********* A typical RT server is meant to manage a large amount of tickets. Much @@ -162,7 +171,7 @@ RT's TicketSQL language. File: rt-liber.info, Node: Query Compiler, Next: Query Language, Up: Queries -3.1 Query Compiler +4.1 Query Compiler ================== In order to browse and view tickets a list of needs to be requested from @@ -178,7 +187,7 @@ number of TicketSQL tokens. File: rt-liber.info, Node: Query Language, Prev: Query Compiler, Up: Queries -3.2 Query Language +4.2 Query Language ================== rt-liberation's Sexp-based query language covers a portion of the @@ -246,7 +255,7 @@ in function calls: File: rt-liber.info, Node: Ticket Browser, Next: Ticket Viewer, Prev: Queries, Up: Top -4 Ticket Browser +5 Ticket Browser **************** The ticket browser is a special buffer which provides a convenient @@ -338,7 +347,7 @@ string, the following is equivalent: File: rt-liber.info, Node: Ticket Browser Display, Next: Ticket Browser Sorting, Up: Ticket Browser -4.1 Ticket Browser Display +5.1 Ticket Browser Display ========================== The ticket browser displays the tickets in the browser by calling @@ -398,7 +407,7 @@ RT-LIBER-BROWSER-PRIORITY-CUTOFF File: rt-liber.info, Node: Ticket Browser Sorting, Next: Ticket Browser Filtering, Prev: Ticket Browser Display, Up: Ticket Browser -4.2 Ticket Browser Sorting +5.2 Ticket Browser Sorting ========================== The tickets in the browser are displayed by default in reverse @@ -445,7 +454,7 @@ functions to perform comparisons between ticket objects: File: rt-liber.info, Node: Ticket Browser Filtering, Next: Multiple Ticket Browsers, Prev: Ticket Browser Sorting, Up: Ticket Browser -4.3 Ticket Browser Filtering +5.3 Ticket Browser Filtering ============================ The Ticket Browser can also filter out (that is, not display) certain @@ -483,7 +492,7 @@ ticket is to be filtered. File: rt-liber.info, Node: Multiple Ticket Browsers, Prev: Ticket Browser Filtering, Up: Ticket Browser -4.4 Multiple Ticket Browsers +5.4 Multiple Ticket Browsers ============================ It is sometimes useful to rename the ticket browser buffer to something @@ -517,12 +526,11 @@ supervisor*" and "*new tickets*" respectively: File: rt-liber.info, Node: Ticket Viewer, Next: Gnus Integration, Prev: Ticket Browser, Up: Top -5 Ticket Viewer +6 Ticket Viewer *************** -The ticket viewer is an interface for viewing the contents of a ticket. -It provides font-locking to make reading the contents easier via -RT-LIBER-VIEWER-FONT-LOCK-KEYWORDS and a number of key-bindings. +The ticket viewer is an interface for viewing the contents of a ticket +and for sending answers. The ticket viewer provides key-bindings to help compose emails to send to the RT email interface. The key-bindings for composing email @@ -531,21 +539,14 @@ depends on the email-backend system you have installed into rt-liberation. 'rt-liberation-gnus.el' provides integration with Gnus, *Note Gnus Integration::. - Setting RT-LIBER-JUMP-TO-LATEST to 't' will cause the viewer to -automatically scroll to the latest comment in a ticket when that ticket -is visited. By default RT-LIBER-JUMP-TO-LATEST is set to 'nil'. - - When in the ticket viewer buffer, invoking -"rt-liber-viewer-take-ticket" will "take" the ticket. - 'q' Bury the ticket viewer buffer. 'n' - Move point to the next section in ticket. + Move to the next section in ticket. 'N' - Move point to the newest correspondence section, if any. + Move to the last section. 'p' Move point to the previous section in ticket. @@ -553,29 +554,11 @@ is visited. By default RT-LIBER-JUMP-TO-LATEST is set to 'nil'. 'V' Visit the current ticket in a Web browser. -'m' - Compose an answer to the current ticket. - 'M' Compose an answer to the current ticket. The content section around point will be inserted into the email body and commented out. -'t' - Compose a provisional answer to the current ticket. - -'T' - Compose a provisional answer to the current ticket. The content - section around point will be inserted into the email body and - commented out. - -'F' - Compose an answer to the current ticket. The content section - around point will be inserted into the email body verbatim. - -'c' - Compose a comment for the current ticket. - 'C' Comment on the ticket using the current context @@ -594,7 +577,7 @@ is visited. By default RT-LIBER-JUMP-TO-LATEST is set to 'nil'. File: rt-liber.info, Node: Gnus Integration, Next: Tracking Updates, Prev: Ticket Viewer, Up: Top -6 Gnus Integration +7 Gnus Integration ****************** The file 'rt-liberation-gnus.el' implements integration with Gnus for @@ -649,7 +632,7 @@ the Viewer will be able to call into it, *Note Ticket Viewer::. File: rt-liber.info, Node: Tracking Updates, Next: Batch Operations, Prev: Gnus Integration, Up: Top -7 Tracking Updates +8 Tracking Updates ****************** The functions in 'rt-liberation-update.el' help keep up with updates to @@ -678,7 +661,7 @@ watch for updates. For example: File: rt-liber.info, Node: Batch Operations, Next: Local Storage, Prev: Tracking Updates, Up: Top -8 Batch Operations +9 Batch Operations ****************** The extension 'rt-liberation-multi.el' implements performing batch @@ -711,8 +694,8 @@ through all of the marked tickets. File: rt-liber.info, Node: Local Storage, Next: Copying, Prev: Batch Operations, Up: Top -9 Local Storage -*************** +10 Local Storage +**************** 'rt-liberation-storage.el' implements associating arbitrary ancillary data with tickets. The data is stored locally and is not sent to the RT @@ -744,7 +727,7 @@ can be extended to associate any arbitrary data with any ticket. File: rt-liber.info, Node: Copying, Next: The GNU FDL, Prev: Local Storage, Up: Top -10 The GNU General Public License. +11 The GNU General Public License. ********************************** Version 3, 29 June 2007 @@ -1460,7 +1443,7 @@ please read <https://www.gnu.org/licenses/why-not-lgpl.html>. File: rt-liber.info, Node: The GNU FDL, Next: Concept Index, Prev: Copying, Up: Top -11 GNU Free Documentation License +12 GNU Free Documentation License ********************************* Version 1.2, November 2002 @@ -1855,7 +1838,7 @@ File: rt-liber.info, Node: The GNU FDL, Next: Concept Index, Prev: Copying, choose any version ever published (not as a draft) by the Free Software Foundation. -11.1 ADDENDUM: How to use this License for your documents +12.1 ADDENDUM: How to use this License for your documents ========================================================= To use this License in a document you have written, include a copy of @@ -1896,6 +1879,7 @@ Concept Index * Menu: * Batch Operations: Batch Operations. (line 6) +* configuration: Configuration. (line 6) * FDL, GNU Free Documentation License: The GNU FDL. (line 6) * Gnus Integration: Gnus Integration. (line 6) * installation: Installation. (line 6) @@ -1926,7 +1910,7 @@ Function Index * Menu: * revert-buffer: Ticket Browser. (line 48) -* revert-buffer <1>: Ticket Viewer. (line 66) +* revert-buffer <1>: Ticket Viewer. (line 40) * rt-liber-browse-query: Ticket Browser. (line 12) * rt-liber-browser-ancillary-text: Local Storage. (line 22) * rt-liber-browser-assign: Ticket Browser. (line 62) @@ -1939,7 +1923,6 @@ Function Index * rt-liber-browser-resolve: Ticket Browser. (line 65) * rt-liber-browser-take-ticket-at-point: Ticket Browser. (line 71) * rt-liber-display-ticket-at-point: Ticket Browser. (line 45) -* rt-liber-jump-to-latest-correspondence: Ticket Viewer. (line 31) * rt-liber-lex-lessthan-p: Ticket Browser Sorting. (line 15) * rt-liber-mark-ticket-at-point: Batch Operations. (line 18) @@ -1948,27 +1931,23 @@ Function Index * rt-liber-multi-flag-as-spam-and-delete: Batch Operations. (line 30) * rt-liber-multi-set-status-open: Batch Operations. (line 21) * rt-liber-multi-set-status-resolved: Batch Operations. (line 24) -* rt-liber-next-section-in-viewer: Ticket Viewer. (line 28) * rt-liber-next-ticket-in-browser: Ticket Browser. (line 39) -* rt-liber-previous-section-in-viewer: Ticket Viewer. (line 34) * rt-liber-previous-ticket-in-browser: Ticket Browser. (line 42) * rt-liber-time-lessthan-p: Ticket Browser Sorting. (line 30) * rt-liber-update: Tracking Updates. (line 17) -* rt-liber-viewer-answer: Ticket Viewer. (line 40) -* rt-liber-viewer-answer-provisionally: Ticket Viewer. (line 48) -* rt-liber-viewer-answer-provisionally-this: Ticket Viewer. (line 51) -* rt-liber-viewer-answer-this: Ticket Viewer. (line 43) -* rt-liber-viewer-answer-verbatim-this: Ticket Viewer. (line 56) -* rt-liber-viewer-comment: Ticket Viewer. (line 60) -* rt-liber-viewer-comment-this: Ticket Viewer. (line 63) -* rt-liber-viewer-mode-quit: Ticket Viewer. (line 25) -* rt-liber-viewer-show-ticket-browser: Ticket Viewer. (line 75) -* rt-liber-viewer-visit-in-browser: Ticket Viewer. (line 37) +* rt-liber-viewer-show-ticket-browser: Ticket Viewer. (line 49) +* rt-liber-viewer-visit-in-browser: Ticket Viewer. (line 29) +* rt-liber-viewer2-answer: Ticket Viewer. (line 32) +* rt-liber-viewer2-comment: Ticket Viewer. (line 37) +* rt-liber-viewer2-last-section-in: Ticket Viewer. (line 23) +* rt-liber-viewer2-mode-quit: Ticket Viewer. (line 17) +* rt-liber-viewer2-next-section-in: Ticket Viewer. (line 20) +* rt-liber-viewer2-previous-section-in: Ticket Viewer. (line 26) * scroll-down: Ticket Browser. (line 77) -* scroll-down <1>: Ticket Viewer. (line 72) +* scroll-down <1>: Ticket Viewer. (line 46) * scroll-up: Ticket Browser. (line 74) -* scroll-up <1>: Ticket Viewer. (line 69) +* scroll-up <1>: Ticket Viewer. (line 43) File: rt-liber.info, Node: Variable Index, Next: Keybinding Index, Prev: Function Index, Up: Top @@ -1994,63 +1973,59 @@ Keybinding Index * a (ticket browser): Ticket Browser. (line 62) * A (ticket browser): Local Storage. (line 22) -* c (ticket viewer): Ticket Viewer. (line 60) -* C (ticket viewer): Ticket Viewer. (line 63) +* C (ticket viewer): Ticket Viewer. (line 37) * DEL (ticket browser): Ticket Browser. (line 77) -* DEL (ticket viewer): Ticket Viewer. (line 72) -* F (ticket viewer): Ticket Viewer. (line 56) +* DEL (ticket viewer): Ticket Viewer. (line 46) * g (ticket browser): Ticket Browser. (line 48) * G (ticket browser): Ticket Browser. (line 51) -* g (ticket viewer): Ticket Viewer. (line 66) -* h (ticket viewer): Ticket Viewer. (line 75) +* g (ticket viewer): Ticket Viewer. (line 40) +* h (ticket viewer): Ticket Viewer. (line 49) * m (ticket browser): Ticket Browser. (line 80) * M (ticket browser): Batch Operations. (line 18) -* m (ticket viewer): Ticket Viewer. (line 40) -* M (ticket viewer): Ticket Viewer. (line 43) +* M (ticket viewer): Ticket Viewer. (line 32) * n (ticket browser): Ticket Browser. (line 39) -* n (ticket viewer): Ticket Viewer. (line 28) -* N (ticket viewer): Ticket Viewer. (line 31) +* n (ticket viewer): Ticket Viewer. (line 20) +* N (ticket viewer): Ticket Viewer. (line 23) * o (ticket browser): Ticket Browser. (line 68) * p (ticket browser): Ticket Browser. (line 42) * P (ticket browser): Ticket Browser. (line 83) -* p (ticket viewer): Ticket Viewer. (line 34) +* p (ticket viewer): Ticket Viewer. (line 26) * q (ticket browser): Ticket Browser. (line 36) -* q (ticket viewer): Ticket Viewer. (line 25) +* q (ticket viewer): Ticket Viewer. (line 17) * r (ticket browser): Ticket Browser. (line 65) * RET (ticket browser): Ticket Browser. (line 45) * s (ticket browser): Ticket Browser. (line 55) * S (ticket browser): Ticket Browser. (line 58) * SPC (ticket browser): Ticket Browser. (line 74) -* SPC (ticket viewer): Ticket Viewer. (line 69) +* SPC (ticket viewer): Ticket Viewer. (line 43) * t (ticket browser): Ticket Browser. (line 71) -* t (ticket viewer): Ticket Viewer. (line 48) -* t (ticket viewer) <1>: Ticket Viewer. (line 51) -* V (ticket viewer): Ticket Viewer. (line 37) +* V (ticket viewer): Ticket Viewer. (line 29) Tag Table: Node: Top680 -Node: Introduction2956 -Node: Installation3563 -Node: Queries5135 -Node: Query Compiler5697 -Node: Query Language6338 -Node: Ticket Browser8777 -Node: Ticket Browser Display11249 -Node: Ticket Browser Sorting13240 -Node: Ticket Browser Filtering15190 -Node: Multiple Ticket Browsers16733 -Node: Ticket Viewer17902 -Node: Gnus Integration20074 -Node: Tracking Updates22362 -Node: Batch Operations23439 -Node: Local Storage24619 -Node: Copying25697 -Node: The GNU FDL63246 -Node: Concept Index85638 -Node: Function Index87219 -Node: Variable Index90569 -Node: Keybinding Index90945 +Node: Introduction3025 +Node: Installation3632 +Node: Configuration4139 +Node: Queries5451 +Node: Query Compiler6014 +Node: Query Language6655 +Node: Ticket Browser9094 +Node: Ticket Browser Display11566 +Node: Ticket Browser Sorting13557 +Node: Ticket Browser Filtering15507 +Node: Multiple Ticket Browsers17050 +Node: Ticket Viewer18219 +Node: Gnus Integration19478 +Node: Tracking Updates21766 +Node: Batch Operations22843 +Node: Local Storage24023 +Node: Copying25103 +Node: The GNU FDL62652 +Node: Concept Index85044 +Node: Function Index86698 +Node: Variable Index89683 +Node: Keybinding Index90059 End Tag Table