Closed Bug 341899 (pw-doc) Opened 16 years ago Closed 16 years ago
document the prefwindow reorg
Sigh, once more.
I don't think Jeff is the right person to do this, will try to find help.
Whiteboard: [swag: 1 week] → [swag: 1 week][mustfix]
Assignee: jwalden+bmo → rflint
Status: NEW → ASSIGNED
Ryan, did you make some progress? What's the status? I know this is a *lot* of work, so I'd like to know if it's on track.
(In reply to comment #3) > Ryan, did you make some progress? What's the status? I know this is a *lot* of > work, so I'd like to know if it's on track. > Things are going well. I have everything mostly reorganized, rewritten and changes to the prefwindow up to the 26th have been documented. A somewhat out-of-date copy of prefs.xhtml is on my website here: http://www.screwedbydesign.com/mozilla/bugs/341899/prefs.xhtml (I'll try to get a recent copy up tonight :)). I've just been waiting on things to stabilize a bit more before I start posting patches.
*** Bug 347970 has been marked as a duplicate of this bug. ***
*** Bug 347968 has been marked as a duplicate of this bug. ***
trying to give localizers some guidance on when work might land on them. any idea when a freeze point might hit for this?
Content changes only. I'll be attaching patches for the ToC once a few other pages have been updated.
Attachment #235940 - Flags: review?(jwalden+fxhelp)
Comment on attachment 235940 [details] [diff] [review] Patch v1 I've barely looked at any of the actual content of this patch, but the first thing I notice is that you've only patched prefs.xhtml. In order for the entries in the help viewer sidebar to work, you'll have to change all associated entries in the table of contents, glossary, and search database RDF files. You'll also need to search through all other help files for all links which are targeted at prefs.xhtml and ensure that all such links still work. Note that many of the targets are going to have to be renamed during this step (i.e, from "prefs.xhtml#general_options" to "prefs.xhtml#main_options"), and keep in mind that some UI has moved from its original pane to a different (and possibly entirely new) pane, perhaps even changing in the process. You might also want to look at bug 279506 to see what sort of things were done (and how they were done) the last time (gaaah!!!!) we had to do this. I'm working on content-based review comments now, but what I've written so far should give you plenty to do while I'm working my way through it. ;-)
Attachment #235940 - Flags: review?(jwalden+fxhelp) → review-
*** Bug 351028 has been marked as a duplicate of this bug. ***
Assignee: rflint → sheppy
Status: ASSIGNED → NEW
Gotta bow out for a couple hours -- will get back on this when I return. In the meantime, however, do an interdiff between this and the previous patch to see what's changed (preferably with -w if interdiff allows it if you value your sanity).
Assignee: eshepherd → jwalden+bmo
Attachment #237588 - Attachment is obsolete: true
Status: NEW → ASSIGNED
Comment on attachment 237632 [details] [diff] [review] WIP with modifications >Index: firebird-toc.rdf >=================================================================== >+ <rdf:li> <rdf:Description ID="prefs-clear-private-data" nc:name="Clear Private Data Settings" nc:link="prefs.xhtml#clear_private_data"/> </rdf:li> This pref section is named "Private Data". >+ <rdf:li> <rdf:Description ID="prefs-clear-private-data" nc:name="Password Settings" nc:link="prefs.xhtml#security_passwords"/> </rdf:li> >+ <rdf:li> <rdf:Description ID="prefs-history" nc:name="Warning Messages" nc:link="prefs.xhtml#warning_messages"/> </rdf:li> These ID's need to be fixed! They are already used. >+ <rdf:li> <rdf:Description ID="prefs-advanced-networl" nc:name="Network" nc:link="prefs.xhtml#advanced_network"/> </rdf:li> Should be "prefs-advanced-network". >+ <rdf:li> <rdf:Description ID="prefs-advanced-security" nc:name="Encryption" nc:link="prefs.xhtml#advanced_encryption"/> </rdf:li> Should be "prefs-advanced-encryption". >Index: prefs.xhtml >=================================================================== >+<p><em>Warn when closing multiple tabs</em><br/> Warn *me* when closing multiple tabs >+<p><em>Warn when opening multiple tabs might slow down &brandShortName;</em><br/> Warn *me* when opening multiple tabs might slow down &brandShortName; >+<p><em>Always show the tab bar</em><br/> >+ If you're only viewing one web page in a &brandShortName; window, the tab >+ bar is not not normally shown. Check this &pref.singular; to always show s/not not/not/ >+ <p><em>Show me a preview and ask me which Feed Reader to use</em><br/> >+ When you view a feed within &brandShortName;, you will be shown a preview >+ of its contents. With this &pref.singular; selected, you given a choice "you *are* given a choice"? >+ <h3 id="security_passwords">Passwords</h3> >+ <p><em>Remember passwords for sites</em><br/> >+ &brandShortName; can securely save passwords you enter in web forms to >+ make it easier to log on to web sites. Clear this checkbox to prevent >+ &brandShortName; from remembering your passwords. </p> Should perhaps the "Exceptions..." button be documented? >+ <dt>I leave an encrypted page for one that isn't encrypted</dt> >+ <dd>With this &pref.singular; is enabled, &brandShortName; will warn you Superfluous "is" here. Same thing in the following two <dd>'s. > <h4 id="languages">Languages</h4> >- > <p>Some web pages are offered in more than one language. Click the > <em>Edit Languages...</em> button to specify your preferred > languages.</p> The button is now labeled "Choose...". > <h3 id="advanced_update">Update tab</h3> Here there is a checkbox previously labeled "Warn me if this will disable extensions or themes" that is now called "Warn me if this will disable any of my add-ons".
Assignee: jwalden+bmo → jwalden+fxhelp
Status: ASSIGNED → NEW
Typo/ID fixes merged with Jeff's patch
Attachment #237632 - Attachment is obsolete: true
Interdiff of the lastest two patches sans whitespace.
Still working down through prefs.xhtml... I've folded in the mentioned changes in v3 (I've been working from v2), so those issues should all be "addressed" here (in the sense that the changes have been made, not that the changes are necessarily final). I've made the changes I think are necessary up to the <!--DONE TO HERE--> note, and what's before there should be in reasonable shape. Still plugging away...
Whiteboard: [swag: 1 week][mustfix] → [WIP patch, traction happening]
I should have just done this while I was writing the prefwindow and not budged on doing the two simultaneously -- this timing is ridiculous. Things done to ensure content is up-to-date: - complete read-through of prefs.xhtml with tweaks/rewrites of anything and everything that I thought needed it - tree-wide search for "prefs.xhtml" to verify each location is correct - skim-through of all existent help files for references to prefs - a further search for "pref" in all help docs to catch any references - search for helpURI, helpTopic to check that all help buttons should work - verification of ids during traversal of prefs.xhtml for modifications Things with which I could use help: - testing every single table-of-contents entry, search entry, and link within help docs to ensure all work correctly - testing of all help buttons to ensure all work correctly - verification that &pref.(singular|plural)(Caps)?; is used instead of "preferences" or "options" (platform-specific terminology) in all places where it makes sense - checking for adherence to the help docs style guides (note that some current docs don't fully adhere; I changed [and will change] only that which I was already touching): <http://www.mozilla.org/projects/help-viewer/documentation_language-style> <http://www.mozilla.org/projects/help-viewer/documentation_coding-style> - a read-through of the changes to see if anything doesn't make sense, could use "better" (more concise, clearer, etc.) wording, is overly technical or requires more knowledge than an average-ish Internet user might know (or any other concern, however trivial) - grammar/spelling checks -- I'm good, but I'll occasionally slip - double-check that the words used in docs match up *exactly* with the words in UI (consistency) - what exactly are "raise"ing and "lower"ing windows (advanced JS options)? - security warnings dialog explanatory text: suggest improvements or complain loudly if weak explanations aren't worth the space they take, since none of the descriptions are more meaningful than their UI - *anything whatsoever that you think might be a concern* This could use as many eyes as possible, partly because this is late, partly because I doubt I'm going to have the time in the next couple days to give an accounting of why I made most of the changes I did, partly because the usual reviewer's not really around for a few more days (unless you have time for some drive-by reviewing from Turkey, Steffen? ;-) ), and mostly because this is really bloody huge. Please -- *anyone* -- if you have useful comments on prefwindow-related docs content, post them here.
Can we please, for l10n sake, avoid renaming the help topic anchors? It seems gratuitous and will cause otherwise-working localized help to not work.
Stupid question: how do I actually take the patch and turn it into something I can read?
Jeff: This is crazy big. It'll take at least 4-7 days for localizers to work on this, and I'm only talking about active localizations (first 20 or so). It seems impossible for me to get all localizations do this changes anytime that soon. :(
As we've stated before, the localization of help is basically independent of the en-US text; localizers can fix the docs at any time before or after this lands. What I'm worried about is the integration-point change, which makes localized help depend on this patch.
OK, I'm reading this over now that I've built with the revised help, and here are some comments: General comments: - The headings indicating the label of a control are formatted in several different ways. Sometimes, it's on a line all by itself and sometimes it's not. Sometimes it has a colon after it and sometimes it doesn't. These need to be standardized, preferably on a line by themselves with no colon. See "When Bon Echo starts:", "Home Page", and "Show the Downloads window when downloading a file", all right at the top of the Main Preferences section for examples of three different ways this heading is done. Main Preferences: - Under "When Bon Echo starts:", there is no blank line between the first two paragraphs, while there is everywhere else. - "Home page" section -- change "you select your home page" to "you specify your home page" Tabs Preferences: - I suggest changing "Cmd" to "Command" when describing the command key on the Mac, at least the first time you mention it. Content Preferences: - "Load images automatically" -- this section has some awkward wording: "Depending on if you enable images,..." This sentence doesn't make a lot of sense. Perhaps something more like: "If you enable loading images automatically, the Exceptions... button lets you select sites from which images will not automatically load. If image loading is disabled, the Exceptions... button lets you specify sites from which images will automatically load." Or something like that. - "Enable Java" -- this description mentions that you have to install the Java plugin, but it's installed automatically as far as I know. This might need to be rephrased somehow. On Windows, you do have to install the JVM itself though. - "Fonts & Colors" -- it might be a good idea to specifically say that the "Fonts Dialog" is what's opened when you click the Advanced... button. More coming...
(In reply to comment #20) > Can we please, for l10n sake, avoid renaming the help topic anchors? It seems > gratuitous and will cause otherwise-working localized help to not work. Certainly some of it can be un-renamed, but most of the changes things are significant and are the result of things which didn't exist in the old prefwindow. I can avoid some changes such as fonts/colors dialogs to make things easier, but for most of it retaining names is more likely to induce a false sense of workingness than to actually save work. By the way, this is a trunk patch (which might coincidentally apply to branch), and it's going to remain one. I'll fix branch issues such as un-renaming in a branch patch. (In reply to comment #22) > Jeff: This is crazy big. It'll take at least 4-7 days for localizers to work > on this, and I'm only talking about active localizations (first 20 or so). Don't I know; this was most of my Friday night, pretty much all of Saturday and Sunday, and most of my Monday night.
Feeds Preferences - "For example, a feeds might summarize" -- "feeds" should be "feed" here. Privacy Preferences - Instead of "Cmd+J", use "Cmd-J" or "Command-J". Mac users use "-" rather than "+" to indicate pressing multiple keys at once. - "Cookies" -- I suggest changing "such as your preferences when visiting that site" to "such as site specific preferences". This sounds less like Firefox stores its own preferences in cookies. - "Private Data" -- change "Cmd+Shift+Del" to "Command-Shift-Delete" or "Cmd-Shift-Delete". I also suggest changing "To clear your private data at a later time" to "To clear your private data from outside the preferences window". Security Preferences - I'd like to suggest mentioning the word "phishing" in the description of "Tell me if the site I'm visiting is a suspected forgery", even though the term isn't used in the UI. - "Remember passwords for sites" -- there's no blank line between the two paragraphs in this section. - "Use a master password" -- there's some awkward wording here. Try changing "Bon Echo will ask you to enter it once each time you open Bon Echo the first time it's needed" to "each time you start Bon Echo, it will ask you to enter the password the first time it needs to access a certificate or stored password." I also suggest changing "If a master password is already set, you will need it to change..." to "If a master password is set, you will need to enter it in order to change..." More to come.
Advanced Preferences - In the Update tab, under "Automatically download and install the update", there's no blank line between the two paragraphs. I'll look at the rest of the changes after lunch.
Per the bonecho meeting today, we'd like to get this landed on the branch today, without the renamed IDs, so that localizers can translate it appropriately; details of language can be fixed subsequently if necessary. Jeff, can you manage to do this today, or coordinate with sheppy about doing so?
Assignee: jwalden+fxhelp → eshepherd
Status: ASSIGNED → NEW
I'm working on getting it migrated to branch now, and I'll apply appropriate changes based on my review as well.
Jeff's right that reverting the IDs is going to be a massive pain. Both the docs and the prefs window have been significantly reorganized, meaning that even if we put as many names back as we can, links are still likely to go to the wrong place unless they get updated.
How desperately do we need to keep the same anchor IDs? There's no way not to change at least some of them due to the sizeable difference in content and the arrangement of this window. I can get a final patch submitted with the IDs Jeff used within an hour. Redoing all the IDs will take at least a day, probably two, given the need to maintain integrity with the revamped doc layout while at the same time keeping compatible with the old IDs.
Realistically, I don't see how there's any gain from reverting any more ids than the ones involved in the changes to non-help files (which basically comes to only the fonts and colors dialogs and the private data section ids).
That's what I was talking about, the changed entrypoints from the prefwindow. I don't care about IDs that are internal to the en-US help.
Oh, okay, I can take care of that relatively easily. Working on it now.
This is my revised version of Jeff's patch, with some minor corrections, the entry point target IDs reverted to the previous names, and the colors and font dialogs both routed to the same main section head in the help instead of the the corresponding subheaders in order to make that possible.
Comment on attachment 238132 [details] [diff] [review] Hopefully final en-US patch we need to get this in ASAP. I tested this, looks good (at least isn't broken). This seems pretty complete, but let's get it into builds so everyone can test tomorrow. Please continue to look for things
landed. marking fixed1.8.1 please file any issues with the new text or missing bits as followups, assigning to sheppy and nominating for blocking!
Status: NEW → RESOLVED
Closed: 16 years ago
Resolution: --- → FIXED
Small issues found: - using_firebird.xhtml contains ">File Types &pref.plural;<", but I think the &pref.plural is not needed here as it does not refer to one of the pref sections - the same file contains "to to" (move it around) - The new Google section in menu_reference.xhtml appears to contains unnecessary spaces ("will be anonymous" and "policy. Requires")
I've applied fixes for those to my copy of the files. I'll post a new patch later this evening, unless someone needs a patch earlier than that.
Fixes all known issues up to the moment.
Maybe a stupid question, but what is this for: <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:nc="http://home.netscape.com/NC-rdf#"> Why the RDF namespace is declared twice here, one time as the default one, and the second time as the "rdf" one?
(In reply to comment #41) > Maybe a stupid question, but what is this for: > > <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" > + xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#" > xmlns:nc="http://home.netscape.com/NC-rdf#"> Ah, the joy of XML namespaces... We use it as the default namespace to avoid having to prefix a lot of elements with "rdf" -- cuts down on clutter dramatically. We "still" have an "rdf" prefix for two reasons. First, I only changed elements I was already touching (to keep the noise ratio down for localizers), so the file is half-cleaner, half-still-dirty. (See search-db.rdf for a fully clean file.) Second, even if I had changed the entire file, the ID/about attributes on most of the elements when unprefixed are not in a namespace, but the RDF spec requires that those two attributes actually be in the RDF namespace and not in no namespace. (Contrast this with XHTML, which takes the sensible view that XHTML attributes aren't in a namespace, eliminating a ton of noisy prefixing.) Mozilla accepts the two in no namespace as a historical quirk, but I'd prefer not to rely on Mozilla quirks and would rather write valid RDF whenever possible. If you have further questions, ask. XML namespaces just suck that way.
(In reply to comment #42) > We "still" have an "rdf" prefix for two reasons. First, I only changed > elements I was already touching (to keep the noise ratio down for localizers), ...and thank you for keeping this ratio down. :) > If you have further questions, ask. XML namespaces just suck that way. No, your answer satisfies me, and I'm now ready to port these changes to the localized firebird-toc.rdf. :) Thanks.
Some more preference fixes. This rolls up the changes in the patch posted on 9/13 as well as fixing cases where the term "option" was being hardcoded instead of using the &pref.singular; code.
Attachment #238685 - Flags: review? → review?(mconnor)
Comment on attachment 238685 [details] [diff] [review] More help text fixes Needs a couple more tweaks we've found.
Attachment #238685 - Flags: review?(mconnor)
This should wind up all the help fixes known to date that haven't already been applied.
Attachment #238685 - Attachment is obsolete: true
Comment on attachment 238735 [details] [diff] [review] More help text fixes >Index: browser/locales/en-US/chrome/help/prefs.xhtml >=================================================================== > <p>In Page Setup, you can change the following settings for pages you want to > print:</p> > > <ul> >- <li><strong>Format & Options</strong>: Choose the orientation, scale, and other >- options: >+ <li><strong>Format & &pref.pluralCaps;</strong>: Choose the orientation, scale, and other >+ &pref.plural;: The label for that tab actually is "Format & Options" on all three platforms. http://lxr.mozilla.org/mozilla/source/toolkit/locales/en-US/chrome/global/printPageSetup.dtd#5
Comment on attachment 238735 [details] [diff] [review] More help text fixes r=me with comment 47 addressed (don't change "Format & Options"). And thanks everyone for the hard work! I haven't had time to read through the entire document yet, but all the Help buttons and the toc links work.
This includes all the fixes from the previous patch that hasn't been implemented yet (invalidated by this attachment), plus three more caught by tonnes, including two silly typos and one window referred to by the wrong name.
Comment on attachment 239037 [details] [diff] [review] Wraps up all the unimplemented changes, plus new ones r+a=me with pref.singular corrected to pref.plural where it matters
Comment on attachment 239037 [details] [diff] [review] Wraps up all the unimplemented changes, plus new ones As you can't use "display: none" in <title> effectively, this: - <title>&brandFullName; Options</title> + <title>&brandFullName; &pref.pluralCaps;</title> will be rendered as "Mozilla Firefox OptionsPreferences"... <title> tags are only displayed if the file is opened in a normal browser window, not in the help browser.
Comment on attachment 239037 [details] [diff] [review] Wraps up all the unimplemented changes, plus new ones >Index: browser/locales/en-US/chrome/help/using_firebird.xhtml >- <li><strong>Format & Options</strong>: Choose the orientation, scale, and other >- options: >+ <li><strong>Format & &pref.pluralCaps;</strong>: Choose the orientation, scale, and other >+ &pref.singular;: Again, this change is wrong. The first tab is the Page Setup dialog is called "Format & Options" across platforms: http://lxr.mozilla.org/mozilla1.8/source/toolkit/components/printing/content/printPageSetup.xul#68 http://lxr.mozilla.org/mozilla1.8/source/toolkit/locales/en-US/chrome/global/printPageSetup.dtd#5
This fixes the minor glitch mconnor spotted and reverts a couple of unnecessary changes we decided not to apply.
Attachment #239037 - Attachment is obsolete: true
OK, where is this tab anyway, because I can't find it anywhere in the UI to actually see it. The Page Setup dialog box has no Firefox customizations to it of any kind on the Mac.
On Windows, menu File -> Page Setup. The dialog has a "Format & Options" tab and a "Margins & Header/Footer" tab. Your last patch still changes "Format & Options" to "Format & &pref.pluralCaps;". Just remove the second hunk of the using_firebird.xhtml changes from your last patch.
I can undo the patch, but I still don't understand why it matters, since the tab in question doesn't actually exist on the Mac anyway.
Fixed the "Format & Options" thing.
Attachment #239039 - Attachment is obsolete: true
(In reply to comment #57) > Created an attachment (id=239044)  > Fixes steffen's reported issue > > Fixed the "Format & Options" thing. I think using &pref.singular; on those 2 cases in prefs is not a good idea, as these are 2 of 3 selectable drop-down menu options (thus choices, not settings) of which the 3rd is still left as it is. Doing so would look weird or even be confusing for mac/unix in many languages. If you leave these out as well, it should be OK.
> I think using &pref.singular; on those 2 cases in prefs is not a good idea, as > these are 2 of 3 selectable drop-down menu options (thus choices, not settings) > of which the 3rd is still left as it is. Doing so would look weird or even be > confusing for mac/unix in many languages. If you leave these out as well, it > should be OK. Are there specific places you're concerned about? I changed several of these back to "option" in the most recent revision of the patch.
(In reply to comment #56) > I still don't understand why it matters, since the > tab in question doesn't actually exist on the Mac anyway. The Page Setup tab exists on Linux though, and is labelled, like on Windows, "Format & Options".
(In reply to comment #59) > Are there specific places you're concerned about? I changed several of these > back to "option" in the most recent revision of the patch. You did well; I was talking about the 2 that were left in.
customization.xhtml has a link to https://addons.mozilla.org/extensions/ . Shouldn't this link conform to http://wiki.mozilla.org/Firefox2/L10n_Requirements#addons.mozilla.org_.28AMO.29 ?
I'm not convinced it should. en-US help is strictly copied over for quite a few locales, and I'd prefer it to stay that way. A locale-independent URL seems to be better here than a hard-coded en-US one.
You need to log in before you can comment on or make changes to this bug.