--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/user_guide.txt	Thu Jan 09 22:59:22 2003 +0000
@@ -0,0 +1,402 @@
+==========
+User Guide
+==========
+
+:Version: $Revision: 1.12 $
+
+.. 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.
+
+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.
+
+
+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:
+
+.. 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 Page
+--------------
+
+XXX: some information about how searching works
+
+
+Under the covers
+----------------
+
+Index views may be modified by 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).
+========== =============================================================
+
+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.
+
+Permissions divide access controls up into answering questions like:
+
+- may the user edit issues ("Edit", "issue")
+- 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:
+
+- only managers may sign off issues as complete
+- don't give users who register through email 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:
+
+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
+
+Subject-line information
+------------------------
+
+The subject line of the incoming message is examined to find one of:
+
+1. the item that the message is responding to,
+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 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.
+
+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.
+
+For example,
+
+- setting the priority of an issue::
+
+   Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
+
+- adding yourself to a nosy list::
+
+   Subject: Re: [issue2] we're out of widgets [nosy=+richard]
+
+- setting the nosy list to just you and cliff::
+
+   Subject: Re: [issue2] we're out of widgets [nosy=richard,cliff]
+
+- removing yourself from a nosy list and setting the priority::
+
+   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.
+
+
+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".
+
+**reopening of resolved issues**
+ When a message is is received for a resolved issue, the issue status is
+ automatically reset to "chatting" to indicate new information has been
+ received.
+
+
+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.
+
+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.
+* In a multipart/alternative message or part, we look for a text/plain
+  subpart and ignore the other parts.
+
+If the message is a response to a previous message, and contains quoted
+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
+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.
+
+The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
+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.
+
+``ADD_RECIPIENTS_TO_NOSY``
+ Do the recipients (To:, Cc:) of a message get placed on the nosy list?
+ If 'new' is used, then the recipients will only be added when a message
+ creates a new issue. If 'yes', then the recipients will be added on
+ followups too. If 'no', they're never added to the nosy.
+
+
+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.
+
+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.
+
+
+Command Line Tool
+=================
+
+The basic usage is::
+
+ Help:
+ roundup-admin -h
+  roundup-admin help                       -- this help
+  roundup-admin help <command>             -- command-specific help
+  roundup-admin help all                   -- all available help
+
+ Options:
+  -i instance home  -- specify the issue tracker "home directory" to administer
+  -u                -- the user[:password] to use for commands
+  -c                -- when outputting lists of data, just comma-separate them
+
+ Commands:
+  commit
+  create classname property=value ...
+  display designator
+  export [class[,class]] export_dir
+  find classname propname=value ...
+  get property designator[,designator]*
+  help topic
+  history designator
+  import import_dir
+  initialise [adminpw]
+  install [template [backend [admin password]]]
+  list classname [property]
+  pack period | date
+  reindex
+  retire designator[,designator]*
+  rollback
+  security [Role name]
+  set designator[,designator]* propname=value ...
+  specification classname
+  table classname [property[,property]*]
+
+Commands may be abbreviated as long as the abbreviation matches only one
+command, e.g. l == li == lis == list.
+
+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``".
+
+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.::
+  
+    Input of...        Means...
+    "2000-04-17.03:45" 2000-04-17.08: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
+    "."                "right now"
+    
+- 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.
+  
+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).
+
+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.
+
+
+
+-----------------
+
+Back to `Table of Contents`_
+
+.. _`Table of Contents`: index.html
+.. _`customisation documentation`: customizing.html