232054 - Update Help content on filters

Status: RESOLVED FIXED

(SeaMonkey :: Help Documentation, defect)

Description

[Daniel Wang]

Need to document the various filter actions. I think the content was written
back when the only available action is "filter to folder"

Comment 1

[Stefan [:stefanh]]

Giacomo, do you see anything that's missing?

Comment 2

[Giacomo Magnini]

Content seems updated, but there's no entry in the index file... You need to
search for "filter", which is not enough IMHO.

Comment 3

[Stefan [:stefanh]]

Hmm, an entry called "Filters" that links to "Creating Message Filters"? Would
that be sufficient, or should we add more stuff to the index (like "Message
filters" etc) that links to "Creating Message Filters"?

Comment 4

[Giacomo Magnini]

Attachment: Add entry to help-index1.rdf about message filters

Comment 5

[Ian Neal]

Comment on attachment 202639 [details] [diff] [review]
Add entry to help-index1.rdf about message filters

>Index: extensions/help/resources/locale/en-US/help-index1.rdf
>===================================================================
>+       <rdf:Description ID="message_filters"
>+         nc:name="Creating message filters"
>+         nc:link="mail_help.xhtml#creating_message_filters"/>
>+     </rdf:li>
>+     <rdf:li>
Won't this appear under M in the index but with the title "Creating message filters"? There is already an entry under Mail and Newsgroups for "creating filters"

As Daniel says the actual help is a bit of out of date:
a) It does not detail context menu way of adding filters
b) Talks More and Fewer instead of "+" and "-"
c) Seems to suggest you can only perform one action with each filter

Comment 6

[Giacomo Magnini]

(In reply to comment #5)
> Won't this appear under M in the index but with the title "Creating message
> filters"? There is already an entry under Mail and Newsgroups for "creating
> filters"

Should I add one into the C category for easier finding?

> b) Talks More and Fewer instead of "+" and "-"

Will try to update somewhat the content to deal with a) and c).

Comment 7

[Giacomo Magnini]

The More/Fewer problem was accidentally fixed in bug 283318. :)

Comment 8

[Serge Gautherie (:sgautherie)]

Patch seems to apply to 1.8 branch only.
Don't know the plan about 1.9 trunk.

Comment 9

[Stefan [:stefanh]]

(In reply to comment #8)
> Patch seems to apply to 1.8 branch only.
> Don't know the plan about 1.9 trunk.
> 

We don't do those kind of string changes on 1.8

Comment 10

[RickieES aka Ricardo Palomares]

Attachment: A first draft of requested changes in mail_help.xhtml

I know we are string frozen and this can't be applied to SM 2.0, but I've thought it would be nice to have a first proposal to requested changes. :-) Since it is just something to get feedback, I don't formally request a review nor provide changes to RDF files. BTW, is help-index1.rdf still used in the new help viewer?

Comment 11

[Jens Hatlak (:InvisibleSmiley)]

Comment on attachment 405610 [details] [diff] [review]
A first draft of requested changes in mail_help.xhtml

(In reply to comment #10)
> BTW, is help-index1.rdf still used in the new help viewer?

Yes, it defines the set of possible search results.

I know you didn't request formal review but I thought it might help to address some language issues before the patch grows bigger. I hope you don't mind.

>-    messages to act on, and the action you want the filter to perform.</li>
>+    messages to act on, and the action(s) you want the filter to perform.</li>

You may just as well use only the plural form (without parenthesis). The interface makes it pretty obvious that single actions are possible as well.

>+  <li>Select when do you want the filter to be applied. This setting enables

No "do" here.

>+    you to define some filters to be applied in a automatic way (when checking

Use "an" before vowels that are pronounced as such (counterexample: "university").

>+    mail), on demand (manually run), or both. <q>After classification</q> means
>+    that junk and phishing controls will be run before applying the
>+    filters.</li>

Since this is per filter it should either be "filter" or "actions".

>+    <p><strong>Tip</strong>: Message filters are applied one after one. It

"one after another".

>+      could be that you don't want all filters to be run if one or more

"don&apos;t".

>+      messages matches some conditions. For instance, you may want to tag

"match".

>+      as <q>Important</q> all messages from your boss e-mail address, and you

"boss&apos;s" (and putting "as <q>Important</q>" after "address" will probably sound more natural).

>+      may want all messages containing the word <q>Memorandum</q> in its

"their" instead of "its".

>+      folder, even if it contains <q>Memorandum</q> in the subject. So
>+      the first message filter you define should match your boss e-mail

"boss&apos;s"

>+<p><strong>Note</strong>: You can also manually run message filters at any

I think "run message filters manually" would be better.

>+  time. In the Mail window, choose Tools, and then select Run Filters on Folder
>+  to apply filters to the current folder, or Run Filters on Message to apply
>+  filters in the selected message (if any).</p>

"to" the selected message.

>-  <li>Open the Message menu, and choose Create Filter From Message. You see the
>-    Filter Rules dialog box. Using the sender&apos;s email address,
>-    &brandShortName; prefills the filter name, the filter matching criteria,
>-    and the filter action (Move to folder).</li>
>+  <li>Open the Message menu, and choose Create Filter From Message. Or, in the
>+    message header pane, right click in the sender name and choose Create
>+    Filter from.</li>

AFAIK the Oxford comma only applies to enumerations. Thus there should be no comma before "and" here (It was wrong before if I'm right, though). No "in" (or anything else) before "the sender name". Capitalize "from".

>   <li>Choose a destination folder in which to store the incoming messages from
>-    the specified sender, or create a new folder.</li>
>+    the specified sender, or create a new folder. You can also choose another
>+    action(s) for this filter.</li>

"action" ("another" doesn't work with "actions").

Comment 12

[RickieES aka Ricardo Palomares]

Attachment: Draft patch with Jens comments applied

Thank you for your comments, Jens. :-)

Comment 13

[Jens Hatlak (:InvisibleSmiley)]

Comment on attachment 405690 [details] [diff] [review]
Draft patch with Jens comments applied

>+  <li>To run filters on existing messages in a folder, select the folder
>+    in the bottom dropdown list and click <q>Run now</q> button.</li>

Missed that the first time: "the" missing after "click" and "now" needs to be capitalized to match the UI.

No need to post a new patch just for that, though. Meanwhile you may think about whether help-index1.rdf needs additions for this bug (note that "Creating message filters", as proposed in comment 4, is already in there).

When you are comfortable with the quality of your patch you may request formal review, independent from whether it'll make SM 2.0 or not.

Comment 14

[RickieES aka Ricardo Palomares]

Attachment: New patch fixing additional points in comment #13

Taking bug

Comment 15

[RickieES aka Ricardo Palomares]

(In reply to comment #13)
> (From update of attachment 405690 [details] [diff] [review])
> >+  <li>To run filters on existing messages in a folder, select the folder
> >+    in the bottom dropdown list and click <q>Run now</q> button.</li>
> 
> Missed that the first time: "the" missing after "click" and "now" needs to be
> capitalized to match the UI.
>


Fixed, and I've slightly adapted the "Junk Mail Controls and Filters" section now that Junk controls may run before filters.


> No need to post a new patch just for that, though. Meanwhile you may think
> about whether help-index1.rdf needs additions for this bug (note that "Creating
> message filters", as proposed in comment 4, is already in there).


I've used the search box with "filter" and I get four results:

- creating filters
- Creating Message Filters
- Filtering messages from a Specific Sender, and
- Junk Mail Controls and Filters

So search box uses both help-index1.rdf and suite-toc.rdf, and I think there is no need to add more entries to help-index1.rdf. Actually, maybe "creating filters" is a bit redundant to "Creating Message Filters", don't you think so?

In case you think it isn't, who can I ask to review? Just Ian or Stefan? I don't want to overload them if there is more people able to do the review (and, actually, you have already done it). :-)

Thank you very much.

Comment 16

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #15)
> I've used the search box with "filter" and I get four results:
> 
> - creating filters
> - Creating Message Filters
> - Filtering messages from a Specific Sender, and
> - Junk Mail Controls and Filters
> 
> So search box uses both help-index1.rdf and suite-toc.rdf, and I think there is
> no need to add more entries to help-index1.rdf.

Agreed.

> Actually, maybe "creating
> filters" is a bit redundant to "Creating Message Filters", don't you think so?

Maybe, but I don't feel strongly about that and they are defined in two different files with different contents/aims. Unless Neil or stefanh object you can leave it as it is.

> In case you think it isn't, who can I ask to review? Just Ian or Stefan?

The SeaMonkey project areas page says IanN, stefanh, Neil. But that's not up-to-date. For one I've never seen Neil reviewing Help patches. Also it doesn't list me. Yet. ;-)

> I don't want to overload them if there is more people able to do the review
> (and, actually, you have already done it). :-)

Yes, let's finish this, shall we? :-)


     <p><strong>Tip</strong>: To automatically tag incoming messages, choose
       <q>Tag the message</q> from the drop-down list.</p>
       
While we're here, please make that "Tag Message" to match the actual string in the list.

+      and would contain two actions: <q>Tag message</q> as <q>Important</q> and
+      <q>Stop filter execution</q>.</p>

"Tag Message" and "Stop Filter Execution".

+  <li>You see the Filter Rules dialog box. Using the sender&apos;s email
+    address, &brandShortName; prefills the filter name, the filter matching
+    criteria, and the filter action (Move to folder).</li>

1. Currently there are four occurences of "e-mail" in the file. You used both that form and "email" which is throughout the rest of the file. Please change all occurences of "e-mail" in the file by "email", i.e. both the four existing ones and all in your additions.

2. You will see that if when you arrive here (Filter Rules dialog, coming from a message) the filter name is not prefilled anymore (it was in SM 1.1). This is because the filter name will now be generated for you based on the criteria if you don't fill one in. Also "Move to folder" is actually "Move Message to" in the list. Please make the necessary changes. Finally you may consider adding a note like "You may change any of these.".

+    the specified sender, or create a new folder. You can also choose another
+    action for this filter.</li>

"choose other actions".

+<p>Junk Mail Controls run after mail filters (unless you set the filte to run

"filter" (missing "r").


When you're done, upload a new (Mercurial) patch, request review from me for the new patch and once I've set r+ request approval-seamonkey2.0.1 for it to get this into 2.0.1. Thanks for working on this!

Comment 17

[RickieES aka Ricardo Palomares]

Attachment: Patch applying fixes outlined in comment #16 [Checkin: comments 19+20]

I'm always asking forgiveness for my delays, so I won't do an exception here. :-) Sorry, I've been busy IRL and reviewing my SM localization. Here is the patch (based on comm-central, although no changes have landed in mail_help.xhtml in neither comm-central nor comm-1.9.1).

Comment 18

[Jens Hatlak (:InvisibleSmiley)]

Comment on attachment 408298 [details] [diff] [review]
Patch applying fixes outlined in comment #16 [Checkin: comments 19+20]

There's trailing whitespace in the line "or remove additional actions." and the first occurence of "Tag Message" needs to be capitalized as well. I can easily address those two on checkin, thus r=me.

Comment 19

[Jens Hatlak (:InvisibleSmiley)]

Comment on attachment 408298 [details] [diff] [review]
Patch applying fixes outlined in comment #16 [Checkin: comments 19+20]

http://hg.mozilla.org/comm-central/rev/cef2a64db731

Comment 20

[Jens Hatlak (:InvisibleSmiley)]

Comment on attachment 408298 [details] [diff] [review]
Patch applying fixes outlined in comment #16 [Checkin: comments 19+20]

http://hg.mozilla.org/releases/comm-1.9.1/rev/bb5939898954