289776 - Make Help table of contents fully platform-specific

Status: RESOLVED FIXED

(Firefox Graveyard :: Help Documentation, defect)

Description

[Jeff Walden (gone starting June 8)]

Once I check in the patch in bug 254992 when I have time to watch the tree,
we'll be able to have platform-specific panel data in Firefox Help.  We should
start taking advantage of this.

The apparent lack of any real ordering in how nodes are listed when the nodes
are split between documents will be helpful here, because the patch doesn't
allow for any detailed sequencing of platform-specific and platform-independent
nodes (i.e., have <specific><general><specific><general><specific> without using
5 separate RDF files to store the data.  Of course, if a node's contents are
entirely specific to one or all platforms, this isn't a problem.

The problem of how to specify platform-independent children of a
platform-specific node (e.g. the children of the Options document) without
duplicating the data in the source tree is one that will require some
consideration.  Duplicating the data is easy, but keeping it in sync becomes
annoying.  Another possible solution would be to store such data in a DTD. 
Because the platform-specific node's ID isn't the same for all platforms (it'll
be <platformfile>.rdf#ID), I don't think there's a way to do this with just RDF,
but I could be wrong.

Comment 1

[Jeff Walden (gone starting June 8)]

A list of somehow-platform-specific stuff in firebird-toc.rdf:
-top level
  -Options topic needs title change (more stuff enum'd below)
-sub levels
  -download manager
    -options
  -using Firefox
    -navigating pages > copy/save/print pages > using print preview
    -improving speed/efficiency > make default browser
  -controlling popups
    -options
  -options/preferences
    -Make Default Browser
  -menu reference
    -Firefox menu
    -Window menu
    -File > Print Preview
    -File > Exit/Quit
    -Edit > Preferences
    -Tools > email stuff
    -Tools > Options
    -Help > For IE Users

...and I think that's it.  This is going to be a real pain, especially with how
things are sometimes interwoven.  I'm really starting to think the original idea
of having an optional nc:platform attribute for RDF nodes here is a much, much,
much better idea than attempting to use what's already available throughout (the
problem being that we'd have to write a patch and get it approved ASAP).  It's
more logical and would have less redundancy (which would make it easier to write
patches).  As it is right now we're going to have a lot of duplication of stuff
(particularly in the Options topic, and I haven't even gotten to the index yet)
if we do it the way I think we'd do it.

Comment 2

[Jeff Walden (gone starting June 8)]

As a bug affecting l10n, I have to fix this before the freeze coming up in the
next couple weeks.  This will require bug 295817 and bug 296012 both be fixed
before the l10n freeze.  Both have mostly-working patches, but because of code
overlap it'll take me at least couple days to provide a final patch for bug
296012 after bug 295817 is fixed.

The fix for this bug should be trivial, tho it will be somewhat tedious.  I
estimate it would take probably an hour to produce (and thoroughly test, once
bug 296012 is fixed).

Comment 3

[Hendrik Maryns]

Hi, I suppose this will involve getting rid of the parentheses around (windows)
in
http://lxr.mozilla.org/mozilla/source/browser/locales/en-US/chrome/help/menu_reference.xhtml#75,
as well as the remarks in the same file that some options are not/only available
on platform X?  (Line 96)

Comment 4

[Hendrik Maryns]

It seems like there is an entry missing in menu reference: Under Go, there is
also a link to the history, which isn't documented. (Windows)

Comment 5

[Hendrik Maryns]

Also, the explanation for Quit/Exit seems a bit nonsensical: if there is any
window open... there always is a window open!

Comment 6

[Hendrik Maryns]

(In reply to comment #5)
> Also, the explanation for Quit/Exit seems a bit nonsensical: if there is any
> window open... there always is a window open!

Even more: I don't get any warning message at all. (with three tabs open)

Comment 7

[Steffen Wilberg]

Regarding comment 3: yes.
Regarding comments 4 to 6: This has nothing to do with this bug. Please file a
new one. And the warning message is on by default (Tools->Options->Tabs->Warn
when closing multiple tabs).

Comment 8

[Jeff Walden (gone starting June 8)]

With bug 296012 minused, this isn't going to be plussed to block 1.1.  We'll
just have to work as fast as we can to fix it should that bug get fixed in time.

Comment 9

[Jeff Walden (gone starting June 8)]

Attachment: Patch for toc (only, mostly intentionally)

(In reply to comment #1)
>     -navigating pages > copy/save/print pages > using print preview

I didn't change this because it wrongly displays on all platforms now.	When we
fix that we can change it properly.

>     -improving speed/efficiency > make default browser

>     -Tools > email stuff

Shell service changes make this unneeded.

I also removed About Firefox from display in the Help menu on Mac -- see
<http://lxr.mozilla.org/mozilla/source/browser/base/content/baseMenuOverlay.xul#100>.


I didn't change the hidden datasources because they're clearly a lower
priority.  Also, if we're getting rid of the multiple instances of stuff like
"Options", this is going to change pretty radically then anyway.  Finally, it's
late and I need sleep more than I want to fix them.  :-)

Comment 10

[Steffen Wilberg]

Comment on attachment 190796 [details] [diff] [review]
Patch for toc (only, mostly intentionally)

Sorry for the delay, I messed up my Linux system.

Thanks for this nice improvement over 1.0!

Please also fix this in menu reference by adding the respective platform
classes to the menu ref and the toc:
<h3 id="print_preview">Print Preview (Windows and Linux only)</h3>
<h3 id="for_ie_users">For Internet Explorer Users (Windows only)</h3>

> I also removed About Firefox from display in the Help menu on Mac
Sure, but please also hide it from the menu reference.

r=me with that.

The hidden datasources need major cleanup anyway, which is another bug.

Comment 11

[Jeff Walden (gone starting June 8)]

Patch checked in, marking FIXED.  Platform specificity in hidden datasources
will be added in the patch(es) for bug 299976.