From 736c95865460dedb7c35d09e3734bc1167968398 Mon Sep 17 00:00:00 2001 From: richard Date: Wed, 10 Oct 2001 01:47:55 +0000 Subject: [PATCH] more doc git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@285 57a73879-2fb5-44c3-a270-3262357dd7e2 --- doc/index.html | 119 +++++++++++++++++++++++++++---------------------- 1 file changed, 66 insertions(+), 53 deletions(-) diff --git a/doc/index.html b/doc/index.html index d8759a4..a5ac988 100644 --- a/doc/index.html +++ b/doc/index.html @@ -157,12 +157,6 @@ The email addresses used by the system by default are:
roundup's internal use (problems, etc) -Note: -We run the instance as group "issue_tracker" and add the mail and web user -("mail" and "apache" on our RedHat 7.1 system) to that group, as well as -any admin people. - -

E-Mail Interface

Set up a mail alias called "issue_tracker" as:
@@ -247,11 +241,13 @@ the easiest and most flexible method of doing so is: mkdir instance_home chown issue_tracker:issue_tracker instance_home chmod g+rwxs instance_home -chmod o-rwx instance_home roundup-admin -i instance_home init -
  • Now, edit the /etc/group line for issue_tracker so it includes the unix -logins of all the users who are going to administer your roundup instance. +
  • Now, edit the /etc/group line for the issue_tracker group so it includes +the unix logins of all the users who are going to administer your roundup +instance. If you're running the web or mail gateways, then be sure to +include those users in the group too (on some Linux systems, these +users are "www" or "apache" and "mail".)
    E-Mail interface @@ -470,6 +466,30 @@ Index views may be modified by the following arguments:

    E-Mail Gateway

    +

    Performing Actions

    +The subject line of the incoming message is examined to determine whether +the message is an attempt to create a new item or to discuss an existing +item. A designator enclosed in square brackets is sought as the first thing +on the subject line (after skipping any "Fwd:" or "Re:" prefixes). +

    +If an item designator (class name and id number) is found there, the newly +created "msg" node is added to the "messages" property for that item, and +any new "file" nodes 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" node and its "files" property initialized to contain any new "file" +nodes. + +

    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. +explanatory message given in the exception. + +

    Message content

    Incoming messages are examined for multiple parts:
    • In a multipart/mixed message or part, each subpart is extracted and @@ -481,7 +501,7 @@ Incoming messages are examined for multiple parts: subpart and ignore the other parts.
    -

    Message content summary

    +

    Message summary

    The "summary" property on message nodes 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 @@ -500,27 +520,22 @@ passwords.) If we prefer to reject mail from outside sources, we can simply register an auditor on the "user" class that prevents the creation of user nodes with no passwords. -

    Performing Actions

    -The subject line of the incoming message is examined to determine whether -the message is an attempt to create a new item or to discuss an existing -item. A designator enclosed in square brackets is sought as the first thing -on the subject line (after skipping any "Fwd:" or "Re:" prefixes). - -If an item designator (class name and id number) is found there, the newly -created "msg" node is added to the "messages" property for that item, and -any new "file" nodes 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" node and its "files" property initialized to contain any new "file" -nodes. -

    Triggers

    Both cases may trigger detectors (in the first case we are calling the set() method to add the message to the item's spool; in the second case we are calling the create() method to create a new node). If an auditor raises an exception, the original message is bounced back to the sender with the -explanatory message given in the exception. + +

    Nosy Lists

    +A standard detector is provided that watches for additions +to the "messages" property. When a new message is added, the +detector sends it 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.

    Customising Roundup

    @@ -639,10 +654,8 @@ this: issue.setkey('title') -

    Class, FileClass, IssueClass - creating a new information store

    -A Class defines a particular class (or type) of data that will be -stored in the database. In the instance above, we've defined 7 classes of -information: +

    Classes and Properties - creating a new information store

    +In the instance above, we've defined 7 classes of information:
    priority
    Defines the possible levels of urgency for issues. @@ -661,20 +674,25 @@ information:
    Initially emtyp, this is where the issue information is stored.

    -We define the "priority" and "status" classes to allow two things: reduction in the -amount of information stored on the issue and more powerful, accurate +We define the "priority" and "status" classes to allow two things: reduction +in the amount of information stored on the issue and more powerful, accurate searching of issues by priority and status. By only requiring a link on the issue (which is stored as a single number) we reduce the chance that someone mis-types a priority or status - or simply makes a new one up. + +

    Class and Nodes

    +A Class defines a particular class (or type) of data that will be +stored in the database. A class comprises one or more properties, which +given the information about the class nodes.

    +The actual data entered into the database, using class.create() +are called nodes. They have a special immutable property called +id. We sometimes refer to this as the nodeid. -Class -
    -Class is the basic store of information. -

    -A class is comprised of one or more properties of the following type: +

    Properties

    +A Class is comprised of one or more properties of the following types:
    • String properties are for storing arbitrary-length @@ -695,20 +713,14 @@ the value is an integer, the id of the chosen node. in a specified class. The value is a list of integers.
    -

    - -FileClass -
    +

    FileClass

    FileClasses save their "content" attribute off in a separate file from the rest of the database. This reduces the number of large entries in the database, which generally makes databases more efficient, and also allows us to use command-line tools to operate on the files. They are stored in the files sub-directory of the db directory in your instance. -

    - -IssueClass -
    +

    IssueClass

    IssueClasses automatically include the "messages", "files", "nosy", and "superseder" properties.

    @@ -722,15 +734,15 @@ issue which has superceded this one. They also have the dynamically generated "creation", "activity" and "creator" properties.

    -The value of the "creation" property is the date when an item was created, +The value of the "creation" property is the date when a node was created, and the value of the "activity" property is the date when any property on -the item was last edited (equivalently, these are the dates on the first -and last records in the item's journal). The "creator" property holds a +the node was last edited (equivalently, these are the dates on the first +and last records in the node's journal). The "creator" property holds a link to the user that created the issue.

    setkey(property)

    Select a String property of the class to be the key property. The key -property muse be unique, and allows references to the items in the class by +property muse be unique, and allows references to the nodes in the class by the content of the key property. That is, we can refer to users by their username, e.g. let's say that there's an issue in roundup, issue 23. There's also a user, richard who happens to be user 2. To assign an issue to him, @@ -746,9 +758,10 @@ or Note, the same thing can be done in the web and e-mail interfaces.

    create(information)

    -Create an item in the database. This is generally used to create items in +Create a node in the database. This is generally used to create nodes in the "definitional" classes like "priority" and "status". +

    Web Interface

    The web interface works behind the cgi-bin/roundup.cgi or roundup-server @@ -821,7 +834,7 @@ SELECT fields and Multilinks use SELECT MULTIPLE fields. Options:
    size (number) - width of TEXT fields.
    height (number) - number of nows in SELECT MULTIPLE tags.
    -showid (boolean) - true includes the id of linked items in the SELECT +showid (boolean) - true includes the id of linked nodes in the SELECT MULTIPLE fields. @@ -881,7 +894,7 @@ note to go along with a change. list -List the items specified by property using the standard index for +List the nodes specified by property using the standard index for the class.

    Arguments:
    @@ -1126,7 +1139,7 @@ system on their time.

     

    -$Id: index.html,v 1.12 2001-10-09 07:31:02 richard Exp $ +$Id: index.html,v 1.13 2001-10-10 01:47:55 richard Exp $

     

    -- 2.30.2