Closed Bug 881057 Opened 6 years ago Closed 6 years ago

Improve wording in the appcache command

Categories

(DevTools Graveyard :: Graphic Commandline and Toolbar, defect)

defect
Not set

Tracking

(Not tracked)

RESOLVED FIXED
Firefox 24

People

(Reporter: bugzilla, Assigned: miker)

References

Details

Attachments

(1 file)

When localizing the strings for the new appcache command, I found two strings that I think are difficult to understand:

asteriskInWrongSection=Asterisk used as a wildcard in the %S section at line %S. A single line containing an asterisk is called the online whitelist wildcard flag and is only valid in the NETWORK section. Other uses of the * character are prohibited. The presence of this flag indicates that any URI not listed as cached is to be implicitly treated as being in the online whitelist namespaces. If the flag is not present then the blocking state indicates that URIs not listed explicitly in the manifest are to be treated as unavailable.

fallbackAsterisk=Asterisk (*) incorrectly used as a wildcard in a fallback namespace at line %S. Namespaces simply need to match a path prefix.

Both strings use the term "namespace". I have only found this term in the HTML spec on how to parse a cache manifest. I have not found any tutorials or other documentation on appcache, that uses this term. I believe the spec language is targeted at browser developers and not web developers. The strings refer to terms defined in the spec, but not used anywhere else, such as "the online whitelist wildcard flag", "online whitelist namespaces", "blocking state" and "fallback namespace". I therefore think these two strings may be easy to understand for browser developers, but not for web developers.

Also, when I tried out the validator on http://html5demos.com/offlineapp the asteriskInWrongSection message was shown (because the manifest contains NETWORK: http://*). It did not seem to me like the message signaled an error, but after reading up on it, it does seem to me like an error.

I suggest these alternative strings:

asteriskInWrongSection2=Asterisk (*) incorrectly used in the %S section at line %S. If a line i the NETWORK section contains only a singler asteisk character, then any URI not listed in the manifest will be treated as if the URI was listed in the NETWORK section. Otherwice such URI will be treated as unavailable. Other uses of the * character are prohibited.

fallbackAsterisk2=Asterisk (*) incorrectly used in the FALLBACK section at line %S. URIs in the FALLBACK section simply need to match a prefix of the request URI.

PS: Please always use %1$S, %2$S, ... instead of %S, %S, ... in strings when there are multiple replacements. It makes it much easier for localizers to know how to do it if they need to change the order of the replacements.
Another difficult to understand string in this file is cacheManifestOnlyFirstLine:

"CACHE MANIFEST" is only valid on the first line at line %S. 
Suggestion:
"CACHE MANIFEST" is only valid on the first line but was found at line %S.
I agree with these changes although there were a couple of typos.

We should have:

asteriskInWrongSection2=Asterisk (*) incorrectly used in the %S section at line %S. If a line in the NETWORK section contains only a single asterisk character, then any URI not listed in the manifest will be treated as if the URI was listed in the NETWORK section. Otherwice such URIs will be treated as unavailable. Other uses of the * character are prohibited.

fallbackAsterisk2=Asterisk (*) incorrectly used in the FALLBACK section at line %S. URIs in the FALLBACK section simply need to match a prefix of the request URI.

cacheManifestOnlyFirstLine2="CACHE MANIFEST" is only valid on the first line but was found at line %S.
Status: UNCONFIRMED → NEW
Ever confirmed: true
Attached patch PatchSplinter Review
Attachment #760859 - Flags: review?(jwalker)
Assignee: nobody → mratcliffe
Status: NEW → ASSIGNED
Attachment #760859 - Flags: review?(jwalker) → review+
Whiteboard: [land-in-fx-team]
https://hg.mozilla.org/mozilla-central/rev/fdbd98251aad
Status: ASSIGNED → RESOLVED
Closed: 6 years ago
Flags: in-testsuite+
Resolution: --- → FIXED
Whiteboard: [fixed-in-fx-team]
Target Milestone: --- → Firefox 24
Depends on: 882337
No longer depends on: 909681
Product: Firefox → DevTools
Product: DevTools → DevTools Graveyard
You need to log in before you can comment on or make changes to this bug.