diff options
Diffstat (limited to 'manual/en/manual_013.xml')
| -rw-r--r-- | manual/en/manual_013.xml | 667 |
1 files changed, 667 insertions, 0 deletions
diff --git a/manual/en/manual_013.xml b/manual/en/manual_013.xml new file mode 100644 index 0000000..a0e4da9 --- /dev/null +++ b/manual/en/manual_013.xml @@ -0,0 +1,667 @@ +<?xml version='1.0' encoding='UTF-8'?><chapter id="sylpheed-13"> + <title>Filters, actions and templates</title> + <para> +Sylpheed offers three powerfull tools to help you automatically +and efficently manage you mails. These tools are:</para> + <itemizedlist> + <listitem> + <para> + The <computeroutput>filters</computeroutput>, that let you sort you incoming messages and move + them into your folders based on their sender, their content, + using regular expressions. + </para> + </listitem> + <listitem> + <para> + The <computeroutput>actions</computeroutput> feature is a convenient way for the user to launch + external commands to process a complete message file including + headers and body or just one of its parts. + It allows also the use of an external command to filter the whole + text or just a selected part in the message window or in the + compose window. + </para> + </listitem> + <listitem> + <para> + The <computeroutput>templates</computeroutput> that let you pre-define complete messages + leaving placeholders in the text to be filled at composition time. + </para> + </listitem> + </itemizedlist> + <section> + <title>Filters </title> + <para> +Written by Nick Selby (sylpheed@nickselby.com) +</para> + <para> +Sylpheed provides powerful filters to allow users to automatically +pre-sort incoming mail based on a set of rules that the user defines. +As a most simple example, let's say you work at the Acme Grommet Company, +and you want all e-mail from your co-workers to be placed in one mailbox. +To accomplish this, you would set up a filter that would place all mail +whose "From" header includes the phrase "acmegrommet.com" into a specific +mailbox. +</para> + <para> +Sylpheed allows you much more control than just that simple setup; +you may create filters based on several variables, including an +"If this AND that" or "If the message contains this OR does NOT contain that" +etc. It's very cool. +</para> + </section> + <section> + <title>Finding The Filter Setting Dialog </title> + <para> +The filter settings dialog is located in the <computeroutput>Configuration</computeroutput> menu, +under the title "Filter Setting" or from the <computeroutput>Tools</computeroutput> menu, under in +the <computeroutput>Create filter rules</computeroutput> sub menu. You may also use establish a +keyboard shortcut (see Keyboard Shortcuts). +</para> + <mediaobject> + <imageobject> + <imagedata fileref="snapshots/filters..png"/> + </imageobject> + </mediaobject> + </section> + <section> + <title>Setting Up Filters</title> + <para> +Operator(s) and Processing instructions combine to create a Filter Rule. + +* Operators +The dialog's first setting option establishes the Operator, the variable +that will tell the filter what specific text to look for to trigger a +filter. Each Filter Rule may have up to two operator sets. +</para> + <para> +Each Operator variable contains three sections: <computeroutput>Header</computeroutput>, +<computeroutput>Keyword</computeroutput> and <computeroutput>Predicate</computeroutput>. +</para> + <para> +Header is a drop-down box which defines in which message header +Sylpheed's filter will search. Choices range from <computeroutput>Subject</computeroutput> +to <computeroutput>X-Mailer</computeroutput>. </para> + <para><computeroutput>Keyword</computeroutput> is a a text box in which you may enter the text +for which the filter will search. </para> + <para>Predicate allows you to choose to filter based on whether the operator +contains, or does not contain, the text you enter in the Keyword field. +</para> + <para> +Example: Create an Operator in which the X-Mailer field of an incoming +message contains the word 'Eudora'.</para> + <itemizedlist> + <listitem> + <para> + Step 1. Under the <computeroutput>Header</computeroutput> drop-down box, select + <computeroutput>X-Mailer</computeroutput>. + </para> + </listitem> + <listitem> + <para> + Step 2. In the <computeroutput>Keyword</computeroutput> text box, type 'eudora' + (case insensitive) + </para> + </listitem> + <listitem> + <para> + Step 3. Determine appropriate Predicate setting. Default + is <computeroutput>Contains</computeroutput>. + </para> + </listitem> + </itemizedlist> + <para>The second Operator setting, which is set identically to the +first, also allows the user to select an AND/OR setting +declaring the relationship between the two operators. +</para> + <para> +Example: Create an Operator set which will process mail with +a <computeroutput>From</computeroutput> header of bob@acmegrommet.com AND a subject +of "2001 Spring Grommet Collection"</para> + <itemizedlist> + <listitem> + <para> + Step 1. Under the first Operator set's Header drop-down + box, select <computeroutput>From</computeroutput>. + </para> + </listitem> + <listitem> + <para> + Step 2. In the <computeroutput>Keyword</computeroutput> text box, type + 'bob@acmegrommet.com' (case insensitive). + </para> + </listitem> + <listitem> + <para> + Step 3. Leave <computeroutput>Predicate</computeroutput> setting on default, + <computeroutput>Contains</computeroutput> + </para> + </listitem> + <listitem> + <para> + Step 4. Leave <computeroutput>AND/OR</computeroutput> box on default setting, <computeroutput>and</computeroutput>. + </para> + </listitem> + <listitem> + <para> + Step 5. Under the second Operator set's <computeroutput>Header</computeroutput> + drop-down box, select <computeroutput>Subject</computeroutput>. + </para> + </listitem> + <listitem> + <para> + Step 6. In the <computeroutput>Keyword</computeroutput> text box, type + '2001 spring grommet collection' (case insensitive). + </para> + </listitem> + <listitem> + <para> + Step 7. Leave <computeroutput>Predicate</computeroutput> setting on default, + <computeroutput>Contains</computeroutput>. + </para> + </listitem> + </itemizedlist> + </section> + <section> + <title>Message Processing </title> + <para> +Once you've established the Operator(s) that will define +which messages will be processed, it's time to tell +Sylpheed what to do with messages that match the operator(s). +You may choose between two radio button-selected settings: +<computeroutput>Destination</computeroutput> and <computeroutput>Don't Receive</computeroutput>. +</para> + <para> +Selecting <computeroutput>Destinations</computeroutput> will enable you to route +the mail into a mailbox which you specify. +</para> + <para> +Selecting <computeroutput>Don't Receive</computeroutput> will instruct Sylpheed +to not download messages with that operator. Note that with +<computeroutput>Don't Receive</computeroutput>, Sylpheed merely leaves the message +on your mailserver - it does not delete it. </para> + <para>To specify a mailbox to which you want the message transfered, +click on the radio button to the left of the word <computeroutput>Destination</computeroutput> +in the dialog. (Currently, in order to specify a mailbox you +must have created that mailbox prior to activating the Filter +Setting dialog.) Clicking the <computeroutput>Select</computeroutput> button will open +a pop-up window containing all mail folders currently active +in your copy of Sylpheed. Select the mailbox you wish by either </para> + <itemizedlist> + <listitem> + <para> + (a) double clicking on the mail folder name or + </para> + </listitem> + <listitem> + <para> + (b) clicking the mail folder name and then clicking <computeroutput>OK</computeroutput>. + </para> + </listitem> + </itemizedlist> + <para> +To specify that the message not be retrieved, and left +on your mail server, click the radio button to the left +of the words <computeroutput>Don't Receive</computeroutput>. +</para> + </section> + <section> + <title>Filter Registration </title> + <para> +Now that you have set the Operator and the Processing Rule, +all that's left to do is tell Sylpheed to save the entire +Filter Rule. <emphasis>If you skip this step, the filter won't work</emphasis>. +</para> + <para> +The <computeroutput>Register Rules</computeroutput> configuration has three options: +<computeroutput>Register</computeroutput>, <computeroutput>Substitute</computeroutput> and <computeroutput>Delete</computeroutput>. +</para> + <itemizedlist> + <listitem> + <para> + <computeroutput>Register</computeroutput> saves the Filter Rule. + </para> + </listitem> + <listitem> + <para> + <computeroutput>Substitute</computeroutput> modifies an existing registered + Filter Rule. + </para> + </listitem> + <listitem> + <para> + <computeroutput>Delete</computeroutput> will remove a previously registered + Filter Rule. + </para> + </listitem> + </itemizedlist> + <para>Example of Registering A Filter Rule: Create a Filter Rule +that moves all mail with the subject of "Sylpheed Manual" +into the (previously created) mail folder "Sylpheed Manual Mail".</para> + <itemizedlist> + <listitem> + <para> + Step 1. Under the first Operator set's <computeroutput>Header</computeroutput> + drop-down box, select <computeroutput>Subject</computeroutput>. + </para> + </listitem> + <listitem> + <para> + Step 2. In the <computeroutput>Keyword</computeroutput> text box, type + 'sylpheed manual' (case insensitive). + </para> + </listitem> + <listitem> + <para> + Step 3. Leave <computeroutput>Predicate</computeroutput> setting on default, + <computeroutput>Contains</computeroutput>. Leave second Operator set empty. + </para> + </listitem> + <listitem> + <para> + Step 4. Click <computeroutput>Destinations</computeroutput> radio button; + select "Sylpheed Manual Mail" folder. + </para> + </listitem> + <listitem> + <para> + Step 5. Click <computeroutput>Register</computeroutput>. + </para> + </listitem> + <listitem> + <para> + Step 6. Click <computeroutput>OK</computeroutput>. + </para> + </listitem> + </itemizedlist> + <para>Example of Substituting A Filter Rule: Modify a previously +created Filter Rule that moves all mail with the subject +of "Sylpheed Manual" to sort mail not to the mail folder +"Sylpheed Manual Mail" but rather the mail folder "Sylpheed Questions"</para> + <itemizedlist> + <listitem> + <para> + Step 1. Under the first Operator set's <computeroutput>Header</computeroutput> + drop-down box, select <computeroutput>Subject</computeroutput>. + </para> + </listitem> + <listitem> + <para> + Step 2. In the <computeroutput>Keyword</computeroutput> text box, type + 'sylpheed manual' (case insensitive). + </para> + </listitem> + <listitem> + <para> + Step 3. Leave <computeroutput>Predicate</computeroutput> setting on default, + <computeroutput>Contains</computeroutput>. Leave second Operator set empty. + </para> + </listitem> + <listitem> + <para> + Step 4. Click <computeroutput>Destinations</computeroutput> radio button; + select "Sylpheed Questions" folder. + </para> + </listitem> + <listitem> + <para> + Step 5. Click <computeroutput>Substitute</computeroutput>. + </para> + </listitem> + <listitem> + <para> + Step 6. Click <computeroutput>OK</computeroutput>. + </para> + </listitem> + </itemizedlist> + <para>Example of Deleting a Filter Rule: Remove the previously +created Filter Rule which refers to Subject:Sylpheed Questions.</para> + <itemizedlist> + <listitem> + <para> + Step 1. In the <computeroutput>Registered Rules</computeroutput> select box, + highlight the filter entitled + "<computeroutput>Subject:Sylpheed Manual: :::Sylpheed Questions:1:1:m</computeroutput>" + </para> + </listitem> + <listitem> + <para> + Step 2. Click the <computeroutput>Delete</computeroutput> Button. + </para> + </listitem> + <listitem> + <para> + Step 3. Confirm the deletion by clicking <computeroutput>Yes</computeroutput> in the + confirmation pop-up that asks, + <computeroutput>Do you really want to delete this rule?</computeroutput> + </para> + </listitem> + <listitem> + <para> + Step 4. Click <computeroutput>OK</computeroutput>. + </para> + </listitem> + </itemizedlist> + </section> + <section> + <title>Registered Rule Order </title> + <para> +One caveat about all this: the order in which Filter Rules +are created could adversely affect your intended message sorting, +and one needs to consider this when creating or updating Filter Rules. +</para> + <para> +For example, a Filter Rule saying, "Move anything containing 'ABC' +to Mailbox X" listed above another Filter Rule saying "Move anything +containing 'ABCDEF' to Mailbox Y" will cause the latter of these +filters not to process. +</para> + <para> +Think about the way Sylpheed goes down its list: first, it would say.. +"Hmm, any messages with ABC? Ah, there's one! Move it". +Then it would think, "Okay, any messages with ABCDEF?" +To which the answer would be "no" - that ABCDEF was already +filtered because it contained "ABC". +</para> + <para> +Bummer. +</para> + <para> +In order to avoid this, you must ensure that the more complex +Filter Rule is processed first, by placing it higher than a +similar, conflicting Filter Rule. +</para> + <para> +To move a Registered Rule higher or lower within the Registered +Rule box, select the rule you would like to move, and click on +the <computeroutput>Up</computeroutput> or <computeroutput>Down</computeroutput> buttons. This will "move" the +rule up or down, above or below a potentially conflicting Filter Rule. +</para> + </section> + <section> + <title>How to Filter Messages </title> + <para> +Filtering messages can be done in several ways:</para> + <itemizedlist> + <listitem> + <para> + Sylpheed automatically filters incoming mail from + POP servers. + </para> + </listitem> + <listitem> + <para> + If you incorporate mail from a unix mailbox, then + in the <computeroutput>Common preferences</computeroutput> (<computeroutput>Configuration</computeroutput> menu), + you need to check the box called <computeroutput>Filter on incorporation</computeroutput>. + You find this box in the <computeroutput>Receive</computeroutput> tab in the space + <computeroutput>Local spool</computeroutput>. + </para> + </listitem> + <listitem> + <para> + You can also select the option <computeroutput>Filter messages</computeroutput> + from the Summary menu. + </para> + </listitem> + </itemizedlist> + <para>Please note that, at time of writing, Sylpheed does -NOT YET- +has filtering of IMAP messages enabled.</para> + </section> + <section> + <title>Filtering mail with Procmail </title> + <para> +If you feel that Sylpheed has not enough options to perform +filtering for you, then you can look at Sylpheed Claws which +has more options for filtering. You can find the Claws version +(the cutting edge, experimental version of Sylpheed) +sylpheed-claws.sourceforge.net. +</para> + <para> +Another option, if you do not want to work with an experimental +version of Sylpheed, is Procmail. Procmail is a powerful mail +filtering program that is triggered from the Mail Transport +Agent (i.e. Sendmail, Postfix, Qmail). Procmail is called by +default from these programs after receiving e-mail. +</para> + <para> +The trick to procmail is to tell it that mail has to be filtered +into MH mail folders. This is not difficult though. +</para> + <para> +Normally procmail moves mail into MBOX format, this is one large +file containing all mails in a folder. MH uses separate files +for each e-mail. All you need to do is point the destination +of a procmail rule to <destination folder>/. +It is the "slash dot" that does the trick.</para> + </section> + <section> + <title>Actions </title> + <para> +The following section is a copy of +<ulink url="http://melvin.hadasht.free.fr/home/sylpheed/actions/index.html">Melvin's page</ulink>. + +</para> + <para> +The "actions" feature is a convenient way for the user to +launch external commands to process a complete message file +including headers and body or just one of its parts. +It allows also the use of an external command to filter the +whole text or just a selected part in the message window or +in the compose window. This is a generic tool that allows +to do any uncommon actions on the messages, and thus extends +the possibilities of Sylpheed. For example, Sylpheed does not +include the rot13 cyphering algorithm popular in some +newsgroups. It does not support natively armored encryption +or clear signing. It does not support uuencoded messages. +As all these features can be handled by external programs, +the actions provide a convenient way to use them from the menu bar.</para> + </section> + <section> + <title>Usage </title> + <para> +To create a new action, go to the <computeroutput>Configuration</computeroutput> menu, +select the <computeroutput>Actions...</computeroutput> entry. The <computeroutput>Actions setting</computeroutput> +dialog offers to enter the Menu name that will trigger the command. +The created menu will be found in the <computeroutput>Tools -> Actions</computeroutput> submenu. +By inserting a slash / in the menu name, you create a submenu.</para> + <para>The command is entered in the Command line entry. Note that +Sylpheed stores every single email in a separate file. This allows +to use the following syntax for the command:</para> + <itemizedlist> + <listitem> + <para> + <computeroutput>%f</computeroutput> denotes the file name of the selected message. + If you selected more than one, then the command will be + launched for each message with the appropriate file name. + </para> + </listitem> + <listitem> + <para> + <computeroutput>%F</computeroutput> denotes the list of the file names of the + selected message. If only one message is selected, + this amounts to <computeroutput>%f</computeroutput>, but if more messages are + selected, then the command will be launched only once + with the list of the file names. (You can use both + <computeroutput>%f</computeroutput> and <computeroutput>%F</computeroutput> in one command: then the + command will be launched for each selected message + with the name of this message and with the list of + all selected messages. I did not find a practical + example for this.). + </para> + </listitem> + <listitem> + <para> + <computeroutput>%p</computeroutput> denotes the current selected message part + of a multipart message. The part is decoded accordingly. + If the message is not a multipart message, it denotes + the message body. + </para> + </listitem> + <listitem> + <para> + Prepending <computeroutput>></computeroutput>: this will allow you to send + to the command's standard input a text that you will + enter in a dialog window. + </para> + </listitem> + <listitem> + <para> + Prepending <computeroutput>*</computeroutput>: this will allow you to send to + the command's standard input a text that you will enter + in a dialog window. But in contrast to prepending + <computeroutput>></computeroutput>, the entered text is hidden + (useful when entering passwords). + </para> + </listitem> + <listitem> + <para> + Appending an ampersand <computeroutput>&</computeroutput>: this will run + the command asynchronously. That means "fire and forget". + Sylpheed won't wait for the command to finish, nor will + it catch its output or its error messages. + </para> + </listitem> + <listitem> + <para> + Prepending the vertical bar <computeroutput>|</computeroutput> (pipe-in): + this will send the current displayed text or the current + selected text from the message view or the compose + window to the command standard input. The command will + silently fail if more than one message is selected. + </para> + </listitem> + <listitem> + <para> + Appending the vertical bar <computeroutput>|</computeroutput> (pipe-out): this + will replace the current displayed text or the current + selected text from the message window or the compose + window with the command standard output. The command + will silently fail if more than one message is selected. + </para> + </listitem> + <listitem> + <para> + Appending the "greater than" sign <computeroutput>></computeroutput> will + insert the command output in the message. The difference + between the trailing <computeroutput>|</computeroutput> is that no text will be + deleted or replaced. Most used when composing mails to + insert text. + </para> + </listitem> + </itemizedlist> + <para><emphasis>Note</emphasis>: It is not possible to use actions containing +<computeroutput>%f</computeroutput>, <computeroutput>%F</computeroutput> or <computeroutput>%p</computeroutput> from the compose window. +</para> + <para> +When a command is run, and unless it is run asynchronously, +Sylpheed will be insensitive to any interaction and it will wait +for the command to finish. If the command takes too long +(5 seconds), it will popup a dialog window allowing to stop it. +This dialog will also be displayed as soon as the command has +some output: error messages or even its standard output when +the command is not a "pipe-out" command. When multiple commands +are being run, they are run in parallel and each command output +is separated from the outputs of the others. +</para> + </section> + <section> + <title>Examples </title> + <para> +Here are some examples that are listed in the same syntax +as used for storing the actions list. You can copy and past +the definition in your <computeroutput>~/.sylpheed/actionsrc</computeroutput> file +(exit Sylpheed before). The syntax is very simple: one line +per action, each action contains the menu name and the command +line separated by a colon and a space ": ". +Alternatively, you can use <computeroutput>Configuration -> Actions...</computeroutput> +and for each example enter a menu name and copy&paste the +text after the colon and space ": " in the command definition. +</para> +<!-- missing table --> <para>The gpg-enc-syl script is to be found +<ulink url="http://melvin.hadasht.free.fr/home/sylpheed/actions/gpg-enc-syl">here (gpg-enc-syl)</ulink>. +It calls gpg with the --yes command line option that you may want +to remove it. See gpg manual page for info.</para> + <para>The gpg-sign-syl script is to be found +<ulink url="http://melvin.hadasht.free.fr/home/sylpheed/actions/gpg-sign-syl">here (gpg-sign-syl)</ulink>. +It needs the ssh-askpass utility found in OpenSSH. It can be +replaced by any X11 tool that asks some (hidden) text which +is then sent to standard output. Another version that uses +an xterm is to be found +<ulink url="http://melvin.hadasht.free.fr/home/sylpheed/actions/gpg-sign-syl-xterm">here (gpg-sign-syl-xterm)</ulink>.</para> + <para>The uudec script is to be found +<ulink url="http://melvin.hadasht.free.fr/home/sylpheed/actions/uudec">here (uudec)</ulink>. +It needs uudecode and ImageMagick's display. The latter can be +replaced by any image viewer that can get input from standard +input. The script could also be modified to use temporary +files instead of standard input.</para> + <para>The google_msgid.pl script is to be found +<ulink url="http://melvin.hadasht.free.fr/home/sylpheed/actions/google_msgid.pl">here (google_msgid.pl)</ulink> +Example and script by Thorsten Maerz. Edit the script to change +the browser (default is mozilla).</para> + <para>The tnef-claws bash script was written by Shawn Lamson and is +to be found +<ulink url="http://melvin.hadasht.free.fr/home/sylpheed/actions/tnef-claws">here</ulink>. +The script is well commented. You need to have the tnef package +already installed.</para> + </section> + <section> + <title>Templates </title> + <para> +With Sylpheed you can define mail templates to use when replying +to messages. A template can contain raw text (that will be inserted +in the composed mail without any change), and placeholders that are +replaced at composition time by the actual value of the selected +fields from the original message. +</para> + <para> +A typical use of the template could be to define the legal notice +to be appended to your messages (the usual notice that contains a +text like: "here are my own words and not those of my company, my +boss is not liable for them, bla, bla, bla"). +</para> + <para> +To define a new template, in the <computeroutput>Configuration</computeroutput> menu select +the <computeroutput>Templates</computeroutput> entry and fill the form:</para> + <mediaobject> + <imageobject> + <imagedata fileref="snapshots/template..png"/> + </imageobject> + </mediaobject> + <para> +The name parameter is used to identify each template, this name +will then appear in the <computeroutput>Tools/Templates</computeroutput> menu in the +composition window. +The content of the <computeroutput>To</computeroutput> field will be appended to the original +content of the corresponding field in the message you are composing. +The content of the <computeroutput>Subject</computeroutput> field will replace the orignal subject +of the message you are composing. +</para> + <para> +In the upper pane, type in the text you want to put in the template, +use the <computeroutput>Symbols</computeroutput> button to open a help window that contains +the description of all the placeholders you can use in a template +(there is one for the sender, one for the date, one for the message +ID, ...), then use the <computeroutput>Register</computeroutput> button to validate the +template. If you do not register the template, when leaving the form +the template will be canceled. To modify an existing template, select +it in the lower pane, modify its text, then use the <computeroutput>Substitute</computeroutput> +button. As you may guess, the <computeroutput>Delete</computeroutput> button removes the selected +template. Finally validate your changes with the <computeroutput>OK</computeroutput> button. +If you use the <computeroutput>Cancel</computeroutput> button, the form is closed and your changes +are lost (deleted templates are back, added templates are lost). + +</para> + <para> +To use a template, open the composition window and select the template +from the <computeroutput>Tools/Templates</computeroutput> menu. You can then choose to insert +the template into your message or to completely replace the text of the +message by the template. This only affects the body of the message. +If you choose to insert the template, its text will be inserted at the +cursor location. +</para> + <para> +The placeholders are taken from the source message when replying, so +they have no meaning when composing a new message. +</para> + </section> +</chapter>
\ No newline at end of file |