299976 - Remove identical items from glossary/index datasources and make them platform-specific

Status: RESOLVED FIXED

(Firefox Graveyard :: Help Documentation, defect)

Description

[Steffen Wilberg]

Now that Search is much more exposed in the Help Viewer, we need to improve that
a bit.

Enter "tab" in the Search bar.
Result: Most of the results in the list are duplicated. "Tabbed Browsing" is
listed 6 times, 5 of which link to the top of tabbed_browsing.xhtml.

Comment 1

[Jeff Walden (gone starting June 8)]

We should probably create a hidden search datasource and get rid of the glossary
and index completely.  From now on using index and glossary datasources should
be considered deprecated.  (I need to mention this in the scant help viewer docs
I've partially moved to devmo.)

While we're doing this, we should remove the now-useless hierarchies from the
now-hidden datasources; they unnecessarily add to the processing required to
load help docs.  Also, we shouldn't let this datasource just be a copy of the
old ones in terms of content -- the focus must now be on creating keyword-rich
titles that lead to relevant content.

Comment 2

[Steffen Wilberg]

Taking. As a first step, I'm going to tear the index apart, removing all items
not already covered by the toc or the glossary, and moving the remaining items
to the top level.

Comment 3

[Steffen Wilberg]

Attachment: patch v1: slash and burn

Sigh, we spent quite a bit of work in fixing and polishing the index before
1.0. But it's a relief that we don't have to do that again.
I'd suggest to keep glossary.rdf for glossary-related items and the index for
other items for at least the 1.8/1.5 timeframe. After that, we can decide
whether to merge them or not.

The toc needs some further love as well. I'd suggest to add the word "Menu" in
front of "File", "Edit", etc.  We should also add "Options" or "Preferences"
after "General", "Privacy", etc.

We should consider adding "(glossary)" or ", defined" to the glossary items.

Comment 4

[Jeff Walden (gone starting June 8)]

Comment on attachment 191851 [details] [diff] [review]
patch v1: slash and burn

I'm running very short on time right now so don't consider this a full review,
but here are a few quick things to note:

>+        <rdf:li><rdf:Description ID="accessibility-options" nc:name="Accessibility Options" nc:link="prefs.xhtml#accessibility"/></rdf:li>

Items like this need to be duplicated -- once for "options" and once for
"preferences", with an nc:platform attribute set accordingly.  For now lump
"os2" together with Windows as we do in the platform class style rules; showing
something on OS/2 is better than showing nothing.

Also, if you have the time and don't mind testing, I'd be interested in seeing
whether each of these still works if we move all the RDF-related things into
the default namespace.	Right now the ID attribute isn't in any namespace and
only works because Mozilla's RDF parser is brain-dead.	If we convert the
"xmlns:rdf" namespace to a regular "xmlns" namespace and do a s/rdf:// I think
everything should still work and the RDF files will be more valid.  Assuming
you have time I'd like you to test this, please do this and see how it goes. 
If it works, post a revised patch that does this.  If not, just post results
and we'll skip the idea.

Comment 5

[Steffen Wilberg]

So I tried this:
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:nc="http://home.netscape.com/NC-rdf#">
and did a s/rdf://. Works fine.

But while we're at it, why not make the RDF Validator happy?
The Validator (http://www.w3.org/RDF/Validator/) still shows the same errors:
Unqualified use of rdf:about has been deprecated.
Unqualified use of rdf:ID has been deprecated.

"Unqualified" means without "rdf:". So I replaced "about" by "rdf:about" and ID
by "rdf:ID". This results in an error because the rdf: namespace isn't defined.
Adding back xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" results in:
"Your RDF document validated successfully."

Comment 6

[Steffen Wilberg]

Attachment: patch v1.1

I didn't touch toc and glossary in a similar way since I don't want to upset
the localizers.

I also fixed Accessibility Options/Preferences.

Comment 7

[Steffen Wilberg]

Ah, you already recommended rdf:about/rdf:ID in bug 296017.

Comment 8

[Jeff Walden [:Waldo]]

Comment on attachment 192014 [details] [diff] [review]
patch v1.1

(In reply to comment #5)

> But while we're at it, why not make the RDF Validator happy?



That's pretty much the point of these additional, tangential changes. :-)



> So I tried this:

> <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"

>      xmlns:nc="http://home.netscape.com/NC-rdf#">

> and did a s/rdf://. Works fine.

> 

> The Validator (http://www.w3.org/RDF/Validator/) still shows the same errors:

> Unqualified use of rdf:about has been deprecated.

> Unqualified use of rdf:ID has been deprecated.



These errors are a result of a misunderstanding I had of how attributes without
an explicit namespace work.  My intent was to fix the validation errors, but I
didn't know there's a difference between the following:



<?xml version="1.0"?>

<foo xmlns="http://example.org/foo#" xmlns:r="http://example.org/foo#">

  <bar attr="bob"/>

</foo>



<?xml version="1.0"?>

<foo xmlns="http://example.org/foo#" xmlns:r="http://example.org/foo#">

  <bar r:attr="bob"/>

</foo>



See also <http://www.stylusstudio.com/xmldev/200101/post90270.html>, which
seems to have been resolved per the validator error.



Come to think of it, we don't need rdf:ID attributes anywhere except the table
of contents file.  rdf:ID is only used if we're specifically targetting a node
as something that we might want to open via an external link (the rdf:ID
specifies the topic to be opened).  Thus, we don't need any rdf:ID attributes
in the index or glossary files.  (If we were only using the rdf ns for rdf:ID,
we can also get rid of that too.)

>Index: mozilla/browser/locales/en-US/chrome/help/firebird-index1.rdf


>+        <li><Description rdf:ID="go-menu-choosing-from-recent-pages" nc:name="Recently visited web pages" nc:link="using_firebird.xhtml#moving_to_another_page"/></li>

Capitalize the words in the nc:name, please.


>+        <li><Description rdf:ID="home-button" nc:name="Home button" nc:link="using_firebird.xhtml#viewing_your_home_page"/></li>

Capitalize "button", please.


>+        <li><Description rdf:ID="searching-using-loc-bar" nc:name="Searching using the Location Bar" nc:link="using_firebird.xhtml#moving_to_another_page"/></li>

>+        <li><Description rdf:ID="searching-using-search-bar" nc:name="Searching using the Search Bar" nc:link="using_firebird.xhtml#searching_the_web"/></li>

Capitalize "using", please.


>+        <li><Description rdf:ID="searching-text-from-page" nc:name="Searching using text from page" nc:link="using_firebird.xhtml#searching_on_selected_words_in_a_web_page"/></li>

s/using text from page/Using Text From the Page/


>Index: mozilla/browser/locales/en-US/chrome/help/firebird-toc.rdf


>-  <!-- The following nodes are intentionally linkable but not displayable -->

>-  <rdf:Description ID="prefs-languages" nc:name="Languages" nc:link="prefs.xhtml#languages"/>


This will break the part of the prefs dialog that was linking here.  Keep this
one and remove the one you added to the index; this one is functionally the
same as the one in the index *except* that it's linkable.

Anyway, this is looking pretty good!  I didn't realize just how much of the
index was duplicated from the toc until I sat down and actually took a good
look through it.  r=me with the aforementioned changes.

Comment 9

[Steffen Wilberg]

Attachment: patch v1.2

I removed the rdf:IDs and the xmlns:rdf (since that would only be used for
rdf:about) from the index. The validator only shows a single error about using
"about" instead of rdf:about".

I readeded "prefs-languages" to the toc to make it linkable (since I removed
the IDs from the index), but also left it in the index to make it searchable.

Comment 10

[Jeff Walden (gone starting June 8)]

(In reply to comment #9)
> I removed the rdf:IDs and the xmlns:rdf (since that would only be used for
> rdf:about) from the index. The validator only shows a single error about using
> "about" instead of rdf:about".

Hm, I didn't realize we needed that for rdf:about as well as for rdf:ID.  Could
you add it back on checkin, then?  Draconian error handling means that there's a
big difference between "valid" and "almost valid".

Comment 11

[Mike Connor [:mconnor]]

not a blocker, someone please land by Friday.

Comment 12

[Jeff Walden (gone starting June 8)]

Patch checked in on both branch and trunk, with the rdf ns added back to the
index.  I didn't realize it was only a warning instead of an error, but it still
is probably a good idea to avoid using deprecated features where possible.  I
also added an "rdf:" to the about attribute in the glossary, fixing the single
problem  that made it not fully validate without warnings.

We probably need to add more stuff to the index to get better search coverage,
but this is an excellent start for now.  I'm adding late-l10n to the keywords so
that localizers notice this change, and when we've fixed all the issues which
should be fixed for 1.5 we need to specifically mention this bug as something to
watch in a post to n.p.m.l10n.