1 <?xml version="1.0" encoding="UTF-8"?>
2 <?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>
4 <!DOCTYPE document SYSTEM "dactyl://content/dtd" [
5 <!ENTITY tab "   ">
10 title="&dactyl.appName; Developer information"
11 xmlns="&xmlns.dactyl;"
12 xmlns:html="&xmlns.html;">
14 <h1 tag="developer-information developer">Developer information</h1>
17 <h2 tag="writing-docs documentation">Writing documentation</h2>
20 In order for any user-visible change to be accepted into the mainline, it
21 must be accompanied by accurate documentation. The docs are written in an
22 XML dialect similar to XHTML, with a few tags specific to our
23 documentation. For example:
27 <tags><F1> :help :h help</tags>
28 <spec>:h<oa>elp</oa> <oa>subject</oa></spec>
32 Open the help page. The default page, as specified by <o>helpfile</o> is shown
33 unless <oa>subject</oa> is specified. If you need help for a specific topic, try
34 <ex>:help overview</ex>.
40 creates a new help section for the command <ex>:help</ex> and for
41 the related key binding, <k name="F1"/>. It also creates help tags
42 for the command, its shortcuts, the key binding, and the general
43 topic, ‘help’. These tags enable linking to this section from
44 other mentions of the topic and from the <ex>:help</ex> command.
47 <h3 tag="help-tags help-xml">Help tags</h3>
50 The following is a list of the more common XML tags used in help pages,
51 along with their highlight groups.
56 <dt>p</dt> <dd>A paragraph (HelpParagraph)</dd>
57 <dt>h1</dt> <dd>A first-level heading (HelpHead1)</dd>
58 <dt>h2</dt> <dd>A second-level heading (HelpHead2)</dd>
59 <dt>h3</dt> <dd>A third-level heading (HelpHead3)</dd>
60 <dt>h4</dt> <dd>A fourth-level heading (HelpHead4)</dd>
61 <dt>code</dt> <dd>A pre-formatted code block. (HelpCode)</dd>
62 <dt>note</dt> <dd><note>A note paragraph. (HelpNote)</note></dd>
63 <dt>strut</dt> <dd>A horizontal strut which prevents any previous floating elements from appearing below it.</dd>
64 <dt>warning</dt> <dd><warning>A warning paragraph. (HelpWarning)</warning></dd>
68 <dt>link</dt> <dd>A generic link. (HelpLink)</dd>
69 <dt>&tab;@topic</dt> <dd>The topic of the link. Either a help topic or a fully-qualified URI.</dd>
70 <dt>em</dt> <dd><em>Emphasized</em> text. (HelpEm)</dd>
71 <dt>str</dt> <dd>A <str>string</str>, with its contents wrapped in quotes. (HelpString)</dd>
72 <dt>logo</dt> <dd>&dactyl.appName;'s logo. (Logo)</dd>
76 <dt>item</dt> <dd>A help entry (HelpItem)</dd>
77 <dt>&tab;tags</dt> <dd>See the 'Tagging' section (HelpTags)</dd>
78 <dt>&tab;spec</dt> <dd>The specification for this item, such as an example command line. (HelpSpec)</dd>
79 <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>
80 <dt>&tab;type</dt> <dd>For options, the type of the option.
81 <em>number</em>, <em>boolean</em>, <em>string</em>, <em>stringlist</em>, or <em>charlist</em>.
84 <dt>&tab;default</dt> <dd>For options, the default value. (HelpDefault)</dd>
85 <dt>&tab;description</dt> <dd>The description of this help item. (HelpDescription)</dd>
86 <dt>&tab;&tab;@short</dt> <dd>Indicates that this is a short description which should appear between the specs and tags.</dd>
87 <dt>a</dt> <dd>Required <a>argument</a>. (HelpArg)</dd>
88 <dt>oa</dt> <dd>Optional <oa>argument</oa>. (HelpOptionalArg)</dd>
92 <dt>tags</dt> <dd>Space-separated list of strings to tag. Displayed right-aligned, and used for cross-linking. (HelpTags)</dd>
93 <dt>@tag</dt> <dd>The tag attribute. Applied to any element, generates a <tags> element for the given tags. (HelpTag)</dd>
97 <dt>o</dt> <dd>Link to an option. (HelpOpt)</dd>
98 <dt>ex</dt> <dd>Link to an Ex command. (HelpEx)</dd>
99 <dt>k</dt> <dd>Link to a key. (HelpKey)</dd>
100 <dt>&tab;@name</dt> <dd>The name attribute to <k>. When provided, <<a>value</a>> is prepended to
101 the element's contents, i.e., <em><k name="Tab"/></em> becomes <em><k name="Tab"/></em>.
103 <dt>&tab;@mode</dt> <dd>The mode attribute to <k>. Some keys have different functions in different modes.
104 You can use this attribute to specify which of the modes (other than Normal) a key pertains to.
105 The <<a>value</a>> is prepended to the element's contents, i.e., <em><k name="C-i" mode="I"/></em>
106 becomes <em><k name="C-i" mode="I"/></em>, and <em><k mode="t">i</k></em> becomes <em><k mode="t">i</k></em>.
108 <dt>t</dt> <dd>Links to an arbitrary help topic. (HelpTopic)</dd>
111 <dt>Plugins</dt><dd/>
112 <dt>@lang</dt> <dd>When applied to any element under
113 <plugin>, that element is only visible for a specific
115 <dt>plugin</dt> <dd>The container tag used for describing a plugin.</dd>
116 <dt>&tab;@name</dt> <dd>The name of the plugin. Used as the plugin's help tag.</dd>
117 <dt>&tab;@version</dt> <dd>The plugin's version number.</dd>
118 <dt>&tab;@href</dt> <dd>The plugin's home page.</dd>
119 <dt>&tab;@summary</dt> <dd>A short description of the plugin, shown in its section head.</dd>
121 <dt>info</dt> <dd>An element with the same
122 attributes as plugin, which may override the latter for
123 specific locales</dd>
125 <dt>project</dt> <dd>The project for which this plugin was intended.</dd>
126 <dt>&tab;@name</dt> <dd>The name of the project (i.e., <str>&dactyl.appName;</str>)</dd>
127 <dt>&tab;@min-version</dt> <dd>The minimum version of the project for which this plugin is intended to work.</dd>
128 <dt>&tab;@max-version</dt> <dd>The maximum version of the project for which this plugin is intended to work.</dd>
130 <dt>author</dt> <dd>The plugin's author. May appear more than once.</dd>
131 <dt>&tab;@href</dt> <dd>The author's home page.</dd>
132 <dt>&tab;@email</dt> <dd>The author's email address.</dd>
134 <dt>license</dt> <dd>The plugin's license. May appear more than once.</dd>
135 <dt>&tab;@href</dt> <dd>The URI of a page which shows or explains the license.</dd>
138 <h2 tag="generating-docs">Generating documentation</h2>
141 You can also autogenerate most of the XML help after you have
142 written a new command, mapping or option.
145 <example><ex>:echo dactyl.generateHelp(commands.get(<str>addons</str>), <![CDATA[<p>Extra text</p>]]>)</ex></example>
147 <h2 tag="writing-plugins">Writing plugins</h2>
150 Writing &dactyl.appName; plugins is incredibly simple. Plugins are
151 simply JavaScript files which run with full chrome privileges and
152 have full access to the &dactyl.appName; and &dactyl.host; APIs.
153 Each plugin has its own global object, which means that the
154 variables and functions that you create won't pollute the global
155 <em>window</em> or private <em>dactyl</em> namespaces. This means
156 that there's no need to wrap your plugin in a closure, as is often
157 the practice in JavaScript development. Furthermore, any plugin
158 which is installed in your <o>runtimepath</o><em>/plugins</em>
159 directory will find its context stored in
160 <em>plugins.<pluginName></em>, which is often invaluable during
161 development and testing.
165 Plugins are always initialized after the main window is loaded, so
166 there is no need to write <str>load</str> event handlers. Beyond
167 that, what you may do with your plugins is practically limitless.
168 Plugins have full access to all of the chrome resources that
169 ordinary &dactyl.host; does, along with the entire power of the
170 &dactyl.appName; API. If you need a starting point, have a look at some
171 <link topic="&dactyl.plugins;">existing plugins</link> or
172 <link topic="http://addon.mozilla.org/">extensions</link>,
174 <link topic="&dactyl.code;source/browse/">&dactyl.appName;</link>
178 <h3 tag="plugin-documentation">Plugin documentation</h3>
181 Plugins should provide inline documentation, which will appear on the
182 <ex>:help <str delim="">plugins</str></ex> page. The markup for help entries is the same
183 as the above, along with a few extra plugin-specific entries. Here is an
184 example from the popular <em>flashblock</em> extension:
187 <xml-block><escape><hl key="HelpXMLString">use strict</hl>;
188 XML.ignoreWhitespace = <hl key="Boolean">false</hl>;
189 XML.prettyPrinting = <hl key="Boolean">false</hl>;
190 <hl key="HelpXML">var</hl> INFO = <!-- Cursed manual XML highlighting! -->
191 <hl key="HelpXMLTagStart"><plugin
192 <hl key="HelpXMLAttribute">name</hl><hl key="HelpXMLString">flashblock</hl>
193 <hl key="HelpXMLAttribute">version</hl><hl key="HelpXMLString">1.0</hl>
194 <hl key="HelpXMLAttribute">href</hl><hl key="HelpXMLString">http://dactyl.sf.net/pentadactyl/plugins#flashblock-plugin</hl>
195 <hl key="HelpXMLAttribute">summary</hl><hl key="HelpXMLString">Flash Blocker</hl>
196 <hl key="HelpXMLAttribute">xmlns</hl>{NS}></hl></escape>
197 <author email="maglione.k@gmail.com">Kris Maglione</author>
198 <license href="http://opensource.org/licenses/mit-license.php">MIT</license>
199 <project name="Pentadactyl" min-version="1.0"/>
201 This plugin provides the same features as the ever popular FlashBlock
202 Firefox addon. Flash animations are substituted with place holders which
203 play the original animation when clicked. Additionally, this plugin provides
204 options to control which sites can play animations without restrictions, and
205 triggers to toggle the playing of animation on the current page.
208 <tags>'fb' 'flashblock'</tags>
209 <spec>'flashblock' 'fb'</spec>
211 <default>true</default>
214 Controls the blocking of flash animations. When true, place
215 holders are substituted for flash animations on untrusted sites.
220 <hl key="HelpXMLTagEnd"></plugin></hl></escape>;</xml-block>
223 The inline XML is made possible by
224 <link topic="https://developer.mozilla.org/en/E4X">E4X</link>.
225 It is important that the documentation be assigned to the
226 <em>INFO</em> variable, or &dactyl.appName; will not be able
227 to find it. The XML property changes are not compulsory, but
228 they do prevent certain formatting problems that may occur
229 otherwise. Beginning your file with <str>use strict</str>, while
230 not required, helps to prevent a lot of common errors.
234 The documentation that you provide behaves exactly as other
235 &dactyl.appName; documentation, which means that the tags you
236 provide are available via <ex>:help</ex> with full tag
237 completion and cross-referencing support. Although documentation
238 is not required, we strongly recommend that all plugin authors
239 provide at least basic documentation of the functionality of
240 their plugins and of each of the options, commands, and
241 especially mappings that they provide.
246 <!-- vim:se sts=4 sw=4 et: -->