ENH: use FOAM_DOC_BROWSER to specify alternative html document browser

- change from 'kde-open %f' to the desktop-agnostic 'firefox %f' as
  the default document browser.

etc/controlDict

@@ -18,7 +18,7 @@ FoamFile
 
 Documentation
 {
-    docBrowser      "kde-open %f";
+    docBrowser      "firefox %f";
     doxyDocDirs
     (
         "$WM_PROJECT_USER_DIR/html"

src/OpenFOAM/global/argList/argList.C

@@ -881,7 +881,12 @@ void Foam::argList::displayDoc(bool source) const
 
     if (found)
     {
-        string docBrowser(docDict.lookup("docBrowser"));
+        string docBrowser = getEnv("FOAM_DOC_BROWSER");
+        if (docBrowser.empty())
+        {
+            docDict.lookup("docBrowser") >> docBrowser;
+        }
+        // can use FOAM_DOC_BROWSER='application file://%f' if required
         docBrowser.replaceAll("%f", docFile);
 
         Info<< "Show documentation: " << docBrowser.c_str() << endl;

src/OpenFOAM/global/argList/argList.H

@@ -37,7 +37,7 @@ Description
     @verbatim
         ( "file1.txt" "file2.txt" ... "fileN.txt" )
     @endverbatim
-    The backslash-escaping has been used to avoid shell expansions.
+    The backslash-escaping is required to avoid interpretation by the shell.
 
     @par Default command-line options
     @param -case \<dir\> \n
@@ -57,10 +57,14 @@ Description
     global case.
 
 Note
-    - Adjustment of the valid (mandatory) arguments
+    - The document browser used is defined by the @b FOAM_DOC_BROWSER
+      environment variable or the <tt>Documentation/docBrowser</tt> entry
+      in the <tt>~OpenFOAM/controlDict</tt> file. 
+      The \%f token is used as a placeholder for the file name.
+    - The valid (mandatory) arguments can be adjusted
       by directly manipulating the argList::validArgs static member.
-    - Adjustment of the valid options
-      via the addOption/removeOption static methods or by directly
+    - The valid options can be adjusted
+      via the addOption/removeOption static methods instead of directly
       manipulating the argList::validOptions static member.
 
 SourceFiles