474525 - Help update for Synchronization & Storage (Disk Space) settings

Status: RESOLVED FIXED

(SeaMonkey :: Help Documentation, defect)

Description

[Serge Gautherie (:sgautherie)]

(I noticed this whilst testing bug 369096 comment 18.)

Comment 1

[rsx11m]

Serge, how specific do you intend this to be for bug 436615 only?

I'm currently looking into the account-manager bugs I was involved in (and related ones) to see which updates are required for the help content, that's bug 410597 and bug 478605 for the Synchronization & Storage page. With your agreement, we could generalize this bug to "Help update for Synchronization & Storage (Disk Space) settings" to handle all of those in a single patch.

> That part is still a confusing, I would say:
> For example, selecting an Imap Inbox in its folder property does not select the
> "Keep messages ..." checkbox in its corresponding settings, thus its advanced
> button remains disabled.

If you expect significant follow-up changes for bug 436615 requiring additional modifications in the help content, I can file those other changes as a separate bug so that this one here can be kept specific. On the other hand, what you described in your comment sounds more like a bug in the logic of the "Keep" checkbox, it should be ascertained though that the folder settings apply regardless of what that box shows.

Comment 2

[Serge Gautherie (:sgautherie)]

(In reply to comment #1)
> Serge, how specific do you intend this to be for bug 436615 only?

I filed this bug as a reminder only.

> With your
> agreement, we could generalize this bug to "Help update for Synchronization &
> Storage (Disk Space) settings" to handle all of those in a single patch.

Do as is best for your work ;-)

> > That part is still a confusing, I would say:
> > For example, selecting an Imap Inbox in its folder property does not select the
> > "Keep messages ..." checkbox in its corresponding settings, thus its advanced
> > button remains disabled.
> 
> If you expect significant follow-up changes for bug 436615 requiring additional
> modifications in the help content, I can file those other changes as a separate
> bug so that this one here can be kept specific. On the other hand, what you
> described in your comment sounds more like a bug in the logic of the "Keep"
> checkbox, it should be ascertained though that the folder settings apply
> regardless of what that box shows.

(I'm not sure where this comes from.)

Comment 3

[rsx11m]

Ok, I'll see what has to be done based on the current state of implementation.

(In reply to comment #2)
> (I'm not sure where this comes from.)

From the comment you are referring to in your own reminder. ;-)

> (I noticed this whilst testing bug 369096 comment 18.)

Comment 4

[Serge Gautherie (:sgautherie)]

(In reply to comment #3)
> From the comment you are referring to in your own reminder. ;-)

Ah, yes ... Well, comment 17 and comment 18 questions there are unanswered, I'll probably need to open new bugs about it...

Comment 5

[rsx11m]

If you do, please make them block this bug here so that we can keep track of any changes and update the help content as necessary.

Comment 6

[rsx11m]

I think this describes the current behavior of the new folder selection, based on some testing and code review:

(mail_help.xhtml, starting line 3962 in its current version)
>  <ol>
>    <li>Open the Edit menu and choose Mail &amp; Newsgroups Account Settings. You
>      see the Mail &amp; Newsgroups Account Settings dialog box.</li>
> +  <li>Choose the Synchronization &amp; Storage category for an IMAP
> +    account.</li>
>  </ol>
> 
> +<ul>
> +  <li><strong>Keep messages for this account on this computer</strong>: Select
> +    this option so that messages in your folders will be available when you
> +    are working offline. This setting also applies to any new folders
> +    created or subscribed to.</li>
> +  <li><strong>Advanced</strong>: Click to open a dialog to select the
>      folders that you want to make available for offline use. See
>      <a href="#selecting_items_for_offline_viewing">Selecting Items for Offline
> +    Viewing</a> for more information.
> +    <p><strong>Note</strong>: While the default setting can be overridden for
> +      an individual folder, those per-folder settings are <em>removed</em>
> +      whenever the <q>Keep messages for this account</q> box is toggled.</p>
> +  </li>
>  ...

Thus, while you /can/ specify the offline status per folder, and those will be observed even if the global "Keep" setting is disabled, any such customization will be removed as soon as you touch the "Keep" checkbox. It will just iterate over all folders of the account and set or reset its offline status depending on which status of the general preference you are toggling to.

That certainly may be confusing and would warrant its own bug report. I could imaging either a tri-state (or quad-state) checkbox for "Keep" which would indicate that not all folders have the same offline setting, or just allow the "Advanced" button to be visible also if the "Keep" box is unchecked along with some clarification of the label.

I'll include this description of the current behavior into the patch, though it may change if some rewriting is done for this functionality.

Comment 7

[rsx11m]

Attachment: Proposed updates

This should cover the changes, also renaming a couple of internal references
and their respective wiring. The patch also includes the separate section for
the retention policy setting as proposed in bug 459580 comment #1.

Comment 8

[rsx11m]

Some additional comments on the patch posted yesterday:

> diff -r 1248bb519102 suite/locales/en-US/chrome/common/help/help-index1.rdf
> @@ -1058,19 +1058,19 @@
>       <rdf:li>
> -       <rdf:Description ID="Mail_and_Newsgroups:Disk_Space_settings"
> -         nc:name="Disk Space settings"
> -         nc:link="mail_help.xhtml#offline_and_disk_space"/>
> +       <rdf:Description ID="Mail_and_Newsgroups:synchronization_and_storage_disk_space"
> +         nc:name="synchronization &amp; storage, disk space"
> +         nc:link="mail_help.xhtml#synchronization_and_storage"/>
>       </rdf:li>

The fact aside that this would have to be moved into its alphabetically correct order (where we currently don't have an alphabetical index in the help viewer, but anyway), I'm not sure if this is the best way to represent this category. The underlying problem is that it may have two different names ("Disk Space" or "Synchronization & Storage" depending on account type) for the same panel, and is indeed addressing two different things.

The alternative proposal is to have two entries instead, one for example named "disk space and storage settings" at the current location, the other "offline synchronization settings" more down. In this case, the correct entry pops up with either mutation of disk space versus storage as well as offline versus synchronization. It is my understanding that the entries in that section don't have to match the title of a category but a more of a "how to" nature.

> diff -r 1248bb519102 suite/locales/en-US/chrome/common/help/suite-toc.rdf
> @@ -447,19 +447,19 @@
>  <rdf:Description about="#mail-doc-offline-space">
>      <nc:subheadings>
>        <rdf:Seq>
> -        <rdf:li> <rdf:Description ID="mail_offline_imap" nc:name="IMAP" ...
> +        <rdf:li> <rdf:Description ID="mail_offline_imap" nc:name="IMAP" ...
>          <rdf:li> <rdf:Description ID="mail_offline_pop3" nc:name="POP"  ...
> -        <rdf:li> <rdf:Description ID="mail_offline_nntp" nc:name="News" ...
> +        <rdf:li> <rdf:Description ID="mail_offline_nntp" nc:name="News" ...
>        </rdf:Seq>
>      </nc:subheadings>
>    </rdf:Description>

In this part, I have omitted a reference to "mail_help.xhtml#retention_policy" on purpose. It is more a second-level subheading which equally applies to all three main subheadings, thus it's not listed here. If the table of contents is supposed to have the exact layout of the headings though, I can add this as "Retention", "Retention Policy", or "Message Retention".

Let me know what you think (and anything else you find).

Comment 9

[rsx11m]

Attachment: Proposed updates (v2) [Checkin: Comment 18]

Patch updated for white-space format and including the first part mentioned
in comment #8 to introduce two entries in help-index1.rdf, thus matching both variants of this category. The subsubheading (second part of that comment)
hasn't been changed in suite-toc.rdf for the reasons described.

Comment 10

[Stefan [:stefanh]]

I'm really sorry, but I'm not sure if I'll be able to look at this before my vacation (second week of June).

Comment 11

[rsx11m]

Comment on attachment 374678 [details] [diff] [review]
Proposed updates (v2)
[Checkin: Comment 18]

No problem, I'm switching this to IanN for the time being, maybe he gets a chance to look at this earlier.

Due to bug 326584, I'd probably phrase the retention-policy labels stronger:

> +  <li><strong>Don't delete any messages</strong>: Keep all messages [unless
> +    other criteria apply]. Never delete messages [based on age].</li>

> +  <li><strong>Always delete read messages</strong>: Select this option to
> +    remove read messages [<em>regardless</em> of their age].</li>

The final wording would depend by the labels picked in bug 326584, which could be done as part of the patch there if the rest is ok.

Comment 12

[Ian Neal]

There seems to be a certain amount of duplication in the help around 3084 and 3358 and 4001, if you are able to tackle this easily great, if not, say.

Comment 13

[rsx11m]

It seems rather normal to have a general discussion item which is then
duplicated at the help for a specific pane, saw this in bug 489169 as well for the Composition & Addressing category. Each occurrence has its own context:

 - 3084 is the general introductory "working offline" discussion;
 - 3358 is specific to the selection of folders in the "Advanced" dialog;
 - 4001 has specific instructions for the Synchronization & Storage items.

Unless you can point to an overly redundant part that you have in mind, I'm not exactly sure what and how to change here. Each of those sections should pop up in different situations; e.g., 4001 when clicking Help in the settings pane, with a reference to 3358 for selecting the folders in the Advanced dialog, etc.

Comment 14

[rsx11m]

Ian, thanks for the review. You didn't say if this includes comment #11, so I didn't post a new patch as the current one still applies. It's unclear anyway where bug 326584 is going, a comment suggests to remove the "delete read messages" altogether, in which case the current labels are clear enough again.

Comment 15

[Ian Neal]

(In reply to comment #14)
> Ian, thanks for the review. You didn't say if this includes comment #11, so I
> didn't post a new patch as the current one still applies. It's unclear anyway
> where bug 326584 is going, a comment suggests to remove the "delete read
> messages" altogether, in which case the current labels are clear enough again.

I assumed any changes would be done as part of that patch rather than in here.

Comment 16

[rsx11m]

Right, I'll keep an eye on what's happening with a patch there and will
follow up if necessary changes to the help content aren't taken care of.

Comment 17

[rsx11m]

Comment on attachment 374678 [details] [diff] [review]
Proposed updates (v2)
[Checkin: Comment 18]

If someone checks this in, I can finalize the SeaMonkey part of my patch for bug 326584. ;-)

Comment 18

[Serge Gautherie (:sgautherie)]

Comment on attachment 374678 [details] [diff] [review]
Proposed updates (v2)
[Checkin: Comment 18]


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

Comment 19

[rsx11m]

Thanks, the retention-policy part will be updated in attachment 382147 [details] [diff] [review].