On Mon, Jun 30, 2008 at 04:14:52PM +1000, Trent W. Buck wrote: > On Mon, Jun 30, 2008 at 12:10:26PM +1000, Trent W. Buck wrote: >> PS: I home to clean up this script a little in subsequent posts, >> but I'll probably get distracted. > See attached for a significantly improved version.
In the end I got sick of this; it occurred to me that you probably aren't re-generating the manpage from the pod data every time you build a .deb, so I might as well just hand-write the replacement manpage. See attached for the finished version.
.TH rt 1 .SH NAME rt \- command-line interface to Request Tracker 3.0 or newer .SH SYNOPSIS \f[B]rt\f[R] <\f[I]action\f[R]> [\f[I]options\f[R]] [\f[I]arguments\f[R]] or \f[B]rt\f[R] shell .SH DESCRIPTION .B rt allows you to interact with an RT server over HTTP, and offers an interface to RT's functionality that is better-suited to automation and integration with other tools. Each invocation of this program must specify an action (e.g. edit, create), options to modify behaviour, and other arguments required by the specified action. (For example, most actions expect a list of numeric object IDs to act upon.) The details of the syntax and arguments for each action are given in \f[I]ACTIONS\f[R]. Some actions may be referred to by more than one name (`create' is the same as `new', for example). You may also call `rt shell', which will give you an `rt>' prompt at which you can issue commands. Objects are identified by a type and an ID (which can be a name or a number, depending on the type). For some actions, the object type is implied (you can only comment on tickets); for others, the user must specify it explicitly. .SH OBJECTS Syntax: <\f[I]type\f[R]>/<\f[I]id\f[R]>[/<\f[I]attributes\f[R]>] Every object in RT has a type (e.g. `ticket', `queue') and a numeric ID. Some types of objects can also be identified by name (like users and queues). Furthermore, objects may have named attributes (such as `ticket/1/history'). An object specification is like a path in a virtual filesystem, with object types as top-level directories, object IDs as subdirectories, and named attributes as further subdirectories. A comma-separated list of names, numeric IDs, or numeric ranges can be used to specify more than one object of the same type. Note that the list must be a single argument (i.e., no spaces). For example, `user/root,1-3,5,7-10,ams' is a list of ten users; the same list can also be written as `user/ams,root,1,2,3,5,7,8-10'. .SH FORMS This program uses RFC822 header-style forms to represent object data in a form that's suitable for processing both by humans and scripts. A form is a set of (field, value) specifications, with some initial commented text and interspersed blank lines allowed for convenience. Field names may appear more than once in a form; a comma-separated list of multiple field values may also be specified directly. Field values can be wrapped as in RFC822, with leading whitespace. The longest sequence of leading whitespace common to all the lines is removed (preserving further indentation). There is no limit on the length of a value. Multiple forms are separated by a line containing only `--\\n'. .\" A more detailed specification will be provided soon. For now, .\" the server-side syntax checking will suffice. .SH QUERIES RT3 uses an SQL-like syntax to specify object selection constraints. See the <RT:...> documentation for details. .\" I'm going to have to write it, aren't I? .SH TYPES You can currently operate on the following types of objects: .SS Tickets Tickets are identified by a numeric ID. In addition to the generic operations list, show, edit and create, the following ticket-specific actions exist: link, merge, comment and correspond. The following attributes can be used with `rt show' or `rt edit' to retrieve or edit other information associated with tickets: .TP 24 links A ticket's relationships with others. .TP history All of a ticket's transactions. .TP history/type/<type> Only a particular type of transaction. .TP history/id/<id> Only the transaction of the specified id. .TP attachments A list of attachments. .TP attachments/<id> The metadata for an individual attachment. .TP attachments/<id>/content The content of an individual attachment. .SS Users and Groups Users and groups are identified by name or numeric ID. In addition to the generic operations list, show, edit and create, the following type-specific actions exist: grant and revoke. The following attributes can be used with `rt show' or `rt edit' to retrieve or edit other information associated with users and groups: .TP 24 rights Global rights granted to this user. .TP rights/<queue> Queue rights for this user. .SS Queues Queues are identified by name or numeric ID. Currently, they can be subjected to the following actions: show, edit and create. .SH "COMMANDS (ACTIONS)" You can currently perform the following actions: .SS rt <ls|list|search> [options] "query string" Displays a list of objects matching the specified conditions. (`ls', `list', and `search' are synonyms.) Conditions are expressed in the SQL-like syntax used internally by RT3. (For more information, see \f[I]QUERIES\f[R].) The query string must be supplied as one argument. (Right now, the server doesn't support listing anything but tickets. Other types will be supported in future; this client will be able to take advantage of that support without any changes.) The following options control how much information is displayed about each matching object: .TP 16 -i Numeric IDs only. (Useful for |rt edit -; see \f[I]EXAMPLES\f[R].) .TP -s Short description. .TP -l Longer description. .PP In addition, .TP 16 -o +/-<field> Orders the returned list by the specified field. .TP -S var=val Submits the specified variable with the request. .TP -t type Specifies the type of object to look for. (The default is ticket.) .SS rt show [options] <object-ids> Displays details of the specified objects. For some types, object information is further classified into named attributes (for example, `1-3/links' is a valid ticket specification that refers to the links for tickets 1-3). Consult \f[I]TYPES\f[R] and \f[I]OBJECTS\f[R] for further details. This command writes a set of forms representing the requested object data to STDOUT. Options: .TP 16 - Read IDs from STDIN instead of the command-line. .TP -t type Specifies object type. .TP -f a,b,c Restrict the display to the specified fields. .TP -S var=val Submits the specified variable with the request. .TP -v Verbose display .SS rt edit [options] <object-ids> [<set|add|del> field=value [field=value] ...] Edits information corresponding to the specified objects. If, instead of `edit', an action of `new' or `create' is specified, then a new object is created. In this case, no numeric object IDs may be specified, but the syntax and behaviour remain otherwise unchanged. This command typically starts an editor to allow you to edit object data in a form for submission. If you specified enough information on the command-line, however, it will make the submission directly. The command line may specify field-values in three different ways. `set' sets the named field to the given value, `add' adds a value to a multi-valued field, and `del' deletes the corresponding value. Each `field=value' specification must be given as a single argument. For some types, object information is further classified into named attributes (for example, `1-3/links' is a valid ticket specification that refers to the links for tickets 1-3). These attributes may also be edited. Consult \f[I]TYPES\f[R] and \f[I]OBJECTS\f[R] for further details. Options: .TP 16 - Read numeric IDs from STDIN instead of the command-line. (Useful with rt ls ... | rt edit -; see examples below.) .TP -i Read a completed form from STDIN before submitting. .TP -o Dump the completed form to STDOUT instead of submitting. .TP -e Allows you to edit the form even if the command-line has enough information to make a submission directly. .TP -S var=val Submits the specified variable with the request. .TP -t type Specifies object type. .SS rt <comment|correspond> [options] <ticket-id> Adds a comment (or correspondence) to the specified ticket (the only difference being that comments aren't sent to the requestors.) This command will typically start an editor and allow you to type a comment into a form. If, however, you specified all the necessary information on the command line, it submits the comment directly. (See \f[I]FORMS\f[R] for more information about forms.) Options: .TP 16 -m <text> Specify comment text. .TP -a <file> Attach a file to the comment. (May be used more than once to attach multiple files.) .TP -c <addrs> A comma-separated list of Cc addresses. .TP -b <addrs> A comma-separated list of Bcc addresses. .TP -w <time> Specify the time spent working on this ticket. .TP -e Starts an editor before the submission, even if arguments from the command line were sufficient. .SS rt merge <from-id> <to-id> Merges the first ticket specified into the second ticket specified. .SS rt link [-d] <id-A> <link> <id-B> Creates (or, with -d, deletes) a link between the specified tickets. The link can (irrespective of case) be any of: .TP 32 DependsOn (DependedOnBy) A depends upon B (or vice versa). .TP RefersTo (ReferredToBy) A refers to B (or vice versa). .TP MemberOf (HasMember) A is a member of B (or vice versa). .PP To view a ticket's links, use `rt show ticket/3/links'. Options: .TP 8 -d Deletes the specified link. .SS rt <take|untake|steal> <ticket-id> Sets the owner of the specified ticket to the current user, assuming said user has the bits to do so, or releases the ticket. `Take' is used on tickets which are not currently owned (Owner: Nobody), `steal' is used on tickets which *are* currently owned, and `untake' is used to `release' a ticket (reset its Owner to Nobody). `Take' cannot be used on tickets which are currently owned. .SS rt <grant|revoke> .SS rt logout Terminates the currently established login session. You will need to provide authentication credentials before you can continue using the server. (See \f[I]FILES\f[R] and \f[I]ENVIRONMENT\f[R] for details about authentication.) .SS rt shell Opens an interactive shell, at which you can issue commands. To exit the shell, type `quit' or `exit'. Commands can be given at the shell in the same form as they would be given at the command line without the leading 'rt' invocation. .SS rt <quit|exit> Use `quit' or `exit' to leave the shell. Only valid within shell mode. .SH EXAMPLES .SS Objects ticket/1 ticket/1/attachments ticket/1/attachments/3 ticket/1/attachments/3/content ticket/1-3/links ticket/1-3,5-7/history user/ams user/ams/rights user/ams,rai,1/rights .SS Commands rt ls "Priority > 5 and Status='new'" rt ls -o +Subject "Priority > 5 and Status='new'" rt ls -o -Created "Priority > 5 and Status='new'" rt ls -i "Priority > 5"|rt edit - set status=resolved rt ls -t ticket "Subject like '[PATCH]%'" rt show -t ticket -f id,subject,status 1-3 rt show ticket/3/attachments/29 rt show ticket/3/attachments/29/content rt show ticket/1-3/links rt show ticket/3/history rt show -v ticket/3/history rt show -t user 2 # Interactive (starts $EDITOR with a form). rt edit ticket/3 rt create -t ticket # Non-interactive. rt edit ticket/1-3 \\ add [EMAIL PROTECTED] \\ set priority=3 rt ls -t tickets -i 'Priority > 5' | rt edit - set status=resolved rt edit ticket/4 \\ set priority=3 [EMAIL PROTECTED] \\ add [EMAIL PROTECTED] [EMAIL PROTECTED] rt create -t ticket \\ set subject='new ticket' priority=10 \\ add [EMAIL PROTECTED] rt comment -m 'Not worth fixing.' -a stddisclaimer.h 23 rt link 2 dependson 3 rt link -d 4 referredtoby 6 # 6 no longer refers to 4 $ rt shell rt> create -t ticket set subject='new' add [EMAIL PROTECTED] # Ticket 8 created. rt> quit $ alice$ rt create -t ticket set subject="New ticket" # Ticket 7 created. alice$ rt take 7 # Owner changed from Nobody to alice alice$ su bob bob$ rt steal 7 # Owner changed from alice to bob bob$ rt untake 7 # Owner changed from bob to Nobody $ rt shell rt> quit $ .SH FILES This program has two major sources of configuration information: its configuration files, and the environment. The program looks for configuration directives in a file named .rtrc (or $RTCONFIG; see below) in the current directory, and then in more distant ancestors, until it reaches /. If no suitable configuration files are found, it will also check for ~/.rtrc and /etc/request-tracker3.6/rt.conf. The following directives may occur, one per line: .TP 24 server <URL> URL to RT server. .TP user <username> RT username. .TP passwd <passwd> RT user's password. .TP query <RT Query> Default RT Query for list action .TP orderby <order> Default RT order for list action .PP Blank and #-commented lines are ignored. .SH ENVIRONMENT The following environment variables override any corresponding values defined in configuration files: .TP 16 RTUSER .TP RTPASSWD .TP RTSERVER .TP RTDEBUG Numeric debug level. (Set to 3 for full logs.) .TP RTCONFIG Specifies a name other than ".rtrc" for the configuration file. .TP RTQUERY Default RT Query for rt list .TP RTORDERBY Default order for rt list .SH AUTHOR Designed and implemented for Best Practical Solutions, LLC by Abhijit Menon-Sen <[EMAIL PROTECTED]> .SH BUGS This is an unsupported preview release. Please report bugs to [EMAIL PROTECTED] .SH NOTES This manual page was created from rt's internal documentation (`rt help') for Debian GNU/Linux by Trent W. Buck <[EMAIL PROTECTED]>, since the original program does not have one.