[request-tracker-maintainers] Bug#488609: improved version of generator script

[Trent W. Buck]

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.
-------------- next part --------------
.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 cc=foo at example.com \\
   set priority=3
 rt ls -t tickets -i 'Priority > 5' |
   rt edit - set status=resolved
 rt edit ticket/4 \\
   set priority=3 owner=bar at example.com \\
   add cc=foo at example.com bcc=quux at example.net
 rt create -t ticket \\
   set subject='new ticket' priority=10 \\
   add cc=foo at example.com

 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 cc=foo at example.com
 # 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 <ams at wiw.org>

.SH BUGS

This is an unsupported preview release.
Please report bugs to rt-bugs at bestpractical.com.

.SH NOTES

This manual page was created from rt's internal documentation (`rt
help') for Debian GNU/Linux by Trent W. Buck <trentbuck at gmail.com>,
since the original program does not have one.