254982 - "preference" in docs in Linux, "option" in docs elsewhere

Status: RESOLVED FIXED

(Firefox Graveyard :: Help Documentation, defect)

Description

[Jeff Walden (gone starting June 8)]

This is is hit-or-miss for getting into Firefox 1.0 before the localization
freeze, but I'll give it a shot.  If I can do it relatively cleanly (which I
think I can), I'll have a patch tonight.  For good luck I'll be nominating this
for blocking-aviary1.0PR in a second.

Comment 1

[Jeff Walden (gone starting June 8)]

Nope, too late tonight.  Patch tomorrow night.

Comment 2

[Jeff Walden (gone starting June 8)]

Attachment: Replace Tools &gt; Options with platform-specific <span>s

The method used is described below.

Unpatched:
...simply visit <span class="menuPath">Tools &gt; Options</span> to set...

Patched:
...simply visit <span class="menuPath"><span class="noUnix">Tools &gt;
Options</span><span class="unix">Edit &gt; Preferences</span></span> to set...

It's rather ugly, but it's completely functional.  The decision to use nested
<span>s instead of <span class="menuPath noUnix"/><span class="menuPath unix"/>
was completely arbitrary, and as long as we don't cut the timing too close I
could create a patch for that method if it's the preferred one.

Notes: the attached patch fixes this bug, but because of approval backups and
waiting checkins it also includes fixes for bug 249231 and bug 253657.	I very
much hope that doesn't make it more difficult to check into the tree, tho I
hear cvs is usually intelligent enough to figure out these things.

Comment 3

[Jeff Walden (gone starting June 8)]

Comment on attachment 155765 [details] [diff] [review]
Replace Tools &gt; Options with platform-specific <span>s

This bug is impossible for 1.0...we did a bug on Mozdev that got rid of all
references to preferences, and we'd have to fix them all back using CSS to
properly fix this.

The only way I can think to do this is to create several entities with
different cases and states of pluralization that would hold the proper text
within associated <span/> elements, perhaps like so:

&options.pluralCaps;
 - is equal to -
<span class="unix">Preferences</span><span class="noUnix">Options</span>

This is simply impossible before 1.0.  The docs will be wrong, but
realistically there's nothing we can do about it now.

Comment 4

[Jeff Walden (gone starting June 8)]

Note to self: make sure to work around the OS/2 issues the link below might
present (as well as the other OS/2 issues that exist but haven't been investigated).

http://bugzilla.mozilla.org/show_bug.cgi?id=255609

Comment 5

[Jeff Walden (gone starting June 8)]

Reevaluating this.  This is an ugly bug that needs to be fixed for 1.0.

Comment 6

[Jeff Walden (gone starting June 8)]

Attachment: Create entities for option/preference (various caps states) and use them

The method used is as follows:

First, create a DTD file to hold all entities that refer to
options/preferences.  Entities added to the file include one for "Tools >
Options", "preference", "preferences", "Preference", and "Preferences".  Within
each entity, include specific HTML coding to display the proper string on each
platform.  Do so by enclosing each string in an element and giving each element
the proper platform class for platformClasses.css to hide or display as needed.
 Pull in this DTD file in all Help documents.  Then, systematically replace all
references to the original text with the proper entity.

There are also a few additional, mostly unrelated changes here.  One corrects
the documentation on downloading, which didn't reflect the autodownload policy
that's now on all platforms.  I tried to eliminate extraneous use of
"preference" and "option" while doing this (to simplify greps to make sure I'd
gotten everything).  I also updated the dates at the bottom of every file
because of the new DTD that gets pulled with every document view.

Comment 7

[Jeff Walden (gone starting June 8)]

Comment on attachment 160846 [details] [diff] [review]
Create entities for option/preference (various caps states) and use them

Steffen, what do you think of this?  The only bad part of this is that it won't
fix the ToC and index, but that's part of another bug and can't be fixed with
this method.

Also, I forgot one other extraneous change: the DTD contains a few entities for
the bug to display Cmd on Mac for keyboard shortcuts.  They aren't hooked up,
tho -- I'm waiting for this patch to get in before doing that.

Comment 8

[Steffen Wilberg]

Comment on attachment 160846 [details] [diff] [review]
Create entities for option/preference (various caps states) and use them

Ouch! I guess it's consequent to the things in Preferences preferences instead
of options. But localizers will probably shoot us :)

Is it really necessary to get rid of the word "option" altogether?
Like in "Select the 'ask me every time' option from the Keep Cookies combo
box"?

Anyway, I really like the concept of using entites. Please add a <!--
LOCALIZATION NOTE --> to platformStrings.dtd, telling the localizers that they
may add (and use) entities if they need it for grammatical cases, like
pref.dative.singular etc.

Comment 9

[Steffen Wilberg]

> Ouch! I guess it's consequent to the things in Preferences preferences instead
...to call the things...

Comment 10

[Jeff Walden (gone starting June 8)]

Fixed branch and trunk with this l10n note:

> This file contains platform-specific strings which
> occur in large numbers throughout Help docs.
> Generally, for these strings it's less code to store
> them here than to hard-code the value of the entity
> in every place it's used, or using an entity is less
> confusing than typing a string like the jumbled messes
> used below for "preference" and derivatives.  Feel free
> to add more strings here as long as you run them by the
> Help module owner first (to prevent excessive use of
> such strings when other methods are preferable).

Now it's on to the keys bug to hook up the entities for those, sometime
/relatively/ soon (hopefully within a few days, not quite sure tho).  Scratch
another bug from the 1.0 list...