mirror of
https://github.com/gryf/pentadactyl-pm.git
synced 2025-12-24 15:52:26 +01:00
246 lines
12 KiB
XML
246 lines
12 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<?xml-stylesheet type="text/xsl" href="chrome://dactyl/content/help.xsl"?>
|
||
|
||
<!DOCTYPE document SYSTEM "chrome://dactyl/content/help.dtd" [
|
||
<!ENTITY tab "   ">
|
||
]>
|
||
|
||
<document
|
||
name="developer"
|
||
title="&dactyl.appName; Developer information"
|
||
xmlns="&xmlns.dactyl;"
|
||
xmlns:html="&xmlns.html;">
|
||
|
||
<h1 tag="developer-information developer">Developer information</h1>
|
||
<toc start="2"/>
|
||
|
||
<h2 tag="writing-docs documentation">Writing documentation</h2>
|
||
|
||
<p>
|
||
In order for any user-visible change to be accepted into the mainline, it
|
||
must be accompanied by accurate documentation. The docs are written in an
|
||
XML dialect similar to XHTML, with a few tags specific to our
|
||
documentation. For example:
|
||
</p>
|
||
|
||
<xml-block><item>
|
||
<tags><F1> :help :h help</tags>
|
||
<spec>:h<oa>elp</oa> <oa>subject</oa></spec>
|
||
<spec><F1></spec>
|
||
<description>
|
||
<p>
|
||
Open the help page. The default page, as specified by <o>helpfile</o> is shown
|
||
unless <oa>subject</oa> is specified. If you need help for a specific topic, try
|
||
<ex>:help overview</ex>.
|
||
</p>
|
||
</description>
|
||
</item></xml-block>
|
||
|
||
<p>
|
||
creates a new help section for the command <ex>:help</ex> and for
|
||
the related key binding, <k name="F1"/>. 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 from
|
||
other mentions of the topic and from the <ex>:help</ex> command.
|
||
</p>
|
||
|
||
<h3 tag="help-tags help-xml">Help tags</h3>
|
||
|
||
<p>
|
||
The following is a list of the more common XML tags used in help pages,
|
||
along with their highlight groups.
|
||
</p>
|
||
|
||
<dl>
|
||
<dt>Layout</dt><dd/>
|
||
<dt>p</dt> <dd>A paragraph (HelpParagraph)</dd>
|
||
<dt>h1</dt> <dd>A first-level heading (HelpHead)</dd>
|
||
<dt>h2</dt> <dd>A second-level heading (HelpSubhead)</dd>
|
||
<dt>h3</dt> <dd>A third-level heading (HelpSubsubhead)</dd>
|
||
<dt>code</dt> <dd>A pre-formatted code block. (HelpCode)</dd>
|
||
<dt>note</dt> <dd><note>A note paragraph. (HelpNote)</note></dd>
|
||
<dt>strut</dt> <dd>A horizontal strut which prevents any previous floating elements from appearing below it.</dd>
|
||
<dt>warning</dt> <dd><warning>A warning paragraph. (HelpWarning)</warning></dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>Generic</dt><dd/>
|
||
<dt>link</dt> <dd>A generic link. (HelpLink)</dd>
|
||
<dt>&tab;@topic</dt> <dd>The topic of the link. Either a help topic or a fully-qualified URI.</dd>
|
||
<dt>em</dt> <dd><em>Emphasized</em> text. (HelpEm)</dd>
|
||
<dt>str</dt> <dd>A <str>string</str>, with its contents wrapped in quotes. (HelpString)</dd>
|
||
<dt>logo</dt> <dd>&dactyl.appName;'s logo. (Logo)</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>Items</dt><dd/>
|
||
<dt>item</dt> <dd>A help entry (HelpItem)</dd>
|
||
<dt>&tab;tags</dt> <dd>See the 'Tagging' section (HelpTags)</dd>
|
||
<dt>&tab;spec</dt> <dd>The specification for this item, such as an example command line. (HelpSpec)</dd>
|
||
<dt>&tab;strut</dt> <dd>A horizontal formatting strut which ensures that all previous <tags> and <spec> elements appear above the ones that follow.</dd>
|
||
<dt>&tab;type</dt> <dd>For options, the type of the option.
|
||
<em>number</em>, <em>boolean</em>, <em>string</em>, <em>stringlist</em>, or <em>charlist</em>.
|
||
(HelpType)
|
||
</dd>
|
||
<dt>&tab;default</dt> <dd>For options, the default value. (HelpDefault)</dd>
|
||
<dt>&tab;description</dt> <dd>The description of this help item. (HelpDescription)</dd>
|
||
<dt>&tab;&tab;@short</dt> <dd>Indicates that this is a short description which should appear between the specs and tags.</dd>
|
||
<dt>a</dt> <dd>Required <a>argument</a>. (HelpArg)</dd>
|
||
<dt>oa</dt> <dd>Optional <oa>argument</oa>. (HelpOptionalArg)</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>Tagging</dt><dd/>
|
||
<dt>tags</dt> <dd>Space-separated list of strings to tag. Displayed right-aligned, and used for cross-linking. (HelpTags)</dd>
|
||
<dt>@tag</dt> <dd>The tag attribute. Applied to any element, generates a <tags> element for the given tags. (HelpTag)</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>Linking</dt><dd/>
|
||
<dt>o</dt> <dd>Link to an option. (HelpOpt)</dd>
|
||
<dt>ex</dt> <dd>Link to an Ex command. (HelpEx)</dd>
|
||
<dt>k</dt> <dd>Link to a key. (HelpKey)</dd>
|
||
<dt>&tab;@name</dt> <dd>The name attribute to <k>. When provided, <<a>value</a>> is prepended to
|
||
the element's contents, i.e., <em><k name="Tab"/></em> becomes <em><k name="Tab"/></em>.
|
||
</dd>
|
||
<dt>&tab;@mode</dt> <dd>The mode attribute to <k>. Some keys have different functions in different modes.
|
||
You can use this attribute to specify which of the modes (other than Normal) a key pertains to.
|
||
The <<a>value</a>> is prepended to the element's contents, i.e., <em><k name="C-i" mode="i"/></em>
|
||
becomes <em><k name="C-i" mode="i"/></em>, and <em><k mode="i">i</k></em> becomes <em><k mode="i">i</k></em>.
|
||
</dd>
|
||
<dt>t</dt> <dd>Links to an arbitrary help topic. (HelpTopic)</dd>
|
||
</dl>
|
||
<dl>
|
||
<dt>Plugins</dt><dd/>
|
||
<dt>@lang</dt> <dd>When applied to any element under
|
||
<plugin>, that element is only visible for a specific
|
||
locale.</dd>
|
||
<dt>plugin</dt> <dd>The container tag used for describing a plugin.</dd>
|
||
<dt>&tab;@name</dt> <dd>The name of the plugin. Used as the plugin's help tag.</dd>
|
||
<dt>&tab;@version</dt> <dd>The plugin's version number.</dd>
|
||
<dt>&tab;@href</dt> <dd>The plugin's home page.</dd>
|
||
<dt>&tab;@summary</dt> <dd>A short description of the plugin, shown in its section head.</dd>
|
||
|
||
<dt>info</dt> <dd>An element with the same
|
||
attributes as plugin, which may override the latter for
|
||
specific locales</dd>
|
||
|
||
<dt>project</dt> <dd>The project for which this plugin was intended.</dd>
|
||
<dt>&tab;@name</dt> <dd>The name of the project (i.e., <str>&dactyl.appName;</str>)</dd>
|
||
<dt>&tab;@min-version</dt> <dd>The minimum version of the project for which this plugin is intended to work.</dd>
|
||
<dt>&tab;@max-version</dt> <dd>The maximum version of the project for which this plugin is intended to work.</dd>
|
||
|
||
<dt>author</dt> <dd>The plugin's author. May appear more than once.</dd>
|
||
<dt>&tab;@href</dt> <dd>The author's home page.</dd>
|
||
<dt>&tab;@email</dt> <dd>The author's email address.</dd>
|
||
|
||
<dt>license</dt> <dd>The plugin's license. May appear more than once.</dd>
|
||
<dt>&tab;@href</dt> <dd>The URI of a page which shows or explains the license.</dd>
|
||
</dl>
|
||
|
||
<h2 tag="generating-docs">Generating documentation</h2>
|
||
|
||
<p>
|
||
You can also autogenerate most of the XML help after you have
|
||
written a new command, mapping or option.
|
||
</p>
|
||
|
||
<example><ex>:echo dactyl.generateHelp(commands.get(<str>addons</str>), <![CDATA[<p>Extra text</p>]]>)</ex></example>
|
||
|
||
<h2 tag="writing-plugins">Writing plugins</h2>
|
||
|
||
<p>
|
||
Writing &dactyl.appName; plugins is incredibly simple. Plugins are
|
||
simply JavaScript files which run with full chrome privileges and
|
||
have full access to the &dactyl.appName; and &dactyl.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>dactyl</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>/plugins</em>
|
||
directory will find its context stored in
|
||
<em>plugins.<pluginName></em>, which is often invaluable during
|
||
development and testing.
|
||
</p>
|
||
|
||
<p>
|
||
Plugins are always initialized after the main window is loaded, so
|
||
there is no need to write <str>load</str> event handlers. Beyond
|
||
that, what you may do with your plugins is practically limitless.
|
||
Plugins have full access to all of the chrome resources that
|
||
ordinary &dactyl.host; does, along with the entire power of the
|
||
&dactyl.appName; API. If you need a starting point, have a look at some
|
||
<link topic="&dactyl.plugins;">existing plugins</link> or
|
||
<link topic="http://addon.mozilla.org/">extensions</link>,
|
||
especially the
|
||
<link topic="&dactyl.code;source/browse/">&dactyl.appName;</link>
|
||
source.
|
||
</p>
|
||
|
||
<h3 tag="plugin-documentation">Plugin documentation</h3>
|
||
|
||
<p>
|
||
Plugins should provide inline documentation, which will appear on the
|
||
<ex>:help plugins</ex> page. The markup for help entries is the same
|
||
as the above, along with a few extra plugin-specific entries. Here is an
|
||
example from the popular <em>flashblock</em> extension:
|
||
</p>
|
||
|
||
<xml-block><escape><hl key="HelpXMLString">use strict</hl>;
|
||
XML.ignoreWhitespace = <hl key="Boolean">false</hl>;
|
||
XML.prettyPrinting = <hl key="Boolean">false</hl>;
|
||
<hl key="HelpXML">var</hl> INFO = <!-- Cursed manual XML highlighting! -->
|
||
<hl key="HelpXMLTagStart"><plugin
|
||
<hl key="HelpXMLAttribute">name</hl><hl key="HelpXMLString">flashblock</hl>
|
||
<hl key="HelpXMLAttribute">version</hl><hl key="HelpXMLString">1.0</hl>
|
||
<hl key="HelpXMLAttribute">href</hl><hl key="HelpXMLString">http://dactyl.sf.net/pentadactyl/plugins#flashblock-plugin</hl>
|
||
<hl key="HelpXMLAttribute">summary</hl><hl key="HelpXMLString">Flash Blocker</hl>
|
||
<hl key="HelpXMLAttribute">xmlns</hl>{NS}></hl></escape>
|
||
<author email="maglione.k@gmail.com">Kris Maglione</author>
|
||
<license href="http://opensource.org/licenses/mit-license.php">MIT</license>
|
||
<project name="Pentadactyl" min-version="1.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.
|
||
</p>
|
||
<item>
|
||
<tags>'fb' 'flashblock'</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>
|
||
<escape><oa>...</oa>
|
||
<hl key="HelpXMLTagEnd"></plugin></hl></escape>;</xml-block>
|
||
|
||
<p>
|
||
The inline XML is made possible by
|
||
<link topic="https://developer.mozilla.org/en/E4X">E4X</link>.
|
||
It is important that the documentation be assigned to the
|
||
<em>INFO</em> variable, or &dactyl.appName; will not be able
|
||
to find it. The XML property changes are not compulsory, but
|
||
they do prevent certain formatting problems that may occur
|
||
otherwise. Beginning your file with <str>use strict</str>, while
|
||
not required, helps to prevent a lot of common errors.
|
||
</p>
|
||
|
||
<p>
|
||
The documentation that you provide behaves exactly as other
|
||
&dactyl.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.
|
||
</p>
|
||
|
||
</document>
|
||
|
||
<!-- vim:se sts=4 sw=4 et: -->
|