From 5821575d5c32c300500dd48108cfd76154a3d863 Mon Sep 17 00:00:00 2001 From: richard Date: Tue, 24 Sep 2002 02:01:21 +0000 Subject: [PATCH] half-backed cleaning up of user guide git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1223 57a73879-2fb5-44c3-a270-3262357dd7e2 --- doc/user_guide.txt | 120 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 102 insertions(+), 18 deletions(-) diff --git a/doc/user_guide.txt b/doc/user_guide.txt index 342fece..b195b54 100644 --- a/doc/user_guide.txt +++ b/doc/user_guide.txt @@ -2,7 +2,7 @@ User Guide ========== -:Version: $Revision: 1.7 $ +:Version: $Revision: 1.8 $ .. contents:: @@ -10,8 +10,98 @@ 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. +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". + +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 +--------------------- + +You may access your tracker through one of three ways: + +1. through the `web interface`_, +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. + + 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. + +The web interface is broken up into the following parts: + +1. `lists of items`_, +2. `display, edit or entry of an item`_, and +3. `searching page`_. + + +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: + +.. img: images/index_logged_out.png + +The screen is divided up into three sections: + +.. img: images/page_layout.png + +you may either register or log in. Registration takes you to: + +.. img: images/registration.png + +Once you're logged in, the screen changes slightly to: + +.. img: images/index_logged_in.png + +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. + +Create a new issue with "create new" under the issue subheading. This will +take you to: + +.. img: images/new_issue.png + +Enter some information and click "submit new entry" and you'll be rewarded +with: + +.. img: images/new_issue_created.png + +or, if you don't enter all the required information (or some other error +occurs) you'll get something like: + +.. img: images/new_issue_error.png + +Searching +--------- + +TODO: some information about how searching works + + +Under the covers +---------------- Index views may be modified by the following arguments: @@ -30,24 +120,18 @@ propname selects the values the item properties given by propname must have (very basic search/filter). ========== ============================================================= -Searching -~~~~~~~~~ - -TODO: some information about how searching works - - Access Controls -~~~~~~~~~~~~~~~ +--------------- Managing Issues -~~~~~~~~~~~~~~~ +--------------- TODO: some mention of how the various widgets work E-Mail Gateway --------------- +============== E-mail sent to Roundup is examined for several pieces of information: @@ -56,7 +140,7 @@ E-mail sent to Roundup is examined for several pieces of information: 3. e-mail attachments which should be associated with the message Subject-line information -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ The subject line of the incoming message is examined to find one of: @@ -84,7 +168,7 @@ 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 @@ -113,7 +197,7 @@ off. 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 @@ -134,7 +218,7 @@ sections, then these will be stripped out of the message if the ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``. 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 @@ -144,7 +228,7 @@ 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 @@ -172,7 +256,7 @@ the message may be added to the `nosy list`_ depending on: Nosy List -::::::::: +~~~~~~~~~ The nosy list watches for additions to the "messages" property of items. When a new message is added, it is sent to all the users @@ -188,7 +272,7 @@ to determine if they get a nosy list copy of the message too. Command Line Tool ------------------ +================= The basic usage is:: -- 2.30.2