Fixed some issues around the help index

- Now the help index can be installed with the app
  Fallback is auto-generated index in app folder.
- The index can be generated by script with
  RBA::HelpSource#create_index_file
- The index is read only when the help dialog
  is opened (reduces start time)

src/lay/gsiDeclLayHelpDialog.cc

@@ -99,8 +99,9 @@ Class<lay::HelpSource> decl_HelpSource (laybasicdecl_BrowserSource (), "HelpSour
   gsi::method ("get_dom", &lay::HelpSource::get_dom, "@brief For internal use") + 
 #endif
   gsi::method ("urls", &lay::HelpSource::urls, "@brief Reserved for internal use") +
-  gsi::method ("title_for", &lay::HelpSource::title_for, "@brief Reserved internal use") +
-  gsi::method ("parent_of", &lay::HelpSource::parent_of, "@brief Reserved internal use"),
+  gsi::method ("title_for", &lay::HelpSource::title_for, gsi::arg ("path"), "@brief Reserved internal use") +
+  gsi::method ("parent_of", &lay::HelpSource::parent_of, gsi::arg ("path"), "@brief Reserved internal use") +
+  gsi::method ("create_index_file", &lay::HelpSource::create_index_file, gsi::arg ("path"), "@brief Reserved internal use"),
   "@brief A \\BrowserSource implementation delivering the help text for the help dialog\n"
   "This class can be used together with a \\BrowserPanel or \\BrowserDialog object to implement "
   "custom help systems.\n"

src/lay/layHelpDialog.cc

@@ -74,15 +74,6 @@ HelpDialog::~HelpDialog ()
   //  .. nothing yet ..
 }
 
-void 
-HelpDialog::build_index ()
-{
-  if (! mp_help_source) {
-    mp_help_source = new lay::HelpSource ();
-    tl::StaticObjects::reg (&mp_help_source);
-  }
-}
-
 void HelpDialog::title_changed (const QString &)
 {
   QString wt;
@@ -127,9 +118,11 @@ void HelpDialog::initialize ()
   if (! m_initialized) {
     m_initialized = true;
     mp_browser_panel->set_search_url ("int:/search.xml", "string");
-    if (mp_help_source) {
-      mp_browser_panel->set_source (mp_help_source);
+    if (! mp_help_source) {
+      mp_help_source = new lay::HelpSource ();
+      tl::StaticObjects::reg (&mp_help_source);
     }
+    mp_browser_panel->set_source (mp_help_source);
     mp_browser_panel->set_home ("int:/index.xml");
   }
 }

src/lay/layHelpDialog.h

@@ -53,8 +53,6 @@ public:
   void showEvent (QShowEvent *);
   void hideEvent (QHideEvent *);
 
-  static void build_index ();
-
 protected slots:
   void title_changed (const QString &t);
 

src/lay/layHelpSource.cc

@@ -247,6 +247,20 @@ help_index_structure ("help-index",
 
 HelpSource::HelpSource ()
   : m_kindex (0)
+{
+  initialize_index ();
+}
+
+HelpSource::HelpSource (bool make_index)
+  : m_kindex (0)
+{
+  if (make_index) {
+    initialize_index ();
+  }
+}
+
+void
+HelpSource::initialize_index ()
 {
   try {
 
@@ -254,36 +268,23 @@ HelpSource::HelpSource ()
 
     bool ok = false;
 
-    std::string cache_file = tl::to_string (QDir (tl::to_qstring (lay::Application::instance ()->appdata_path ())).absoluteFilePath (QString::fromUtf8 ("help-index.xml")));
+    const QString help_index_cache_file = QString::fromUtf8 ("help-index.xml");
+    std::string per_user_cache_file = tl::to_string (QDir (tl::to_qstring (lay::Application::instance ()->appdata_path ())).absoluteFilePath (help_index_cache_file));
 
-    try {
-      tl::XMLFileSource in (cache_file);
-      help_index_structure.parse (in, *this);
-      if (m_klayout_version == lay::Application::instance ()->version ()) {
-        ok = true;
-      }
-    } catch (tl::Exception &ex) {
-      tl::warn << ex.msg ();
-    } catch (std::runtime_error &ex) {
-      tl::warn << ex.what ();
-    } catch (...) {
-      tl::warn << "unknown error.";
-    }
+    //  Try to obtain the help index from the installation or application path
 
-    if (! ok) {
+    std::vector<std::string> cache_files;
+    cache_files.push_back (tl::to_string (QDir (tl::to_qstring (lay::Application::instance ()->inst_path ())).absoluteFilePath (help_index_cache_file)));
+    cache_files.push_back (per_user_cache_file);
 
-      m_index.clear ();
-      m_titles.clear ();
-      m_title_map.clear ();
+    for (std::vector<std::string>::const_iterator c = cache_files.begin (); ! ok && c != cache_files.end (); ++c) {
 
-      tl::AbsoluteProgress progress (tl::to_string (QObject::tr ("Initializing help index")), 1);
-      progress.can_cancel (false);
-      scan ("/index.xml", progress);
       try {
-
-        tl::OutputStream os (cache_file, tl::OutputStream::OM_Plain);
-        help_index_structure.write (os, *this);
-
+        tl::XMLFileSource in (*c);
+        help_index_structure.parse (in, *this);
+        if (m_klayout_version == lay::Application::instance ()->version ()) {
+          ok = true;
+        }
       } catch (tl::Exception &ex) {
         tl::warn << ex.msg ();
       } catch (std::runtime_error &ex) {
@@ -294,11 +295,20 @@ HelpSource::HelpSource ()
 
     }
 
+    if (! ok) {
+      //  If no index is found, create one in "per_user_cache_file"
+      produce_index_file (per_user_cache_file);
+    }
+
   } catch (tl::Exception &ex) {
+
     m_index.clear ();
     m_titles.clear ();
     m_title_map.clear ();
+    m_parent_of.clear ();
+
     tl::error << ex.msg ();
+
   }
 }
 
@@ -307,6 +317,38 @@ HelpSource::~HelpSource()
   //  .. nothing yet ..
 }
 
+void
+HelpSource::produce_index_file (const std::string &path)
+{
+  m_index.clear ();
+  m_titles.clear ();
+  m_title_map.clear ();
+  m_parent_of.clear ();
+
+  tl::AbsoluteProgress progress (tl::to_string (QObject::tr ("Initializing help index")), 1);
+  progress.can_cancel (false);
+  scan ("/index.xml", progress);
+  try {
+
+    tl::OutputStream os (path, tl::OutputStream::OM_Plain);
+    help_index_structure.write (os, *this);
+
+  } catch (tl::Exception &ex) {
+    tl::warn << ex.msg ();
+  } catch (std::runtime_error &ex) {
+    tl::warn << ex.what ();
+  } catch (...) {
+    tl::warn << "unknown error.";
+  }
+}
+
+void
+HelpSource::create_index_file (const std::string &path)
+{
+  HelpSource source (false);
+  source.produce_index_file (path);
+}
+
 std::string
 HelpSource::klayout_version () const
 {

src/lay/layHelpSource.h

@@ -145,6 +145,11 @@ public:
 
   std::vector<std::string> urls ();
 
+  /**
+   *  @brief Creates a help index file at the given path
+   */
+  static void create_index_file (const std::string &path);
+
 private:
   std::vector<IndexEntry> m_index;
   std::map<std::string, std::string> m_parent_of;
@@ -153,8 +158,11 @@ private:
   std::string m_klayout_version;
   int m_kindex;
 
+  HelpSource (bool make_index);
   QDomDocument produce_search (const std::string &index);
   QDomDocument produce_main_index ();
+  void produce_index_file (const std::string &path);
+  void initialize_index ();
   std::string process (const QDomDocument &doc, const std::string &path);
   void process_child_nodes (const QDomElement &element, const std::string &path, QXmlStreamWriter &writer);
   void process (const QDomElement &element, const std::string &path, QXmlStreamWriter &writer);

src/lay/layMainWindow.cc

@@ -1183,9 +1183,6 @@ MainWindow::close_all ()
 void
 MainWindow::about_to_exec ()
 {
-  //  do this now since we have a window where we can show the progress on the first call ..
-  HelpDialog::build_index ();
-
   //  Give the plugins a change to do some last-minute initialisation and checks
   for (tl::Registrar<lay::PluginDeclaration>::iterator cls = tl::Registrar<lay::PluginDeclaration>::begin (); cls != tl::Registrar<lay::PluginDeclaration>::end (); ++cls) {
     lay::PluginDeclaration *pd = const_cast<lay::PluginDeclaration *> (&*cls);