X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Fuser_guide.txt;h=055c5da5cc14ef162bf7189f02d31b4a5d5603a7;hb=a6e5b8ddba07c02ca388a77f1382460681a9e42f;hp=33e9f3387f95abf8df6b5a525b50a9188920406f;hpb=a04cbd05f2bfb643b0e3953d0010d9c70d14f4b3;p=roundup.git diff --git a/doc/user_guide.txt b/doc/user_guide.txt index 33e9f33..055c5da 100644 --- a/doc/user_guide.txt +++ b/doc/user_guide.txt @@ -2,27 +2,35 @@ User Guide ========== -:Version: $Revision: 1.18 $ - .. contents:: -Note: this document will refer to *issues* as the primary store of information -in the tracker. This is the default of the classic template, bubt may vary in -any given installation. +.. hint:: + This document will refer to *issues* as the primary store of + information in the tracker. This is the default of the classic template, + but may vary in any given installation. + Your Tracker in a Nutshell ========================== -Your tracker holds information about issues in bundles we call *items*. An -item may be an *issue* (a bug or feature request) or a *user*. The issue-ness or -user-ness is called the item's *class*. So, for bug reports and features, the -class is "issue", and for users the class is "user". +Your tracker holds information about issues in bundles we call *items*. +An item may be an *issue* (a bug or feature request) or a *user*. The +issue-ness or user-ness is called the item's *class*. So, for bug +reports and features, the class is "issue", and for users the class is +"user". + +Each item in the tracker has an ID number that identifies it along with +its item class. To identify a particular issue or user, we combine the +class with the number to create a unique label, so that user 1 (who, +incidentally, is *always* the "admin" user) is referred to as "user1". +Issue number 315 is referred to as "issue315". We call that label the +item's *designator*. + +Items in the database are never deleted, they're just "retired". You +can still refer to them by ID - hence removing an item won't break +references to the item. It's just that the item won't appear in any +listings. -Each item in the tracker has an id number that identifies it along with its -item class. To identify a particular issue or user, we combine the class with -the number to create a unique label, so that user 1 (who, incidentally, is -*always* the "admin" user) is referred to as "user1". Issue number 315 is -referred to as "issue315". We call that label the item's *designator*. Accessing the Tracker --------------------- @@ -33,20 +41,64 @@ You may access your tracker through one of three ways: 2. through the `e-mail gateway`_, or 3. using the `command line tool`_. -The last is usually only used by administrators. Most users will use the web -and email interfaces. All three are explained below. +The last is usually only used by administrators. Most users will use the +web and e-mail interfaces. All three are explained below. + + +Issue life cycles in Roundup +---------------------------- + +New issues may be submitted via the web or e-mail. + +By default, the issue will have the status "unread". If another message +is received for the issue, its status will change to "chatting". +The "home" page for a tracker will generally display all issues which +are not "resolved". -Searching in your Tracker -------------------------- +If an issue is closed, and a new message is received then it'll be +reopened to the state of "chatting". + +The full set of **prority** and **status** values are: + +=========== ===================================== +Priority Description +=========== ===================================== +"critical" panic: work is stopped! +"urgent" important, but not deadly +"bug" lost work or incorrect results +"feature" want missing functionality +"wish" avoidable bugs, missing conveniences +=========== ===================================== + +============= ===================================== +Status Description +============= ===================================== +"unread" submitted but no action yet +"deferred" intentionally set aside +"chatting" under review or seeking clarification +"need-eg" need a reproducible example of a bug +"in-progress" understood; development in progress +"testing" we think it's done; others, please test +"done-cbb" okay for now, but could be better +"resolved" fix has been released +============= ===================================== + + +Entering values in your Tracker +------------------------------- + +All interfaces to your tracker use the same format for entering values. +This means the web interface for entering a new issue, the web interface +for searching issues, the e-mail interface and even the command-line +administration tool. -All interfaces to your tracker use the same format for sepcifying search -parameters. String and Numeric properties ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -These fields just take a simple text value, like ``topic=It's broken``. +These fields just take a simple text value, like ``It's broken``. + Boolean properties ~~~~~~~~~~~~~~~~~~ @@ -54,16 +106,21 @@ Boolean properties These fields take a value which indicates "yes"/"no", "true"/"false", "1"/"0" or "on"/"off". + Constrained (link and multilink) properties ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Fields like "Assigned To" and "Topics" hold references to items in other +Fields like "Assigned To" and "Keywords" hold references to items in other classes ("user" and "keyword" in those two cases.) -We use a comma-separated list of values to indicated which values of "user" -or "keyword" are interesting. The values may be either numeric ids or the -names of items. The special value "-1" may be used to match items where the -property is not set. For example, the following searches on the issues: +Sometimes, the selection is done through a menu, like in the "Assigned +To" field. + +Where the input is not a simple menu selection, we use a comma-separated +list of values to indicated which values of "user" or "keyword" are +interesting. The values may be either numeric ids or the names of items. +The special value "-1" may be used to match items where the property is +not set. For example, the following searches on the issues: ``assignedto=richard,george`` match issues which are assigned to richard or george. @@ -71,74 +128,122 @@ property is not set. For example, the following searches on the issues: match issues that are not assigned to a user. ``assignedto=2,3,40`` match issues that are assigned to users 2, 3 or 40. -``topic=user interface`` - match issues with the keyword "user interface" in their topic list -``topic=web interface,email interface`` - match issues with the keyword "web interface" or "email interface" in - their topic list -``topic=-1`` - match issues with no topics set +``keyword=user interface`` + match issues with the keyword "user interface" in their keyword list +``keyword=web interface,e-mail interface`` + match issues with the keyword "web interface" or "e-mail interface" in + their keyword list +``keyword=-1`` + match issues with no keywords set Date properties ~~~~~~~~~~~~~~~ -Some fields in the search page (e.g. "Activity" or "Creation date") hold -dates. A plain date entered as a search field will match that date exactly -in the database. We may also accept ranges of dates. You can specify range -of dates in one of two formats: +Date-and-time stamps are specified with the date in +international standard format (``yyyy-mm-dd``) joined to the time +(``hh:mm:ss``) by a period ``.``. Dates in this form can be easily +compared and are fairly readable when printed. An example of a valid +stamp is ``2000-06-24.13:03:59``. We'll call this the "full date +format". When Timestamp objects are printed as strings, they appear in +the full date format. + +For user input, some partial forms are also permitted: the whole time or +just the seconds may be omitted; and the whole date may be omitted or +just the year may be omitted. If the time is given, the time is +interpreted in the user's local time zone. The Date constructor takes +care of these conversions. In the following examples, suppose that +``yyyy`` is the current year, ``mm`` is the current month, and ``dd`` is +the current day of the month. + +- "2000-04-17" means +- "01-25" means +- "2000-04-17.03:45" means +- "08-13.22:13" means +- "11-07.09:32:43" means +- "14:25" means +- +- "8:47:11" means +- +- the special date "." means "right now" + + +When searching, a plain date entered as a search field will match that date +exactly in the database. We may also accept ranges of dates. You can +specify range of dates in one of two formats: 1. English syntax:: - [[From] ][ To ] + [From ][To ] - Keywords "From" and "To" are case insensitive. Keyword "From" is optional. + Keywords "From" and "To" are case insensitive. Keyword "From" is + optional. 2. "Geek" syntax:: - [][; ] + [];[] Either first or second ```` can be omitted in both syntaxes. For example, if you enter string "from 9:00" to "Creation date" field, roundup will find all issues, that were created today since 9 AM. +The ```` may also be an interval, as described in the next section. Searching of "-2m; -1m" on activity field gives you issues which were active between period of time since 2 months up-till month ago. -Other possible examples (consider local time is Sat Mar 8 22:07:48 2003):: +Other possible examples (consider local time is 2003-03-08.22:07:48): + +- "from 2-12 to 4-2" means + +- "FROM 18:00 TO +2m" means + +- "12:00;" means + +- "tO +3d" means + +- "2002-11-10; 2002-12-12" means + +- "; 20:00 +1d" means + +- "2003" means + +- "2003-04" means + + + +Interval properties +~~~~~~~~~~~~~~~~~~~ - >>> Range("from 2-12 to 4-2") - - - >>> Range("18:00 TO +2m") - - - >>> Range("12:00") - - - >>> Range("tO +3d") - - - >>> Range("2002-11-10; 2002-12-12") - +Date intervals are specified using the suffixes "y", "m", and "d". The +suffix "w" (for "week") means 7 days. Time intervals are specified in +hh:mm:ss format (the seconds may be omitted, but the hours and minutes +may not). - >>> Range("; 20:00 +1d") - +- "3y" means three years +- "2y 1m" means two years and one month +- "1m 25d" means one month and 25 days +- "2w 3d" means two weeks and three days +- "1d 2:50" means one day, two hours, and 50 minutes +- "14:00" means 14 hours +- "0:04:33" means four minutes and 33 seconds -Interval properties -~~~~~~~~~~~~~~~~~~~ +Simple support for collision detection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -XXX explain... +Item edit pages remember when the item was last edited. When a form is +submitted, the user will be informed if someone else has edited the item +at the same time they tried to. Web Interface ============= -Note: this document contains screenshots of the default look and feel. Your -site may have a slightly (or very) different look, but the functionality will -be very similar, and the concepts still hold. +.. note:: + This document contains screenshots of the default look and feel. + Your site may have a slightly (or very) different look, but the + functionality will be very similar, and the concepts still hold. The web interface is broken up into the following parts: @@ -150,94 +255,112 @@ The web interface is broken up into the following parts: Lists of Items -------------- -The first thing you'll see when you log into Roundup will be a list of open -(ie. not resolved) issues. This list has been generated by a bunch of controls -`under the covers`_ but for now, you can see something like: +The first thing you'll see when you log into Roundup will be a list of +open (ie. not resolved) issues. This list has been generated by a bunch +of controls `under the covers`_ but for now, you can see something like: -.. img: images/index_logged_out.png +.. image:: images/index_logged_out.png -The screen is divided up into three sections: +The screen is divided up into three sections. There's a title which tells +you where you are, a sidebar which contains useful navigation tools and a +body which usually displays either a list of items or a single item from +the tracker. -.. img: images/page_layout.png +You may either register or log in. Registration takes you to: -you may either register or log in. Registration takes you to: +.. image:: images/registration.png -.. img: images/registration.png +Once you're logged in, the sidebar changes to: -Once you're logged in, the screen changes slightly to: +.. image:: images/index_logged_in.png -.. img: images/index_logged_in.png +You can now get to your "My Details" page: -Note that the sidebar menu has changed slightly, so you can now get to your -"My Details" page: - -.. img: images/my_details.png - -Note the new information on this page - the history. +.. image:: images/my_details.png Display, edit or entry of an item --------------------------------- -Create a new issue with "create new" under the issue subheading. This will -take you to: - -.. img: images/new_issue.png - -The `nosy list`_ is explained below. -Enter some information and click "submit new entry" and you'll be rewarded -with: +Create a new issue with "create new" under the issue subheading. This +will take you to: -.. img: images/new_issue_created.png +.. image:: images/new_issue.png -or, if you don't enter all the required information (or some other error -occurs) you'll get something like: +Editing an issue uses the same form, though now you'll see attached files +and messages, and the issue history at the bottom of the page: -.. img: images/new_issue_error.png +.. image:: images/edit_issue.png Searching Page -------------- -see `searching in your tracker`_ for an explanation of how the searching -works. +See `entering values in your tracker`_ for an explanation of what you +may type into the search form. + + +Saving queries +~~~~~~~~~~~~~~ + +You may save queries in the tracker by giving the query a name. Each user +may only have one query with a given name - if a subsequent search is +performed with the same query name supplied, then it will edit the +existing query of the same name. + +Queries may be marked as "private". These queries are only visible to the +user that created them. If they're not marked "private" then all other +users may include the query in their list of "Your Queries". Marking it as +private at a later date does not affect users already using the query, nor +does deleting the query. + +If a user subsequently creates or edits a public query, a new personal +version of that query is made, with the same editing rules as described +above. + Under the covers ~~~~~~~~~~~~~~~~ -The searching page converts your selections into the following arguments: - -========== ============================================================= -Argument Description -========== ============================================================= -:sort sort by prop name, optionally preceeded with '-' - to give descending or nothing for ascending sorting. -:group group by prop name, optionally preceeded with '-' or - to sort in descending or nothing for ascending order. -:filter selects which props should be displayed in the filter - section. Default is all. -:columns selects the columns that should be displayed. - Default is all. -propname selects the values the item properties given by propname - must have (very basic search/filter). -========== ============================================================= - -You may manually write URLS that contain these arguments, like so (whitespace -has been added for clarity):: +The searching page converts your selections into the following +arguments: + +============ ============================================================= +Argument Description +============ ============================================================= +@sort sort by prop name, optionally preceeded with '-' to give + descending or nothing for ascending sorting. The sort + argument can have several props separated with comma. +@group group by prop name, optionally preceeded with '-' or to sort + in descending or nothing for ascending order. The group + argument can have several props separated with comma. +@columns selects the columns that should be displayed. Default is + all. +@filter indicates which properties are being used in filtering. + Default is none. +propname selects the values the item properties given by propname must + have (very basic search/filter). +@search_text performs a full-text search (message bodies, issue titles, + etc) +============ ============================================================= + +You may manually write URLS that contain these arguments, like so +(whitespace has been added for clarity):: /issue?status=unread,in-progress,resolved& - topic=security,ui& - :group=priority& - :sort=-activity& - :filters=status,topic& - :columns=title,status,fixer + keyword=security,ui& + @group=priority,-status& + @sort=-activity& + @filters=status,keyword& + @columns=title,status,fixer Access Controls --------------- -User access is controlled through Permissions. These are are grouped into -Roles, and users have a comma-separated list of Roles assigned to them. +User access is controlled through Permissions. These are are grouped +into Roles, and users have a comma-separated list of Roles assigned to +them. Permissions divide access controls up into answering questions like: @@ -245,22 +368,33 @@ Permissions divide access controls up into answering questions like: - is the user allowed to use the web interface ("Web Access") - may the user edit other user's Roles through the web ("Web Roles") -Any number of new Permissions and Roles may be created as described in the -customisation documentation. Examples of new access controls are: +Any number of new Permissions and Roles may be created as described in +the customisation documentation. Examples of new access controls are: - only managers may sign off issues as complete -- don't give users who register through email web access +- don't give users who register through e-mail web access - let some users edit the details of all users E-Mail Gateway ============== -E-mail sent to Roundup is examined for several pieces of information: +Roundup trackers may be used to facilitate e-mail conversations around +issues. The "nosy" list attached to each issue indicates the users who +should receive e-mail when messages are added to the issue. + +When e-mail comes into a tracker that identifies an issue in the subject +line, the content of the e-mail is attached to the issue. + +You may even create new issues from e-mail messages. + +E-mail sent to a tracker is examined for several pieces of information: 1. `subject-line information`_ identifying the purpose of the e-mail -2. `e-mail message content`_ which is to be extracted -3. e-mail attachments which should be associated with the message +2. `sender identification`_ using the sender of the message +3. `e-mail message content`_ which is to be extracted +4. e-mail attachments which should be associated with the message + Subject-line information ------------------------ @@ -271,37 +405,42 @@ The subject line of the incoming message is examined to find one of: 2. the type of item the message should create, or 3. we default the item class and try some trickiness -If the subject line contains a prefix in ``[square brackets]`` then we're -looking at case 1 or 2 above. Note that any "re:" or "fwd:" prefixes are -stripped off the subject line before we start looking for real information. +If the subject line contains a prefix in ``[square brackets]`` then +we're looking at case 1 or 2 above. Any "re:" or "fwd:" prefixes are +stripped off the subject line before we start looking for real +information. + +If an item designator (class name and id number, for example +``issue123``) is found there, a new "msg" item is added to the +"messages" property for that item, and any new "file" items are added to +the "files" property for the item. -If an item designator (class name and id number, for example ``issue123``) -is found there, a new "msg" item is added to the "messages" property for -that item, and any new "file" items are added to the "files" property for -the item. +If just an item class name is found there, we attempt to create a new +item of that class with its "messages" property initialized to contain +the new "msg" item and its "files" property initialized to contain any +new "file" items. -If just an item class name is found there, we attempt to create a new item of -that class with its "messages" property initialized to contain the new "msg" -item and its "files" property initialized to contain any new "file" items. +The third case above - where no ``[information]`` is provided, the +tracker's ``MAIL_DEFAULT_CLASS`` configuration variable defines what +class of item the message relates to. We try to match the subject line +to an existing item of the default class, and if there's a match, the +message is related to that matched item. If not, then a new item of the +default class is created. -The third case above - where no ``[information]`` is provided, the tracker's -``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item -the message relates to. We try to match the subject line to an existing -item of the default class, and if there's a match, the message is related to -that matched item. If not, then a new item of the default class is created. Setting Properties ~~~~~~~~~~~~~~~~~~ -The e-mail interface also provides a simple way to set properties on items. At -the end of the subject line, propname=value pairs can be specified in square -brackets, using the same conventions as for the roundup set shell command. +The e-mail interface also provides a simple way to set properties on +items. At the end of the subject line, propname=value pairs can be +specified in square brackets, using the same conventions as for the +roundup set shell command. For example, - setting the priority of an issue:: - Subject: Re: [issue1] the coffee machine is broken! [priority=urgent] + Subject: Re: [issue2] the coffee machine is broken! [priority=urgent] - adding yourself to a nosy list:: @@ -315,17 +454,17 @@ For example, Subject: Re: [issue2] we're out of widgets [nosy=-richard;priority=bug] -In all cases, the message relates to issue 2. The ``Re:`` prefix is stripped -off. +In all cases, the message relates to issue 2. The ``Re:`` prefix is +stripped off. Automatic Properties ~~~~~~~~~~~~~~~~~~~~ **status of new issues** - When a new message is received that is not identified as being related to an - existing issue, it creates a new issue. The status of the new issue is - defaulted to "unread". + When a new message is received that is not identified as being related + to an existing issue, it creates a new issue. The status of the new + issue is defaulted to "unread". **reopening of resolved issues** When a message is is received for a resolved issue, the issue status is @@ -333,20 +472,38 @@ Automatic Properties received. +Sender identification +--------------------- + +If the sender of an e-mail is unknown to Roundup (looking up both user +primary e-mail addresses and their alternate addresses) then a new user +may be created, depending on tracker configuration (see the `Admin +Guide`_ section "Users and Security" for configuration details.) + +.. _`Admin Guide`: admin_guide.html + +The new user will have their username set to the "user" part of +"user@domain" in their e-mail address. Their password will be +completely randomised, and they'll have to visit the web interface to +have it changed. Some sites don't allow web access by users who register +via e-mail like this. + + E-Mail Message Content ---------------------- -Roundup only associates plain text (MIME type ``text/plain``) as messages for -items. Any other parts of a message are associated as downloadable files. If -no plain text part is found, the message is rejected. +Roundup only associates plain text (MIME type ``text/plain``) as +messages for items. Any other parts of a message are associated as +downloadable files. If no plain text part is found, the message is +rejected. To do this, incoming messages are examined for multiple parts: * In a multipart/mixed message or part, each subpart is extracted and - examined. The text/plain subparts are assembled to form the textual body - of the message, to be stored in the file associated with a "msg" class - item. Any parts of other types are each stored in separate files and - given "file" class items that are linked to the "msg" item. + examined. The text/plain subparts are assembled to form the textual + body of the message, to be stored in the file associated with a "msg" + class item. Any parts of other types are each stored in separate files + and given "file" class items that are linked to the "msg" item. * In a multipart/alternative message or part, we look for a text/plain subpart and ignore the other parts. @@ -357,24 +514,24 @@ sections, then these will be stripped out of the message if the Message summary ~~~~~~~~~~~~~~~ -The "summary" property on message items is taken from the first non-quoting -section in the message body. The message body is divided into sections by blank -lines. Sections where the second and all subsequent lines begin with a ">" or -"|" character are considered "quoting sections". The first line of the first -non-quoting section becomes the summary of the message. +The "summary" property on message items is taken from the first +non-quoting section in the message body. The message body is divided +into sections by blank lines. Sections where the second and all +subsequent lines begin with a ">" or "|" character are considered +"quoting sections". The first line of the first non-quoting section +becomes the summary of the message. Address handling ---------------- All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming -message are -looked up among the tracker users, and the corresponding users are placed -in the -"recipients" property on the new "msg" item. The address in the ``From:`` header -similarly determines the "author" property of the new "msg" item. The default -handling for addresses that don't have corresponding users is to create new -users with no passwords and a username equal to the address. +message are looked up among the tracker users, and the corresponding +users are placed in the "recipients" property on the new "msg" item. The +address in the ``From:`` header similarly determines the "author" +property of the new "msg" item. The default handling for addresses that +don't have corresponding users is to create new users with no passwords +and a username equal to the address. The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of the message may be added to the `nosy list`_ depending on: @@ -382,8 +539,8 @@ the message may be added to the `nosy list`_ depending on: ``ADD_AUTHOR_TO_NOSY`` Does the author of a message get placed on the nosy list automatically? If 'new' is used, then the author will only be added when a message - creates a new issue. If 'yes', then the author will be added on followups - too. If 'no', they're never added to the nosy. + creates a new issue. If 'yes', then the author will be added on + followups too. If 'no', they're never added to the nosy. ``ADD_RECIPIENTS_TO_NOSY`` Do the recipients (To:, Cc:) of a message get placed on the nosy list? @@ -397,36 +554,40 @@ Nosy List Roundup watches for additions to the "messages" property of items. -When a new message is added, it is sent to all the users -on the "nosy" list for the item that are not already on the "recipients" list -of the message. Those users are then appended to the "recipients" property on -the message, so multiple copies of a message are never sent to the same user. -The journal recorded by the hyperdatabase on the "recipients" property then -provides a log of when the message was sent to whom. +When a new message is added, it is sent to all the users on the "nosy" +list for the item that are not already on the "recipients" list of the +message. Those users are then appended to the "recipients" property on +the message, so multiple copies of a message are never sent to the same +user. The journal recorded by the hyperdatabase on the "recipients" +property then provides a log of when the message was sent to whom. -If the author of the message is also in the nosy list for the item that the -message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried -to determine if they get a nosy list copy of the message too. +If the author of the message is also in the nosy list for the item that +the message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` +is queried to determine if they get a nosy list copy of the message too. Mail gateway script command line -------------------------------- +Usage:: + + roundup-mailgw [[-C class] -S field=value]* [method] + The roundup mail gateway may be called in one of three ways: - . with an instance home as the only argument, - . with both an instance home and a mail spool file, or - . with both an instance home and a pop server account. + - with an instance home as the only argument, + - with both an instance home and a mail spool file, or + - with both an instance home and a pop server account. It also supports optional -C and -S arguments that allows you to set a fields for a class created by the roundup-mailgw. The default class if -not specified is msg, but the other classes: issue, file, user can -also be used. The -S or --set options uses the same +not specified is msg, but the other classes: issue, file, user can also +be used. The -S or --set options uses the same property=value[;property=value] notation accepted by the command line -roundup command or the commands that can be given on the Subject line -of an email message. +roundup command or the commands that can be given on the Subject line of +an e-mail message. -It can let you set the type of the message on a per email address basis. +It can let you set the type of the message on a per e-mail address basis. PIPE: In the first case, the mail gateway reads a single message from the @@ -455,11 +616,39 @@ POP: are both valid. The username and/or password will be prompted for if not supplied on the command-line. +POPS: + Connect to a POP server over ssl. This requires python 2.4 or later. + This supports the same notation as POP:: + + pops username:password@server + APOP: Same as POP, but using Authenticated POP:: apop username:password@server +IMAP: + Connect to an IMAP server. This supports the same notation as that of + POP mail:: + + imap username:password@server + + It also allows you to specify a specific mailbox other than INBOX using + this format:: + + imap username:password@server mailbox + +IMAPS: + Connect to an IMAP server over ssl. + This supports the same notation as IMAP:: + + imaps username:password@server [mailbox] + +IMAPS_CRAM: + Connect to an IMAP server over ssl using CRAM-MD5 authentication. + This supports the same notation as IMAP:: + + imaps_cram username:password@server [mailbox] Command Line Tool ================= @@ -473,10 +662,10 @@ The basic usage is:: -u -- the user[:password] to use for commands -d -- print full designators not just class id numbers -c -- when outputting lists of data, comma-separate them. - Same as '-S ","'. + Same as '-S ","'. -S -- when outputting lists of data, string-separate them -s -- when outputting lists of data, space-separate them. - Same as '-S " "'. + Same as '-S " "'. Only one of -s, -c or -S can be specified. @@ -512,64 +701,66 @@ The basic usage is:: All commands (except help) require a tracker specifier. This is just the -path to the roundup tracker you're working with. A roundup tracker is where -roundup keeps the database and configuration file that defines an issue -tracker. It may be thought of as the issue tracker's "home directory". -It may be specified in the environment variable ``TRACKER_HOME`` or on -the command line as "``-i tracker``". +path to the roundup tracker you're working with. A roundup tracker is +where roundup keeps the database and configuration file that defines an +issue tracker. It may be thought of as the issue tracker's "home +directory". It may be specified in the environment variable +``TRACKER_HOME`` or on the command line as "``-i tracker``". -A designator is a classname and an itemid concatenated, eg. bug1, user10, ... -Property values are represented as strings in command arguments and in the -printed results: +A designator is a classname and an itemid concatenated, eg. bug1, +user10, ... Property values are represented as strings in command +arguments and in the printed results: - Strings are, well, strings. - Password values will display as their encoded value. -- Date values are printed in the full date format in the local time zone, - and accepted in the full format or any of the partial formats explained - below.:: +- Date values are printed in the full date format in the local time + zone, and accepted in the full format or any of the partial formats + explained below.:: Input of... Means... - "2000-04-17.03:45" 2000-04-17.08:45:00 + "2000-04-17.03:45" 2000-04-17.03:45:00 "2000-04-17" 2000-04-17.00:00:00 "01-25" yyyy-01-25.00:00:00 - "08-13.22:13" yyyy-08-14.03:13:00 - "11-07.09:32:43" yyyy-11-07.14:32:43 - "14:25" yyyy-mm-dd.19:25:00 - "8:47:11" yyyy-mm-dd.13:47:11 + "08-13.22:13" yyyy-08-13.22:13:00 + "11-07.09:32:43" yyyy-11-07.09:32:43 + "14:25" yyyy-mm-dd.14:25:00 + "8:47:11" yyyy-mm-dd.08:47:11 + "2003" 2003-01-01.00:00:00 + "2003-04" 2003-04-01.00:00:00 "." "right now" -- Link values are printed as item designators. When given as an argument, - item designators and key strings are both accepted. +- Link values are printed as item designators. When given as an + argument, item designators and key strings are both accepted. - Multilink values are printed as lists of item designators joined by - commas. When given as an argument, item designators and key strings are - both accepted; an empty string, a single item, or a list of items joined - by commas is accepted. + commas. When given as an argument, item designators and key strings + are both accepted; an empty string, a single item, or a list of items + joined by commas is accepted. When multiple items are specified to the roundup get or roundup set -commands, the specified properties are retrieved or set on all the listed -items. When multiple results are returned by the roundup get or roundup -find commands, they are printed one per line (default) or joined by commas -(with the "``-c``" option). +commands, the specified properties are retrieved or set on all the +listed items. When multiple results are returned by the roundup get or +roundup find commands, they are printed one per line (default) or joined +by commas (with the "``-c``" option). -Where the command changes data, a login name/password is required. The login may -be specified as either "``name``" or "``name:password``". +Where the command changes data, a login name/password is required. The +login may be specified as either "``name``" or "``name:password``". - ``ROUNDUP_LOGIN`` environment variable - the "``-u``" command-line option -If either the name or password is not supplied, they are obtained from the -command-line. +If either the name or password is not supplied, they are obtained from +the command-line. + Using with the shell -~~~~~~~~~~~~~~~~~~~~ +-------------------- -With version 0.6.0 or newer of roundup which supports: multiple -designators to display and the -d, -S and -s flags. +With version 0.6.0 or newer of roundup (which introduced support for +multiple designators to display and the -d, -S and -s flags): -To find all messages regarding chatting issues that -contain the word "spam", for example, you could execute the -following command from the directory where the database -dumps its files:: +To find all messages regarding chatting issues that contain the word +"spam", for example, you could execute the following command from the +directory where the database dumps its files:: shell% for issue in `roundup-admin -ds find issue status=chatting`; do > grep -l spam `roundup-admin -ds ' ' get messages $issue` @@ -612,7 +803,7 @@ You can also display issue contents:: or status:: shell% roundup-admin get name `/tools/roundup/bin/roundup-admin \ - -dc -i /var/roundup/sysadmin get status issue3,issue1` + -dc -i /var/roundup/sysadmin get status issue3,issue1` unread deferred @@ -631,7 +822,7 @@ which is the same as:: Also the tautological:: shell% roundup-admin get name \ - `roundup-admin -dc get status \`roundup-admin -dc find issue \ + `roundup-admin -dc get status \`roundup-admin -dc find issue \ status=chatting\`` chatting chatting @@ -639,9 +830,3 @@ Also the tautological:: Remember the roundup commands that accept multiple designators accept them ',' separated so using '-dc' is almost always required. ------------------ - -Back to `Table of Contents`_ - -.. _`Table of Contents`: index.html -.. _`customisation documentation`: customizing.html