Bug 1588871 - Clean up comments and remove as much preprocessing in the helpviewer as possible. r=IanN a=IanN
authorFrank-Rainer Grahl <frgrahl@gmx.net>
Wed, 30 Oct 2019 19:42:39 +0100
changeset 32351 a034a02220f00215ce87c5662432cf9af05a9508
parent 32350 a93a71b87c7e1c0f4914e2ac64105e968c8005fb
child 32352 20f92f529dad9e10cedf9564c74675550c8f51a5
push id225
push userfrgrahl@gmx.net
push dateWed, 30 Oct 2019 18:44:45 +0000
treeherdercomm-esr60@4f5c19b9a6b7 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersIanN, IanN
bugs1588871
Bug 1588871 - Clean up comments and remove as much preprocessing in the helpviewer as possible. r=IanN a=IanN
suite/components/helpviewer/content/contextHelp.js
suite/components/helpviewer/content/help.js
suite/components/helpviewer/content/help.xul
suite/components/helpviewer/content/helpContextOverlay.xul
suite/components/helpviewer/jar.mn
suite/locales/en-US/chrome/common/help/suitehelp.rdf
--- a/suite/components/helpviewer/content/contextHelp.js
+++ b/suite/components/helpviewer/content/contextHelp.js
@@ -1,68 +1,70 @@
-# This Source Code Form is subject to the terms of the Mozilla Public
-# License, v. 2.0. If a copy of the MPL was not distributed with this
-# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 ChromeUtils.import("resource://gre/modules/Services.jsm");
+ChromeUtils.import("resource://gre/modules/XPCOMUtils.jsm");
 
-# Set the default content pack to the Mozilla content pack. Use the
-# setHelpFileURI function to set this value.
+XPCOMUtils.defineLazyModuleGetter(this, "AppConstants",
+                                  "resource://gre/modules/AppConstants.jsm");
+
+// Set the default content pack to the Mozilla content pack. Use the
+// setHelpFileURI function to set this value.
 var helpFileURI;
 
-# openHelp - Opens up the Mozilla Help Viewer with the specified
-#    topic and content pack.
-# see http://www.mozilla.org/projects/help-viewer/content_packs.html
+// openHelp - Opens up the Mozilla Help Viewer with the specified
+//    topic and content pack.
+// see http://www.mozilla.org/projects/help-viewer/content_packs.html
 function openHelp(topic, contentPack)
 {
-# helpFileURI is the content pack to use in this function. If contentPack is defined,
-# use that and set the helpFileURI to that value so that it will be the default.
+  // helpFileURI is the content pack to use in this function. If contentPack is defined,
+  // use that and set the helpFileURI to that value so that it will be the default.
   helpFileURI = contentPack || helpFileURI;
 
-# Try to find previously opened help.
+  // Try to find previously opened help.
   var topWindow = locateHelpWindow(helpFileURI);
 
   if ( topWindow ) {
-# Open topic in existing window.
+    // Open topic in existing window.
     topWindow.focus();
     topWindow.displayTopic(topic);
   } else {
-# Open topic in new window.
+    // Open topic in new window.
     const params = Cc["@mozilla.org/embedcomp/dialogparam;1"]
                      .createInstance(Ci.nsIDialogParamBlock);
     params.SetNumberStrings(2);
     params.SetString(0, helpFileURI);
     params.SetString(1, topic);
-#ifdef XP_WIN
-#define HELP_ALWAYS_RAISED_TOGGLE
-#endif
-#ifdef HELP_ALWAYS_RAISED_TOGGLE
+
+    let openFeatures = "chrome,all,dialog=no";
+
+    if (AppConstants.platform == "win") {
+      openFeatures += ",alwaysRaised";
+    }
     Services.ww.openWindow(null, "chrome://help/content/help.xul", "_blank",
-                           "chrome,all,alwaysRaised,dialog=no", params);
-#else
-    Services.ww.openWindow(null, "chrome://help/content/help.xul", "_blank",
-                           "chrome,all,dialog=no", params);
-#endif
+                           openFeatures, params);
   }
 }
 
-# setHelpFileURI - Sets the default content pack to use in the Help Viewer
+// setHelpFileURI - Sets the default content pack to use in the Help Viewer
 function setHelpFileURI(rdfURI)
 {
   helpFileURI = rdfURI;
 }
 
-# Locate existing help window for this content pack.
+// Locate existing help window for this content pack.
 function locateHelpWindow(contentPack) {
     const iterator = Services.wm.getEnumerator("suite:help");
     var topWindow = null;
     var aWindow;
 
-# Loop through help windows looking for one with selected content
-# pack.
+    // Loop through help windows looking for one with selected content
+    // pack.
     while (iterator.hasMoreElements()) {
         aWindow = iterator.getNext();
         if (!aWindow.closed && aWindow.getHelpFileURI() == contentPack) {
             topWindow = aWindow;
         }
     }
     return topWindow;
 }
--- a/suite/components/helpviewer/content/help.js
+++ b/suite/components/helpviewer/content/help.js
@@ -1,101 +1,120 @@
-# This Source Code Form is subject to the terms of the Mozilla Public
-# License, v. 2.0. If a copy of the MPL was not distributed with this
-# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 ChromeUtils.import("resource://gre/modules/Services.jsm");
+ChromeUtils.import("resource://gre/modules/XPCOMUtils.jsm");
 
-# Global Variables
+XPCOMUtils.defineLazyModuleGetter(this, "AppConstants",
+  "resource://gre/modules/AppConstants.jsm");
+
+// Global Variables
 var helpExternal;
 var helpBrowser;
 var helpSearchPanel;
 var emptySearch;
 var emptySearchText;
 var emptySearchLink = "about:blank";
 var helpTocPanel;
 var helpIndexPanel;
 var helpGlossaryPanel;
 var strBundle;
 var gTocDSList = "";
 
-# Namespaces
+// Namespaces
 const NC = "http://home.netscape.com/NC-rdf#";
 const MAX_LEVEL = 40; // maximum depth of recursion in search datasources.
 const MAX_HISTORY_MENU_ITEMS = 6;
 
-# ifdef logic ripped from toolkit/components/help/content/platformClasses.css
-#ifdef XP_WIN
-const platform = "win";
-#else
-#ifdef XP_MACOSX
-const platform = "mac";
-#else
-const platform = "unix";
-#endif
-#endif
+const platform = getCurrentPlatform();
 
-# Resources
+// Resources
 const RDF = Cc["@mozilla.org/rdf/rdf-service;1"].getService(Ci.nsIRDFService);
 const RDF_ROOT = RDF.GetResource("urn:root");
 const NC_PANELLIST = RDF.GetResource(NC + "panellist");
 const NC_PANELID = RDF.GetResource(NC + "panelid");
 const NC_EMPTY_SEARCH_TEXT = RDF.GetResource(NC + "emptysearchtext");
 const NC_EMPTY_SEARCH_LINK = RDF.GetResource(NC + "emptysearchlink");
 const NC_DATASOURCES = RDF.GetResource(NC + "datasources");
 const NC_PLATFORM = RDF.GetResource(NC + "platform");
 const NC_SUBHEADINGS = RDF.GetResource(NC + "subheadings");
 const NC_NAME = RDF.GetResource(NC + "name");
 const NC_CHILD = RDF.GetResource(NC + "child");
 const NC_LINK = RDF.GetResource(NC + "link");
 const NC_TITLE = RDF.GetResource(NC + "title");
 const NC_BASE = RDF.GetResource(NC + "base");
 const NC_DEFAULTTOPIC = RDF.GetResource(NC + "defaulttopic");
 
-var RDFContainer =
-      Cc["@mozilla.org/rdf/container;1"].createInstance(Ci.nsIRDFContainer);
+var RDFContainer = Cc["@mozilla.org/rdf/container;1"]
+                     .createInstance(Ci.nsIRDFContainer);
 const CONSOLE_SERVICE = Cc['@mozilla.org/consoleservice;1']
                           .getService(Ci.nsIConsoleService);
 
 var RE;
 
 var helpFileURI;
 var helpFileDS;
-# Set from nc:base attribute on help rdf file. It may be used for prefix
-# reduction on all links within the current help set.
+// Set from nc:base attribute on help rdf file. It may be used for prefix
+// reduction on all links within the current help set.
 var helpBaseURI;
 
 /* defaultTopic is either set
    1. in the openHelp() call, passed as an argument to the Help window and
       evaluated in init(), or
    2. in nc:defaulttopic in the content pack (e.g. firebirdhelp.rdf),
       evaluated in loadHelpRDF(), or
    3. "welcome" as a fallback, specified in loadHelpRDF() as well;
       displayTopic() then uses defaultTopic because topic is null. */
 var defaultTopic;
 
 const NSRESULT_RDF_SYNTAX_ERROR = 0x804e03f7;
 
-# This function is called by dialogs/windows that want to display
-# context-sensitive help
-# These dialogs/windows should include the script
-# chrome://help/content/contextHelp.js
+// Translate the current application platform to one the
+// help viewer understands.
+function getCurrentPlatform() {
+
+  // The supported platforms are defined in
+  // suite/locales/en-US/chrome/common/help/suitehelp.rdf.
+  // We can't just return the current platform 1:1 because
+  // this would need l10n changes for all languages.
+   if (AppConstants.platform == "win") {
+     return "win";
+   }
+
+   if (AppConstants.platform == "macosx") {
+     return "mac";
+   }
+
+   if (AppConstants.platform == "linux") {
+     return "unix";
+   }
+
+   // We never end up here in official builds.
+   return "---";
+}
+
+// This function is called by dialogs/windows that want to display
+// context-sensitive help
+// These dialogs/windows should include the script
+// chrome://help/content/contextHelp.js
 function displayTopic(topic) {
     // Get the page to open.
     var uri = getLink(topic);
     // Use default topic if specified topic is not found.
     if (!uri) {
         uri = getLink(defaultTopic);
     }
     // Load the page.
     if (uri)
       loadURI(uri);
 }
 
-# Initialize the Help window
+// Initialize the Help window
 function init() {
   // Cache panel references.
   helpSearchPanel = document.getElementById("help-search-panel");
   helpTocPanel = document.getElementById("help-toc-panel");
   helpIndexPanel = document.getElementById("help-index-panel");
   helpGlossaryPanel = document.getElementById("help-glossary-panel");
   helpBrowser = document.getElementById("help-content");
 
@@ -223,20 +242,20 @@ function hideSearchSidebar(aEvent) {
 
   var sidebar = document.getElementById("help-search-sidebar");
   sidebar.setAttribute("hidden", "true");
 
   var tableOfContents = document.getElementById("help-toc-sidebar");
   tableOfContents.removeAttribute("hidden");
 }
 
-# loadHelpRDF
-# Parse the provided help content pack RDF file, and use it to
-# populate the datasources attached to the trees in the viewer.
-# Filter out any information not applicable to the user's platform.
+// loadHelpRDF
+// Parse the provided help content pack RDF file, and use it to
+// populate the datasources attached to the trees in the viewer.
+// Filter out any information not applicable to the user's platform.
 function loadHelpRDF() {
   if (!helpFileDS) {
     try {
       helpFileDS = RDF.GetDataSourceBlocking(helpFileURI);
     } catch (e) {
       if (e.result == NSRESULT_RDF_SYNTAX_ERROR) {
         log("Help file: " + helpFileURI + " contains a syntax error.");
       } else {
@@ -305,46 +324,47 @@ function loadHelpRDF() {
         tree.builder.rebuild();
       }
     } catch (e) {
       log(e + "");
     }
   }
 }
 
-# filterDatasourceByPlatform
-# Remove statements for other platforms from a datasource.
+// filterDatasourceByPlatform
+// Remove statements for other platforms from a datasource.
 function filterDatasourceByPlatform(aDatasource) {
   filterNodeByPlatform(aDatasource, RDF_ROOT, 0);
 }
 
-# filterNodeByPlatform
-# Remove statements for other platforms from the provided datasource.
+// filterNodeByPlatform
+// Remove statements for other platforms from the provided datasource.
 function filterNodeByPlatform(aDatasource, aCurrentResource, aCurrentLevel) {
   if (aCurrentLevel > MAX_LEVEL) {
      log("Datasources over " + MAX_LEVEL + " levels deep are unsupported.");
      return;
   }
 
   // get the subheadings under aCurrentResource and filter them
   var nodes = aDatasource.GetTargets(aCurrentResource, NC_SUBHEADINGS, true);
   while (nodes.hasMoreElements()) {
     var node = nodes.getNext();
     node = node.QueryInterface(Ci.nsIRDFResource);
     // should we test for rdf:Seq here?  see also doFindOnDatasource
     filterSeqByPlatform(aDatasource, node, aCurrentLevel+1);
   }
 }
 
-# filterSeqByPlatform
-# Go through the children of aNode, if any, removing statements applicable
-# only on other platforms.
+// filterSeqByPlatform
+// Go through the children of aNode, if any, removing statements applicable
+// only on other platforms.
 function filterSeqByPlatform(aDatasource, aNode, aCurrentLevel) {
   // get nc:subheading children into an enumerator
-  var RDFC = Cc["@mozilla.org/rdf/container;1"].createInstance(Ci.nsIRDFContainer);
+  var RDFC = Cc["@mozilla.org/rdf/container;1"]
+               .createInstance(Ci.nsIRDFContainer);
   RDFC.Init(aDatasource, aNode);
   var targets = RDFC.GetElements();
 
   // process items in the rdf:Seq
   while (targets.hasMoreElements()) {
     var currentTarget = targets.getNext();
 
     // find out on which platforms this node is meaningful
@@ -363,30 +383,30 @@ function filterSeqByPlatform(aDatasource
       continue;
     }
 
     // filter any children
     filterNodeByPlatform(aDatasource, currentTarget, aCurrentLevel+1);
   }
 }
 
-# Prepend helpBaseURI to list of space separated links if they don't start with
-# "chrome:"
+// Prepend helpBaseURI to list of space separated links if they don't start with
+// "chrome:"
 function normalizeLinks(helpBaseURI, links) {
   if (!helpBaseURI) {
     return links;
   }
   var ls = links.split(/\s+/);
   if (ls.length == 0) {
     return links;
   }
   for (var i=0; i < ls.length; ++i) {
     if (ls[i] == "")
       continue;
-      
+
     if (ls[i].substr(0,7) != "chrome:" && ls[i].substr(0,4) != "rdf:")
       ls[i] = helpBaseURI + ls[i];
   }
   return ls.join(" ");
 }
 
 function getLink(ID) {
     if (!ID)
@@ -406,18 +426,18 @@ function getLink(ID) {
       var link = tocDS.GetTarget(resource, NC_LINK, true);
       if (!link)  // no such rdf:ID found
         continue;
       return link.QueryInterface(Ci.nsIRDFLiteral).Value;
     }
     return null;
 }
 
-# Called by contextHelp.js to determine if this window is displaying the
-# requested help file.
+// Called by contextHelp.js to determine if this window is displaying the
+// requested help file.
 function getHelpFileURI() {
     return helpFileURI;
 }
 
 function getBrowser() {
   return helpBrowser;
 }
 
@@ -622,18 +642,18 @@ function onselect_loadURI(tree) {
     }// when switching between tabs a spurious row number is returned.
 }
 
 function focusSearch() {
   var searchBox = document.getElementById("findText");
   searchBox.focus();
 }
 
-# doFind - Searches the help files for what is located in findText and outputs into
-#        the find search tree.
+// doFind - Searches the help files for what is located in findText and outputs into
+//        the find search tree.
 function doFind() {
     if (document.getElementById("help-search-sidebar").hidden)
       showSearchSidebar();
 
     var searchTree = document.getElementById("help-search-tree");
     var findText = document.getElementById("findText");
 
     // clear any previous results.
@@ -771,68 +791,67 @@ function getLiteralValue(literal, defaul
         }
     }
     if (defaultValue) {
         return defaultValue;
     }
     return null;
 }
 
-# Write debug string to error console.
+// Write debug string to error console.
 function log(aText) {
     CONSOLE_SERVICE.logStringMessage(aText);
 }
 
 function getBoolPref (aPrefname, aDefault)
 {
   try {
     var pref = Cc["@mozilla.org/preferences-service;1"]
                  .getService(Ci.nsIPrefBranch);
     return pref.getBoolPref(aPrefname);
   }
   catch(e) {
     return aDefault;
   }
 }
 
-# getXulWin - Returns the current Help window as a nsIXULWindow.
+// getXulWin - Returns the current Help window as a nsIXULWindow.
 function getXulWin()
 {
   window.QueryInterface(Ci.nsIInterfaceRequestor);
   var webnav = window.getInterface(Ci.nsIWebNavigation);
   var dsti = webnav.QueryInterface(Ci.nsIDocShellTreeItem);
   var treeowner = dsti.treeOwner;
   var ifreq = treeowner.QueryInterface(Ci.nsIInterfaceRequestor);
 
   return ifreq.getInterface(Ci.nsIXULWindow);
 }
 
-# toggleZLevel - Toggles whether or not the window will always appear on top. Because
-#   alwaysRaised is not supported on an OS other than Windows, this code will not
-#   appear in those builds.
-#
-#   element - The DOM node that persists the checked state.
-#ifdef XP_WIN
-#define HELP_ALWAYS_RAISED_TOGGLE
-#endif
-#ifdef HELP_ALWAYS_RAISED_TOGGLE
+// toggleZLevel - Toggles whether or not the window will always appear on top. Because
+//   alwaysRaised is not supported on an OS other than Windows, this code will not
+//   be used in those builds.
+//
+//   element - The DOM node that persists the checked state.
 function toggleZLevel(element)
 {
+  if (AppConstants.platform != "win") {
+    return;
+  }
+
   var xulwin = getXulWin();
-  
+
   // Now we can flip the zLevel, and set the attribute so that it persists correctly
   if (xulwin.zLevel > xulwin.normalZ) {
     xulwin.zLevel = xulwin.normalZ;
     element.setAttribute("checked", "false");
   } else {
     xulwin.zLevel = xulwin.raisedZ;
     element.setAttribute("checked", "true");
   }
 }
-#endif
 
 var helpContentListener = {
   onStartURIOpen: function(aURI) {
     return false;
   },
   doContent: function(aContentType, aIsContentPreferred, aRequest, aContentHandler) {
     throw Cr.NS_ERROR_UNEXPECTED;
   },
--- a/suite/components/helpviewer/content/help.xul
+++ b/suite/components/helpviewer/content/help.xul
@@ -14,19 +14,16 @@
 ]>
 
 <window id="help"
         windowtype="suite:help"
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
         width="700"
         height="550"
 #ifdef XP_WIN
-#define HELP_ALWAYS_RAISED_TOGGLE
-#endif
-#ifdef HELP_ALWAYS_RAISED_TOGGLE
         persist="width height screenX screenY zlevel"
 #else
         persist="width height screenX screenY"
 #endif
         onload="init();"
         onunload="window.XULBrowserWindow.destroy();">
 
   <script type="application/javascript" src="chrome://help/content/help.js"/>
--- a/suite/components/helpviewer/content/helpContextOverlay.xul
+++ b/suite/components/helpviewer/content/helpContextOverlay.xul
@@ -1,9 +1,9 @@
-<?xml version="1.0"?> 
+<?xml version="1.0"?>
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 <!DOCTYPE overlay [
     <!ENTITY % helpDTD SYSTEM "chrome://help/locale/help.dtd">
     %helpDTD;
 ]>
@@ -39,19 +39,16 @@
                 label="&fullZoomEnlargeBtn.label;"
                 accesskey="&fullZoomEnlargeBtn.accesskey;"
                 oncommand="ZoomManager.enlarge();"/>
       <menuitem id="zoom-out"
                 label="&fullZoomReduceBtn.label;"
                 accesskey="&fullZoomReduceBtn.accesskey;"
                 oncommand="ZoomManager.reduce();"/>
 #ifdef XP_WIN
-#define HELP_ALWAYS_RAISED_TOGGLE
-#endif
-#ifdef HELP_ALWAYS_RAISED_TOGGLE
       <menuseparator/>
       <menuitem id="context-zlevel"
                 type="checkbox"
                 checked="true"
                 persist="checked"
                 label="&zLevel.label;"
                 accesskey="&zLevel.accesskey;"
                 oncommand="toggleZLevel(this);"/>
--- a/suite/components/helpviewer/jar.mn
+++ b/suite/components/helpviewer/jar.mn
@@ -1,11 +1,11 @@
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 comm.jar:
 % content help %content/communicator/helpviewer/
 *  content/communicator/helpviewer/help.xul                         (content/help.xul)
-*  content/communicator/helpviewer/contextHelp.js                   (content/contextHelp.js)
-*  content/communicator/helpviewer/help.js                          (content/help.js)
+   content/communicator/helpviewer/contextHelp.js                   (content/contextHelp.js)
+   content/communicator/helpviewer/help.js                          (content/help.js)
 *  content/communicator/helpviewer/helpContextOverlay.xul           (content/helpContextOverlay.xul)
 *  content/communicator/helpviewer/platformClasses.css              (content/platformClasses.css)
--- a/suite/locales/en-US/chrome/common/help/suitehelp.rdf
+++ b/suite/locales/en-US/chrome/common/help/suitehelp.rdf
@@ -18,39 +18,39 @@
             nc:title="&brandFullName; Help"
             nc:defaulttopic="welcome"
             nc:base="chrome://communicator/locale/help/">
         <nc:panellist>
             <Seq>
                 <li>
                     <Description nc:panelid="toc"
                         nc:datasources="suite-toc.rdf"
-                        nc:platform="win mac os2 unix"/>
+                        nc:platform="win mac unix"/>
                 </li>
                 <li>
                     <Description nc:panelid="toc"
                         nc:datasources="help-win.rdf"
                         nc:platform="win"/>
                 </li>
                 <li>
                     <Description nc:panelid="search"
                         nc:datasources="rdf:null"
-                        nc:platform="win mac os2 unix"
+                        nc:platform="win mac unix"
                         nc:emptysearchtext="[No matching items found.]"
                         nc:emptysearchlink="help_help.xhtml#search_tips"/>
                 </li>
                 <li>
                     <Description nc:panelid="glossary"
                         nc:datasources="help-glossary.rdf"
-                        nc:platform="win mac os2 unix"/>
+                        nc:platform="win mac unix"/>
                 </li>
                 <li>
                     <Description nc:panelid="index"
                         nc:datasources="help-indexAZ.rdf help-index1.rdf"
-                        nc:platform="win mac os2 unix"/>
+                        nc:platform="win mac unix"/>
                 </li>
                 <li>
                     <Description nc:panelid="index"
                         nc:datasources="help-win.rdf"
                         nc:platform="win"/>
                 </li>
             </Seq>
         </nc:panellist>