Developer information

Writing documentation

For every new feature, writing documentation is mandatory for the patch to be accepted. The docs are written in an XML dialect similar to XHTML, with a few tags specific to our documentation. For example:


     :help :h help]]]]>
    :help subject
    ]]]]>
    
        
            Open help window.
            The default section is shown unless subject is specified.
            If you need help for a specific topic, try :help overview.
        
    

]]>

creates a new help section for the command :help and for the related key binding, . It also creates help tags for the command, its shortcuts, the key binding, and the general topic, 'help'. These tags enable linking to this section when from other mentions of the topic and from the :help command. The above code displays as:

:help :h help]]> :help subject ]]>

Open help window. The default section is shown unless subject is specified. If you need help for a specific topic, try :help overview.

If you don't know in which file/section you should put some documentation, ask on the mailing list or on #vimperator.

Help tags

The following is a list of the more common XML tags used in help pages, along with their highlight groups.

Layout
p: A paragraph (HelpParagraph)
h1: A first-level heading (HelpHead)
h2: A second-level heading (HelpSubhead)
h3: A third-level heading (HelpSubsubhead)
code: A pre-formatted code block. (HelpCode)
note: A note paragraph. (HelpNote)
warning: A warning paragraph. (HelpWarning)

Generic
link: A generic link. (HelpLink)
&tab;@topic: The topic of the link. Either a help topic or a fully-qualified URI.
em: Emphasized text. (HelpEm)
str: A string, with its contents wrapped in quotes. (HelpString)
logo: &liberator.appname;'s logo. (Logo)

Items
item: A help entry (HelpItem)
&tab;tags: See the 'Tagging' section (HelpTags)
&tab;spec: The specification for this item, such as an example command-line. (HelpSpec)
&tab;type: For options, the type of the option. number, boolean, string, string, stringlist, or charlist. (HelpType)
&tab;default: For options, the default value. (HelpDefault)
&tab;description: The description of this help item. (HelpDescription)
a: Required argument. (HelpArg)
oa: Optional argument. (HelpOptionalArg)

Tagging
tags: Space-separated list of strings to tag. Displayed right-aligned, and used for cross-linking. (HelpTags)
@tag: The tag attribute. Applied to any element, generates a <tags> element with its value for its contents. (HelpTag)

Linking
o: Link to an option. (HelpOpt)
ex: Link to an ex command. (HelpEx)
k: Link to a key. (HelpKey)
&tab;@name: The name attribute to <k>. When provided, <value> is prepended to the element's contents, i.e., <k name="lt"/> becomes .
t: Links to an arbitrary help topic. (HelpTopic)

Plugins
plugin: The container tag used for describing a plugin.
&tab;@name: The name of the plugin. Used as the plugin's help tag.
&tab;@version: The plugin's version number.
&tab;@href: The plugin's home page.
&tab;@summary: A short description of the plugin, shown in its section head.
project: The project for which this plugin was intended.
&tab;@name: The name of the project (i.e., &liberator.name;)
&tab;@minVersion: The minimum version of the project for which this plugin is intended to work.
&tab;@maxVersion: The maximum version of the project for which this plugin is intended to work.
author: The plugin's author. May appear more than once.
&tab;@href: The author's home page.
&tab;@email: The author's email address.
license: The plugin's license. May appear more than once.
&tab;@href: The URI of a page which shows or explains the license.

Generating documentation

You can also autogenerate most of the XML help after you have written a new command, mapping or option.

:echo util.generateHelp(commands.get(addons), Extra text

]]>)

Writing plugins

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 window or private liberator 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 runtimepath/plugin directory will find its context stored in plugins.<pluginName>, which is often invaluable during development and testing.

Plugin documentation

Plugins may provide inline documentation, which will appear on the :help plugins 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 flashblock extension:


    Kris Maglione
    MIT
    
    
        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.
    
    
	'flashblock' 'fb'
	'flashblock' 'fb'
        boolean
        true
	
            
                Controls the blocking of flash animations. When true, place
                holders are substituted for flash animations on untrusted sites.
            
	
    ]]>
    …;
]]>

The inline XML is made possible by E4X. It's important that the documentation be assigned to the INFO 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 :help 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.