Some cleanups related to addons

git-svn-id: https://svn.kvirc.de/svn/trunk/kvirc@4508 17fca916-40b9-46aa-a4ea-0a15b648b75c

2 files changed, 71 insertions, 41 deletions

diff --git a/doc/addon.howto.txt b/doc/addon.howto.txt
index d51100ad9..ba6531e7d 100644
--- a/doc/addon.howto.txt
+++ b/doc/addon.howto.txt
@@ -30,18 +30,21 @@ be translated in several languages.
 
 2. INSTALLATION
 
-The addons are usually shipped in compressed archives (.kva). KVIrc will look for the
-installer file called "install.kvs" and executes it when the user will ask for your
-addon to be installed. The install.kvs contains the code for the registration of your
-addon and will include all the other necessary source files. 
+The addons are usually shipped in compressed archives (.kva). A simple double
+click on the *.kva file should be sufficient to install the addon for the current user.
+
+Another way to install the package is to use the /addon.install command.
+Under the hood, the double click will just invoke kvirc by passing the *.kva file
+name as parameter. KVirc will recognize it as being an addon package and will
+automatically invoke "/addon.install <filename>" on it.
 
 
 3. A TYPICAL ADDON LAYOUT
 
-As stated above, the addons are usually shipped in a compressed archive.
-Once uncompressed, the installer will check the directory tree containing the addon
-code and all the relatedfiles. In order to have uniformity the installer complains if
-the structure below is not respected.
+As stated above, the addons are usually shipped in a compressed archive. The
+/addon.install command will uncompress it to a temporary directory.
+The uncompressed tree is substantially the same directory tree that you have 
+to create in order to package your addon and it usually looks like this:
 
     name-version/
      +- init.kvs
@@ -76,19 +79,17 @@ the structure below is not respected.
               \- ...
 
 The entries with a slash (/) at the end are directories while the other are files.
-Please note that you need all of these directories or the routine that automagically
-creates the installer will fail. 
+
 The toplevel directory should be named with your addon name and version. Use no spaces
-in the directory entries (this will make the things simplier for people that want to
-use your addon).
+in the directory entries: this will make the things simplier for people that want to
+use your addon.
 
-Hint: Remember that your addon is going to be installed on different platforms (at
-least linux, macosx and windows based). The poor windows' notepad has serious problems
-with reading text files that contain only linefeeds as line separators. Keep it in mind...
+The init.kvs is the mandatory initialization script which must contain all the
+procedures required to register your addon inside the KVIrc subsystems.
 
-The initialization script has to be named init.kvs and must contain all the routines
-to register your addon.
-Eg.:
+For example:
+
+    ...
 
     # Register classes
     MyAddon::classes::register
@@ -112,29 +113,43 @@ Eg.:
     option boolAutoAcceptDccSend 1
     option boolShowMinimizedDebugWindow 1
 
+    ...
+
+
+The init.kvs is the only really mandatory piece of an addon. Most real-world addons,
+however, will be split over several kvs source files. Canonically these
+source files are placed in the src/ subdirectory and the init.kvs invokes
+them in the right order. More about the init.kvs script in section 4.
+
+Source file names should contain the namespace of the addon, the optional
+subnamespace and the name of the feature, like $addonNS_$subNS_[$subNS_[...]]$name.kvs.
 
-The main source directory for your addon have to be named "src" and must contain the
-implementation of the features you're going to provide. File names should contain the
-namespace of the addon, the optional subnamespace and the name of the feature, like
-$addonNS_$subNS_[$subNS_[...]]$name.kvs.
 Eg.:
 
     # A class which handles a database
-    MyAddon_classes_database.kvs
+
+    src/MyAddon_classes_database.kvs
     
     # A class which handles the options of our addon in a GUI
-    MyAddon_classes_gui_options.kvs
+
+    src/MyAddon_classes_gui_options.kvs
     
     # A script containing some logging functions
-    MyAddon_functions_logging.kvs
+
+    src/MyAddon_functions_logging.kvs
 
 
-The "locale" directory should contain the *.mo catalogue's files for your tranlations.
-The localization process of a script is explained in this document. Your *.mo filenames
-should be prefixed by your addon name.
+The init.kvs script must invoke (by using /parse or /include) these files
+in the correct order.
 
-The configuration directory "config" should contains only the files which store the
-configuration of your addon and must end with the .kvc extension.
+
+If your addon is translated in different languages then the "locale" directory should
+contain the *.mo catalogue files for your tranlations. The localization process of a
+script is explained in the KVIrc documentation. Your *.mo filenames should be prefixed
+by your addon name.
+
+If your addon needs an initial configuration then your config files should be placed
+in the "config" subdirectory and shoud have *.kvs as extension.
 
 The "pics" and "sound" (if relevant) directories should contain your multimedia files.
 It's a good idea to have your pics file in PNG format and sound files in WAV format.
@@ -142,10 +157,12 @@ It's a good idea to have your pics file in PNG format and sound files in WAV for
 The "help" directory should contain subdirectories for each language your help files
 are written in. The languages dirs should be named with the language code also used for
 the translation files (like "en", "it" etc...).
+
 Please note that english is the default language and KVIrc will fallback to the "en"
 subdirectory when no other language is found around...
 
 
+
 4. THE HELP AND CONFIGURATION CALLBACKS
 
 Each addon can have a help and a configuration callback. These are set respectively by
@@ -167,6 +184,7 @@ scripts that can show up a dialog that allows configuring all of the addon featu
 To use this callback you will probably need some object scripting.
 
 
+
 5. THE REAL WORK
 
 The real addon work is done by the scripts contained in the source directory. They will
@@ -248,7 +266,17 @@ The name of the classes refer to the ones described above.
     }
 
 
-7. WHERE TO START
+7. HINTS
+
+- Use namespaces for your aliases and your classes. This will help avoiding
+  collisions with other scripts and addons.
+
+- Remember that your addon is going to be installed on different platforms (at
+  least linux, macosx and windows based). The poor windows' notepad has serious problems
+  with reading text files that contain only linefeeds as line separators. Keep it in mind...
+
+
+8. WHERE TO START
 
 It is a good idea to start on the KVIrc web site. There are surely several addons to
 look at. Pick one that seems simple and analyze its layout and code (wow... the free
diff --git a/src/modules/addon/packaddondialog.cpp b/src/modules/addon/packaddondialog.cpp
index af7828990..ec011c253 100644
--- a/src/modules/addon/packaddondialog.cpp
+++ b/src/modules/addon/packaddondialog.cpp
@@ -203,10 +203,12 @@ bool KviPackAddonDialog::createInstaller(QString * pszError)
 
 	// install.kvs: addon registration
 	szTmp += QString("addon.register(\"%1\",\"%2\",\"%1\",\"%3\",\"%4\",\"%5\")\n").arg(m_szName, m_szVersion, m_szDescription, m_szMinVersion, m_szIcon);
-	szTmp += "{\n\t# This is our uninstall callback: it will be called by KVIrc when addon.uninstall is invoked\n\t";
-        szTmp += QString("%1::uninstall::uninstall\n").arg(m_szName);
-        szTmp += QString("\t%1::uninstall::uninstallfiles\n").arg(m_szName);
-        szTmp += QString("\t%1::uninstall::uninstallaliases\n}\n\n").arg(m_szName);
+	szTmp += "{\n";
+	szTmp += "\t# This is our uninstall callback: it will be called by KVIrc when addon.uninstall is invoked\n";
+	szTmp += QString("\t%1::uninstall::uninstall\n").arg(m_szName);
+	szTmp += QString("\t%1::uninstall::uninstallfiles\n").arg(m_szName);
+	szTmp += QString("\t%1::uninstall::uninstallaliases\n").arg(m_szName);
+	szTmp += "}\n\n";
 	szTmp += "# Ok, addon.register succeeded. We can go on with the installation.\n\n";
 
 	// install.kvs: run path
@@ -219,15 +221,15 @@ bool KviPackAddonDialog::createInstaller(QString * pszError)
 
 	// install.kvs: copy files
 	szTmp += "# Copy files in each subdirectory\n# the pics\n";
-        szTmp += QString("if (!$file.exists($file.localdir(\"pics/%1\"))) file.mkdir $file.localdir(\"pics/%1\")\n\n").arg(m_szName);
-        szTmp += QString("%installer->$copyFiles(\"%mypath/pics/%1\",\"*.png\",$file.localdir(\"pics/%1\"))\n\n").arg(m_szName);
+	szTmp += QString("if (!$file.exists($file.localdir(\"pics/%1\"))) file.mkdir $file.localdir(\"pics/%1\")\n\n").arg(m_szName);
+	szTmp += QString("%installer->$copyFiles(\"%mypath/pics/%1\",\"*.png\",$file.localdir(\"pics/%1\"))\n\n").arg(m_szName);
 	szTmp += "# the translations\n";
-        szTmp += QString("if (!$file.exists($file.localdir(\"locale/%1\"))) file.mkdir $file.localdir(\"locale/%1\")\n\n").arg(m_szName);
+	szTmp += QString("if (!$file.exists($file.localdir(\"locale/%1\"))) file.mkdir $file.localdir(\"locale/%1\")\n\n").arg(m_szName);
 
-        szTmp += "%installer->$copyFiles(\"%mypath/locale/%1\",\"*.mo\",$file.localdir(\"locale/%1\"))\n\n";
+	szTmp += "%installer->$copyFiles(\"%mypath/locale/%1\",\"*.mo\",$file.localdir(\"locale/%1\"))\n\n";
 
 	szTmp += "# the documentation\n";
-        szTmp += QString("if (!$file.exists($file.localdir(\"help/%1\"))) file.mkdir $file.localdir(\"help/en/%1\")\n\n").arg(m_szName);
+	szTmp += QString("if (!$file.exists($file.localdir(\"help/%1\"))) file.mkdir $file.localdir(\"help/en/%1\")\n\n").arg(m_szName);
 	szTmp += QString("%installer->$copyFiles(\"%mypath/help/en/%1/\",\"*.html\",$file.localdir(\"help/en/%1\"))\n\n").arg(m_szName);
 
 	// install.kvs: generate uninstall alias
@@ -269,7 +271,7 @@ bool KviPackAddonDialog::createInstaller(QString * pszError)
 
 	// Open file for writing
 	QFile installer(addon.filePath("install.kvs"));
-        if(!installer.open(QIODevice::WriteOnly))
+	if(!installer.open(QIODevice::WriteOnly))
 	{
 		*pszError = __tr2qs_ctx("Cannot open file for writing.","addon");
 		return false;