From 3ef62a0570055da710328937e7f65dbb2c027c62 Mon Sep 17 00:00:00 2001
From: ivan <ivan>
Date: Mon, 12 Aug 2002 06:17:09 +0000
Subject: import rt 2.0.14

---
 rt/docs/design_docs/cli_spec | 354 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 354 insertions(+)
 create mode 100644 rt/docs/design_docs/cli_spec

(limited to 'rt/docs/design_docs/cli_spec')

diff --git a/rt/docs/design_docs/cli_spec b/rt/docs/design_docs/cli_spec
new file mode 100644
index 000000000..48a7f34e1
--- /dev/null
+++ b/rt/docs/design_docs/cli_spec
@@ -0,0 +1,354 @@
+
+Find tickets to operate on:
+        --id=<tickets>          Find only tickets in the range <tickets>
+                synonyms:
+                --limit-id, --tickets, --limit-tickets
+        --limit-queue=<queue>
+        --limit-status=<status>
+        --limit-owner=<owner>
+        --limit-priority=<priority>
+        --limit-requestor=<email>
+        --limit-subject=<string>      (Subject contains)
+        --limit-body=<string>         (body contains)
+        --limit-created=(before/after) <date>
+        --limit-due=(before/after) <date>
+        --limit-starts=(before/after) <date>
+        --limit-started=(before/after) <date>
+
+        --limit-first=<int>           Start on the <int>th row returned by the
+                                database  
+        --limit-rows=<int>      Find only <int> rows
+
+Display:
+        --show                  shows a ticket history
+        --history               ditto
+
+        --summary               default option. shows a ticket summary
+                --format        Optional format string. If not specified,
+                                uses the value of ENV{'RT_LISTING_FORMAT'}
+                                or an internal default
+        
+
+Basic ticket editing:
+
+	--status=(open|stall|resolve|kill)
+	--subject=<string>
+        --owner=<owner>
+	--queue=<queue>
+	--time-left=<minutes>
+
+Watcher-related editing:
+
+	--add-requestor=<email>
+	--del-requestor=<email>
+	--add-cc=<email>
+	--del-cc=<email>
+	--add-admincc=<email>
+	--del-admincc=<email>
+
+Priority related editing:
+
+	--priority=<int>
+	--final-priority=<int>
+
+Date related editing:
+
+	--due=date
+	--starts=date
+	--started=date
+	--contacted=date
+
+
+
+Ticket updates:
+
+	--comment 
+	--reply | --respond 
+
+
+Links
+
+	--add-link 
+		--type=<DependsOn|MemberOf|RelatedTo>
+		needs one of:
+		   --target=<ticketid> 
+		   --base=<ticketid>
+
+	--del-link <link-id>
+
+
+
+Condiments:
+	any update can take:
+
+		--time-taken <minutes>
+
+	Ticket updates can take:
+
+		--source 	-- specify a source file to read the content from
+		--edit		= give me an editor to edit the message
+		--no-edit	= don't give me an editor to edit the message.
+
+
+
+
+----- Forwarded message from deborah kaplan <deborah@curl.com> -----
+
+Date: Fri, 14 Apr 2000 11:43:18 -0400 (EDT)
+From: deborah kaplan <deborah@curl.com>
+To: Jesse <jesse@fsck.com>
+Subject: Re: [rt-devel] RT Projects list
+
+Finally, here is the functional spec for the command line
+interface.  This is for the user interface only; if you think
+this is right, I will add the administrative interface as well.
+Should I post to rt-devel, add to the ticket, or just modify
+based on your kibbitzing?  When you are happy with it I'll start
+the code.
+
+-deborah
+
+
+RT command line interface functional specification
+Author: Deborah Kaplan (Deborah@suberic.net)
+Version:0.1
+
+Requirements: 
+
+RT needs a CLI for various reasons.  If a user is restricted to a
+dumb terminal, she needs to be able to access the RT database and
+manipulate it fully.  The full functionality of both the RT
+database and the RT administrative interface should be available
+from this CLI.
+
+There are two possible types of CLI which I will discuss here.
+The first is a curses-style interface, which allows the user to
+move about a series of menus and choices, usually using arrow
+keys.  As RT supplies a Web interface, there is no need for this
+curses-style interface to be written as part of RT.  Instead, the
+RT developers should pick one tty-based Web browser (e.g. lynx,
+w3m) and make sure that all of the RT pages are easily readable
+with that tty based browser.  Installation of that browser should
+be recommended in the RT installation documentation as a
+supported method of accessing RT from a tty.
+
+The second possible type of CLI is more minimal: a series of
+commands which can be run at a UNIX command prompt which provide
+full functionality to the RT database and administrative
+interface.  There are two major benefits to this second type of
+CLI.  First of all, in order to use this CLI, you need no extra
+tools (Web browsers, etc.).  All that is required is a UNIX
+command line prompt and an installation of RT.  Secondly, a user
+of RT who has a very specific command to run and who knows the
+appropriate CLI commands can accomplish her task much more
+quickly with a single command then she could navigating through a
+menu based interface.
+
+In the specification, I will describe the second type of CLI.
+
+Caveats:
+
+This specification draws heavily on the structure of formatting
+command line options for cvs.  RT faces a smaller version of the
+same kinds of problems cvs faces: we want to create a very rich
+command set without sacrificing ease-of-use. 
+
+I am not wedded to any specific command names if they seem
+impractical; I merely am proposing the command names that seem
+reasonable to me at this moment.
+
+Finally, I am finding the functioning of the web UI from RT 1.
+If the functionality differs greatly in RT 2, I will need to
+modify this specification.
+
+Specification:
+
+There are two commands: "rt", which is the primary interface to
+the database, and "rtadmin", which is the administrative
+interface to the database.
+
+The format of an rt command is as follows:
+
+ rt <command> 
+    <command> is one of:
+
+    - help
+      print an overview of the commands which can be run
+
+    - print <queue> <options> 
+      with no options, dump to the screen a list of all open
+      requests in <queue> -- the equivalent of "Display Queue" in
+      the existing Web interface.
+
+      <queue> is the name of an RT queue
+      <option> is either:
+
+        -f <filename> |  --filename <filename>
+	   where <filename> is the name of a file (defaulting to
+	   ~/.rtrc) in which the options described below can be
+	   placed in the format "^ <long option name> <option value>
+	   $".
+
+        Or a series of the following options:
+
+        -o <owner name> |  --owner <owner name>: restrict tickets
+	viewed to those owned by <owner name>.
+	   This option can be used multiple times in one call of
+	   the rt command in order to produce a list which
+	   contains tickets owned by multiple owners.  Giving the
+	   empty string ("") as an option to this switch will
+	   restrict tickets viewed to those which have no owner.
+	   If this switch is given with no argument, the option
+	   defaults to the user name of the currently running
+	   process.
+
+        -r <requestor name> | --requestor <requestor name>:
+	restrict tickets viewed to those requested by <requestor
+	name>.
+	   This option can be used multiple times in one call of
+	   the rt command in order to produce a list which
+	   contains tickets requested by multiple requesters.  If
+	   this switch is given with no arguments, it produces an
+	   error.
+
+        -s <status> | --status <status>: restrict tickets viewed
+	to those with the status named in <status>.
+	   This option can be used multiple times in one call of
+	   the rt command in order to produce a list which
+	   contains tickets with multiple statuses (statii?
+	   Dragon NaturallySpeaking recognizes "statuses" as a
+	   word).  This option defaults to status "open".
+
+        -j <subject> | --subject <subject>: restrict tickets
+	viewed to those which contain <subject> as a substring in
+	the subject field of the ticket.
+	   This command can be used multiple times in one call of
+	   the rt command in order to produce a list which
+	   contains tickets with various subject substrings.  If
+	   the option is called with no argument, the result is
+	   an error.
+
+        -h | --help: print a usage message.
+
+        -n | --number: print out a specific ticket.
+	   This command can be used multiple times to produce a
+	   list which contains multiple tickets.  If the option
+	   is called with no argument, the result is an error.
+
+    This completes all of the print options which are available
+    in the Web interface, except the sort options.  I maintain
+    that this command is already excessively complex, and that
+    adding functionality which can be replicated easily by
+    standard UNIX tools is unnecessary added complexity.  I
+    recommend that the man pages and documentation for this
+    option contain an example of a command line run (e.g. of rt |
+    awk) which replicates the sorting functionality provided by
+    the Web interface.
+
+    - edit <ticket> <options>
+      with no options, or with no <ticket>, produces the same
+      output as the --help option.
+      Otherwise, edits the ticket with number <ticket> as
+      indicated in the options given.  All options listed below
+      except for --help and --number can be used in conjunction
+      with one another to change many features of the same ticket
+      all at once.
+
+        -h | --help: print usage message
+
+        -s <status> | --status <status>: change the status to the
+	status listed in <status>.
+	   No <status> listed, or 1 listed it does not come from
+	   a list of approve statuses, produces an error.
+
+        -o <owner name> |  --owner <owner name>: set to the owner
+	of the ticket the owner named.
+	   Follows whatever convention is finally decided on for
+	   the requirement to steal a ticket that is owned by
+	   somebody else.  No <owner named> listed has the user
+	   who is running the rt program take the ticket.  If
+	   that user is not a valid owner, or the 1 listed does
+	   not come from a list of approve names, produces an
+	   error.
+
+        -r <requestor name> | --requestor <requestor name>: sets
+	the requestor to <requestor name>.
+	   Follows any conventions that the Web UI follows to
+	   make sure that this is a legal name.  If not legal, or
+	   left blank, produces an error.
+
+        -j <subject> | --subject <subject>:  sets the subject of
+	the ticket to <subject>.
+	   If the option is called with no argument, the result
+	   is an error.
+
+        -n <number one> <number 2> | --number <number one>
+	<number 2>: merges ticket number <number one> into ticket
+	<number 2>.
+	   If both arguments are not provided, the result is an
+	   error.
+
+        -q <queue> | --queue <queue>: set the queue to that
+	named.
+	   If <queue> is not listed, or the 1 listed does not
+	   come from a list of approve queues, produces an
+	   error.
+
+        -a <area> | --area <area>: set the area of the ticket to
+	that named.
+	   If <area> is not listed, or the 1 listed does not come
+	   from a list of approve areas, produces an error.
+
+        -c <time stamp> | --contact <time stamp>: sets the last
+	user contact field, and produces an error if the format
+	is invalid.
+	   If the argument is left blank, sets the last user
+	   contact field to now.
+
+        -p <priority> | --priority <priority>: sets the current
+	priority to the 1 listed.
+	   Produces an error if the argument is left blank.
+
+        -f <priority> | --final <priority>: sets the final
+	priority to the 1 listed.
+	   Produces an error if the arguments left blank.
+
+        -d <date due> | --datedue <date due>: sets the due date
+	to the 1 listed.
+	   Produces an error if the argument is left blank, or if
+	   the format is invalid.
+
+    - comment <options>
+      with no options, this command reads from standard input
+      until it sees EOF and appends that to the ticket as a
+      comment.
+
+        -h | --help: print usage message
+
+        -c | --comment: append as a comment.  This is the default behavior.
+
+        -r | --reply: append as a reply.
+
+        -f <filename> | --file <filename>: can be used with
+	either the comment or reply options.  Instead of reading
+	from standard input, read the text of the comment or
+	reply from the file <filename>.
+
+    - report <options>
+      this command is a place holder for reporting functionality
+      which does not yet exist.  It will probably have the
+      default behavior to select reports at the command line or
+      choose default reports from a .rtrc file.  In a future
+      version, it can output graphs in some graphical format.
+
+
+
+----- End forwarded message -----
+
+-- 
+jesse reed vincent -- root@eruditorum.org -- jesse@fsck.com 
+70EBAC90: 2A07 FC22 7DB4 42C1 9D71 0108 41A3 3FB3 70EB AC90
+
+"If IBM _wanted_ to make clones, we could make them cheaper and faster than
+anyone else!"  - An IBM Rep. visiting Vassar College's Comp Sci Department.
+
-- 
cgit v1.2.1


From ded0451e9582df33cae6099a2fb72b4ea25076cf Mon Sep 17 00:00:00 2001
From: ivan <ivan>
Date: Tue, 15 Jul 2003 13:30:43 +0000
Subject: reverting to vendor branch rt 3.0.4, hopefully

---
 rt/docs/design_docs/cli_spec | 361 +++----------------------------------------
 1 file changed, 19 insertions(+), 342 deletions(-)

(limited to 'rt/docs/design_docs/cli_spec')

diff --git a/rt/docs/design_docs/cli_spec b/rt/docs/design_docs/cli_spec
index 48a7f34e1..ae5f29f76 100644
--- a/rt/docs/design_docs/cli_spec
+++ b/rt/docs/design_docs/cli_spec
@@ -1,354 +1,31 @@
 
-Find tickets to operate on:
-        --id=<tickets>          Find only tickets in the range <tickets>
-                synonyms:
-                --limit-id, --tickets, --limit-tickets
-        --limit-queue=<queue>
-        --limit-status=<status>
-        --limit-owner=<owner>
-        --limit-priority=<priority>
-        --limit-requestor=<email>
-        --limit-subject=<string>      (Subject contains)
-        --limit-body=<string>         (body contains)
-        --limit-created=(before/after) <date>
-        --limit-due=(before/after) <date>
-        --limit-starts=(before/after) <date>
-        --limit-started=(before/after) <date>
+Things the cli must do
+	create ticket
+	comment
+	reply
+	update ticket metadata
+	search for tickets
+	update a bunch of tickets.
+	list tickets
+        login/logout
 
-        --limit-first=<int>           Start on the <int>th row returned by the
-                                database  
-        --limit-rows=<int>      Find only <int> rows
 
-Display:
-        --show                  shows a ticket history
-        --history               ditto
+should support multiple rt servers
 
-        --summary               default option. shows a ticket summary
-                --format        Optional format string. If not specified,
-                                uses the value of ENV{'RT_LISTING_FORMAT'}
-                                or an internal default
-        
+create/edit/update should use EDITOR or take from a file or stdin
 
-Basic ticket editing:
+should be able to update ticket sttributes from a commandline without invoking an editor or needing to use stdin.
 
-	--status=(open|stall|resolve|kill)
-	--subject=<string>
-        --owner=<owner>
-	--queue=<queue>
-	--time-left=<minutes>
+login/logout should store RT session cookies rather than constantly transmitting the username/password combo.
 
-Watcher-related editing:
+rtserver and rt username should come from env variables. but should be able to be overridden by commandline options. 
 
-	--add-requestor=<email>
-	--del-requestor=<email>
-	--add-cc=<email>
-	--del-cc=<email>
-	--add-admincc=<email>
-	--del-admincc=<email>
+rt password should be able to be specified on the commandline (say from a script) or, failing that be prompted for within the application (as rt's sbin/initdb script does) ...or maybe able to be read from a stash file on disk.
 
-Priority related editing:
+must be able to dowaload attachments from cli.
+ 
+ it might also be cool to be able to generate session-length urls for attavhments so you can use a browser. but that's not necessary.
 
-	--priority=<int>
-	--final-priority=<int>
 
-Date related editing:
-
-	--due=date
-	--starts=date
-	--started=date
-	--contacted=date
-
-
-
-Ticket updates:
-
-	--comment 
-	--reply | --respond 
-
-
-Links
-
-	--add-link 
-		--type=<DependsOn|MemberOf|RelatedTo>
-		needs one of:
-		   --target=<ticketid> 
-		   --base=<ticketid>
-
-	--del-link <link-id>
-
-
-
-Condiments:
-	any update can take:
-
-		--time-taken <minutes>
-
-	Ticket updates can take:
-
-		--source 	-- specify a source file to read the content from
-		--edit		= give me an editor to edit the message
-		--no-edit	= don't give me an editor to edit the message.
-
-
-
-
------ Forwarded message from deborah kaplan <deborah@curl.com> -----
-
-Date: Fri, 14 Apr 2000 11:43:18 -0400 (EDT)
-From: deborah kaplan <deborah@curl.com>
-To: Jesse <jesse@fsck.com>
-Subject: Re: [rt-devel] RT Projects list
-
-Finally, here is the functional spec for the command line
-interface.  This is for the user interface only; if you think
-this is right, I will add the administrative interface as well.
-Should I post to rt-devel, add to the ticket, or just modify
-based on your kibbitzing?  When you are happy with it I'll start
-the code.
-
--deborah
-
-
-RT command line interface functional specification
-Author: Deborah Kaplan (Deborah@suberic.net)
-Version:0.1
-
-Requirements: 
-
-RT needs a CLI for various reasons.  If a user is restricted to a
-dumb terminal, she needs to be able to access the RT database and
-manipulate it fully.  The full functionality of both the RT
-database and the RT administrative interface should be available
-from this CLI.
-
-There are two possible types of CLI which I will discuss here.
-The first is a curses-style interface, which allows the user to
-move about a series of menus and choices, usually using arrow
-keys.  As RT supplies a Web interface, there is no need for this
-curses-style interface to be written as part of RT.  Instead, the
-RT developers should pick one tty-based Web browser (e.g. lynx,
-w3m) and make sure that all of the RT pages are easily readable
-with that tty based browser.  Installation of that browser should
-be recommended in the RT installation documentation as a
-supported method of accessing RT from a tty.
-
-The second possible type of CLI is more minimal: a series of
-commands which can be run at a UNIX command prompt which provide
-full functionality to the RT database and administrative
-interface.  There are two major benefits to this second type of
-CLI.  First of all, in order to use this CLI, you need no extra
-tools (Web browsers, etc.).  All that is required is a UNIX
-command line prompt and an installation of RT.  Secondly, a user
-of RT who has a very specific command to run and who knows the
-appropriate CLI commands can accomplish her task much more
-quickly with a single command then she could navigating through a
-menu based interface.
-
-In the specification, I will describe the second type of CLI.
-
-Caveats:
-
-This specification draws heavily on the structure of formatting
-command line options for cvs.  RT faces a smaller version of the
-same kinds of problems cvs faces: we want to create a very rich
-command set without sacrificing ease-of-use. 
-
-I am not wedded to any specific command names if they seem
-impractical; I merely am proposing the command names that seem
-reasonable to me at this moment.
-
-Finally, I am finding the functioning of the web UI from RT 1.
-If the functionality differs greatly in RT 2, I will need to
-modify this specification.
-
-Specification:
-
-There are two commands: "rt", which is the primary interface to
-the database, and "rtadmin", which is the administrative
-interface to the database.
-
-The format of an rt command is as follows:
-
- rt <command> 
-    <command> is one of:
-
-    - help
-      print an overview of the commands which can be run
-
-    - print <queue> <options> 
-      with no options, dump to the screen a list of all open
-      requests in <queue> -- the equivalent of "Display Queue" in
-      the existing Web interface.
-
-      <queue> is the name of an RT queue
-      <option> is either:
-
-        -f <filename> |  --filename <filename>
-	   where <filename> is the name of a file (defaulting to
-	   ~/.rtrc) in which the options described below can be
-	   placed in the format "^ <long option name> <option value>
-	   $".
-
-        Or a series of the following options:
-
-        -o <owner name> |  --owner <owner name>: restrict tickets
-	viewed to those owned by <owner name>.
-	   This option can be used multiple times in one call of
-	   the rt command in order to produce a list which
-	   contains tickets owned by multiple owners.  Giving the
-	   empty string ("") as an option to this switch will
-	   restrict tickets viewed to those which have no owner.
-	   If this switch is given with no argument, the option
-	   defaults to the user name of the currently running
-	   process.
-
-        -r <requestor name> | --requestor <requestor name>:
-	restrict tickets viewed to those requested by <requestor
-	name>.
-	   This option can be used multiple times in one call of
-	   the rt command in order to produce a list which
-	   contains tickets requested by multiple requesters.  If
-	   this switch is given with no arguments, it produces an
-	   error.
-
-        -s <status> | --status <status>: restrict tickets viewed
-	to those with the status named in <status>.
-	   This option can be used multiple times in one call of
-	   the rt command in order to produce a list which
-	   contains tickets with multiple statuses (statii?
-	   Dragon NaturallySpeaking recognizes "statuses" as a
-	   word).  This option defaults to status "open".
-
-        -j <subject> | --subject <subject>: restrict tickets
-	viewed to those which contain <subject> as a substring in
-	the subject field of the ticket.
-	   This command can be used multiple times in one call of
-	   the rt command in order to produce a list which
-	   contains tickets with various subject substrings.  If
-	   the option is called with no argument, the result is
-	   an error.
-
-        -h | --help: print a usage message.
-
-        -n | --number: print out a specific ticket.
-	   This command can be used multiple times to produce a
-	   list which contains multiple tickets.  If the option
-	   is called with no argument, the result is an error.
-
-    This completes all of the print options which are available
-    in the Web interface, except the sort options.  I maintain
-    that this command is already excessively complex, and that
-    adding functionality which can be replicated easily by
-    standard UNIX tools is unnecessary added complexity.  I
-    recommend that the man pages and documentation for this
-    option contain an example of a command line run (e.g. of rt |
-    awk) which replicates the sorting functionality provided by
-    the Web interface.
-
-    - edit <ticket> <options>
-      with no options, or with no <ticket>, produces the same
-      output as the --help option.
-      Otherwise, edits the ticket with number <ticket> as
-      indicated in the options given.  All options listed below
-      except for --help and --number can be used in conjunction
-      with one another to change many features of the same ticket
-      all at once.
-
-        -h | --help: print usage message
-
-        -s <status> | --status <status>: change the status to the
-	status listed in <status>.
-	   No <status> listed, or 1 listed it does not come from
-	   a list of approve statuses, produces an error.
-
-        -o <owner name> |  --owner <owner name>: set to the owner
-	of the ticket the owner named.
-	   Follows whatever convention is finally decided on for
-	   the requirement to steal a ticket that is owned by
-	   somebody else.  No <owner named> listed has the user
-	   who is running the rt program take the ticket.  If
-	   that user is not a valid owner, or the 1 listed does
-	   not come from a list of approve names, produces an
-	   error.
-
-        -r <requestor name> | --requestor <requestor name>: sets
-	the requestor to <requestor name>.
-	   Follows any conventions that the Web UI follows to
-	   make sure that this is a legal name.  If not legal, or
-	   left blank, produces an error.
-
-        -j <subject> | --subject <subject>:  sets the subject of
-	the ticket to <subject>.
-	   If the option is called with no argument, the result
-	   is an error.
-
-        -n <number one> <number 2> | --number <number one>
-	<number 2>: merges ticket number <number one> into ticket
-	<number 2>.
-	   If both arguments are not provided, the result is an
-	   error.
-
-        -q <queue> | --queue <queue>: set the queue to that
-	named.
-	   If <queue> is not listed, or the 1 listed does not
-	   come from a list of approve queues, produces an
-	   error.
-
-        -a <area> | --area <area>: set the area of the ticket to
-	that named.
-	   If <area> is not listed, or the 1 listed does not come
-	   from a list of approve areas, produces an error.
-
-        -c <time stamp> | --contact <time stamp>: sets the last
-	user contact field, and produces an error if the format
-	is invalid.
-	   If the argument is left blank, sets the last user
-	   contact field to now.
-
-        -p <priority> | --priority <priority>: sets the current
-	priority to the 1 listed.
-	   Produces an error if the argument is left blank.
-
-        -f <priority> | --final <priority>: sets the final
-	priority to the 1 listed.
-	   Produces an error if the arguments left blank.
-
-        -d <date due> | --datedue <date due>: sets the due date
-	to the 1 listed.
-	   Produces an error if the argument is left blank, or if
-	   the format is invalid.
-
-    - comment <options>
-      with no options, this command reads from standard input
-      until it sees EOF and appends that to the ticket as a
-      comment.
-
-        -h | --help: print usage message
-
-        -c | --comment: append as a comment.  This is the default behavior.
-
-        -r | --reply: append as a reply.
-
-        -f <filename> | --file <filename>: can be used with
-	either the comment or reply options.  Instead of reading
-	from standard input, read the text of the comment or
-	reply from the file <filename>.
-
-    - report <options>
-      this command is a place holder for reporting functionality
-      which does not yet exist.  It will probably have the
-      default behavior to select reports at the command line or
-      choose default reports from a .rtrc file.  In a future
-      version, it can output graphs in some graphical format.
-
-
-
------ End forwarded message -----
-
--- 
-jesse reed vincent -- root@eruditorum.org -- jesse@fsck.com 
-70EBAC90: 2A07 FC22 7DB4 42C1 9D71 0108 41A3 3FB3 70EB AC90
-
-"If IBM _wanted_ to make clones, we could make them cheaper and faster than
-anyone else!"  - An IBM Rep. visiting Vassar College's Comp Sci Department.
+I'm envisioning this as similar to the subversion cli, actually. 
 
-- 
cgit v1.2.1