how-to recreate "corrupted" ohwconfig.xml (Error in OHW Configuration)

You've just installed Oracle EMGC (Enterprise Manager Grid Control) but 
when you try to access any help pages you receive the following error 
message:

   Error in OHW Configuration
   OHW configuration file error detected. Please contact the system administrator. 

Oracle Metalink's Note:462567.1 suggests to:
   "Replace ohwconfig.xml file from backup or other working instance"
pointing that ohwconfig.xml is located in:
   $OH/sysman/webapps/emd/online_help/ohwconfig.xml

Both of these suggestions are wrong, here's why:
   a) what if there's no backup?  This is a brand new install!
   b) ohwconfig.xml is not really located in:
         $OH/sysman/webapps/emd/online_help/

First of all we need to find the real cause of the error message, so lets go and do that:
cd /u01/app/oracle/product/oms10g/opmn/logs/
vi OC4J~OC4J_EM~default_island~1
------------- here are the relevant error messages ------------
08/04/02 16:50:55 oracle.help.library.helpset.HelpSetParseException: JAR entry psm_gc_cs.hs not found in /u01/app/oracle/product/oms10g/j2ee/OC4J_EM/applications/em/em/online_help/psm_gc_cs/psm_gc_cs_help_fr.jar
08/04/02 16:50:55       at oracle.help.library.helpset.HelpSet._parseFile(Unknown Source)
08/04/02 16:50:55       at oracle.help.library.helpset.HelpSet._initHelpSet(Unknown Source)
08/04/02 16:50:55       at oracle.help.library.helpset.HelpSet.<init>(Unknown Source)
08/04/02 16:50:55       at oracle.help.web.config.parser.LocalesSectionParser._handleHelpSet(Unknown Source)
08/04/02 16:50:55       at oracle.help.web.config.parser.LocalesSectionParser._parseBooks(Unknown Source)
08/04/02 16:50:55       at oracle.help.web.config.parser.LocalesSectionParser._parseLocale(Unknown Source)
08/04/02 16:50:55       at oracle.help.web.config.parser.LocalesSectionParser.parse(Unknown Source)
08/04/02 16:50:55       at oracle.help.web.config.parser.OHWParser._parse(Unknown Source)
08/04/02 16:50:55       at oracle.help.web.config.parser.OHWParser.getGlobalConfiguration(Unknown Source)
08/04/02 16:50:55       at oracle.help.web.OHWController._createOHWConfiguration(Unknown Source)
08/04/02 16:50:55       at oracle.help.web.OHWController.init(Unknown Source)
08/04/02 16:50:55       at com.evermind.server.http.HttpApplication.loadServlet(HttpApplication.java:2354)
08/04/02 16:50:55       at com.evermind.server.http.HttpApplication.findServlet(HttpApplication.java:4795)
08/04/02 16:50:55       at com.evermind.server.http.HttpApplication.getRequestDispatcher(HttpApplication.java:2821)
08/04/02 16:50:55       at com.evermind.server.http.HttpRequestHandler.processRequest(HttpRequestHandler.java:680)
08/04/02 16:50:55       at com.evermind.server.http.AJPRequestHandler.run(AJPRequestHandler.java:224)
08/04/02 16:50:55       at com.evermind.server.http.AJPRequestHandler.run(AJPRequestHandler.java:133)
08/04/02 16:50:55       at com.evermind.util.ReleasableResourcePooledExecutor$MyWorker.run(ReleasableResourcePooledExecutor.java:192)
08/04/02 16:50:55       at java.lang.Thread.run(Thread.java:534)
08/04/02 16:50:55 Critical error in OHW configuration. Config URL: file:/u01/app/oracle/product/oms10g/j2ee/OC4J_EM/applications/em/em/online_help/ohwconfig.xml ::
HelpSet 'psm_gc_cs_fr' : Unknown error when parsing hs file: JAR entry psm_gc_cs.hs not found in /u01/app/oracle/product/oms10g/j2ee/OC4J_EM/applications/em/em/online_help/psm_gc_cs/psm_gc_cs_help_fr.jar

Alright, so what do we see here?  First the config file is:

   /u01/app/oracle/product/oms10g/j2ee/OC4J_EM/applications/em/em/online_help/ohwconfig.xml

Second, the "HelpSet" that's defined in the ohwconfig.xml points to a non-existent file:

   JAR entry psm_gc_cs.hs not found

Next, we need to fix the ohwconfig.xml.  Here's the "template" of helpSet:

        <helpSet id="iastop_cs" jar="iastop_cs/iastop_cs_help.jar" location="iastop_cs.hs"/>

Knowing the above format we can now find all of the existing *_help.jar to 
construct a valid ohwconfig.xml.  Instead of doing it manually lets use a 
script:

cd /u01/app/oracle/product/oms10g/j2ee/OC4J_EM/applications/em/em/online_help/
vi build-ohwconfig.sh
------------- insert the following --------
#!/bin/ksh

for x in `find . -name *_help.jar`
do
	bsn=`basename $x`
	drn=`dirname $x`
	id=`basename $drn`
	jar="${id}/${bsn}"
	location=`echo $bsn | sed 's/_help\.jar/\.hs/'`
	
	echo "        <helpSet id=\"${id}\" jar=\"${jar}\" location=\"${location}\"/>"
done
- - - - - - - - - - - - END - - - - - - - - - - - 


## Make build-ohwconfig.sh executable and run-it:
##
chmod +x build-ohwconfig.sh
./build-ohwconfig.sh > ohwconfig.tmp


## Now modify ohwconfig.tmp by insterting the remaning XML "header" and "footer":
##
vi ohwconfig.tmp
------------ insert the following before and after the "helpSet id" block of code -----
<?xml version="1.0" encoding="UTF-8"?>
<helpConfiguration version="2.0" xmlns="http://xmlns.oracle.com/help/web/config">

<!-- Specify the branding information.  You can specify
     brandingText or brandingImage, if both are specified
     brandingText will be used -->

  <brandings>
    <branding locales="en_US" text="Oracle Enterprise Manager Online Help" />
  </brandings>

<!-- OHW automatically uses the system default Locale and
     the default encoding for that Locale for Locale
     sensitive operations.  You can override this behavior
     by filling out the localeSettings. Note that the encoding
     for the content HTML files is specified in those files
     directly.

     Within each local definition specify the set of books for that locale.
     The books element can contain any number of helpBook objects, helpSet
     objects or a mixture of both.

 -->

  <locales>
    <locale language="en" country="US">
      <books>
           helpSet id= ... goes here ...
           helpSet id= ... goes here ...
           helpSet id= ... goes here ...
      </books>
    </locale>
  </locales>

  <!-- Navigator aliases - to allow for legacy navigator names. -->
  <navigatorAliases>
    <alias name="oracle.help.navigator.tocNavigator.TOCNavigator"
           value="oracle.help.web.navigator.tocNavigator.TOCTreeNavigator" />
  </navigatorAliases>

<!-- The maxSearchThreads parameter determines the maximum
     number of threads that will be spawned for searching.
     This will be the maximum number of simultaneous
     searches that OHW can perform.  This value should be
     carefully tuned to correspond to the estimated load
     on the servlet.

     Specify the merging behavior by providing values for the
     combineBooks and useLabelInfo attributes.
-->

  <parameters>
    <combineBooks>true</combineBooks>
    <useLabelInfo>false</useLabelInfo>
    <maxSearchThreads>10</maxSearchThreads>
    <defaultHomeID>myTopicID</defaultHomeID>
  </parameters>

</helpConfiguration>
- - - - - - - - - - - - - - - - END - - - - - - - - - - - - - - - - - - -

## rename files
##
mv ohwconfig.xml ohwconfig.xml.old
mv ohwconfig.tmp ohwconfig.xml

## bounce EM
/u01/app/oracle/product/oms10g/opmn/bin/opmnctl stopall
/u01/app/oracle/product/oms10g/opmn/bin/opmnctl startall

Your problem should now be fixed.