Last Comment Bug 771534 - Create Help documentation for the Preference Pane for Offline Applications implemented in Bug 758677
: Create Help documentation for the Preference Pane for Offline Applications im...
Status: RESOLVED FIXED
:
Product: SeaMonkey
Classification: Client Software
Component: Help Documentation (show other bugs)
: Trunk
: All All
: -- normal (vote)
: seamonkey2.19
Assigned To: rsx11m
:
Mentors:
Depends on: 758677
Blocks: 636993 416234 847182
  Show dependency treegraph
 
Reported: 2012-07-06 08:38 PDT by Philip Chee
Modified: 2013-03-03 08:46 PST (History)
3 users (show)
See Also:
Crash Signature:
(edit)
QA Whiteboard:
Iteration: ---
Points: ---


Attachments
WIP: headers and link targets (4.28 KB, patch)
2013-02-08 06:35 PST, rsx11m
no flags Details | Diff | Splinter Review
Proposed patch (8.46 KB, patch)
2013-02-16 11:28 PST, rsx11m
iann_bugzilla: feedback+
Details | Diff | Splinter Review
Proposed patch (v2) (8.50 KB, patch)
2013-03-02 10:03 PST, rsx11m
iann_bugzilla: review+
Details | Diff | Splinter Review
Final patch (v2b) (8.50 KB, patch)
2013-03-02 12:58 PST, rsx11m
rsx11m.pub: review+
Details | Diff | Splinter Review

Description Philip Chee 2012-07-06 08:38:55 PDT
Bug 758677 Comment 16:
> Follow-up bug or new bug to provide the help?
Comment 1 Philip Chee 2012-07-08 10:54:34 PDT
From: <http://support.mozilla.org/en-US/kb/settings-network-updates-and-encryption#w_offline-web-content-and-user-data>

Offline Web Content and User Data

* Clear Now: Immediately clears data that is being saved by websites for use when you are offline.
* Tell me when a website asks to store data for offline use: Allows websites to store data necessary to be used without an internet connection. If you have previously blocked a website from storing data for offline use and changed your mind, you can click the Exceptions... button. Select the site you want to stop blocking, and click Remove. To remove all websites in the list, click Remove All Sites.

<http://kb.mozillazine.org/Browser.offline-apps.notify>

The HTML 5 Specification defines a mechanism allowing web pages to store information and pre-cached data with a web browser. When websites offer data for offline use, Firefox displays a notification bar in the browser. This preference determines whether Firefox will display the notification or ignore data for offline use.
Comment 2 rsx11m 2013-02-05 12:32:14 PST
I'll try to work this out as a block along with bug 416234 and bug 631566 which need further pointers to the Offline Apps.

For testing I found http://html5demos.com/offlineapp and then there is the official documentation of the feature at http://www.w3.org/TR/offline-webapps/ which also provides a good introduction for the motivation:

"Users of typical online Web applications are only able to use the applications while they have a connection to the Internet. When they go offline, they can no longer check their e-mail, browse their calendar appointments, or prepare presentations with their online tools. Meanwhile, native applications provide those features: e-mail clients cache folders locally, calendars store their events locally, presentation packages store their data files locally.

In addition, while offline, users are dependent on their HTTP cache to obtain the application at all, since they cannot contact the server to get the latest copy.

The HTML 5 specification provides two solutions to this: a SQL-based database API for storing data locally, and an offline application HTTP cache for ensuring applications are available even when the user is not connected to their network."
Comment 3 rsx11m 2013-02-07 10:52:14 PST
Ok, so let's see if I understand this correctly:

 - websites can request to store some or all content locally;
 - if it presents such a manifest, SeaMonkey will check if any
   permissions exist for this site/domain (per Data Manager):
    - if it says "Block" the request is denied,
    - if it says "Allow" the request proceeds;
 - if there are no permissions, it depends on the setting of
   the "Notify..." checkbox:
    - if it is cleared, the request is always denied;
    - if it is checked, an infobar appears:
      - "Allow" will set perms to "Allow" and let it proceed,
      - "Never" will set perms to "Block" and deny the request,
      - "Not Now" denies the request but won't change any perms;
 - checking "Use default" in the Data Manager will clear the entry
   and trigger the infobar to reappear with the next usage;
 - websites can't access offline web content unless allowed,
   even if they were (but aren't any more) allowed to store it;
 - the "Clear" button will trigger offline data to be refetched.

That's what I figured out while playing with the HTML5 demo. Is this correct (and complete), or am I missing anything?
Comment 4 Philip Chee 2013-02-07 21:10:34 PST
> That's what I figured out while playing with the HTML5 demo. Is this correct (and
> complete), or am I missing anything?
That sounds about right.
Comment 5 rsx11m 2013-02-08 04:29:33 PST
Thanks, I'll try to put this into "easy" language.
Comment 6 rsx11m 2013-02-08 06:35:13 PST
Created attachment 711809 [details] [diff] [review]
WIP: headers and link targets

This patch is rather boring, but it establishes headings and anchors needed for bug 416234, and provides the target for the "Help" button in the Offline Apps preference pane.

An introductory section will go on top of "This section describes..." and summarize comment #2. Below the "how to open this pane" part goes the itemized description following comment #3. That's probably all which is needed.
Comment 7 rsx11m 2013-02-16 11:28:44 PST
Created attachment 714817 [details] [diff] [review]
Proposed patch

Here now the first patch with actual contents.

I've noticed that the tree to the left of the preferences window states just "Offline Apps" but the pref pane itself is titled "Offline Web Applications". Thus, I've added the longer title to the help index so that it shows up in searches (also matching "web app" for example).

I'm using "offline storage" in the description even though the label refers to "cache" which may be confusing (and "offline storage" is closer to what's used for the IMAP synchronization, to build a bridge here).

Everything else should be straight-forward.
Comment 8 rsx11m 2013-02-16 16:48:30 PST
Comment on attachment 714817 [details] [diff] [review]
Proposed patch

>+  if you are disconnected from the network. If permitted, websites can store
>+  their content and any data you entered locally in &brandShortName;.

Phil, Ian: Are there any new insights on keeping user-entered data in the offline store? The (surprisingly heated) discussion on this in bug 758677 would suggest that this is possibly separate. If indeed clicking "Clear" won't delete any user data in the process, I should probably remove the "and any data you entered locally" part not to make any misleading or inaccurate statement.
Comment 9 Philip Chee 2013-02-17 06:21:53 PST
I think Bug 758677 comment 24 and the next comment indicate that user-entered data isn't kept in the App Cache. However the clear button will clear both the App Cache and associated local storage (this might be counter-intuitive but it follows what Firefox does).
Comment 10 rsx11m 2013-02-17 08:13:03 PST
Thanks, thus it's hopefully a safe statement.
Comment 11 rsx11m 2013-02-27 09:56:27 PST
Comment on attachment 714817 [details] [diff] [review]
Proposed patch

>+  <li><strong>Your application cache is currently using [__] KB/MB of disk

That label sometimes shows "0 bytes" as well, e.g., after clearing the offline storage. Thus, it may be better to remove the "KB/MB" part given that it's changing all the time.

>+    space</strong>: This entry is informational and provides you with an
>+    estimate of the currently used offline data by all web applications.</li>

Using "by all web applications combined." at the end may be clearer; or, possibly more grammatically correct: "an estimate of the offline data currently used by all web applications combined."
Comment 12 Ian Neal 2013-03-02 09:29:34 PST
Comment on attachment 714817 [details] [diff] [review]
Proposed patch

>+++ b/suite/locales/en-US/chrome/common/help/cs_nav_prefs_advanced.xhtml

>+  <li><strong>Your application cache is currently using [__] KB/MB of disk
bytes also appears when the number is low enough.

>+  <li><strong>Clear</strong>: Immediately clears data that is being saved
Maybe "has been" rather than "is being"

>+      <li><strong>Not Now</strong>: Deny this site to use the offline storage
Perhaps "Deny this site from using" or "Deny this site the use of" instead of "Deny this site to use"

>+      <li><strong>Allow</strong>: Select this option to allow this site
>+        to use the offline storage for all accesses.</li>
Similar to above, needs correcting.
>+      <li><strong>Block</strong>: Select this option to deny this site
>+        to use the offline storage for all accesses.</li>
Similar to above, needs correcting.

>+  <li><strong>The following websites are allowed to store data for offline
>+    use</strong>: Lists the domains of all websites which have stored offline
>+    data, along with the amount of data currently used by this domain.</li>
Perhaps "each domain" rather than "this domain"

>+  <li><strong>Clear data</strong>: Select a website domain and click this
>+    button to delete all offline data for a specific domain. Click <q>Remove
"for the specified domain" rather than "for a specific domain"

f+ for the moment as I would like to see the new patch.
Comment 13 rsx11m 2013-03-02 10:03:21 PST
Created attachment 720302 [details] [diff] [review]
Proposed patch (v2)

(In reply to Ian Neal from comment #12)
> >+  <li><strong>Your application cache is currently using [__] KB/MB of disk
> bytes also appears when the number is low enough.

Yes, that's also what I've noticed in comment #11. Using "bytes/KB/MB" looks funny, thus I've removed the unit completely as it is obvious from the label.

I've also rephrased the end of that description as proposed in my comment.

> >+  <li><strong>Clear</strong>: Immediately clears data that is being saved
> Maybe "has been" rather than "is being"

Done.

> >+      <li><strong>Not Now</strong>: Deny this site to use the offline storage
> Perhaps "Deny this site from using" or "Deny this site the use of" instead
> of "Deny this site to use"

I've made it consistently "this site the use of" as it fits with both "allow" and "deny" equally well.

> >+  <li><strong>The following websites are allowed to store data for offline
> >+    use</strong>: Lists the domains of all websites which have stored offline
> >+    data, along with the amount of data currently used by this domain.</li>
> Perhaps "each domain" rather than "this domain"

Done.

> >+  <li><strong>Clear data</strong>: Select a website domain and click this
> >+    button to delete all offline data for a specific domain. Click <q>Remove
> "for the specified domain" rather than "for a specific domain"

Done.
Comment 14 rsx11m 2013-03-02 12:58:57 PST
Created attachment 720325 [details] [diff] [review]
Final patch (v2b)

Thanks Ian. I've somehow screwed up the checkin message on my previous patch, thus posting a new one to be pushed on comm-central.
Comment 15 Ryan VanderMeulen [:RyanVM] 2013-03-02 19:02:14 PST
https://hg.mozilla.org/comm-central/rev/5623e1fd5491

Note You need to log in before you can comment on or make changes to this bug.