From acf329bfc3f2f5c59b24ea8f6fe7cbbad823d9ae Mon Sep 17 00:00:00 2001
From: Kris Maglione <kris@vimperator.org>
Date: Sun, 1 Nov 2009 00:16:55 -0400
Subject: [PATCH] Add basic help on plugin authorship.

---
 common/content/style.js              |  2 +-
 common/locale/en-US/autocommands.xml |  2 +-
 common/locale/en-US/browsing.xml     |  2 +-
 common/locale/en-US/buffer.xml       |  2 +-
 common/locale/en-US/cmdline.xml      |  2 +-
 common/locale/en-US/developer.xml    | 73 +++++++++++++++++++++++++++-
 common/locale/en-US/gui.xml          |  2 +-
 common/locale/en-US/insert.xml       |  2 +-
 8 files changed, 79 insertions(+), 8 deletions(-)

diff --git a/common/content/style.js b/common/content/style.js
index 1b726dd3..f72b492a 100644
--- a/common/content/style.js
+++ b/common/content/style.js
@@ -156,7 +156,7 @@ Highlights.prototype.CSS = <![CDATA[
 
     HelpKey,liberator|k                         color: #102663;
 
-    HelpLink,liberator|*>html|a                 text-decoration: none;
+    HelpLink,liberator|*>html|a[href]           text-decoration: none;
     HelpLink:hover                              text-decoration: underline;
 
     HelpList                                    display: block; list-style: outside disc;
diff --git a/common/locale/en-US/autocommands.xml b/common/locale/en-US/autocommands.xml
index ed8d49ed..263d2a9f 100644
--- a/common/locale/en-US/autocommands.xml
+++ b/common/locale/en-US/autocommands.xml
@@ -8,7 +8,7 @@
     title="&liberator.appname; Autocommands"
     xmlns="http://vimperator.org/namespaces/liberator"
     xmlns:html="http://www.w3.org/1999/xhtml">
-<h2 tag="autocommands">Automatic commands</h2>
+<h1 tag="autocommands">Automatic commands</h1>
 
 <p>
     Autocommands are a way to automatically execute code when
diff --git a/common/locale/en-US/browsing.xml b/common/locale/en-US/browsing.xml
index 2a15bcf3..e9d4adc7 100644
--- a/common/locale/en-US/browsing.xml
+++ b/common/locale/en-US/browsing.xml
@@ -8,7 +8,7 @@
     title="&liberator.appname; Browsing"
     xmlns="http://vimperator.org/namespaces/liberator"
     xmlns:html="http://www.w3.org/1999/xhtml">
-<h2 tag="surfing browsing">Browsing</h2>
+<h1 tag="surfing browsing">Browsing</h1>
 
 &liberator.appname; overrides nearly all &liberator.host; keys in order to make browsing more
 pleasant for Vim users. On the rare occasions when you want to pass a keystroke
diff --git a/common/locale/en-US/buffer.xml b/common/locale/en-US/buffer.xml
index 20bd1de9..1adc68ae 100644
--- a/common/locale/en-US/buffer.xml
+++ b/common/locale/en-US/buffer.xml
@@ -8,7 +8,7 @@
     title="&liberator.appname; Buffer"
     xmlns="http://vimperator.org/namespaces/liberator"
     xmlns:html="http://www.w3.org/1999/xhtml">
-<h2 tag="buffer document">Buffer</h2>
+<h1 tag="buffer document">Buffer</h1>
 
 &liberator.appname; holds exactly one buffer object for each tab. It is usually an
 (X)HTML document with advanced features.
diff --git a/common/locale/en-US/cmdline.xml b/common/locale/en-US/cmdline.xml
index 9c548499..88ef9559 100644
--- a/common/locale/en-US/cmdline.xml
+++ b/common/locale/en-US/cmdline.xml
@@ -8,7 +8,7 @@
     title="&liberator.appname; Command-line"
     xmlns="http://vimperator.org/namespaces/liberator"
     xmlns:html="http://www.w3.org/1999/xhtml">
-<h2 tag="Command-line-mode Command-line mode-cmdline">Command-line mode</h2>
+<h1 tag="Command-line-mode Command-line mode-cmdline">Command-line mode</h1>
 
 Command-line mode is used to enter Ex commands (<k>:</k>) and text search patterns
 (<k>/</k> and <k>?</k>).
diff --git a/common/locale/en-US/developer.xml b/common/locale/en-US/developer.xml
index ed743938..1dcc430d 100644
--- a/common/locale/en-US/developer.xml
+++ b/common/locale/en-US/developer.xml
@@ -8,7 +8,7 @@
     title="&liberator.appname; Developer information"
     xmlns="http://vimperator.org/namespaces/liberator"
     xmlns:html="http://www.w3.org/1999/xhtml">
-<h2 tag="developer-information">Developer information</h2>
+<h1 tag="developer-information">Developer information</h1>
 
 <h2 tag="writing-docs documentation">Writing documentation</h2>
 
@@ -67,6 +67,77 @@ written a new command, mapping or option. For this, use:
 
   :echo util.generateHelp(commands.get("addons"), "Extra text")
 
+<h2 tag="writing-plugins">Writing plugins</h2>
+
+Writing &liberator.appname; plugins is incredibly simple.
+Plugins are simply JavaScript files which run with full chrome
+privileges and have full access to the &liberator.appname; and
+&liberator.host; APIs. Each plugin has its own global object,
+which means that the variables and functions that you create
+won't pollute the global <em>window</em> or private
+<em>liberator</em> namespaces. This means that there's no need
+to wrap your plugin in a closure, as is often the practice in
+JavaScript development. Furthermore, any plugin which is
+installed in your <o>runtimepath</o><em>/plugin</em> directory
+will find its context stored in
+<em>plugins.&lt;pluginName></em>, which is often invaluable
+during development and testing.
+
+<h3 tag="plugin-documentation">Plugin documentation</h3>
+
+Plugins may provide inline documentation, which will appear on
+the <ex>:help plugins</ex> page. The markup for help entries
+is the same as the above, with a few more plugin specific
+entries. Here is an example from the popular
+<em>flashblock</em> extension:
+
+<code><![CDATA[
+var INFO = 
+<plugin name="flashblock" version="1.0"
+        href="http://ticket.vimperator.org/9"
+        summary="Flash Blocker"
+        xmlns="http://vimperator.org/namespaces/liberator">
+    <author email="maglione.k@gmail.com">Kris Maglione</author>
+    <license href="http://opensource.org/licenses/mit-license.php">MIT</license>
+    <project name="Vimperator" minVersion="2.0"/>
+    <p>
+        This plugin provides the same features as the ever popular FlashBlock
+        Firefox addon. Flash animations are substituted with place holders which
+        play the original animation when clicked. Additionally, this plugin provides
+        options to control which sites can play animations without restrictions, and
+        triggers to toggle the playing of animation on the current page.
+	commandline from the data in a given form.
+    </p>
+    <item>
+	<tags>'flashblock' 'fb'</tags>
+	<spec>'flashblock' 'fb'</spec>
+        <type>boolean</type>
+        <default>true</default>
+	<description>
+            <p>
+                Controls the blocking of flash animations. When true, place
+                holders are substituted for flash animations on untrusted sites.
+            </p>
+	</description>
+    </item>]]>
+    <em>…</em><![CDATA[
+</plugin>;
+]]>
+</code>
+
+The inline XML is made possible by
+<link topic="https://developer.mozilla.org/en/E4X">E4X</link>.
+It's important that the documentation be assigned to the
+<em>INFO</em> variable, or &liberator.appname; will not be able
+to find it. The documentation that you provide behaves exactly
+as other &liberator.appname; documentation, which means that
+the tags you provide are available via <ex>:help</ex> with
+full tag completion and cross-referencing support. Although
+documentation is not required, we strongly recommend that all
+plugin authors provide at least basic documentation of the
+functionality of their plugins and of each of the options,
+commands, and especially mappings that they provide.
+
 </document>
 
 <!-- vim:se sts=4 sw=4 et: -->
diff --git a/common/locale/en-US/gui.xml b/common/locale/en-US/gui.xml
index ca61a464..39836f26 100644
--- a/common/locale/en-US/gui.xml
+++ b/common/locale/en-US/gui.xml
@@ -8,7 +8,7 @@
     title="&liberator.appname; GUI"
     xmlns="http://vimperator.org/namespaces/liberator"
     xmlns:html="http://www.w3.org/1999/xhtml">
-<h2 tag="gui">&liberator.appname;'s GUI</h2>
+<h1 tag="gui">&liberator.appname;'s GUI</h1>
 
 <p>
     Although &liberator.appname; offers the most frequently used &liberator.host; functionality via
diff --git a/common/locale/en-US/insert.xml b/common/locale/en-US/insert.xml
index d13f406f..f8e5c658 100644
--- a/common/locale/en-US/insert.xml
+++ b/common/locale/en-US/insert.xml
@@ -8,7 +8,7 @@
     title="&liberator.appname; Insert Mode"
     xmlns="http://vimperator.org/namespaces/liberator"
     xmlns:html="http://www.w3.org/1999/xhtml">
-<h2 tag="Insert-mode Insert mode-insert">Insert mode</h2>
+<h1 tag="Insert-mode Insert mode-insert">Insert mode</h1>
 
 <p>
     Insert mode is used to enter text in text boxes and text areas. When