# # This is the message file for the rule editor # ####################################################################### # # # Created and maintained by: # # Rich Pito # # rap@ATHENA.MIT.EDU # # # ####################################################################### # # many of these messages have an accompanying HELP message following # them. The help message is named just like the original but it has # the word "HELP" appended to it. That message is given when the user # presses the "Help" key on the requester as additional help. # # Message names which only appear as postfixed with "HELP" are usually # associated with Help Menus and the menu item is the message name # minus the "HELP" postfix. # #---------------------------------------------------------------------- # notes displayed when user asks for help from the ruleeditor ruleeditor help notes [ The first non-switch argument is assumed to be the ruleset name. The second non-switch argument is assumed to be a rule number to edit. If neither the -rule, -before, or -after options are specified the ruleeditor will create a new rule to be appended to the end of the ruleset. The -RS and -SV options are mutually exclusive. The -force option only has significance when creating a new rule set (i.e. the rule set specified does not exist yet). ] ruleeditor help examples [ ruleeditor myrules 3 ruleeditor mynewrules -force ruleeditor myrules -b 1 ] # given to the user when only a short usage summary is appropriate ruleeditor usage [ Usage: ruleeditor ruleset [-rule] rulenum Usage: ruleeditor [-elim] [-force] { [-after] | [-before] | [-rule] } rulenum [-MTmsgtype] { -RSruleset | -SVserver } For more information: Usage: ruleeditor -help ] #---------------------------------------------------------------------- # error message given when can't open a pipe to execute lpr command printer cant open [ Argus Ruleeditor: Unable to open printer. ] printer cant open help [ For some reason a pipe cannot be opened with an lpr command. Unfortunately we cannot offer any more information about this problem. Please consult a user consultant. ] #---------------------------------------------------------------------- # when the user attempts to print something and the UNIX environment # variable PRINTER is not set printer warning [ Argus Ruleeditor: don't know which printer to send the output to because I can't read the Unix Environment variable "PRINTER". If you continue the output may not be sent to the correct printer. Continue printing? ] printer warning help [ In order to print the rule it is necessary to know which printer to send the output to. The Unix environment variable PRINTER should be set to the name of a printer where you want your output to go. For instance, you could set the PRINTER environment variable with the command: setenv PRINTER linus and printer output will be sent to the printer called linus. ] printer done [ Printing Finished. Press "Help" to see the command used to print. ] # should have one %s for the printer command printer done help [ The command used to print the rule was: %s ] #---------------------------------------------------------------------- # warning message before the user wipes all the actions in a rule actions delete warning [ You are about to delete all the actions in the THEN part of your rule! Continue? ] actions delete warning help [ The bar at the top of the THEN part of your rule serves two functions: first it allows you to add a new action before the first action in the THEN part, and second, it allows you to quickly delete all the actions in the THEN part of your rule if you want to start fresh. ] #---------------------------------------------------------------------- # warning message before the user wipes all the fields in a logical grouping fields delete warning [ You are about to delete all the fields beneath the selected bar! Continue? ] fields delete warning help [ The bar at the top of each 'box' or logical grouping in the IF part of the rule serves two functions: first it allows you to add a new field immediately following the bar, and second, it allows you to quickly delete all the fields in the group. NOTE: the logical group which contains the whole IF part is NOT VISIBLE. All you see is the bar of this 'box'. This grouping is of type AND and so implements an AND association between the fields in the IF part of the rule. ] #---------------------------------------------------------------------- # question asked to the user when he attempts to Quit without saving attempt to quit with modifications [ The rule has been modified since it was last saved. Quit Anyway? ] attempt to quit with modifications HELP [ If you quit the ruleeditor without saving it first the changes you have made to the rule will be lost and cannot be recovered. ] #---------------------------------------------------------------------- # Popup question when creating a new rule set. # The following string should contain one '%s' to indicate the name # of the rule set couldn't find rule set [ Ruleeditor: could not find rule set '%s'. Create a new one by that name? ] couldn't find rule set HELP [ Since the ruleeditor could not find the rule set you specified on the command line, it will ask you if you wish to create it in case you have misspelled the rule set name or do not realize that you are creating a new rule set. In order to avoid the ruleeditor asking this question you can specify the -f[orce] option on the command line to 'force' the creation of a new rule set. If the rule set already exists the -f[orce] option is ignored. ] #---------------------------------------------------------------------- # warning message popped up when the user attempts to save a field # which is of invalid type. # this message takes 3 arguments: # the value # the key # field type bad value for field type [ The value '%s' of the field '%s' is not valid. It must be of type '%s'. You may alter the value now if you wish to try again. If you do not wish to alter the value of the field, it will be saved but runrules will ignore this field (i.e. this field will not play a part in determining if this rule fires on a message or not). Alter the value of the field now and press "O.K.", or just press "O.K." and the field will be ignored by runrules. ] bad value for field type HELP [ The value of each field in the IF part of the rule is typed. That is, it is interpreted according to a field type. Argus supports several different field types including 'Date', 'Integer', 'Boolean', and 'Case Insensitive Text'. If the field type is, for instance, 'Date' then some valid phrases are: today June 15, 1989 last week whereas the following are not valid phrases for the field type 'Date': 21 my birthday Hello Mom! Please refer to the documnet "Argus Documentation" for more information on field types and the Date parser. ] #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ # # HELP MESSAGES # #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ #---------------------------------------------------------------------- # THE FOLLOWING ARE HELP MESSAGES FOR THE IF MENU #---------------------------------------------------------------------- add a text field HELP [ The 'add a text field' command allows you to quickly add a text field to the IF part of the rule. There are currently four different kinds of text fields available in Argus. Which kind of text field you would like to associate with this command (i.e. which kind of text field to add) is user settable via the profile component 'AddTextFieldType'. Consult the "Argus Documentation" document for a complete list of field types. ] # this help message appears for each of the easy access field types # available. We can't put the name of the field type that is about to # be added because they are user settable. add an easy access field HELP [ This command allows you to quickly add a field of a specific type. This command is user settable. That is, you can specify which field types you would like to be in this menu by specifying them in the profile component 'EasyAccessFieldTypes'. Consult the "Argus Documentation" document for a complete list of the available field types. ] add a complex field HELP [ The 'add a complex field' command allows you to quickly add a new blank field to the IF part of the rule. The new field, however, will appear in 'complex mode'. When a field is in 'complex mode' you can see and change all the attributes of the field. Consult the "Argus Documentation" document for a complete description of complex mode. ] delete selected item HELP [ The 'delete selected item' command allows you to delete the item in the IF part of the rule which is selected. If any part of a field is selected this option will delete the entire field. If the top label of a logical grouping is selected (i.e. where it may say 'AND', 'OR', or 'NOT') this option will delete that logical grouping. If the control bar for a logical grouping is selected, this option will delete all the items within that logical grouping. NOTE that the label of the outermost logical grouping is NOT visible. Only the control bar of this grouping is visible. The outermost grouping is of type 'AND' and cannot be deleted or changed. ] group fields with OR HELP [ The 'group fields with OR' command allows you to set up an OR association between fields or other logical groupings in the predicate. You choose which fields you want in the logical grouping by dragging a box around them. You do this by selecting this menu item and then clicking the LEFT mouse button somewhere above the first field you wish to put in the new logical grouping. Then move the mouse button below the last field you want in the logical grouping and press the LEFT mouse button again. If at any time you wish to abort the operation, press any mouse button EXCEPT the left mouse button. ] group fields with AND HELP [ The 'group fields with AND' command allows you to set up an AND association between fields or other logical groupings in the predicate. You choose which fields you want in the logical grouping by dragging a box around them. You do this by selecting this menu item and then clicking the LEFT mouse button somewhere above the first field you wish to put in the new logical grouping. Then move the mouse button below the last field you want in the logical grouping and press the LEFT mouse button again. If at any time you wish to abort the operation, press any mouse button EXCEPT the left mouse button. ] group fields with NOT HELP [ The 'group fields with NOT' command allows you to set up a NOT association between fields or other logical groupings in the predicate. You choose which fields you want in the logical grouping by dragging a box around them. You do this by selecting this menu item and then clicking the LEFT mouse button somewhere above the first field you wish to put in the new logical grouping. Then move the mouse button below the last field you want in the logical grouping and press the LEFT mouse button again. Note that it does not make sense to put more than one field or logical grouping in a NOT logical grouping. If at any time you wish to abort the operation, press any mouse button EXCEPT the left mouse button. ] #---------------------------------------------------------------------- # INFO MESSAGES WHEN CLICKING ON BARS AND THINGS #---------------------------------------------------------------------- click on then bar [ You have clicked the left mouse button on the control bar in the THEN section of the rule editor. Unfortunately, we cannot move the focus directly to this control bar. In order to move the focus here you have to use the 'TAB' and 'Shift TAB' keys. 'TAB' moves the focus forward. 'Shift TAB' moves the focus backwards. ] click on then bar HELP [ Focus is that place in the rule editor which appears highlighted. Since editing centers around that thing which has the focus you need to be able to move the focus. Most of the time you can move the focus somewhere by clicking the left mouse button on that thing. Unfortunately, you can't do that with the THEN control bar due to technical difficulties. So, in order to move the focus to the THEN control bar you must use the keyboard. When you have selected the control bar in the THEN section you can then add a new action BEFORE the first action in the THEN section. Also, when the THEN control bar is selected, you can delete all the actions by selecting the 'delete selected action(s)' option from the THEN menu. Please see the 'help on moving around in the rule editor' option in the HELP menu. ] click on assoc bar [ You have clicked the left mouse button on the control bar for a logical grouping in the predicate of your rule. Unfortunately, we cannot move the focus directly to this control bar. In order to move the focus here you have to use the 'TAB' and 'Shift TAB' keys. 'TAB' moves the focus forward. 'Shift TAB' moves the focus backwards. ] click on assoc bar HELP [ Focus is that place in the rule editor which appears highlighted. Since editing centers around that thing which has the focus you need to be able to move the focus. Most of the time you can move the focus somewhere by clicking the left mouse button on that thing. Unfortunately, you can't do that with the control bar of a logical grouping due to technical difficulties. So, in order to move the focus to the control bar of the logical grouping you must use the keyboard. When you have selected the control bar of a logical grouping you can add a new field BEFORE the first field (or logical grouping) in that logical grouping. Also, when the control bar is selected you can easily delete all the fields inside that logical grouping by selecting the 'delete selected item(s)' from the IF menu. Please see the 'help on moving around in the rule editor' option in the HELP menu. ] click on assoc [ You have clicked the left mouse button on the label of a logical grouping in the predicate of your rule. Unfortunately, we cannot move the focus directly to this logioal grouping. In order to move the focus here you have to use the 'TAB' and 'Shift TAB' keys. 'TAB' moves the focus forward. 'Shift TAB' moves the focus backwards. ] click on assoc HELP [ Focus is that place in the rule editor which appears highlighted. Since editing centers around that thing which has the focus you need to be able to move the focus. Most of the time you can move the focus somewhere by clicking the left mouse button on that thing. Unfortunately, you can't do that with the label of a logical grouping due to technical difficulties. So, in order to move the focus to the label of the logical grouping you must use the keyboard. When you have the selected the label of a logical grouping you can add a new field following that logical grouping by selecting the 'add a text field' option (or any of the other similar options) from the IF menu. Also, when the focus is on the label of a logical grouping you can delete the entire logical grouping by selecting the 'delete selected item(s)' from the IF menu. Please see the 'help on moving around in the rule editor' option in the HELP menu. ] #---------------------------------------------------------------------- # THE FOLLOWING ARE HELP MESSAGES FOR THE THEN MENU #---------------------------------------------------------------------- # take away the "HELP" postfix and that is the menu option. add an action HELP [ The 'add an action' command inserts the specified action following the selected action or following the control bar in the THEN section. You must select which action to add by choosing it from the sub menu. ] delete selected action(s) HELP [ The 'delete selected action(s)' command deletes the selected action. If the control bar at the top of the THEN section is selected this command will delete ALL the actions. ] add an argument HELP [ The 'add an argument' command inserts another argument following the selected argument. Please refer to the help on each specific verb for a description of the roles of its arguments. ] delete selected argument HELP [ The 'delete an argument' command deletes the selected argument. Please refer to the help on each specific verb for a description of the roles of its arguments. ] #====================================================================== # THE FOLLOWING ARE HELP MESSAGES FOR THE VERBS #====================================================================== move to HELP [ The 'move to' verb will move the current message to another folder. usage: move to [] notes: the argument determines the format of the destination folder and is optional. This argument allows you to transfer messages from one format to another format easily. examples: move to important-folder move to important-RMAIL-folder RMAIL ] copy to HELP [ The 'copy to' verb will copy the current message to another folder. usage: copy to [] notes: the argument determines the format of the destination folder and is optional. This argument allows you to transfer messages from one format to another format easily. examples: copy to important-folder copy to important-RMAIL-folder RMAIL ] delete current message HELP [ The 'delete current message' verb will mark this message for deletion. The message will continue to be processed by all the other rules in a ruleset. It will be deleted from the folder when runrules has finished. usage: delete current message ] remail current message to HELP [ The 'remail current message to' verb mails the current message to the person/people specified. usage: remail current message notes: The should be specified as you would specify them if you were using the mh mail command. examples: remail current message larry, moe, curly ] runrules HELP [ The 'runrules' verb is used to invoke the Argus runrules command. In this way it is possible to create specialized rulesets which perform only a single task and have other rulesets invoke them when appropriate. usage: runrules [] notes: If the is not specified then the is run on the current folder, otherwise it is run on the specified folder. examples: runrules set-priority-rules runrules set-priority-rules junk-mail-folder ] set user property HELP [ The 'set user property' verb will set a user property to a specified string. usage: set user property notes: The is simple treated as a string although it later may be interpreted as a number by the 'add to user property' or 'subtract from user property' verbs which add or subtract numbers from user properties. examples: set user property boring TRUE set user property importance 20 set user property resend time May 20, 1989 ] clear user property HELP [ The 'clear user property' verb removes the specified user property from the current message. usage: clear user property notes: If you reference a user property that has been cleared (or never set) it is as if the user property does not exist. examples: clear user property boring clear user property importance clear user property resend time ] make user property permanent HELP [ The 'make user property permanent' verb ensures that the specified user property will be stored with the message upon completion of runrules. This ensures that a future execution of runrules on the message will have access to the user property. Normally user properties are not permanent. That is, they are attached to a message with the 'set user property' verb, are referenced by other rules in a rule set, and are discarded when runrules has finished processing the message. If the user property is important or cannot be recomputed, you can save it with the message with this command. Please refer to the section in the "Argus Documentation" document about runrules and user properties for more information. usage: make user property permanent examples: make user property permanent boring make user property permanent importance make user property permanent about-AI? ] add to user property HELP [ The 'add to user property' verb adds a number to a user property. usage: add to user property notes: The value of the in this case is interpreted as an integer. This verb adds to the value of and assigns that value to . examples: add to user property importance 5 ] subtract from user property HELP [ The 'subtract from user property' verb subtracts a number from a user property. usage: subtract from user property notes: The value of the in this case is interpreted as an integer. This verb subtracts from the value of and assigns that value to . examples: subtract from user property importance 5 ] stop processing current message HELP [ The 'stop processing current message' verb forces the current ruleset to finish processing the current message. usage: stop processing current message notes: processing of the current message stops only in the current rule set. If the current ruleset has been invoked by another rule in another rule set, then processing will continue in the previous rule set. examples: stop processing current message ] formatted shell command HELP [ The 'formatted shell command' verb allows you to compose a command line to be sent to a shell as well as the standard input (stdin) for the command. The first argument to this verb is the command line passed to the shell. The second (optional) argument is the stdin for the command. When composing the command line or stdin you may specify sequences of special control characters which will be substituted for various parts of the message. Below is a list of the control sequences and what they are replaced with. %m -> the contents of the field called from the Message. i.e. %mTo: . %u -> the value of the User property . i.e. %uImportance . %w -> the Whole message. %h -> the Header of the message. %b -> the Body of the message. Any character following a back-slash is taken literally. So to specify the character '%' you would type "\%". Since the ruleeditor only allows for single line editing the character sequence "\n" is converted to a newline. Also, the character sequence "\t" is converted to a tab. usage: formatted shell command [] examples: formatted shell command zwrite mackay Look at this message!! \n %b formatted shell command grep "Artificial Intelligence" | zwrite rap %b ] shell with message as stdin HELP [ The 'shell with message as stdin' verb allows you to compose a command line to be sent to a shell and will then send the entire message to that command as stdin. The first (and only) argument to this verb is the command line passed to the shell. There are no interpretation of any special sequences of characters in the argument of this verb as there are in the 'formatted shell command' verb. NOTE: This command is equivalent to the 'formatted shell command' with its second argument set to "%w". usage: shell with message as stdin examples: shell with message as stdin zwrite rap shell with message as stdin cat >> old-messages-as-text-file ] shell with message body as stdin HELP [ The 'shell with message body as stdin' verb allows you to compose a command line to be sent to a shell and will then send the body of the message to that command as stdin. The first (and only) argument to this verb is the command line passed to the shell. There are no interpretation of any special sequences of characters in the argument of this verb as there are in the 'formatted shell command' verb. NOTE: This command is equivalent to the 'formatted shell command' with its second argument set to "%b". usage: shell with message body as stdin examples: shell with message body as stdin zwrite rap shell with message body as stdin cat >> old-messages-as-text-file ] #====================================================================== # MAIN HELP MENU MESSAGES #====================================================================== # take away the "HELP" postfix and that is the menu option. general help HELP [ The rule editor allows you to edit rules for use by the Argus runrules command. Please read the runrules(1) man page. GETTING MORE HELP The rule editor offers extensive help readily available in the 'Help' menu as well as in all the other menus of the rule editor. There are two other main menus in the ruleeditor signified by icons with the small word 'Menu' appearing in them. You can get help on any rule editor function in these two menus. First click the left mouse button on a menu and then click again on the menu option labeled 'Help'. You will then be presented with a sub menu which looks just like the first menu. By clicking on any item in the sub menu you can get help on that command. WHERE TO GO FROM HERE FOR MORE HELP We recommend that you read the 'help on moving around the rule editor' and 'common questions and answers' items in the 'Help' menu before proceeding. There is documentation packaged with with this software. If hard copies of these documents are not readily available an online version is called "... /argus/doc/argus.PS". Man pages are located in the directory "... /argus/doc/man1/". SOME USEFUL TIPS FOR GETTING STARTED o. When creating a rule, first imagine the message or kind of message which you wish to do something with. Model the IF part (predicate) of your rule to look like this message. o. Read the fields in the IF part from left to right. So if you had two field in your rule that looked like this: From: joe Subject bug report you would read "If the message is from Joe and the Subject contains the phrase 'bug report' then..." o. Never create a new rule which performs destructive operations like 'delete', always test your rules first by having them echo something to the screen. The following action will print the string "my great rule fired!!!" every time your new rule matches a message. formatted shell command echo my great rule fired!!! ] help on moving around the rule editor HELP [ Tab --> focus forward Shift Tab --> focus backward left Mouse button --> place focus Editing in the rule editor centers around the 'focus;. The focus is 'on' that place in the rule editor which appears highlighted. Many different places in the rule editor may have the focus but only one place can have it at a time. To move the focus forward press the 'Tab' key. To move the focus backwards press the 'Shift' and 'Tab' keys simultaneously. To move the focus quickly to one spot click on that place with the left mouse button. The focus will do different things when it is on different places. As a rule, when the focus is on a place which looks inset, you can type into it. When the focus is on a place which looks outset it is an option menu. An option menu allows you to choose one item from a set. When the focus is on an option menu, you can activate it by pressing the 'space' key. Then use the arrow keys to move around the menu. When you have moved onto the item which you want to select, press the 'return' key. You can also use an option menu by clicking down the left mouse button on the menu, dragging the mouse until you are over the item you wish to select, and then letting the mouse button up. ] common questions and answers HELP [ Q. How do I add a new field? (like "From:" "mark") A. To add a new field you first need to know where to add it. Any new field is added FOLLOWING the currently selected field (see 'help on moving around the rule editor' for more information about selecting things). Once you have selected a field, click the LEFT mouse button on the menu in the IF part. Once the menu appears, click again on the menu item labeled 'add a text field'. Q. Why is it that only some of the fields in the IF part have an option menu stuck in the middle of them and others don't? A. When a field comes up with an option menu in the middle of it, it means that its field type is something nonstandard like 'Date'. In these cases, it is desirable to explicitly indicate the field operator. Please read the help on 'field types' and 'field operators'. Q. What are the two buttons labeled 'Simple' and 'Complex' for? A. These two buttons allow you to view the fields in the IF part of the rule in simple or complex mode. In simple mode it is easier to grasp the predicate quickly. In complex mode you have direct control over all the attributes which make up a field, but it takes longer to read them. Beginners should normally not need to use Complex mode. Q. Does the order of things matter in the rule editor? A. In the IF part (predicate) order doesn't matter. In the THEN part, order does matter. Please see the help on 'help on THEN part (actions) of rules'. ] help on IF part (predicate) of rule HELP [ The IF part of the rule (the predicate) is composed of fields and logical groupings. The two most important features of a field are its key and value. A key may be something like "To:" and a value may be something like "smith". When the predicate is evaluated against a message, the key will be used to get some piece of information from that message. So if for example the key were "Subject:" the string "about our meeting last night" could be fetched from a message. This information is then compared to the value of the field. If "meeting" were the value of the field then the field would evaluate to TRUE because the word "meeting" (from the value) is in the string "about our meeting last night" (from the key). Fields can also be grouped by logical connectives like OR. This makes it easy to make rules like "IF the message is To: me or Cc: me THEN...". ] help on THEN part (actions) of rule HELP [ The THEN part of a rule consists of a list of actions. Each action is composed of a verb (like "move to" or "stop processing current message") and zero or more arguments to that verb. For example, the "move to" verb needs an argument which says where to move the current message to whereas the "stop processing current message" verb takes no arguments. When the predicate of the rule matches a message, each action in the THEN part is executed in turn. Order of the actions does make a difference except in 2 special cases. Every action following a "move to" or "delete current message" action will still have access to the message even though it has already been 'moved' or 'deleted'. ] help on message components HELP [ It is recommended that you read the help on the IF part of a rule before reading this help message. When a rule is being evaluated against a message, there are many sources of information which can be utilized in order to categorize (or fileter) that message. Some of these sources include the message itself, the list of uer properties attached to the message by other rules, or the interface to the type of mail system being used (like mh, RMAIL, or Babyl). The message component of a field specifies exactly where to look to find a piece of information with the same name as the key of the field. For example, if the message component of a field is simply 'Message' then the header of the message being processed will be searched for a field that has the same name as the key. If the message component is 'Mailer Interface' then the interface to the mailer can be asked for pieces of information with names like "Deleted" whose value can be "TRUE" or "FALSE". ] help on field types HELP [ The field type determines how the value of the field (and the information retrieved from the message using the key) will be interpreted. For example, when using the field type 'Date' the phrases "tomorrow", "October, 16 1989", and "Monday" can all refer to the same day. By using a 'Date' field type you can specify the value of a field as "tomorrow" and it will match the "Date:" of a message sent on October 15, 1989 if you process that message on October 14, 1989. Other field types include integer, several types of text field types, and a Boolean field type. ] examples HELP [ Some example rules are: 1) IF To: smith OR Cc: smith THEN move to personal 2) IF Subject: meeting Date: today THEN Shell with message as stdin echo 3) IF To: xpert Date: 3 weeks ago THEN delete current message ] verbs general help [ Each action in the THEN part of the rule consists of a verb like "move to" and zero or more arguments. When viewing the help on a verb, the usage line is very informative. To the right of the name of the verb will be zero or more arguments listed one after another. If an argument is optional it will appear inside braces ([]). ] help on the Print command HELP [ By clicking on the "Print" button on the bottom of the rule editor you can print the rule as text. The rule editor uses the UNIX command "lpr" to print the rule. If the UNIX environment variable "PRINTER" is set, the lpr command will use the value of that variable as the destination printer. So, if your "PRINTER" environment variable is set to "linus" then the lpr command will send the output to the printer named "linus". If the environment variable "PRINTER" is not set, the lpr command will try to use another default. ]